1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 This is the documentation for the Sphinx documentation builder. Sphinx
10 is a tool that translates a set of reStructuredText source files into
11 various output formats, automatically producing cross-references,
12 indices, etc. That is, if you have a directory containing a bunch of
13 reST-formatted documents (and possibly subdirectories of docs in there
14 as well), Sphinx can generate a nicely-organized arrangement of HTML
15 files (in some other directory) for easy browsing and navigation. But
16 from the same source, it can also generate a PDF file using LaTeX.
17 The focus is on hand-written documentation, rather than auto-generated
19 API docs. Though there is support for that kind of documentation as
20 well (which is intended to be freely mixed with hand-written content),
21 if you need pure API docs have a look at Epydoc, which also understands
22 reST.
23 For a great “introduction” to writing docs in general – the whys and
25 hows, see also Write the docs, written by Eric Holscher.
26 Conversion from other systems
28 This section is intended to collect helpful hints for those wanting to
29 migrate to reStructuredText/Sphinx from other documentation systems.
30 · Gerard Flanagan has written a script to convert pure HTML to reST; it
32 can be found at the Python Package Index.
33 · For converting the old Python docs to Sphinx, a converter was written
35 which can be found at the Python SVN repository. It contains generic
36 code to convert Python-doc-style LaTeX markup to Sphinx reST.
37 · Marcin Wojdyr has written a script to convert Docbook to reST with
39 Sphinx markup; it is at GitHub.
40 · Christophe de Vienne wrote a tool to convert from Open/LibreOffice
42 documents to Sphinx: odt2sphinx.
43 · To convert different markups, Pandoc is a very helpful tool.
45 Use with other systems
47 See the pertinent section in the FAQ list.
48 Prerequisites
50 Sphinx needs at least Python 3.5 to run, as well as the docutils and
51 Jinja2 libraries. Sphinx should work with docutils version 0.12 or some
52 (not broken) SVN trunk snapshot.
53 Usage
55 See /usage/quickstart for an introduction. It also contains links to
56 more advanced sections in this manual for the topics it discusses.
57
59 · Overview
60 · Linux
62 · macOS
64 · Windows
66 · Installation from PyPI
68 · Installation from source
70 Overview
72 Sphinx is written in Python and supports Python 3.5+.
73 Linux
75 Debian/Ubuntu
76 Install either python3-sphinx (Python 3) or python-sphinx (Python 2)
77 using apt-get:
78 $ apt-get install python3-sphinx
80 If it not already present, this will install Python for you.
82 RHEL, CentOS
84 Install python-sphinx using yum:
85 $ yum install python-sphinx
87 If it not already present, this will install Python for you.
89 Other distributions
91 Most Linux distributions have Sphinx in their package repositories.
92 Usually the package is called python3-sphinx, python-sphinx or sphinx.
93 Be aware that there are at least two other packages with sphinx in
94 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
95 search database (Sphinx search).
96 macOS
98 Sphinx can be installed using Homebrew, MacPorts, or as part of a
99 Python distribution such as Anaconda.
100 Homebrew
102 $ brew install sphinx-doc
103 For more information, refer to the package overview.
105 MacPorts
107 Install either python36-sphinx (Python 3) or python27-sphinx (Python 2)
108 using port:
109 $ sudo port install py36-sphinx
111 To set up the executable paths, use the port select command:
113 $ sudo port select --set python python36
115 $ sudo port select --set sphinx py36-sphinx
116 For more information, refer to the package overview.
118 Anaconda
120 $ conda install sphinx
121 Windows
123 Todo
124 Could we start packaging this?
125 Most Windows users do not have Python installed by default, so we begin
127 with the installation of Python itself. If you are unsure, open the
128 Command Prompt (⊞Win-r and type cmd). Once the command prompt is open,
129 type python --version and press Enter. If Python is available, you
130 will see the version of Python printed to the screen. If you do not
131 have Python installed, refer to the Hitchhikers Guide to Python’s
132 Python on Windows installation guides. You must install Python 3.
133 Once Python is installed, you can install Sphinx using pip. Refer to
135 the pip installation instructions below for more information.
136 Installation from PyPI
138 Sphinx packages are published on the Python Package Index. The pre‐
139 ferred tool for installing packages from PyPI is pip. This tool is
140 provided with all modern versions of Python.
141 On Linux or MacOS, you should open your terminal and run the following
143 command.
144 $ pip install -U sphinx
146 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
148 run the same command.
149 C:\> pip install -U sphinx
151 After installation, type sphinx-build --version on the command prompt.
153 If everything worked fine, you will see the version number for the
154 Sphinx package you just installed.
155 Installation from PyPI also allows you to install the latest develop‐
157 ment release. You will not generally need (or want) to do this, but it
158 can be useful if you see a possible bug in the latest stable release.
159 To do this, use the --pre flag.
160 $ pip install -U --pre sphinx
162 Installation from source
164 You can install Sphinx directly from a clone of the Git repository.
165 This can be done either by cloning the repo and installing from the
166 local clone, on simply installing directly via git.
167 $ git clone https://github.com/sphinx-doc/sphinx
169 $ cd sphinx
170 $ pip install .
171 $ pip install git+https://github.com/sphinx-doc/sphinx
173 You can also download a snapshot of the Git repo in either tar.gz or
175 zip format. Once downloaded and extracted, these can be installed with
176 pip as above.
177
179 Once Sphinx is installed, you can proceed with setting up your first
180 Sphinx project. To ease the process of getting started, Sphinx provides
181 a tool, sphinx-quickstart, which will generate a documentation source
182 directory and populate it with some defaults. We’re going to use the
183 sphinx-quickstart tool here, though it’s use by no means necessary.
184 Setting up the documentation sources
186 The root directory of a Sphinx collection of reStructuredText document
187 sources is called the source directory. This directory also contains
188 the Sphinx configuration file conf.py, where you can configure all
189 aspects of how Sphinx reads your sources and builds your documentation.
190 [1]
191 Sphinx comes with a script called sphinx-quickstart that sets up a
193 source directory and creates a default conf.py with the most useful
194 configuration values from a few questions it asks you. To use this,
195 run:
196 $ sphinx-quickstart
198 Answer each question asked. Be sure to say yes to the autodoc exten‐
200 sion, as we will use this later.
201 There is also an automatic “API documentation” generator called
203 sphinx-apidoc; see /man/sphinx-apidoc for details.
204 Defining document structure
206 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
207 tory with conf.py and a master document, index.rst (if you accepted the
208 defaults). The main function of the master document is to serve as a
209 welcome page, and to contain the root of the “table of contents tree”
210 (or toctree). This is one of the main things that Sphinx adds to
211 reStructuredText, a way to connect multiple files to a single hierarchy
212 of documents.
213 reStructuredText directives
215 toctree is a reStructuredText directive, a very versatile piece of
216 markup. Directives can have arguments, options and content.
217 Arguments are given directly after the double colon following the
219 directive’s name. Each directive decides whether it can have argu‐
220 ments, and how many.
221 Options are given after the arguments, in form of a “field list”. The
223 maxdepth is such an option for the toctree directive.
224 Content follows the options or arguments after a blank line. Each
226 directive decides whether to allow content, and what to do with it.
227 A common gotcha with directives is that the first line of the content
229 must be indented to the same level as the options are.
230 The toctree directive initially is empty, and looks like so:
232 .. toctree::
234 :maxdepth: 2
235 You add documents listing them in the content of the directive:
237 .. toctree::
239 :maxdepth: 2
240 usage/installation
242 usage/quickstart
243 ...
244 This is exactly how the toctree for this documentation looks. The doc‐
246 uments to include are given as document names, which in short means
247 that you leave off the file name extension and use forward slashes (/)
248 as directory separators.
249 [image: more info] [image]
251 Read more about the toctree directive.
252 You can now create the files you listed in the toctree and add content,
254 and their section titles will be inserted (up to the maxdepth level) at
255 the place where the toctree directive is placed. Also, Sphinx now
256 knows about the order and hierarchy of your documents. (They may con‐
257 tain toctree directives themselves, which means you can create deeply
258 nested hierarchies if necessary.)
259 Adding content
261 In Sphinx source files, you can use most features of standard reStruc‐
262 turedText. There are also several features added by Sphinx. For exam‐
263 ple, you can add cross-file references in a portable way (which works
264 for all output types) using the ref role.
265 For an example, if you are viewing the HTML version you can look at the
267 source for this document – use the “Show Source” link in the sidebar.
268 Todo
270 Update the below link when we add new guides on these.
271 [image: more info] [image]
273 See /usage/restructuredtext/index for a more in-depth introduction to
274 reStructuredText, including markup added by Sphinx.
275 Running the build
277 Now that you have added some files and content, let’s make a first
278 build of the docs. A build is started with the sphinx-build program:
279 $ sphinx-build -b html sourcedir builddir
281 where sourcedir is the source directory, and builddir is the directory
283 in which you want to place the built documentation. The -b option
284 selects a builder; in this example Sphinx will build HTML files.
285 [image: more info] [image]
287 Refer to the sphinx-build man page for all options that sphinx-build
288 supports.
289 However, sphinx-quickstart script creates a Makefile and a make.bat
291 which make life even easier for you. These can be executed by running
292 make with the name of the builder. For example.
293 $ make html
295 This will build HTML docs in the build directory you chose. Execute
297 make without an argument to see which targets are available.
298 How do I generate PDF documents?
300 make latexpdf runs the LaTeX builder and readily invokes the
302 pdfTeX toolchain for you.
303 Todo
305 Move this whole section into a guide on rST or directives
306 Documenting objects
308 One of Sphinx’s main objectives is easy documentation of objects (in a
309 very general sense) in any domain. A domain is a collection of object
310 types that belong together, complete with markup to create and refer‐
311 ence descriptions of these objects.
312 The most prominent domain is the Python domain. For example, to docu‐
314 ment Python’s built-in function enumerate(), you would add this to one
315 of your source files.
316 .. py:function:: enumerate(sequence[, start=0])
318 Return an iterator that yields tuples of an index and an item of the
320 *sequence*. (And so on.)
321 This is rendered like this:
323 enumerate(sequence[, start=0])
325 Return an iterator that yields tuples of an index and an item of
326 the sequence. (And so on.)
327 The argument of the directive is the signature of the object you
329 describe, the content is the documentation for it. Multiple signatures
330 can be given, each in its own line.
331 The Python domain also happens to be the default domain, so you don’t
333 need to prefix the markup with the domain name.
334 .. function:: enumerate(sequence[, start=0])
336 ...
338 does the same job if you keep the default setting for the default
340 domain.
341 There are several more directives for documenting other types of Python
343 objects, for example py:class or py:method. There is also a cross-ref‐
344 erencing role for each of these object types. This markup will create
345 a link to the documentation of enumerate().
346 The :py:func:`enumerate` function can be used for ...
348 And here is the proof: A link to enumerate().
350 Again, the py: can be left out if the Python domain is the default one.
352 It doesn’t matter which file contains the actual documentation for enu‐
353 merate(); Sphinx will find it and create a link to it.
354 Each domain will have special rules for how the signatures can look
356 like, and make the formatted output look pretty, or add specific fea‐
357 tures like links to parameter types, e.g. in the C/C++ domains.
358 [image: more info] [image]
360 See /usage/restructuredtext/domains for all the available domains and
361 their directives/roles.
362 Basic configuration
364 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
365 cesses your documents. In that file, which is executed as a Python
366 source file, you assign configuration values. For advanced users:
367 since it is executed by Sphinx, you can do non-trivial tasks in it,
368 like extending sys.path or importing a module to find out the version
369 you are documenting.
370 The config values that you probably want to change are already put into
372 the conf.py by sphinx-quickstart and initially commented out (with
373 standard Python syntax: a # comments the rest of the line). To change
374 the default value, remove the hash sign and modify the value. To cus‐
375 tomize a config value that is not automatically added by sphinx-quick‐
376 start, just add an additional assignment.
377 Keep in mind that the file uses Python syntax for strings, numbers,
379 lists and so on. The file is saved in UTF-8 by default, as indicated
380 by the encoding declaration in the first line. If you use non-ASCII
381 characters in any string value, you need to use Python Unicode strings
382 (like project = u'Exposé').
383 [image: more info] [image]
385 See /usage/configuration for documentation of all available config
386 values.
387 Todo
389 Move this entire doc to a different section
390 Autodoc
392 When documenting Python code, it is common to put a lot of documenta‐
393 tion in the source files, in documentation strings. Sphinx supports
394 the inclusion of docstrings from your modules with an extension (an
395 extension is a Python module that provides additional features for
396 Sphinx projects) called autodoc.
397 In order to use autodoc, you need to activate it in conf.py by putting
399 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
400 sions config value. Then, you have a few additional directives at your
401 disposal.
402 For example, to document the function io.open(), reading its signature
404 and docstring from the source file, you’d write this:
405 .. autofunction:: io.open
407 You can also document whole classes or even modules automatically,
409 using member options for the auto directives, like
410 .. automodule:: io
412 :members:
413 autodoc needs to import your modules in order to extract the doc‐
415 strings. Therefore, you must add the appropriate path to sys.path in
416 your conf.py.
417 WARNING:
419 autodoc imports the modules to be documented. If any modules have
420 side effects on import, these will be executed by autodoc when
421 sphinx-build is run.
422 If you document scripts (as opposed to library modules), make sure
424 their main routine is protected by a if __name__ == '__main__' con‐
425 dition.
426 [image: more info] [image]
428 See sphinx.ext.autodoc for the complete description of the features of
429 autodoc.
430 Todo
432 Move this doc to another section
433 Intersphinx
435 Many Sphinx documents including the Python documentation are published
436 on the Internet. When you want to make links to such documents from
437 your documentation, you can do it with sphinx.ext.intersphinx.
438 In order to use intersphinx, you need to activate it in conf.py by
440 putting the string 'sphinx.ext.intersphinx' into the extensions list
441 and set up the intersphinx_mapping config value.
442 For example, to link to io.open() in the Python library manual, you
444 need to setup your intersphinx_mapping like:
445 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
447 And now, you can write a cross-reference like :py:func:`io.open`. Any
449 cross-reference that has no matching target in the current documenta‐
450 tion set, will be looked up in the documentation sets configured in
451 intersphinx_mapping (this needs access to the URL in order to download
452 the list of valid targets). Intersphinx also works for some other
453 domain’s roles including :ref:, however it doesn’t work for :doc: as
454 that is non-domain role.
455 [image: more info] [image]
457 See sphinx.ext.intersphinx for the complete description of the fea‐
458 tures of intersphinx.
459 More topics to be covered
461 · Other extensions:
462 · Static files
464 · Selecting a theme
466 · /usage/advanced/setuptools
468 · Templating
470 · Using extensions
472 · Writing extensions
474
476 [1] This is the usual layout. However, conf.py can also live in
477 another directory, the configuration directory. Refer to the
478 sphinx-build man page for more information.
479
481 reStructuredText (reST) is the default plaintext markup language used
482 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
483 Text syntax, while Sphinx extends this to support additional function‐
484 ality.
485 The below guides go through the most important aspects of reST. For the
487 authoritative reStructuredText reference, refer to the docutils docu‐
488 mentation.
489 reStructuredText Primer
491 reStructuredText is the default plaintext markup language used by
492 Sphinx. This section is a brief introduction to reStructuredText
493 (reST) concepts and syntax, intended to provide authors with enough
494 information to author documents productively. Since reST was designed
495 to be a simple, unobtrusive markup language, this will not take too
496 long.
497 SEE ALSO:
499 The authoritative reStructuredText User Documentation. The “ref”
500 links in this document link to the description of the individual
501 constructs in the reST reference.
502 Paragraphs
504 The paragraph (ref) is the most basic block in a reST document. Para‐
505 graphs are simply chunks of text separated by one or more blank lines.
506 As in Python, indentation is significant in reST, so all lines of the
507 same paragraph must be left-aligned to the same level of indentation.
508 Inline markup
510 The standard reST inline markup is quite simple: use
511 · one asterisk: *text* for emphasis (italics),
513 · two asterisks: **text** for strong emphasis (boldface), and
515 · backquotes: ``text`` for code samples.
517 If asterisks or backquotes appear in running text and could be confused
519 with inline markup delimiters, they have to be escaped with a back‐
520 slash.
521 Be aware of some restrictions of this markup:
523 · it may not be nested,
525 · content may not start or end with whitespace: * text* is wrong,
527 · it must be separated from surrounding text by non-word characters.
529 Use a backslash escaped space to work around that: thisis\ *one*\
530 word.
531 These restrictions may be lifted in future versions of the docutils.
533 It is also possible to replace or expand upon some of this inline
535 markup with roles. Refer to Roles for more information.
536 Lists and Quote-like blocks
538 List markup (ref) is natural: just place an asterisk at the start of a
539 paragraph and indent properly. The same goes for numbered lists; they
540 can also be autonumbered using a # sign:
541 * This is a bulleted list.
543 * It has two items, the second
544 item uses two lines.
545 1. This is a numbered list.
547 2. It has two items too.
548 #. This is a numbered list.
550 #. It has two items too.
551 Nested lists are possible, but be aware that they must be separated
553 from the parent list items by blank lines:
554 * this is
556 * a list
557 * with a nested list
559 * and some subitems
560 * and here the parent list continues
562 Definition lists (ref) are created as follows:
564 term (up to a line of text)
566 Definition of the term, which must be indented
567 and can even consist of multiple paragraphs
569 next term
571 Description.
572 Note that the term cannot have more than one line of text.
574 Quoted paragraphs (ref) are created by just indenting them more than
576 the surrounding paragraphs.
577 Line blocks (ref) are a way of preserving line breaks:
579 | These lines are
581 | broken exactly like in
582 | the source file.
583 There are also several more special blocks available:
585 · field lists (ref, with caveats noted in Field Lists)
587 · option lists (ref)
589 · quoted literal blocks (ref)
591 · doctest blocks (ref)
593 Literal blocks
595 Literal code blocks (ref) are introduced by ending a paragraph with the
596 special marker ::. The literal block must be indented (and, like all
597 paragraphs, separated from the surrounding ones by blank lines):
598 This is a normal text paragraph. The next paragraph is a code sample::
600 It is not processed in any way, except
602 that the indentation is removed.
603 It can span multiple lines.
605 This is a normal text paragraph again.
607 The handling of the :: marker is smart:
609 · If it occurs as a paragraph of its own, that paragraph is completely
611 left out of the document.
612 · If it is preceded by whitespace, the marker is removed.
614 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
616 gle colon.
617 That way, the second sentence in the above example’s first paragraph
619 would be rendered as “The next paragraph is a code sample:”.
620 Code highlighting can be enabled for these literal blocks on a docu‐
622 ment-wide basis using the highlight directive and on a project-wide
623 basis using the highlight_language configuration option. The code-block
624 directive can be used to set highlighting on a block-by-block basis.
625 These directives are discussed later.
626 Doctest blocks
628 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
629 into docstrings. They do not require the literal blocks syntax. The
630 doctest block must end with a blank line and should not end with with
631 an unused prompt:
632 >>> 1 + 1
634 2
635 Tables
637 For grid tables (ref), you have to “paint” the cell grid yourself.
638 They look like this:
639 +------------------------+------------+----------+----------+
641 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
642 | (header rows optional) | | | |
643 +========================+============+==========+==========+
644 | body row 1, column 1 | column 2 | column 3 | column 4 |
645 +------------------------+------------+----------+----------+
646 | body row 2 | ... | ... | |
647 +------------------------+------------+----------+----------+
648 Simple tables (ref) are easier to write, but limited: they must contain
650 more than one row, and the first column cells cannot contain multiple
651 lines. They look like this:
652 ===== ===== =======
654 A B A and B
655 ===== ===== =======
656 False False False
657 True False False
658 False True False
659 True True True
660 ===== ===== =======
661 Two more syntaxes are supported: CSV tables and List tables. They use
663 an explicit markup block. Refer to table-directives for more informa‐
664 tion.
665 Hyperlinks
667 External links
668 Use `Link text <https://domain.invalid/>`_ for inline web links. If
669 the link text should be the web address, you don’t need special markup
670 at all, the parser finds links and mail addresses in ordinary text.
671 IMPORTANT:
673 There must be a space between the link text and the opening < for
674 the URL.
675 You can also separate the link and the target definition (ref), like
677 this:
678 This is a paragraph that contains `a link`_.
680 .. _a link: https://domain.invalid/
682 Internal links
684 Internal linking is done via a special reST role provided by Sphinx,
685 see the section on specific markup, ref-role.
686 Sections
688 Section headers (ref) are created by underlining (and optionally over‐
689 lining) the section title with a punctuation character, at least as
690 long as the text:
691 =================
693 This is a heading
694 =================
695 Normally, there are no heading levels assigned to certain characters as
697 the structure is determined from the succession of headings. However,
698 this convention is used in Python’s Style Guide for documenting which
699 you may follow:
700 · # with overline, for parts
702 · * with overline, for chapters
704 · =, for sections
706 · -, for subsections
708 · ^, for subsubsections
710 · ", for paragraphs
712 Of course, you are free to use your own marker characters (see the reST
714 documentation), and use a deeper nesting level, but keep in mind that
715 most target formats (HTML, LaTeX) have a limited supported nesting
716 depth.
717 Field Lists
719 Field lists (ref) are sequences of fields marked up like this:
720 :fieldname: Field content
722 They are commonly used in Python documentation:
724 def my_function(my_arg, my_other_arg):
726 """A function just for me.
727 :param my_arg: The first of my arguments.
729 :param my_other_arg: The second of my arguments.
730 :returns: A message (just for me, of course).
732 """
733 Sphinx extends standard docutils behavior and intercepts field lists
735 specified at the beginning of documents. Refer to field-lists for more
736 information.
737 Roles
739 A role or “custom interpreted text role” (ref) is an inline piece of
740 explicit markup. It signifies that that the enclosed text should be
741 interpreted in a specific way. Sphinx uses this to provide semantic
742 markup and cross-referencing of identifiers, as described in the appro‐
743 priate section. The general syntax is :rolename:`content`.
744 Docutils supports the following roles:
746 · emphasis – equivalent of *emphasis*
748 · strong – equivalent of **strong**
750 · literal – equivalent of ``literal``
752 · subscript – subscript text
754 · superscript – superscript text
756 · title-reference – for titles of books, periodicals, and other materi‐
758 als
759 Refer to roles for roles added by Sphinx.
761 Explicit Markup
763 “Explicit markup” (ref) is used in reST for most constructs that need
764 special handling, such as footnotes, specially-highlighted paragraphs,
765 comments, and generic directives.
766 An explicit markup block begins with a line starting with .. followed
768 by whitespace and is terminated by the next paragraph at the same level
769 of indentation. (There needs to be a blank line between explicit
770 markup and normal paragraphs. This may all sound a bit complicated,
771 but it is intuitive enough when you write it.)
772 Directives
774 A directive (ref) is a generic block of explicit markup. Along with
775 roles, it is one of the extension mechanisms of reST, and Sphinx makes
776 heavy use of it.
777 Docutils supports the following directives:
779 · Admonitions: attention, caution, danger, error, hint, important,
781 note, tip, warning and the generic admonition. (Most themes style
782 only “note” and “warning” specially.)
783 · Images:
785 · image (see also Images below)
787 · figure (an image with caption and optional legend)
789 · Additional body elements:
791 · contents (a local, i.e. for the current file only, table of con‐
793 tents)
794 · container (a container with a custom class, useful to generate an
796 outer <div> in HTML)
797 · rubric (a heading without relation to the document sectioning)
799 · topic, sidebar (special highlighted body elements)
801 · parsed-literal (literal block that supports inline markup)
803 · epigraph (a block quote with optional attribution line)
805 · highlights, pull-quote (block quotes with their own class
807 attribute)
808 · compound (a compound paragraph)
810 · Special tables:
812 · table (a table with title)
814 · csv-table (a table generated from comma-separated values)
816 · list-table (a table generated from a list of lists)
818 · Special directives:
820 · raw (include raw target-format markup)
822 · include (include reStructuredText from another file) – in Sphinx,
824 when given an absolute include file path, this directive takes it
825 as relative to the source directory
826 · class (assign a class attribute to the next element) [1]
828 · HTML specifics:
830 · meta (generation of HTML <meta> tags)
832 · title (override document title)
834 · Influencing markup:
836 · default-role (set a new default role)
838 · role (create a new role)
840 Since these are only per-file, better use Sphinx’s facilities for
842 setting the default_role.
843 WARNING:
845 Do not use the directives sectnum, header and footer.
846 Directives added by Sphinx are described in directives.
848 Basically, a directive consists of a name, arguments, options and con‐
850 tent. (Keep this terminology in mind, it is used in the next chapter
851 describing custom directives.) Looking at this example,
852 .. function:: foo(x)
854 foo(y, z)
855 :module: some.module.name
856 Return a line of text input from the user.
858 function is the directive name. It is given two arguments here, the
860 remainder of the first line and the second line, as well as one option
861 module (as you can see, options are given in the lines immediately fol‐
862 lowing the arguments and indicated by the colons). Options must be
863 indented to the same level as the directive content.
864 The directive content follows after a blank line and is indented rela‐
866 tive to the directive start.
867 Images
869 reST supports an image directive (ref), used like so:
870 .. image:: gnu.png
872 (options)
873 When used within Sphinx, the file name given (here gnu.png) must either
875 be relative to the source file, or absolute which means that they are
876 relative to the top source directory. For example, the file
877 sketch/spam.rst could refer to the image images/spam.png as
878 ../images/spam.png or /images/spam.png.
879 Sphinx will automatically copy image files over to a subdirectory of
881 the output directory on building (e.g. the _static directory for HTML
882 output.)
883 Interpretation of image size options (width and height) is as follows:
885 if the size has no unit or the unit is pixels, the given size will only
886 be respected for output channels that support pixels. Other units (like
887 pt for points) will be used for HTML and LaTeX output (the latter
888 replaces pt by bp as this is the TeX unit such that 72bp=1in).
889 Sphinx extends the standard docutils behavior by allowing an asterisk
891 for the extension:
892 .. image:: gnu.*
894 Sphinx then searches for all images matching the provided pattern and
896 determines their type. Each builder then chooses the best image out of
897 these candidates. For instance, if the file name gnu.* was given and
898 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
899 builder would choose the former, while the HTML builder would prefer
900 the latter. Supported image types and choosing priority are defined at
901 /usage/builders/index.
902 Note that image file names should not contain spaces.
904 Changed in version 0.4: Added the support for file names ending in an
906 asterisk.
907 Changed in version 0.6: Image paths can now be absolute.
910 Changed in version 1.5: latex target supports pixels (default is
913 96px=1in).
914 Footnotes
917 For footnotes (ref), use [#name]_ to mark the footnote location, and
918 add the footnote body at the bottom of the document after a “Footnotes”
919 rubric heading, like so:
920 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
922 .. rubric:: Footnotes
924 .. [#f1] Text of the first footnote.
926 .. [#f2] Text of the second footnote.
927 You can also explicitly number the footnotes ([1]_) or use auto-num‐
929 bered footnotes without names ([#]_).
930 Citations
932 Standard reST citations (ref) are supported, with the additional fea‐
933 ture that they are “global”, i.e. all citations can be referenced from
934 all files. Use them like so:
935 Lorem ipsum [Ref]_ dolor sit amet.
937 .. [Ref] Book or article reference, URL or whatever.
939 Citation usage is similar to footnote usage, but with a label that is
941 not numeric or begins with #.
942 Substitutions
944 reST supports “substitutions” (ref), which are pieces of text and/or
945 markup referred to in the text by |name|. They are defined like foot‐
946 notes with explicit markup blocks, like this:
947 .. |name| replace:: replacement *text*
949 or this:
951 .. |caution| image:: warning.png
953 :alt: Warning!
954 See the reST reference for substitutions for details.
956 If you want to use some substitutions for all documents, put them into
958 rst_prolog or rst_epilog or put them into a separate file and include
959 it into all documents you want to use them in, using the include direc‐
960 tive. (Be sure to give the include file a file name extension differ‐
961 ing from that of other source files, to avoid Sphinx finding it as a
962 standalone document.)
963 Sphinx defines some default substitutions, see default-substitutions.
965 Comments
967 Every explicit markup block which isn’t a valid markup construct (like
968 the footnotes above) is regarded as a comment (ref). For example:
969 .. This is a comment.
971 You can indent text after a comment start to form multiline comments:
973 ..
975 This whole indented block
976 is a comment.
977 Still in the comment.
979 Source encoding
981 Since the easiest way to include special characters like em dashes or
982 copyright signs in reST is to directly write them as Unicode charac‐
983 ters, one has to specify an encoding. Sphinx assumes source files to
984 be encoded in UTF-8 by default; you can change this with the
985 source_encoding config value.
986 Gotchas
988 There are some problems one commonly runs into while authoring reST
989 documents:
990 · Separation of inline markup: As said above, inline markup spans must
992 be separated from the surrounding text by non-word characters, you
993 have to use a backslash-escaped space to get around that. See the
994 reference for the details.
995 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
997 sible.
998
1000 [1] When the default domain contains a class directive, this directive
1001 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1002 Roles
1004 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1005 ments. They are written as :rolename:`content`.
1006 NOTE:
1008 The default role (`content`) has no special meaning by default. You
1009 are free to use it for anything you like, e.g. variable names; use
1010 the default_role config value to set it to a known role – the any
1011 role to find anything or the py:obj role to find Python objects are
1012 very useful for this.
1013 See /usage/restructuredtext/domains for roles added by domains.
1015 Cross-referencing syntax
1017 Cross-references are generated by many semantic interpreted text roles.
1018 Basically, you only need to write :role:`target`, and a link will be
1019 created to the item named target of the type indicated by role. The
1020 link’s text will be the same as target.
1021 There are some additional facilities, however, that make cross-refer‐
1023 encing roles more versatile:
1024 · You may supply an explicit title and reference target, like in reST
1026 direct hyperlinks: :role:`title <target>` will refer to target, but
1027 the link text will be title.
1028 · If you prefix the content with !, no reference/hyperlink will be cre‐
1030 ated.
1031 · If you prefix the content with ~, the link text will only be the last
1033 component of the target. For example, :py:meth:`~Queue.Queue.get`
1034 will refer to Queue.Queue.get but only display get as the link text.
1035 This does not work with all cross-reference roles, but is domain spe‐
1036 cific.
1037 In HTML output, the link’s title attribute (that is e.g. shown as a
1039 tool-tip on mouse-hover) will always be the full target name.
1040 Cross-referencing anything
1042 :any: New in version 1.3.
1043 This convenience role tries to do its best to find a valid tar‐
1046 get for its reference text.
1047 · First, it tries standard cross-reference targets that would be
1049 referenced by doc, ref or option.
1050 Custom objects added to the standard domain by extensions (see
1052 Sphinx.add_object_type()) are also searched.
1053 · Then, it looks for objects (targets) in all loaded domains.
1055 It is up to the domains how specific a match must be. For
1056 example, in the Python domain a reference of :any:`Builder`
1057 would match the sphinx.builders.Builder class.
1058 If none or multiple targets are found, a warning will be emit‐
1060 ted. In the case of multiple targets, you can change “any” to a
1061 specific role.
1062 This role is a good candidate for setting default_role. If you
1064 do, you can write cross-references without a lot of markup over‐
1065 head. For example, in this Python function documentation
1066 .. function:: install()
1068 This function installs a `handler` for every signal known by the
1070 `signal` module. See the section `about-signals` for more information.
1071 there could be references to a glossary term (usually
1073 :term:`handler`), a Python module (usually :py:mod:`signal` or
1074 :mod:`signal`) and a section (usually :ref:`about-signals`).
1075 The any role also works together with the intersphinx extension:
1077 when no local cross-reference is found, all object types of
1078 intersphinx inventories are also searched.
1079 Cross-referencing objects
1081 These roles are described with their respective domains:
1082 · Python
1084 · C
1086 · C++
1088 · JavaScript
1090 · ReST
1092 Cross-referencing arbitrary locations
1094 :ref: To support cross-referencing to arbitrary locations in any docu‐
1095 ment, the standard reST labels are used. For this to work label
1096 names must be unique throughout the entire documentation. There
1097 are two ways in which you can refer to labels:
1098 · If you place a label directly before a section title, you can
1100 reference to it with :ref:`label-name`. For example:
1101 .. _my-reference-label:
1103 Section to cross-reference
1105 --------------------------
1106 This is the text of the section.
1108 It refers to the section itself, see :ref:`my-reference-label`.
1110 The :ref: role would then generate a link to the section, with
1112 the link title being “Section to cross-reference”. This works
1113 just as well when section and reference are in different
1114 source files.
1115 Automatic labels also work with figures. For example:
1117 .. _my-figure:
1119 .. figure:: whatever
1121 Figure caption
1123 In this case, a reference :ref:`my-figure` would insert a
1125 reference to the figure with link text “Figure caption”.
1126 The same works for tables that are given an explicit caption
1128 using the table directive.
1129 · Labels that aren’t placed before a section title can still be
1131 referenced, but you must give the link an explicit title,
1132 using this syntax: :ref:`Link title <label-name>`.
1133 NOTE:
1135 Reference labels must start with an underscore. When refer‐
1136 encing a label, the underscore must be omitted (see examples
1137 above).
1138 Using ref is advised over standard reStructuredText links to
1140 sections (like `Section title`_) because it works across files,
1141 when section headings are changed, will raise warnings if incor‐
1142 rect, and works for all builders that support cross-references.
1143 Cross-referencing documents
1145 New in version 0.6.
1146 There is also a way to directly link to documents:
1149 :doc: Link to the specified document; the document name can be speci‐
1151 fied in absolute or relative fashion. For example, if the ref‐
1152 erence :doc:`parrot` occurs in the document sketches/index, then
1153 the link refers to sketches/parrot. If the reference is
1154 :doc:`/people` or :doc:`../people`, the link refers to people.
1155 If no explicit link text is given (like usual: :doc:`Monty
1157 Python members </people>`), the link caption will be the title
1158 of the given document.
1159 Referencing downloadable files
1161 New in version 0.6.
1162 :download:
1165 This role lets you link to files within your source tree that
1166 are not reST documents that can be viewed, but files that can be
1167 downloaded.
1168 When you use this role, the referenced file is automatically
1170 marked for inclusion in the output when building (obviously, for
1171 HTML output only). All downloadable files are put into the
1172 _downloads subdirectory of the output directory; duplicate file‐
1173 names are handled.
1174 An example:
1176 See :download:`this example script <../example.py>`.
1178 The given filename is usually relative to the directory the cur‐
1180 rent source file is contained in, but if it absolute (starting
1181 with /), it is taken as relative to the top source directory.
1182 The example.py file will be copied to the output directory, and
1184 a suitable link generated to it.
1185 Not to show unavailable download links, you should wrap whole
1187 paragraphs that have this role:
1188 .. only:: builder_html
1190 See :download:`this example script <../example.py>`.
1192 Cross-referencing figures by figure number
1194 New in version 1.3.
1195 Changed in version 1.5: numref role can also refer sections. And num‐
1198 ref allows {name} for the link text.
1199 :numref:
1202 Link to the specified figures, tables, code-blocks and sections;
1203 the standard reST labels are used. When you use this role, it
1204 will insert a reference to the figure with link text by its fig‐
1205 ure number like “Fig. 1.1”.
1206 If an explicit link text is given (as usual: :numref:`Image of
1208 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1209 title of the reference. As placeholders, %s and {number} get
1210 replaced by the figure number and {name} by the figure caption.
1211 If no explicit link text is given, the numfig_format setting is
1212 used as fall-back default.
1213 If numfig is False, figures are not numbered, so this role
1215 inserts not a reference but the label or the link text.
1216 Cross-referencing other items of interest
1218 The following roles do possibly create a cross-reference, but do not
1219 refer to objects:
1220 :envvar:
1222 An environment variable. Index entries are generated. Also
1223 generates a link to the matching envvar directive, if it exists.
1224 :token:
1226 The name of a grammar token (used to create links between pro‐
1227 ductionlist directives).
1228 :keyword:
1230 The name of a keyword in Python. This creates a link to a ref‐
1231 erence label with that name, if it exists.
1232 :option:
1234 A command-line option to an executable program. This generates
1235 a link to a option directive, if it exists.
1236 The following role creates a cross-reference to a term in a glossary:
1238 :term: Reference to a term in a glossary. A glossary is created using
1240 the glossary directive containing a definition list with terms
1241 and definitions. It does not have to be in the same file as the
1242 term markup, for example the Python docs have one global glos‐
1243 sary in the glossary.rst file.
1244 If you use a term that’s not explained in a glossary, you’ll get
1246 a warning during build.
1247 Math
1249 :math: Role for inline math. Use like this:
1250 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1252 :eq: Same as math:numref.
1254 Other semantic markup
1256 The following roles don’t do anything special except formatting the
1257 text in a different style:
1258 :abbr: An abbreviation. If the role content contains a parenthesized
1260 explanation, it will be treated specially: it will be shown in a
1261 tool-tip in HTML, and output only once in LaTeX.
1262 Example: :abbr:`LIFO (last-in, first-out)`.
1264 New in version 0.6.
1266 :command:
1269 The name of an OS-level command, such as rm.
1270 :dfn: Mark the defining instance of a term in the text. (No index
1272 entries are generated.)
1273 :file: The name of a file or directory. Within the contents, you can
1275 use curly braces to indicate a “variable” part, for example:
1276 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1278 In the built documentation, the x will be displayed differently
1280 to indicate that it is to be replaced by the Python minor ver‐
1281 sion.
1282 :guilabel:
1284 Labels presented as part of an interactive user interface should
1285 be marked using guilabel. This includes labels from text-based
1286 interfaces such as those created using curses or other
1287 text-based libraries. Any label used in the interface should be
1288 marked with this role, including button labels, window titles,
1289 field names, menu and menu selection names, and even values in
1290 selection lists.
1291 Changed in version 1.0: An accelerator key for the GUI label can
1293 be included using an ampersand; this will be stripped and dis‐
1294 played underlined in the output (example: :guilabel:`&Cancel`).
1295 To include a literal ampersand, double it.
1296 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1299 may depend on platform- or application-specific conventions.
1300 When there are no relevant conventions, the names of modifier
1301 keys should be spelled out, to improve accessibility for new
1302 users and non-native speakers. For example, an xemacs key
1303 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1304 ence to a specific application or platform, the same sequence
1305 should be marked as :kbd:`Control-x Control-f`.
1306 :mailheader:
1308 The name of an RFC 822-style mail header. This markup does not
1309 imply that the header is being used in an email message, but can
1310 be used to refer to any header of the same “style.” This is
1311 also used for headers defined by the various MIME specifica‐
1312 tions. The header name should be entered in the same way it
1313 would normally be found in practice, with the camel-casing con‐
1314 ventions being preferred where there is more than one common
1315 usage. For example: :mailheader:`Content-Type`.
1316 :makevar:
1318 The name of a make variable.
1319 :manpage:
1321 A reference to a Unix manual page including the section, e.g.
1322 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1323 dering the manpage if manpages_url is defined.
1324 :menuselection:
1326 Menu selections should be marked using the menuselection role.
1327 This is used to mark a complete sequence of menu selections,
1328 including selecting submenus and choosing a specific operation,
1329 or any subsequence of such a sequence. The names of individual
1330 selections should be separated by -->.
1331 For example, to mark the selection “Start > Programs”, use this
1333 markup:
1334 :menuselection:`Start --> Programs`
1336 When including a selection that includes some trailing indica‐
1338 tor, such as the ellipsis some operating systems use to indicate
1339 that the command opens a dialog, the indicator should be omitted
1340 from the selection name.
1341 menuselection also supports ampersand accelerators just like
1343 guilabel.
1344 :mimetype:
1346 The name of a MIME type, or a component of a MIME type (the
1347 major or minor portion, taken alone).
1348 :newsgroup:
1350 The name of a Usenet newsgroup.
1351 Todo
1353 Is this not part of the standard domain?
1354 :program:
1356 The name of an executable program. This may differ from the
1357 file name for the executable for some platforms. In particular,
1358 the .exe (or other) extension should be omitted for Windows pro‐
1359 grams.
1360 :regexp:
1362 A regular expression. Quotes should not be included.
1363 :samp: A piece of literal text, such as code. Within the contents, you
1365 can use curly braces to indicate a “variable” part, as in file.
1366 For example, in :samp:`print 1+{variable}`, the part variable
1367 would be emphasized.
1368 If you don’t need the “variable part” indication, use the stan‐
1370 dard ``code`` instead.
1371 Changed in version 1.8: Allowed to escape curly braces with
1373 backslash
1374 There is also an index role to generate index entries.
1377 The following roles generate external links:
1379 :pep: A reference to a Python Enhancement Proposal. This generates
1381 appropriate index entries. The text “PEP number” is generated;
1382 in the HTML output, this text is a hyperlink to an online copy
1383 of the specified PEP. You can link to a specific section by
1384 saying :pep:`number#anchor`.
1385 :rfc: A reference to an Internet Request for Comments. This generates
1387 appropriate index entries. The text “RFC number” is generated;
1388 in the HTML output, this text is a hyperlink to an online copy
1389 of the specified RFC. You can link to a specific section by
1390 saying :rfc:`number#anchor`.
1391 Note that there are no special roles for including hyperlinks as you
1393 can use the standard reST markup for that purpose.
1394 Substitutions
1396 The documentation system provides three substitutions that are defined
1397 by default. They are set in the build configuration file.
1398 |release|
1400 Replaced by the project release the documentation refers to.
1401 This is meant to be the full version string including
1402 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1403 release.
1404 |version|
1406 Replaced by the project version the documentation refers to.
1407 This is meant to consist only of the major and minor version
1408 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1409 |today|
1411 Replaced by either today’s date (the date on which the document
1412 is read), or the date set in the build configuration file. Nor‐
1413 mally has the format April 14, 2007. Set by today_fmt and
1414 today.
1415 Directives
1417 As previously discussed, a directive is a generic block of explicit
1418 markup. While Docutils provides a number of directives, Sphinx provides
1419 many more and uses directives as one of the primary extension mecha‐
1420 nisms.
1421 See /usage/restructuredtext/domains for roles added by domains.
1423 SEE ALSO:
1425 Refer to the reStructuredText Primer for an overview of the direc‐
1426 tives provided by Docutils.
1427 Table of contents
1429 Since reST does not have facilities to interconnect several documents,
1430 or split documents into multiple output files, Sphinx uses a custom
1431 directive to add relations between the single files the documentation
1432 is made of, as well as tables of contents. The toctree directive is
1433 the central element.
1434 NOTE:
1436 Simple “inclusion” of one file in another can be done with the
1437 include directive.
1438 NOTE:
1440 To create table of contents for current document (.rst file), use
1441 the standard reST contents directive.
1442 .. toctree::
1444 This directive inserts a “TOC tree” at the current location,
1445 using the individual TOCs (including “sub-TOC trees”) of the
1446 documents given in the directive body. Relative document names
1447 (not beginning with a slash) are relative to the document the
1448 directive occurs in, absolute names are relative to the source
1449 directory. A numeric maxdepth option may be given to indicate
1450 the depth of the tree; by default, all levels are included. [1]
1451 Consider this example (taken from the Python docs’ library ref‐
1453 erence index):
1454 .. toctree::
1456 :maxdepth: 2
1457 intro
1459 strings
1460 datatypes
1461 numeric
1462 (many more documents listed here)
1463 This accomplishes two things:
1465 · Tables of contents from all those documents are inserted, with
1467 a maximum depth of two, that means one nested heading. toc‐
1468 tree directives in those documents are also taken into
1469 account.
1470 · Sphinx knows the relative order of the documents intro,
1472 strings and so forth, and it knows that they are children of
1473 the shown document, the library index. From this information
1474 it generates “next chapter”, “previous chapter” and “parent
1475 chapter” links.
1476 Entries
1478 Document titles in the toctree will be automatically read from
1480 the title of the referenced document. If that isn’t what you
1481 want, you can specify an explicit title and target using a simi‐
1482 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1483 syntax). This looks like:
1484 .. toctree::
1486 intro
1488 All about strings <strings>
1489 datatypes
1490 The second line above will link to the strings document, but
1492 will use the title “All about strings” instead of the title of
1493 the strings document.
1494 You can also add external links, by giving an HTTP URL instead
1496 of a document name.
1497 Section numbering
1499 If you want to have section numbers even in HTML output, give
1501 the toplevel toctree a numbered option. For example:
1502 .. toctree::
1504 :numbered:
1505 foo
1507 bar
1508 Numbering then starts at the heading of foo. Sub-toctrees are
1510 automatically numbered (don’t give the numbered flag to those).
1511 Numbering up to a specific depth is also possible, by giving the
1513 depth as a numeric argument to numbered.
1514 Additional options
1516 You can use caption option to provide a toctree caption and you
1518 can use name option to provide implicit target name that can be
1519 referenced by using ref:
1520 .. toctree::
1522 :caption: Table of Contents
1523 :name: mastertoc
1524 foo
1526 If you want only the titles of documents in the tree to show up,
1528 not other headings of the same level, you can use the titlesonly
1529 option:
1530 .. toctree::
1532 :titlesonly:
1533 foo
1535 bar
1536 You can use “globbing” in toctree directives, by giving the glob
1538 flag option. All entries are then matched against the list of
1539 available documents, and matches are inserted into the list
1540 alphabetically. Example:
1541 .. toctree::
1543 :glob:
1544 intro*
1546 recipe/*
1547 *
1548 This includes first all documents whose names start with intro,
1550 then all documents in the recipe folder, then all remaining doc‐
1551 uments (except the one containing the directive, of course.) [2]
1552 The special entry name self stands for the document containing
1554 the toctree directive. This is useful if you want to generate a
1555 “sitemap” from the toctree.
1556 You can use the reversed flag option to reverse the order of the
1558 entries in the list. This can be useful when using the glob flag
1559 option to reverse the ordering of the files. Example:
1560 .. toctree::
1562 :glob:
1563 :reversed:
1564 recipe/*
1566 You can also give a “hidden” option to the directive, like this:
1568 .. toctree::
1570 :hidden:
1571 doc_1
1573 doc_2
1574 This will still notify Sphinx of the document hierarchy, but not
1576 insert links into the document at the location of the directive
1577 – this makes sense if you intend to insert these links yourself,
1578 in a different style, or in the HTML sidebar.
1579 In cases where you want to have only one top-level toctree and
1581 hide all other lower level toctrees you can add the “includehid‐
1582 den” option to the top-level toctree entry:
1583 .. toctree::
1585 :includehidden:
1586 doc_1
1588 doc_2
1589 All other toctree entries can then be eliminated by the “hidden”
1591 option.
1592 In the end, all documents in the source directory (or subdirec‐
1594 tories) must occur in some toctree directive; Sphinx will emit a
1595 warning if it finds a file that is not included, because that
1596 means that this file will not be reachable through standard nav‐
1597 igation.
1598 Use exclude_patterns to explicitly exclude documents or directo‐
1600 ries from building completely. Use the “orphan” metadata to let
1601 a document be built, but notify Sphinx that it is not reachable
1602 via a toctree.
1603 The “master document” (selected by master_doc) is the “root” of
1605 the TOC tree hierarchy. It can be used as the documentation’s
1606 main page, or as a “full table of contents” if you don’t give a
1607 maxdepth option.
1608 Changed in version 0.3: Added “globbing” option.
1610 Changed in version 0.6: Added “numbered” and “hidden” options as
1613 well as external links and support for “self” references.
1614 Changed in version 1.0: Added “titlesonly” option.
1617 Changed in version 1.1: Added numeric argument to “numbered”.
1620 Changed in version 1.2: Added “includehidden” option.
1623 Changed in version 1.3: Added “caption” and “name” option.
1626 Special names
1629 Sphinx reserves some document names for its own use; you should not try
1630 to create documents with these names – it will cause problems.
1631 The special document names (and pages generated for them) are:
1633 · genindex, modindex, search
1635 These are used for the general index, the Python module index, and
1637 the search page, respectively.
1638 The general index is populated with entries from modules, all
1640 index-generating object descriptions, and from index directives.
1641 The Python module index contains one entry per py:module directive.
1643 The search page contains a form that uses the generated JSON search
1645 index and JavaScript to full-text search the generated documents for
1646 search words; it should work on every major browser that supports
1647 modern JavaScript.
1648 · every name beginning with _
1650 Though only few such names are currently used by Sphinx, you should
1652 not create documents or document-containing directories with such
1653 names. (Using _ as a prefix for a custom template directory is
1654 fine.)
1655 WARNING:
1657 Be careful with unusual characters in filenames. Some formats may
1658 interpret these characters in unexpected ways:
1659 · Do not use the colon : for HTML based formats. Links to other
1661 parts may not work.
1662 · Do not use the plus + for the ePub format. Some resources may not
1664 be found.
1665 Paragraph-level markup
1667 These directives create short paragraphs and can be used inside infor‐
1668 mation units as well as normal text.
1669 .. note::
1671 An especially important bit of information about an API that a
1672 user should be aware of when using whatever bit of API the note
1673 pertains to. The content of the directive should be written in
1674 complete sentences and include all appropriate punctuation.
1675 Example:
1677 .. note::
1679 This function is not suitable for sending spam e-mails.
1681 .. warning::
1683 An important bit of information about an API that a user should
1684 be very aware of when using whatever bit of API the warning per‐
1685 tains to. The content of the directive should be written in
1686 complete sentences and include all appropriate punctuation. This
1687 differs from note in that it is recommended over note for infor‐
1688 mation regarding security.
1689 .. versionadded:: version
1691 This directive documents the version of the project which added
1692 the described feature to the library or C API. When this applies
1693 to an entire module, it should be placed at the top of the mod‐
1694 ule section before any prose.
1695 The first argument must be given and is the version in question;
1697 you can add a second argument consisting of a brief explanation
1698 of the change.
1699 Example:
1701 .. versionadded:: 2.5
1703 The *spam* parameter.
1704 Note that there must be no blank line between the directive head
1706 and the explanation; this is to make these blocks visually con‐
1707 tinuous in the markup.
1708 .. versionchanged:: version
1710 Similar to versionadded, but describes when and what changed in
1711 the named feature in some way (new parameters, changed side
1712 effects, etc.).
1713 .. deprecated:: version
1715 Similar to versionchanged, but describes when the feature was
1716 deprecated. An explanation can also be given, for example to
1717 inform the reader what should be used instead. Example:
1718 .. deprecated:: 3.1
1720 Use :func:`spam` instead.
1721 .. seealso::
1723 Many sections include a list of references to module documenta‐
1724 tion or external documents. These lists are created using the
1725 seealso directive.
1726 The seealso directive is typically placed in a section just
1728 before any subsections. For the HTML output, it is shown boxed
1729 off from the main flow of the text.
1730 The content of the seealso directive should be a reST definition
1732 list. Example:
1733 .. seealso::
1735 Module :py:mod:`zipfile`
1737 Documentation of the :py:mod:`zipfile` standard module.
1738 `GNU tar manual, Basic Tar Format <http://link>`_
1740 Documentation for tar archive files, including GNU tar extensions.
1741 There’s also a “short form” allowed that looks like this:
1743 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1745 New in version 0.5: The short form.
1747 .. rubric:: title
1750 This directive creates a paragraph heading that is not used to
1751 create a table of contents node.
1752 NOTE:
1754 If the title of the rubric is “Footnotes” (or the selected
1755 language’s equivalent), this rubric is ignored by the LaTeX
1756 writer, since it is assumed to only contain footnote defini‐
1757 tions and therefore would create an empty heading.
1758 .. centered::
1760 This directive creates a centered boldfaced line of text. Use
1761 it as follows:
1762 .. centered:: LICENSE AGREEMENT
1764 Deprecated since version 1.1: This presentation-only directive
1766 is a legacy from older versions. Use a rst-class directive
1767 instead and add an appropriate style.
1768 .. hlist::
1771 This directive must contain a bullet list. It will transform it
1772 into a more compact list by either distributing more than one
1773 item horizontally, or reducing spacing between items, depending
1774 on the builder.
1775 For builders that support the horizontal distribution, there is
1777 a columns option that specifies the number of columns; it
1778 defaults to 2. Example:
1779 .. hlist::
1781 :columns: 3
1782 * A list of
1784 * short items
1785 * that should be
1786 * displayed
1787 * horizontally
1788 New in version 0.6.
1790 Showing code examples
1793 There are multiple ways to show syntax-highlighted literal code blocks
1794 in Sphinx: using reST doctest blocks; using reST literal blocks,
1795 optionally in combination with the highlight directive; using the
1796 code-block directive; and using the literalinclude directive. Doctest
1797 blocks can only be used to show interactive Python sessions, while the
1798 remaining three can be used for other languages. Of these three, lit‐
1799 eral blocks are useful when an entire document, or at least large sec‐
1800 tions of it, use code blocks with the same syntax and which should be
1801 styled in the same manner. On the other hand, the code-block directive
1802 makes more sense when you want more fine-tuned control over the styling
1803 of each block or when you have a document containing code blocks using
1804 multiple varied syntaxes. Finally, the literalinclude directive is use‐
1805 ful for including entire code files in your documentation.
1806 In all cases, Syntax highlighting is provided by Pygments. When using
1808 literal blocks, this is configured using any highlight directives in
1809 the source file. When a highlight directive is encountered, it is used
1810 until the next highlight directive is encountered. If there is no high‐
1811 light directive in the file, the global highlighting language is used.
1812 This defaults to python but can be configured using the highlight_lan‐
1813 guage config value. The following values are supported:
1814 · none (no highlighting)
1816 · default (similar to python3 but with a fallback to none without warn‐
1818 ing highlighting fails; the default when highlight_language isn’t
1819 set)
1820 · guess (let Pygments guess the lexer based on contents, only works
1822 with certain well-recognizable languages)
1823 · python
1825 · rest
1827 · c
1829 · … and any other lexer alias that Pygments supports
1831 If highlighting with the selected language fails (i.e. Pygments emits
1833 an “Error” token), the block is not highlighted in any way.
1834 IMPORTANT:
1836 The list of lexer aliases supported is tied to the Pygment version.
1837 If you want to ensure consistent highlighting, you should fix your
1838 version of Pygments.
1839 .. highlight:: language
1841 Example:
1842 .. highlight:: c
1844 This language is used until the next highlight directive is
1846 encountered. As discussed previously, language can be any lexer
1847 alias supported by Pygments.
1848 Additional options
1850 Pygments can generate line numbers for code blocks. To enable
1852 this, use the linenothreshold option.
1853 .. highlight:: python
1855 :linenothreshold: 5
1856 This will produce line numbers for all code blocks longer than
1858 five lines.
1859 To ignore minor errors on highlighting, you can specifiy :force:
1861 option.
1862 Changed in version 2.1: :force: option.
1864 .. code-block:: [language]
1867 Example:
1868 .. code-block:: ruby
1870 Some Ruby code.
1872 The directive’s alias name sourcecode works as well. This
1874 directive takes a language name as an argument. It can be any
1875 lexer alias supported by Pygments. If it is not given, the set‐
1876 ting of highlight directive will be used. If not set, high‐
1877 light_language will be used.
1878 Additional options
1880 Pygments can generate line numbers for code blocks. To enable
1882 this for, use the linenos flag option.
1883 .. code-block:: ruby
1885 :linenos:
1886 Some more Ruby code.
1888 The first line number can be selected with the lineno-start
1890 option. If present, linenos flag is automatically activated:
1891 .. code-block:: ruby
1893 :lineno-start: 10
1894 Some more Ruby code, with line numbering starting at 10.
1896 Additionally, an emphasize-lines option can be given to have
1898 Pygments emphasize particular lines:
1899 .. code-block:: python
1901 :emphasize-lines: 3,5
1902 def some_function():
1904 interesting = False
1905 print 'This line is highlighted.'
1906 print 'This one is not...'
1907 print '...but this one is.'
1908 A caption option can be given to show that name before the code
1910 block. A name option can be provided implicit target name that
1911 can be referenced by using ref. For example:
1912 .. code-block:: python
1914 :caption: this.py
1915 :name: this-py
1916 print 'Explicit is better than implicit.'
1918 A dedent option can be given to strip indentation characters
1920 from the code block. For example:
1921 .. code-block:: ruby
1923 :dedent: 4
1924 some ruby code
1926 A force option can ignore minor errors on highlighting.
1928 Changed in version 1.1: The emphasize-lines option has been
1930 added.
1931 Changed in version 1.3: The lineno-start, caption, name and
1934 dedent options have been added.
1935 Changed in version 1.6.6: LaTeX supports the emphasize-lines
1938 option.
1939 Changed in version 2.0: The language argument becomes optional.
1942 Changed in version 2.1: :force: option has been added.
1945 .. literalinclude:: filename
1948 Longer displays of verbatim text may be included by storing the
1949 example text in an external file containing only plain text.
1950 The file may be included using the literalinclude directive. [3]
1951 For example, to include the Python source file example.py, use:
1952 .. literalinclude:: example.py
1954 The file name is usually relative to the current file’s path.
1956 However, if it is absolute (starting with /), it is relative to
1957 the top source directory.
1958 Additional options
1960 Like code-block, the directive supports the linenos flag option
1962 to switch on line numbers, the lineno-start option to select the
1963 first line number, the emphasize-lines option to emphasize par‐
1964 ticular lines, the name option to provide an implicit target
1965 name, the dedent option to strip indentation characters for the
1966 code block, and a language option to select a language different
1967 from the current file’s standard language. In addition, it sup‐
1968 ports the caption option; however, this can be provided with no
1969 argument to use the filename as the caption. Example with
1970 options:
1971 .. literalinclude:: example.rb
1973 :language: ruby
1974 :emphasize-lines: 12,15-18
1975 :linenos:
1976 Tabs in the input are expanded if you give a tab-width option
1978 with the desired tab width.
1979 Include files are assumed to be encoded in the source_encoding.
1981 If the file has a different encoding, you can specify it with
1982 the encoding option:
1983 .. literalinclude:: example.py
1985 :encoding: latin-1
1986 The directive also supports including only parts of the file.
1988 If it is a Python module, you can select a class, function or
1989 method to include using the pyobject option:
1990 .. literalinclude:: example.py
1992 :pyobject: Timer.start
1993 This would only include the code lines belonging to the start()
1995 method in the Timer class within the file.
1996 Alternately, you can specify exactly which lines to include by
1998 giving a lines option:
1999 .. literalinclude:: example.py
2001 :lines: 1,3,5-10,20-
2002 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2004 line.
2005 Another way to control which part of the file is included is to
2007 use the start-after and end-before options (or only one of
2008 them). If start-after is given as a string option, only lines
2009 that follow the first line containing that string are included.
2010 If end-before is given as a string option, only lines that pre‐
2011 cede the first lines containing that string are included. The
2012 start-at and end-at options behave in a similar way, but the
2013 lines containing the matched string are included.
2014 With lines selected using start-after it is still possible to
2016 use lines, the first allowed line having by convention the line
2017 number 1.
2018 When lines have been selected in any of the ways described
2020 above, the line numbers in emphasize-lines refer to those
2021 selected lines, counted consecutively starting at 1.
2022 When specifying particular parts of a file to display, it can be
2024 useful to display the original line numbers. This can be done
2025 using the lineno-match option, which is however allowed only
2026 when the selection consists of contiguous lines.
2027 You can prepend and/or append a line to the included code, using
2029 the prepend and append option, respectively. This is useful
2030 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2031 markers.
2032 If you want to show the diff of the code, you can specify the
2034 old file by giving a diff option:
2035 .. literalinclude:: example.py
2037 :diff: example.py.orig
2038 This shows the diff between example.py and example.py.orig with
2040 unified diff format.
2041 A force option can ignore minor errors on highlighting.
2043 Changed in version 0.4.3: Added the encoding option.
2045 Changed in version 0.6: Added the pyobject, lines, start-after
2048 and end-before options, as well as support for absolute file‐
2049 names.
2050 Changed in version 1.0: Added the prepend, append, and tab-width
2053 options.
2054 Changed in version 1.3: Added the diff, lineno-match, caption,
2057 name, and dedent options.
2058 Changed in version 1.5: Added the start-at, and end-at options.
2061 Changed in version 1.6: With both start-after and lines in use,
2064 the first line as per start-after is considered to be with line
2065 number 1 for lines.
2066 Changed in version 2.1: Added the force option.
2069 Glossary
2072 .. glossary::
2073 This directive must contain a reST definition-list-like markup
2074 with terms and definitions. The definitions will then be refer‐
2075 enceable with the term role. Example:
2076 .. glossary::
2078 environment
2080 A structure where information about all documents under the root is
2081 saved, and used for cross-referencing. The environment is pickled
2082 after the parsing stage, so that successive runs only need to read
2083 and parse new and changed documents.
2084 source directory
2086 The directory which, including its subdirectories, contains all
2087 source files for one Sphinx project.
2088 In contrast to regular definition lists, multiple terms per
2090 entry are allowed, and inline markup is allowed in terms. You
2091 can link to all of the terms. For example:
2092 .. glossary::
2094 term 1
2096 term 2
2097 Definition of both terms.
2098 (When the glossary is sorted, the first term determines the sort
2100 order.)
2101 If you want to specify “grouping key” for general index entries,
2103 you can put a “key” as “term : key”. For example:
2104 .. glossary::
2106 term 1 : A
2108 term 2 : B
2109 Definition of both terms.
2110 Note that “key” is used for grouping key as is. The “key” isn’t
2112 normalized; key “A” and “a” become different groups. The whole
2113 characters in “key” is used instead of a first character; it is
2114 used for “Combining Character Sequence” and “Surrogate Pairs”
2115 grouping key.
2116 In i18n situation, you can specify “localized term : key” even
2118 if original text only have “term” part. In this case, translated
2119 “localized term” will be categorized in “key” group.
2120 New in version 0.6: You can now give the glossary directive a
2122 :sorted: flag that will automatically sort the entries alphabet‐
2123 ically.
2124 Changed in version 1.1: Now supports multiple terms and inline
2127 markup in terms.
2128 Changed in version 1.4: Index key for glossary term should be
2131 considered experimental.
2132 Meta-information markup
2135 .. sectionauthor:: name <email>
2136 Identifies the author of the current section. The argument
2137 should include the author’s name such that it can be used for
2138 presentation and email address. The domain name portion of the
2139 address should be lower case. Example:
2140 .. sectionauthor:: Guido van Rossum <guido@python.org>
2142 By default, this markup isn’t reflected in the output in any way
2144 (it helps keep track of contributions), but you can set the con‐
2145 figuration value show_authors to True to make them produce a
2146 paragraph in the output.
2147 .. codeauthor:: name <email>
2149 The codeauthor directive, which can appear multiple times, names
2150 the authors of the described code, just like sectionauthor names
2151 the author(s) of a piece of documentation. It too only produces
2152 output if the show_authors configuration value is True.
2153 Index-generating markup
2155 Sphinx automatically creates index entries from all object descriptions
2156 (like functions, classes or attributes) like discussed in
2157 /usage/restructuredtext/domains.
2158 However, there is also explicit markup available, to make the index
2160 more comprehensive and enable index entries in documents where informa‐
2161 tion is not mainly contained in information units, such as the language
2162 reference.
2163 .. index:: <entries>
2165 This directive contains one or more index entries. Each entry
2166 consists of a type and a value, separated by a colon.
2167 For example:
2169 .. index::
2171 single: execution; context
2172 module: __main__
2173 module: sys
2174 triple: module; search; path
2175 The execution context
2177 ---------------------
2178 ...
2180 This directive contains five entries, which will be converted to
2182 entries in the generated index which link to the exact location
2183 of the index statement (or, in case of offline media, the corre‐
2184 sponding page number).
2185 Since index directives generate cross-reference targets at their
2187 location in the source, it makes sense to put them before the
2188 thing they refer to – e.g. a heading, as in the example above.
2189 The possible entry types are:
2191 single Creates a single index entry. Can be made a subentry by
2193 separating the subentry text with a semicolon (this nota‐
2194 tion is also used below to describe what entries are cre‐
2195 ated).
2196 pair pair: loop; statement is a shortcut that creates two
2198 index entries, namely loop; statement and statement;
2199 loop.
2200 triple Likewise, triple: module; search; path is a shortcut that
2202 creates three index entries, which are module; search
2203 path, search; path, module and path; module search.
2204 see see: entry; other creates an index entry that refers from
2206 entry to other.
2207 seealso
2209 Like see, but inserts “see also” instead of “see”.
2210 module, keyword, operator, object, exception, statement, builtin
2212 These all create two index entries. For example, module:
2213 hashlib creates the entries module; hashlib and hashlib;
2214 module. (These are Python-specific and therefore depre‐
2215 cated.)
2216 You can mark up “main” index entries by prefixing them with an
2218 exclamation mark. The references to “main” entries are empha‐
2219 sized in the generated index. For example, if two pages contain
2220 .. index:: Python
2222 and one page contains
2224 .. index:: ! Python
2226 then the backlink to the latter page is emphasized among the
2228 three backlinks.
2229 For index directives containing only “single” entries, there is
2231 a shorthand notation:
2232 .. index:: BNF, grammar, syntax, notation
2234 This creates four index entries.
2236 Changed in version 1.1: Added see and seealso types, as well as
2238 marking main entries.
2239 :index:
2242 While the index directive is a block-level markup and links to
2243 the beginning of the next paragraph, there is also a correspond‐
2244 ing role that sets the link target directly where it is used.
2245 The content of the role can be a simple phrase, which is then
2247 kept in the text and used as an index entry. It can also be a
2248 combination of text and index entry, styled like with explicit
2249 targets of cross-references. In that case, the “target” part
2250 can be a full entry as described for the directive above. For
2251 example:
2252 This is a normal reST :index:`paragraph` that contains several
2254 :index:`index entries <pair: index; entry>`.
2255 New in version 1.1.
2257 Including content based on tags
2260 .. only:: <expression>
2261 Include the content of the directive only if the expression is
2262 true. The expression should consist of tags, like this:
2263 .. only:: html and draft
2265 Undefined tags are false, defined tags (via the -t command-line
2267 option or within conf.py, see here) are true. Boolean expres‐
2268 sions, also using parentheses (like html and (latex or draft))
2269 are supported.
2270 The format and the name of the current builder (html, latex or
2272 text) are always set as a tag [4]. To make the distinction
2273 between format and name explicit, they are also added with the
2274 prefix format_ and builder_, e.g. the epub builder defines the
2275 tags html, epub, format_html and builder_epub.
2276 These standard tags are set after the configuration file is
2278 read, so they are not available there.
2279 All tags must follow the standard Python identifier syntax as
2281 set out in the Identifiers and keywords documentation. That is,
2282 a tag expression may only consist of tags that conform to the
2283 syntax of Python variables. In ASCII, this consists of the
2284 uppercase and lowercase letters A through Z, the underscore _
2285 and, except for the first character, the digits 0 through 9.
2286 New in version 0.6.
2288 Changed in version 1.2: Added the name of the builder and the
2291 prefixes.
2292 WARNING:
2295 This directive is designed to control only content of docu‐
2296 ment. It could not control sections, labels and so on.
2297 Tables
2299 Use reStructuredText tables, i.e. either
2300 · grid table syntax (ref),
2302 · simple table syntax (ref),
2304 · csv-table syntax,
2306 · or list-table syntax.
2308 The table directive serves as optional wrapper of the grid and simple
2310 syntaxes.
2311 They work fine in HTML output, however there are some gotchas when
2313 using tables in LaTeX: the column width is hard to determine correctly
2314 automatically. For this reason, the following directive exists:
2315 .. tabularcolumns:: column spec
2317 This directive gives a “column spec” for the next table occur‐
2318 ring in the source file. The spec is the second argument to the
2319 LaTeX tabulary package’s environment (which Sphinx uses to
2320 translate tables). It can have values like
2321 |l|l|l|
2323 which means three left-adjusted, nonbreaking columns. For col‐
2325 umns with longer text that should automatically be broken, use
2326 either the standard p{width} construct, or tabulary’s automatic
2327 specifiers:
2328 ┌──┬────────────────────────────┐
2330 │L │ flush left column with │
2331 │ │ automatic width │
2332 ├──┼────────────────────────────┤
2333 │R │ flush right column with │
2334 │ │ automatic width │
2335 ├──┼────────────────────────────┤
2336 │C │ centered column with auto‐ │
2337 │ │ matic width │
2338 └──┴────────────────────────────┘
2339 │J │ justified column with │
2343 │ │ automatic width │
2344 └──┴────────────────────────────┘
2345 The automatic widths of the LRCJ columns are attributed by tabu‐
2347 lary in proportion to the observed shares in a first pass where
2348 the table cells are rendered at their natural “horizontal”
2349 widths.
2350 By default, Sphinx uses a table layout with J for every column.
2352 New in version 0.3.
2354 Changed in version 1.6: Merged cells may now contain multiple
2357 paragraphs and are much better handled, thanks to custom Sphinx
2358 LaTeX macros. This novel situation motivated the switch to J
2359 specifier and not L by default.
2360 HINT:
2363 Sphinx actually uses T specifier having done \newcolumn‐
2364 type{T}{J}. To revert to previous default, insert \newcolum‐
2365 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2366 A frequent issue with tabulary is that columns with little
2368 contents are “squeezed”. The minimal column width is a tabu‐
2369 lary parameter called \tymin. You may set it globally in the
2370 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2371 Else, use the tabularcolumns directive with an explicit
2373 p{40pt} (for example) for that column. You may use also l
2374 specifier but this makes the task of setting column widths
2375 more difficult if some merged cell intersects that column.
2376 WARNING:
2378 Tables with more than 30 rows are rendered using longtable,
2379 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2380 ifiers do not work for these tables.
2381 Tables that contain list-like elements such as object
2383 descriptions, blockquotes or any kind of lists cannot be set
2384 out of the box with tabulary. They are therefore set with the
2385 standard LaTeX tabular (or longtable) environment if you
2386 don’t give a tabularcolumns directive. If you do, the table
2387 will be set with tabulary but you must use the p{width} con‐
2388 struct (or Sphinx’s \X and \Y specifiers described below) for
2389 the columns containing these elements.
2390 Literal blocks do not work with tabulary at all, so tables
2392 containing a literal block are always set with tabular. The
2393 verbatim environment used for literal blocks only works in
2394 p{width} (and \X or \Y) columns, hence Sphinx generates such
2395 column specs for tables containing literal blocks.
2396 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2398 backslash in the specifier letter). It is like p{width} with the
2399 width set to a fraction a/b of the current line width. You can
2400 use it in the tabularcolumns (it is not a problem if some LaTeX
2401 macro is also called \X.)
2402 It is not needed for b to be the total number of columns, nor
2404 for the sum of the fractions of the \X specifiers to add up to
2405 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2406 the table will occupy 80% of the line width, the first of its
2407 three columns having the same width as the sum of the next two.
2408 This is used by the :widths: option of the table directive.
2410 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2412 a decimal argument, such has \Y{0.15}: this would have the same
2413 effect as \X{3}{20}.
2414 Changed in version 1.6: Merged cells from complex grid tables
2416 (either multi-row, multi-column, or both) now allow blockquotes,
2417 lists, literal blocks, … as do regular cells.
2418 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2420 \Y{f} and tabulary’s columns.
2421 NOTE:
2424 tabularcolumns conflicts with :widths: option of table direc‐
2425 tives. If both are specified, :widths: option will be
2426 ignored.
2427 Math
2429 The input language for mathematics is LaTeX markup. This is the
2430 de-facto standard for plain-text math notation and has the added advan‐
2431 tage that no further translation is necessary when building LaTeX out‐
2432 put.
2433 Keep in mind that when you put math markup in Python docstrings read by
2435 autodoc, you either have to double all backslashes, or use Python raw
2436 strings (r"raw").
2437 .. math::
2439 Directive for displayed math (math that takes the whole line for
2440 itself).
2441 The directive supports multiple equations, which should be sepa‐
2443 rated by a blank line:
2444 .. math::
2446 (a + b)^2 = a^2 + 2ab + b^2
2448 (a - b)^2 = a^2 - 2ab + b^2
2450 In addition, each single equation is set within a split environ‐
2452 ment, which means that you can have multiple aligned lines in an
2453 equation, aligned at & and separated by \\:
2454 .. math::
2456 (a + b)^2 &= (a + b)(a + b) \\
2458 &= a^2 + 2ab + b^2
2459 For more details, look into the documentation of the AmSMath
2461 LaTeX package.
2462 When the math is only one line of text, it can also be given as
2464 a directive argument:
2465 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2467 Normally, equations are not numbered. If you want your equation
2469 to get a number, use the label option. When given, it selects
2470 an internal label for the equation, by which it can be
2471 cross-referenced, and causes an equation number to be issued.
2472 See eq for an example. The numbering style depends on the out‐
2473 put format.
2474 There is also an option nowrap that prevents any wrapping of the
2476 given math in a math environment. When you give this option,
2477 you must make sure yourself that the math is properly set up.
2478 For example:
2479 .. math::
2481 :nowrap:
2482 \begin{eqnarray}
2484 y & = & ax^2 + bx + c \\
2485 f(x) & = & x^2 + 2xy + y^2
2486 \end{eqnarray}
2487 SEE ALSO:
2489 math-support
2491 Rendering options for math with HTML builders.
2492 latex_engine
2494 Explains how to configure LaTeX builder to support Unicode
2495 literals in math mark-up.
2496 Grammar production displays
2498 Special markup is available for displaying the productions of a formal
2499 grammar. The markup is simple and does not attempt to model all
2500 aspects of BNF (or any derived forms), but provides enough to allow
2501 context-free grammars to be displayed in a way that causes uses of a
2502 symbol to be rendered as hyperlinks to the definition of the symbol.
2503 There is this directive:
2504 .. productionlist:: [name]
2506 This directive is used to enclose a group of productions. Each
2507 production is given on a single line and consists of a name,
2508 separated by a colon from the following definition. If the def‐
2509 inition spans multiple lines, each continuation line must begin
2510 with a colon placed at the same column as in the first line.
2511 The argument to productionlist serves to distinguish different
2513 sets of production lists that belong to different grammars.
2514 Blank lines are not allowed within productionlist directive
2516 arguments.
2517 The definition can contain token names which are marked as
2519 interpreted text (e.g. sum ::= `integer` "+" `integer`) – this
2520 generates cross-references to the productions of these tokens.
2521 Outside of the production list, you can reference to token pro‐
2522 ductions using token.
2523 Note that no further reST parsing is done in the production, so
2525 that you don’t have to escape * or | characters.
2526 The following is an example taken from the Python Reference Manual:
2528 .. productionlist::
2530 try_stmt: try1_stmt | try2_stmt
2531 try1_stmt: "try" ":" `suite`
2532 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2533 : ["else" ":" `suite`]
2534 : ["finally" ":" `suite`]
2535 try2_stmt: "try" ":" `suite`
2536 : "finally" ":" `suite`
2537
2539 [1] The LaTeX writer only refers the maxdepth option of first toctree
2540 directive in the document.
2541 [2] A note on available globbing syntax: you can use the standard
2543 shell constructs *, ?, [...] and [!...] with the feature that
2544 these all don’t match slashes. A double star ** can be used to
2545 match any sequence of characters including slashes.
2546 [3] There is a standard .. include directive, but it raises errors if
2548 the file is not found. This one only emits a warning.
2549 [4] For most builders name and format are the same. At the moment only
2551 builders derived from the html builder distinguish between the
2552 builder format and the builder name.
2553 Note that the current builder tag is not available in conf.py, it
2555 is only available after the builder is initialized.
2556 Field Lists
2558 As previously discussed, field lists are sequences of fields marked up
2559 like this:
2560 :fieldname: Field content
2562 Sphinx provides custom behavior for bibliographic fields compared to
2564 docutils.
2565 File-wide metadata
2567 A field list near the top of a file is normally parsed by docutils as
2568 the docinfo which is generally used to record the author, date of pub‐
2569 lication and other metadata. However, in Sphinx, a field list preced‐
2570 ing any other markup is moved from the docinfo to the Sphinx environ‐
2571 ment as document metadata and is not displayed in the output; a field
2572 list appearing after the document title will be part of the docinfo as
2573 normal and will be displayed in the output.
2574 At the moment, these metadata fields are recognized:
2576 tocdepth
2578 The maximum depth for a table of contents of this file.
2579 :tocdepth: 2
2581 New in version 0.4.
2583 nocomments
2586 If set, the web application won’t display a comment form for a
2587 page generated from this source file.
2588 :nocomments:
2590 orphan If set, warnings about this file not being included in any toc‐
2592 tree will be suppressed.
2593 :orphan:
2595 New in version 1.0.
2597 Domains
2600 New in version 1.0.
2601 Originally, Sphinx was conceived for a single project, the documenta‐
2604 tion of the Python language. Shortly afterwards, it was made available
2605 for everyone as a documentation tool, but the documentation of Python
2606 modules remained deeply built in – the most fundamental directives,
2607 like function, were designed for Python objects. Since Sphinx has
2608 become somewhat popular, interest developed in using it for many dif‐
2609 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2610 markup (like in this documentation).
2611 While this was always possible, it is now much easier to easily support
2613 documentation of projects using different programming languages or even
2614 ones not supported by the main Sphinx distribution, by providing a
2615 domain for every such purpose.
2616 A domain is a collection of markup (reStructuredText directives and
2618 roles) to describe and link to objects belonging together, e.g. ele‐
2619 ments of a programming language. Directive and role names in a domain
2620 have names like domain:name, e.g. py:function. Domains can also pro‐
2621 vide custom indices (like the Python Module Index).
2622 Having domains means that there are no naming problems when one set of
2624 documentation wants to refer to e.g. C++ and Python classes. It also
2625 means that extensions that support the documentation of whole new lan‐
2626 guages are much easier to write.
2627 This section describes what the domains that are included with Sphinx
2629 provide. The domain API is documented as well, in the section
2630 domain-api.
2631 Basic Markup
2633 Most domains provide a number of object description directives, used to
2634 describe specific objects provided by modules. Each directive requires
2635 one or more signatures to provide basic information about what is being
2636 described, and the content should be the description. The basic ver‐
2637 sion makes entries in the general index; if no index entry is desired,
2638 you can give the directive option flag :noindex:. An example using a
2639 Python domain directive:
2640 .. py:function:: spam(eggs)
2642 ham(eggs)
2643 Spam or ham the foo.
2645 This describes the two Python functions spam and ham. (Note that when
2647 signatures become too long, you can break them if you add a backslash
2648 to lines that are continued in the next line. Example:
2649 .. py:function:: filterwarnings(action, message='', category=Warning, \
2651 module='', lineno=0, append=False)
2652 :noindex:
2653 (This example also shows how to use the :noindex: flag.)
2655 The domains also provide roles that link back to these object descrip‐
2657 tions. For example, to link to one of the functions described in the
2658 example above, you could say
2659 The function :py:func:`spam` does a similar thing.
2661 As you can see, both directive and role names contain the domain name
2663 and the directive name.
2664 Default Domain
2666 For documentation describing objects from solely one domain, authors
2668 will not have to state again its name at each directive, role, etc…
2669 after having specified a default. This can be done either via the con‐
2670 fig value primary_domain or via this directive:
2671 .. default-domain:: name
2673 Select a new default domain. While the primary_domain selects a
2674 global default, this only has an effect within the same file.
2675 If no other default is selected, the Python domain (named py) is the
2677 default one, mostly for compatibility with documentation written for
2678 older versions of Sphinx.
2679 Directives and roles that belong to the default domain can be mentioned
2681 without giving the domain name, i.e.
2682 .. function:: pyfunc()
2684 Describes a Python function.
2686 Reference to :func:`pyfunc`.
2688 Cross-referencing syntax
2690 For cross-reference roles provided by domains, the same facilities
2691 exist as for general cross-references. See xref-syntax.
2692 In short:
2694 · You may supply an explicit title and reference target: :role:`title
2696 <target>` will refer to target, but the link text will be title.
2697 · If you prefix the content with !, no reference/hyperlink will be cre‐
2699 ated.
2700 · If you prefix the content with ~, the link text will only be the last
2702 component of the target. For example, :py:meth:`~Queue.Queue.get`
2703 will refer to Queue.Queue.get but only display get as the link text.
2704 The Python Domain
2706 The Python domain (name py) provides the following directives for mod‐
2707 ule declarations:
2708 .. py:module:: name
2710 This directive marks the beginning of the description of a mod‐
2711 ule (or package submodule, in which case the name should be
2712 fully qualified, including the package name). It does not cre‐
2713 ate content (like e.g. py:class does).
2714 This directive will also cause an entry in the global module
2716 index.
2717 options
2719 :platform: platforms (comma separated list)
2721 Indicate platforms which the module is available (if it
2722 is available on all platforms, the option should be omit‐
2723 ted). The keys are short identifiers; examples that are
2724 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2725 is important to use a key which has already been used
2726 when applicable.
2727 :synopsis: purpose (text)
2729 Consist of one sentence describing the module’s purpose –
2730 it is currently only used in the Global Module Index.
2731 :deprecated: (no argument)
2733 Mark a module as deprecated; it will be designated as
2734 such in various locations then.
2735 .. py:currentmodule:: name
2737 This directive tells Sphinx that the classes, functions etc.
2738 documented from here are in the given module (like py:module),
2739 but it will not create index entries, an entry in the Global
2740 Module Index, or a link target for py:mod. This is helpful in
2741 situations where documentation for things in a module is spread
2742 over multiple files or sections – one location has the py:module
2743 directive, the others only py:currentmodule.
2744 The following directives are provided for module and class contents:
2746 .. py:function:: name(parameters)
2748 Describes a module-level function. The signature should include
2749 the parameters as given in the Python function definition, see
2750 Python Signatures. For example:
2751 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2753 For methods you should use py:method.
2755 The description normally includes information about the parame‐
2757 ters required and how they are used (especially whether mutable
2758 objects passed as parameters are modified), side effects, and
2759 possible exceptions.
2760 This information can (in any py directive) optionally be given
2762 in a structured form, see Info field lists.
2763 options
2765 :async: (no value)
2767 Indicate the function is an async function.
2768 New in version 2.1.
2770 .. py:data:: name
2773 Describes global data in a module, including both variables and
2774 values used as “defined constants.” Class and object attributes
2775 are not documented using this environment.
2776 .. py:exception:: name
2778 Describes an exception class. The signature can, but need not
2779 include parentheses with constructor arguments.
2780 .. py:class:: name
2782 .. py:class:: name(parameters)
2784 Describes a class. The signature can optionally include paren‐
2785 theses with parameters which will be shown as the constructor
2786 arguments. See also Python Signatures.
2787 Methods and attributes belonging to the class should be placed
2789 in this directive’s body. If they are placed outside, the sup‐
2790 plied name should contain the class name so that cross-refer‐
2791 ences still work. Example:
2792 .. py:class:: Foo
2794 .. py:method:: quux()
2796 -- or --
2798 .. py:class:: Bar
2800 .. py:method:: Bar.quux()
2802 The first way is the preferred one.
2804 .. py:attribute:: name
2806 Describes an object data attribute. The description should
2807 include information about the type of the data to be expected
2808 and whether it may be changed directly.
2809 .. py:method:: name(parameters)
2811 Describes an object method. The parameters should not include
2812 the self parameter. The description should include similar
2813 information to that described for function. See also Python
2814 Signatures and Info field lists.
2815 options
2817 :abstractmethod: (no value)
2819 Indicate the method is an abstract method.
2820 New in version 2.1.
2822 :async: (no value)
2825 Indicate the method is an async method.
2826 New in version 2.1.
2828 :classmethod: (no value)
2831 Indicate the method is a class method.
2832 New in version 2.1.
2834 :property: (no value)
2837 Indicate the method is a property.
2838 New in version 2.1.
2840 :staticmethod: (no value)
2843 Indicate the method is a static method.
2844 New in version 2.1.
2846 .. py:staticmethod:: name(parameters)
2849 Like py:method, but indicates that the method is a static
2850 method.
2851 New in version 0.4.
2853 .. py:classmethod:: name(parameters)
2856 Like py:method, but indicates that the method is a class method.
2857 New in version 0.6.
2859 .. py:decorator:: name
2862 .. py:decorator:: name(parameters)
2864 Describes a decorator function. The signature should represent
2865 the usage as a decorator. For example, given the functions
2866 def removename(func):
2868 func.__name__ = ''
2869 return func
2870 def setnewname(name):
2872 def decorator(func):
2873 func.__name__ = name
2874 return func
2875 return decorator
2876 the descriptions should look like this:
2878 .. py:decorator:: removename
2880 Remove name of the decorated function.
2882 .. py:decorator:: setnewname(name)
2884 Set name of the decorated function to *name*.
2886 (as opposed to .. py:decorator:: removename(func).)
2888 There is no py:deco role to link to a decorator that is marked
2890 up with this directive; rather, use the py:func role.
2891 .. py:decoratormethod:: name
2893 .. py:decoratormethod:: name(signature)
2895 Same as py:decorator, but for decorators that are methods.
2896 Refer to a decorator method using the py:meth role.
2898 Python Signatures
2900 Signatures of functions, methods and class constructors can be given
2901 like they would be written in Python.
2902 Default values for optional arguments can be given (but if they contain
2904 commas, they will confuse the signature parser). Python 3-style argu‐
2905 ment annotations can also be given as well as return type annotations:
2906 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
2908 For functions with optional parameters that don’t have default values
2910 (typically functions implemented in C extension modules without keyword
2911 argument support), you can use brackets to specify the optional parts:
2912 compile(source[, filename[, symbol]])
2914 It is customary to put the opening bracket before the comma.
2916 Info field lists
2918 New in version 0.4.
2919 Inside Python object description directives, reST field lists with
2922 these fields are recognized and formatted nicely:
2923 · param, parameter, arg, argument, key, keyword: Description of a
2925 parameter.
2926 · type: Type of a parameter. Creates a link if possible.
2928 · raises, raise, except, exception: That (and when) a specific excep‐
2930 tion is raised.
2931 · var, ivar, cvar: Description of a variable.
2933 · vartype: Type of a variable. Creates a link if possible.
2935 · returns, return: Description of the return value.
2937 · rtype: Return type. Creates a link if possible.
2939 NOTE:
2941 In current release, all var, ivar and cvar are represented as “Vari‐
2942 able”. There is no difference at all.
2943 The field names must consist of one of these keywords and an argument
2945 (except for returns and rtype, which do not need an argument). This is
2946 best explained by an example:
2947 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
2949 Send a message to a recipient
2951 :param str sender: The person sending the message
2953 :param str recipient: The recipient of the message
2954 :param str message_body: The body of the message
2955 :param priority: The priority of the message, can be a number 1-5
2956 :type priority: integer or None
2957 :return: the message id
2958 :rtype: int
2959 :raises ValueError: if the message_body exceeds 160 characters
2960 :raises TypeError: if the message_body is not a basestring
2961 This will render like this:
2963 send_message(sender, recipient, message_body[, priority=1])
2965 Send a message to a recipient
2966 Parameters
2968 · sender (str) – The person sending the message
2970 · recipient (str) – The recipient of the message
2972 · message_body (str) – The body of the message
2974 · priority (integer or None) – The priority of the
2976 message, can be a number 1-5
2977 Returns
2979 the message id
2980 Return type
2982 int
2983 Raises
2985 · ValueError – if the message_body exceeds 160 charac‐
2987 ters
2988 · TypeError – if the message_body is not a basestring
2990 It is also possible to combine parameter type and description, if the
2992 type is a single word, like this:
2993 :param int priority: The priority of the message, can be a number 1-5
2995 New in version 1.5.
2997 Container types such as lists and dictionaries can be linked automati‐
3000 cally using the following syntax:
3001 :type priorities: list(int)
3003 :type priorities: list[int]
3004 :type mapping: dict(str, int)
3005 :type mapping: dict[str, int]
3006 :type point: tuple(float, float)
3007 :type point: tuple[float, float]
3008 Multiple types in a type field will be linked automatically if sepa‐
3010 rated by the word “or”:
3011 :type an_arg: int or None
3013 :vartype a_var: str or int
3014 :rtype: float or str
3015 Cross-referencing Python objects
3017 The following roles refer to objects in modules and are possibly hyper‐
3018 linked if a matching identifier is found:
3019 :py:mod:
3021 Reference a module; a dotted name may be used. This should also
3022 be used for package names.
3023 :py:func:
3025 Reference a Python function; dotted names may be used. The role
3026 text needs not include trailing parentheses to enhance readabil‐
3027 ity; they will be added automatically by Sphinx if the add_func‐
3028 tion_parentheses config value is True (the default).
3029 :py:data:
3031 Reference a module-level variable.
3032 :py:const:
3034 Reference a “defined” constant. This may be a Python variable
3035 that is not intended to be changed.
3036 :py:class:
3038 Reference a class; a dotted name may be used.
3039 :py:meth:
3041 Reference a method of an object. The role text can include the
3042 type name and the method name; if it occurs within the descrip‐
3043 tion of a type, the type name can be omitted. A dotted name may
3044 be used.
3045 :py:attr:
3047 Reference a data attribute of an object.
3048 :py:exc:
3050 Reference an exception. A dotted name may be used.
3051 :py:obj:
3053 Reference an object of unspecified type. Useful e.g. as the
3054 default_role.
3055 New in version 0.4.
3057 The name enclosed in this markup can include a module name and/or a
3060 class name. For example, :py:func:`filter` could refer to a function
3061 named filter in the current module, or the built-in function of that
3062 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3063 function in the foo module.
3064 Normally, names in these roles are searched first without any further
3066 qualification, then with the current module name prepended, then with
3067 the current module and class name (if any) prepended. If you prefix
3068 the name with a dot, this order is reversed. For example, in the docu‐
3069 mentation of Python’s codecs module, :py:func:`open` always refers to
3070 the built-in function, while :py:func:`.open` refers to codecs.open().
3071 A similar heuristic is used to determine whether the name is an
3073 attribute of the currently documented class.
3074 Also, if the name is prefixed with a dot, and no exact match is found,
3076 the target is taken as a suffix and all object names with that suffix
3077 are searched. For example, :py:meth:`.TarFile.close` references the
3078 tarfile.TarFile.close() function, even if the current module is not
3079 tarfile. Since this can get ambiguous, if there is more than one pos‐
3080 sible match, you will get a warning from Sphinx.
3081 Note that you can combine the ~ and . prefixes:
3083 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3084 method, but the visible link caption will only be close().
3085 The C Domain
3087 The C domain (name c) is suited for documentation of C API.
3088 .. c:function:: function prototype
3090 Describes a C function. The signature should be given as in C,
3091 e.g.:
3092 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3094 This is also used to describe function-like preprocessor macros.
3096 The names of the arguments should be given so they may be used
3097 in the description.
3098 Note that you don’t have to backslash-escape asterisks in the
3100 signature, as it is not parsed by the reST inliner.
3101 .. c:member:: declaration
3103 Describes a C struct member. Example signature:
3104 .. c:member:: PyObject* PyTypeObject.tp_bases
3106 The text of the description should include the range of values
3108 allowed, how the value should be interpreted, and whether the
3109 value can be changed. References to structure members in text
3110 should use the member role.
3111 .. c:macro:: name
3113 Describes a “simple” C macro. Simple macros are macros which
3114 are used for code expansion, but which do not take arguments so
3115 cannot be described as functions. This is a simple C-language
3116 #define. Examples of its use in the Python documentation
3117 include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
3118 .. c:type:: name
3120 Describes a C type (whether defined by a typedef or struct). The
3121 signature should just be the type name.
3122 .. c:var:: declaration
3124 Describes a global C variable. The signature should include the
3125 type, such as:
3126 .. c:var:: PyObject* PyClass_Type
3128 Cross-referencing C constructs
3130 The following roles create cross-references to C-language constructs if
3131 they are defined in the documentation:
3132 :c:func:
3134 Reference a C-language function. Should include trailing paren‐
3135 theses.
3136 :c:member:
3138 Reference a C-language member of a struct.
3139 :c:macro:
3141 Reference a “simple” C macro, as defined above.
3142 :c:type:
3144 Reference a C-language type.
3145 :c:data:
3147 Reference a C-language variable.
3148 The C++ Domain
3150 The C++ domain (name cpp) supports documenting C++ projects.
3151 Directives for Declaring Entities
3153 The following directives are available. All declarations can start with
3154 a visibility statement (public, private or protected).
3155 .. cpp:class:: class specifier
3157 .. cpp:struct:: class specifier
3159 Describe a class/struct, possibly with specification of inheri‐
3160 tance, e.g.,:
3161 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3163 The difference between cpp:class and cpp:struct is only cos‐
3165 metic: the prefix rendered in the output, and the specifier
3166 shown in the index.
3167 The class can be directly declared inside a nested scope, e.g.,:
3169 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3171 A class template can be declared:
3173 .. cpp:class:: template<typename T, std::size_t N> std::array
3175 or with a line break:
3177 .. cpp:class:: template<typename T, std::size_t N> \
3179 std::array
3180 Full and partial template specialisations can be declared:
3182 .. cpp:class:: template<> \
3184 std::array<bool, 256>
3185 .. cpp:class:: template<typename T> \
3187 std::array<T, 42>
3188 New in version 2.0: The cpp:struct directive.
3190 .. cpp:function:: (member) function prototype
3193 Describe a function or member function, e.g.,:
3194 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3196 A function with parameters and types.
3198 .. cpp:function:: bool myMethod(int, double)
3200 A function with unnamed parameters.
3202 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3204 An overload for the indexing operator.
3206 .. cpp:function:: operator bool() const
3208 A casting operator.
3210 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3212 A constexpr function.
3214 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3216 A copy constructor with default implementation.
3218 Function templates can also be described:
3220 .. cpp:function:: template<typename U> \
3222 void print(U &&u)
3223 and function template specialisations:
3225 .. cpp:function:: template<> \
3227 void print(int i)
3228 .. cpp:member:: (member) variable declaration
3230 .. cpp:var:: (member) variable declaration
3232 Describe a variable or member variable, e.g.,:
3233 .. cpp:member:: std::string MyClass::myMember
3235 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3237 .. cpp:member:: int a = 42
3239 Variable templates can also be described:
3241 .. cpp:member:: template<class T> \
3243 constexpr T pi = T(3.1415926535897932385)
3244 .. cpp:type:: typedef declaration
3246 .. cpp:type:: name
3248 .. cpp:type:: type alias declaration
3250 Describe a type as in a typedef declaration, a type alias decla‐
3251 ration, or simply the name of a type with unspecified type,
3252 e.g.,:
3253 .. cpp:type:: std::vector<int> MyList
3255 A typedef-like declaration of a type.
3257 .. cpp:type:: MyContainer::const_iterator
3259 Declaration of a type alias with unspecified type.
3261 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3263 Declaration of a type alias.
3265 A type alias can also be templated:
3267 .. cpp:type:: template<typename T> \
3269 MyContainer = std::vector<T>
3270 The example are rendered as follows.
3272 typedef std::vector<int> MyList
3274 A typedef-like declaration of a type.
3275 type MyContainer::const_iterator
3277 Declaration of a type alias with unspecified type.
3278 using MyType = std::unordered_map<int, std::string>
3280 Declaration of a type alias.
3281 template<typename T> using MyContainer = std::vector<T>
3283 .. cpp:enum:: unscoped enum declaration
3285 .. cpp:enum-struct:: scoped enum declaration
3287 .. cpp:enum-class:: scoped enum declaration
3289 Describe a (scoped) enum, possibly with the underlying type
3290 specified. Any enumerators declared inside an unscoped enum
3291 will be declared both in the enum scope and in the parent scope.
3292 Examples:
3293 .. cpp:enum:: MyEnum
3295 An unscoped enum.
3297 .. cpp:enum:: MySpecificEnum : long
3299 An unscoped enum with specified underlying type.
3301 .. cpp:enum-class:: MyScopedEnum
3303 A scoped enum.
3305 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3307 A scoped enum with non-default visibility, and with a specified
3309 underlying type.
3310 .. cpp:enumerator:: name
3312 .. cpp:enumerator:: name = constant
3314 Describe an enumerator, optionally with its value defined,
3315 e.g.,:
3316 .. cpp:enumerator:: MyEnum::myEnumerator
3318 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3320 .. cpp:union:: name
3322 Describe a union.
3323 New in version 1.8.
3325 .. cpp:concept:: template-parameter-list name
3328 WARNING:
3330 The support for concepts is experimental. It is based on the
3331 current draft standard and the Concepts Technical Specifica‐
3332 tion. The features may change as they evolve.
3333 Describe a concept. It must have exactly 1 template parameter
3335 list. The name may be a nested name. Example:
3336 .. cpp:concept:: template<typename It> std::Iterator
3338 Proxy to an element of a notional sequence that can be compared,
3340 indirected, or incremented.
3341 **Notation**
3343 .. cpp:var:: It r
3345 An lvalue.
3347 **Valid Expressions**
3349 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3351 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3352 :cpp:expr:`r` is incrementable.
3353 This will render as follows:
3355 template<typename It> concept std::Iterator
3357 Proxy to an element of a notional sequence that can be
3358 compared, indirected, or incremented.
3359 Notation
3361 It r An lvalue.
3363 Valid Expressions
3365 · *r, when r is dereferenceable.
3367 · ++r, with return type It&, when r is incrementable.
3369 New in version 1.5.
3371 Options
3374 Some directives support options:
3375 · :noindex:, see Basic Markup.
3377 · :tparam-line-spec:, for templated declarations. If specified, each
3379 template parameter will be rendered on a separate line.
3380 New in version 1.6.
3382 Anonymous Entities
3385 C++ supports anonymous namespaces, classes, enums, and unions. For the
3386 sake of documentation they must be given some name that starts with @,
3387 e.g., @42 or @data. These names can also be used in cross-references
3388 and (type) expressions, though nested symbols will be found even when
3389 omitted. The @... name will always be rendered as [anonymous] (possi‐
3390 bly as a link).
3391 Example:
3393 .. cpp:class:: Data
3395 .. cpp:union:: @data
3397 .. cpp:var:: int a
3399 .. cpp:var:: double b
3401 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3403 This will be rendered as:
3405 class Data
3407 union [anonymous]
3409 int a
3411 double b
3413 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3415 New in version 1.8.
3417 Aliasing Declarations
3420 Sometimes it may be helpful list declarations elsewhere than their main
3421 documentation, e.g., when creating a synopsis of a class interface.
3422 The following directive can be used for this purpose.
3423 .. cpp:alias:: name or function signature
3425 Insert one or more alias declarations. Each entity can be speci‐
3426 fied as they can in the cpp:any role. If the name of a function
3427 is given (as opposed to the complete signature), then all over‐
3428 loads of the function will be listed.
3429 For example:
3431 .. cpp:alias:: Data::a
3433 overload_example::C::f
3434 becomes
3436 int a
3438 void f(double d) const
3440 void f(double d)
3442 void f(int i)
3444 void f()
3446 whereas:
3448 .. cpp:alias:: void overload_example::C::f(double d) const
3450 void overload_example::C::f(double d)
3451 becomes
3453 void f(double d) const
3455 void f(double d)
3457 New in version 2.0.
3459 Constrained Templates
3462 WARNING:
3463 The support for concepts is experimental. It is based on the current
3464 draft standard and the Concepts Technical Specification. The fea‐
3465 tures may change as they evolve.
3466 NOTE:
3468 Sphinx does not currently support requires clauses.
3469 Placeholders
3471 Declarations may use the name of a concept to introduce constrained
3472 template parameters, or the keyword auto to introduce unconstrained
3473 template parameters:
3474 .. cpp:function:: void f(auto &&arg)
3476 A function template with a single unconstrained template parameter.
3478 .. cpp:function:: void f(std::Iterator it)
3480 A function template with a single template parameter, constrained by the
3482 Iterator concept.
3483 Template Introductions
3485 Simple constrained function or class templates can be declared with a
3486 template introduction instead of a template parameter list:
3487 .. cpp:function:: std::Iterator{It} void advance(It &it)
3489 A function template with a template parameter constrained to be an
3491 Iterator.
3492 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3494 A class template with a template parameter constrained to be
3496 LessThanComparable.
3497 They are rendered as follows.
3499 std::Iterator{It} void advance(It &it)
3501 A function template with a template parameter constrained to be
3502 an Iterator.
3503 std::LessThanComparable{T} class MySortedContainer
3505 A class template with a template parameter constrained to be
3506 LessThanComparable.
3507 Note however that no checking is performed with respect to parameter
3509 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3510 tion even though it would not be valid C++.
3511 Inline Expressions and Types
3513 :cpp:expr:
3514 :cpp:texpr:
3516 Insert a C++ expression or type either as inline code (cpp:expr)
3517 or inline text (cpp:texpr). For example:
3518 .. cpp:var:: int a = 42
3520 .. cpp:function:: int f(int i)
3522 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
3524 A type: :cpp:expr:`const MySortedContainer<int>&`
3526 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
3527 will be rendered as follows:
3529 int a = 42
3531 int f(int i)
3533 An expression: a * f(a) (or as text: a * f(a)).
3535 A type: const MySortedContainer<int>& (or as text const MySort‐
3537 edContainer<int>&).
3538 New in version 1.7: The cpp:expr role.
3540 New in version 1.8: The cpp:texpr role.
3543 Namespacing
3546 Declarations in the C++ domain are as default placed in global scope.
3547 The current scope can be changed using three namespace directives.
3548 They manage a stack declarations where cpp:namespace resets the stack
3549 and changes a given scope.
3550 The cpp:namespace-push directive changes the scope to a given inner
3552 scope of the current one.
3553 The cpp:namespace-pop directive undoes the most recent cpp:names‐
3555 pace-push directive.
3556 .. cpp:namespace:: scope specification
3558 Changes the current scope for the subsequent objects to the
3559 given scope, and resets the namespace directive stack. Note
3560 that the namespace does not need to correspond to C++ names‐
3561 paces, but can end in names of classes, e.g.,:
3562 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3564 All subsequent objects will be defined as if their name were
3566 declared with the scope prepended. The subsequent cross-refer‐
3567 ences will be searched for starting in the current scope.
3568 Using NULL, 0, or nullptr as the scope will change to global
3570 scope.
3571 A namespace declaration can also be templated, e.g.,:
3573 .. cpp:class:: template<typename T> \
3575 std::vector
3576 .. cpp:namespace:: template<typename T> std::vector
3578 .. cpp:function:: std::size_t size() const
3580 declares size as a member function of the class template
3582 std::vector. Equivalently this could have been declared using:
3583 .. cpp:class:: template<typename T> \
3585 std::vector
3586 .. cpp:function:: std::size_t size() const
3588 or:
3590 .. cpp:class:: template<typename T> \
3592 std::vector
3593 .. cpp:namespace-push:: scope specification
3595 Change the scope relatively to the current scope. For example,
3596 after:
3597 .. cpp:namespace:: A::B
3599 .. cpp:namespace-push:: C::D
3601 the current scope will be A::B::C::D.
3603 New in version 1.4.
3605 .. cpp:namespace-pop::
3608 Undo the previous cpp:namespace-push directive (not just pop a
3609 scope). For example, after:
3610 .. cpp:namespace:: A::B
3612 .. cpp:namespace-push:: C::D
3614 .. cpp:namespace-pop::
3616 the current scope will be A::B (not A::B::C).
3618 If no previous cpp:namespace-push directive has been used, but
3620 only a cpp:namespace directive, then the current scope will be
3621 reset to global scope. That is, .. cpp:namespace:: A::B is
3622 equivalent to:
3623 .. cpp:namespace:: nullptr
3625 .. cpp:namespace-push:: A::B
3627 New in version 1.4.
3629 Info field lists
3632 The C++ directives support the following info fields (see also Info
3633 field lists):
3634 · param, parameter, arg, argument: Description of a parameter.
3636 · tparam: Description of a template parameter.
3638 · returns, return: Description of a return value.
3640 · throws, throw, exception: Description of a possibly thrown exception.
3642 Cross-referencing
3644 These roles link to the given declaration types:
3645 :cpp:any:
3647 :cpp:class:
3649 :cpp:struct:
3651 :cpp:func:
3653 :cpp:member:
3655 :cpp:var:
3657 :cpp:type:
3659 :cpp:concept:
3661 :cpp:enum:
3663 :cpp:enumerator:
3665 Reference a C++ declaration by name (see below for details).
3666 The name must be properly qualified relative to the position of
3667 the link.
3668 New in version 2.0: The cpp:struct role as alias for the
3670 cpp:class role.
3671 Note on References with Templates Parameters/Arguments
3674 These roles follow the Sphinx xref-syntax rules. This means
3676 care must be taken when referencing a (partial) template spe‐
3677 cialization, e.g. if the link looks like this:
3678 :cpp:class:`MyClass<int>`. This is interpreted as a link to
3679 int with a title of MyClass. In this case, escape the open‐
3680 ing angle bracket with a backslash, like this:
3681 :cpp:class:`MyClass\<int>`.
3682 When a custom title is not needed it may be useful to use the
3684 roles for inline expressions, cpp:expr and cpp:texpr, where
3685 angle brackets do not need escaping.
3686 Declarations without template parameters and template arguments
3688 For linking to non-templated declarations the name must be a nested
3689 name, e.g., f or MyClass::f.
3690 Overloaded (member) functions
3692 When a (member) function is referenced using just its name, the refer‐
3693 ence will point to an arbitrary matching overload. The cpp:any and
3694 cpp:func roles use an alternative format, which simply is a complete
3695 function declaration. This will resolve to the exact matching over‐
3696 load. As example, consider the following class declaration:
3697 class C
3699 void f(double d) const
3701 void f(double d)
3703 void f(int i)
3705 void f()
3707 References using the cpp:func role:
3709 · Arbitrary overload: C::f, C::f()
3711 · Also arbitrary overload: C::f(), C::f()
3713 · Specific overload: void C::f(), void C::f()
3715 · Specific overload: void C::f(int), void C::f(int)
3717 · Specific overload: void C::f(double), void C::f(double)
3719 · Specific overload: void C::f(double) const, void C::f(double) const
3721 Note that the add_function_parentheses configuration variable does not
3723 influence specific overload references.
3724 Templated declarations
3726 Assume the following declarations.
3727 class Wrapper
3729 template<typename TOuter> class Outer
3731 template<typename TInner> class Inner
3733 In general the reference must include the template parameter declara‐
3735 tions, and template arguments for the prefix of qualified names. For
3736 example:
3737 · template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
3739 Wrapper::Outer)
3740 · template\<typename TOuter> template\<typename TInner> Wrap‐
3742 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
3743 name TInner> Wrapper::Outer<TOuter>::Inner)
3744 Currently the lookup only succeed if the template parameter identifiers
3746 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
3747 will not work.
3748 As a shorthand notation, if a template parameter list is omitted, then
3750 the lookup will assume either a primary template or a non-template, but
3751 not a partial template specialisation. This means the following refer‐
3752 ences work as well:
3753 · Wrapper::Outer (Wrapper::Outer)
3755 · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
3757 · template\<typename TInner> Wrapper::Outer::Inner (template<typename
3759 TInner> Wrapper::Outer::Inner)
3760 (Full) Template Specialisations
3762 Assume the following declarations.
3763 template<typename TOuter> class Outer
3765 template<typename TInner> class Inner
3767 template<> class Outer<int>
3769 template<typename TInner> class Inner
3771 template<> class Inner<bool>
3773 In general the reference must include a template parameter list for
3775 each template argument list. The full specialisation above can there‐
3776 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
3777 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
3778 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
3779 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
3780 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
3781 Partial Template Specialisations
3783 Assume the following declaration.
3784 template<typename T> class Outer<T *>
3786 References to partial specialisations must always include the template
3788 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
3789 template<typename T> Outer<T*>). Currently the lookup only succeed if
3790 the template parameter identifiers are equal strings.
3791 Configuration Variables
3793 See cpp-config.
3794 The Standard Domain
3796 The so-called “standard” domain collects all markup that doesn’t war‐
3797 rant a domain of its own. Its directives and roles are not prefixed
3798 with a domain name.
3799 The standard domain is also where custom object descriptions, added
3801 using the add_object_type() API, are placed.
3802 There is a set of directives allowing documenting command-line pro‐
3804 grams:
3805 .. option:: name args, name args, ...
3807 Describes a command line argument or switch. Option argument
3808 names should be enclosed in angle brackets. Examples:
3809 .. option:: dest_dir
3811 Destination directory.
3813 .. option:: -m <module>, --module <module>
3815 Run a module as a script.
3817 The directive will create cross-reference targets for the given
3819 options, referenceable by option (in the example case, you’d use
3820 something like :option:`dest_dir`, :option:`-m`, or
3821 :option:`--module`).
3822 cmdoption directive is a deprecated alias for the option direc‐
3824 tive.
3825 .. envvar:: name
3827 Describes an environment variable that the documented code or
3828 program uses or defines. Referenceable by envvar.
3829 .. program:: name
3831 Like py:currentmodule, this directive produces no output.
3832 Instead, it serves to notify Sphinx that all following option
3833 directives document options for the program called name.
3834 If you use program, you have to qualify the references in your
3836 option roles by the program name, so if you have the following
3837 situation
3838 .. program:: rm
3840 .. option:: -r
3842 Work recursively.
3844 .. program:: svn
3846 .. option:: -r revision
3848 Specify the revision to work upon.
3850 then :option:`rm -r` would refer to the first option, while
3852 :option:`svn -r` would refer to the second one.
3853 The program name may contain spaces (in case you want to docu‐
3855 ment subcommands like svn add and svn commit separately).
3856 New in version 0.5.
3858 There is also a very generic object description directive, which is not
3861 tied to any domain:
3862 .. describe:: text
3864 .. object:: text
3866 This directive produces the same formatting as the specific ones
3867 provided by domains, but does not create index entries or
3868 cross-referencing targets. Example:
3869 .. describe:: PAPER
3871 You can set this variable to select a paper size.
3873 The JavaScript Domain
3875 The JavaScript domain (name js) provides the following directives:
3876 .. js:module:: name
3878 This directive sets the module name for object declarations that
3879 follow after. The module name is used in the global module index
3880 and in cross references. This directive does not create an
3881 object heading like py:class would, for example.
3882 By default, this directive will create a linkable entity and
3884 will cause an entry in the global module index, unless the noin‐
3885 dex option is specified. If this option is specified, the
3886 directive will only update the current module name.
3887 New in version 1.6.
3889 .. js:function:: name(signature)
3892 Describes a JavaScript function or method. If you want to
3893 describe arguments as optional use square brackets as documented
3894 for Python signatures.
3895 You can use fields to give more details about arguments and
3897 their expected types, errors which may be thrown by the func‐
3898 tion, and the value being returned:
3899 .. js:function:: $.getJSON(href, callback[, errback])
3901 :param string href: An URI to the location of the resource.
3903 :param callback: Gets called with the object.
3904 :param errback:
3905 Gets called in case the request fails. And a lot of other
3906 text so we need multiple lines.
3907 :throws SomeError: For whatever reason in that case.
3908 :returns: Something.
3909 This is rendered as:
3911 $.getJSON(href, callback[, errback])
3913 Arguments
3915 · href (string) – An URI to the location of the
3917 resource.
3918 · callback – Gets called with the object.
3920 · errback – Gets called in case the request
3922 fails. And a lot of other text so we need
3923 multiple lines.
3924 Throws SomeError – For whatever reason in that case.
3926 Returns
3928 Something.
3929 .. js:method:: name(signature)
3931 This directive is an alias for js:function, however it describes
3932 a function that is implemented as a method on a class object.
3933 New in version 1.6.
3935 .. js:class:: name
3938 Describes a constructor that creates an object. This is basi‐
3939 cally like a function but will show up with a class prefix:
3940 .. js:class:: MyAnimal(name[, age])
3942 :param string name: The name of the animal
3944 :param number age: an optional age for the animal
3945 This is rendered as:
3947 class MyAnimal(name[, age])
3949 Arguments
3951 · name (string) – The name of the animal
3953 · age (number) – an optional age for the animal
3955 .. js:data:: name
3957 Describes a global variable or constant.
3958 .. js:attribute:: object.name
3960 Describes the attribute name of object.
3961 These roles are provided to refer to the described objects:
3963 :js:mod:
3965 :js:func:
3967 :js:meth:
3969 :js:class:
3971 :js:data:
3973 :js:attr:
3975 The reStructuredText domain
3977 The reStructuredText domain (name rst) provides the following direc‐
3978 tives:
3979 .. rst:directive:: name
3981 Describes a reST directive. The name can be a single directive
3982 name or actual directive syntax (.. prefix and :: suffix) with
3983 arguments that will be rendered differently. For example:
3984 .. rst:directive:: foo
3986 Foo description.
3988 .. rst:directive:: .. bar:: baz
3990 Bar description.
3992 will be rendered as:
3994 .. foo::
3996 Foo description.
3997 .. bar:: baz
3999 Bar description.
4000 .. rst:directive:option:: name
4002 Describes an option for reST directive. The name can be a sin‐
4003 gle option name or option name with arguments which separated
4004 with colon (:). For example:
4005 .. rst:directive:: toctree
4007 .. rst:directive:option:: caption: caption of ToC
4009 .. rst:directive:option:: glob
4011 will be rendered as:
4013 .. toctree::
4015 :caption: caption of ToC
4017 :glob:
4019 options
4021 :type: description of argument (text)
4023 Describe the type of option value.
4024 For example:
4026 .. rst:directive:: toctree
4028 .. rst:directive:option:: maxdepth
4030 :type: integer or no value
4031 New in version 2.1.
4033 .. rst:role:: name
4036 Describes a reST role. For example:
4037 .. rst:role:: foo
4039 Foo description.
4041 will be rendered as:
4043 :foo: Foo description.
4045 These roles are provided to refer to the described objects:
4047 :rst:dir:
4049 :rst:role:
4051 The Math Domain
4053 The math domain (name math) provides the following roles:
4054 :math:numref:
4056 Role for cross-referencing equations defined by math directive
4057 via their label. Example:
4058 .. math:: e^{i\pi} + 1 = 0
4060 :label: euler
4061 Euler's identity, equation :math:numref:`euler`, was elected one of the
4063 most beautiful mathematical formulas.
4064 New in version 1.8.
4066 More domains
4069 The sphinx-contrib repository contains more domains available as exten‐
4070 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4071 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4072 dqn, Go, Jinja, Operation, and Scala.
4073
4075 Markdown is a lightweight markup language with a simplistic plain text
4076 formatting syntax. It exists in many syntactically different flavors.
4077 To support Markdown-based documentation, Sphinx can use recommonmark.
4078 recommonmark is a Docutils bridge to CommonMark-py, a Python package
4079 for parsing the CommonMark Markdown flavor.
4080 Configuration
4082 To configure your Sphinx project for Markdown support, proceed as fol‐
4083 lows:
4084 1. Install the Markdown parser recommonmark:
4086 pip install --upgrade recommonmark
4088 NOTE:
4090 The configuration as explained here requires recommonmark version
4091 0.5.0 or later.
4092 2. Add recommonmark to the list of configured extensions:
4094 extensions = ['recommonmark']
4096 Changed in version 1.8: Version 1.8 deprecates and version 3.0
4098 removes the source_parsers configuration variable that was used by
4099 older recommonmark versions.
4100 3. If you want to use Markdown files with extensions other than .md,
4103 adjust the source_suffix variable. The following example configures
4104 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4105 down:
4106 source_suffix = {
4108 '.rst': 'restructuredtext',
4109 '.txt': 'markdown',
4110 '.md': 'markdown',
4111 }
4112 4. You can further configure recommonmark to allow custom syntax that
4114 standard CommonMark doesn’t support. Read more in the recommonmark
4115 documentation.
4116
4118 The configuration directory must contain a file named conf.py. This
4119 file (containing Python code) is called the “build configuration file”
4120 and contains (almost) all configuration needed to customize Sphinx
4121 input and output behavior.
4122 An optional file docutils.conf can be added to the configuration
4123 directory to adjust Docutils configuration if not otherwise overrid‐
4124 den or set by Sphinx.
4125 The configuration file is executed as Python code at build time (using
4127 execfile(), and with the current directory set to its containing direc‐
4128 tory), and therefore can execute arbitrarily complex code. Sphinx then
4129 reads simple names from the file’s namespace as its configuration.
4130 Important points to note:
4132 · If not otherwise documented, values must be strings, and their
4134 default is the empty string.
4135 · The term “fully-qualified name” refers to a string that names an
4137 importable Python object inside a module; for example, the FQN
4138 "sphinx.builders.Builder" means the Builder class in the
4139 sphinx.builders module.
4140 · Remember that document names use / as the path separator and don’t
4142 contain the file name extension.
4143 · Since conf.py is read as a Python file, the usual rules apply for
4145 encodings and Unicode support.
4146 · The contents of the config namespace are pickled (so that Sphinx can
4148 find out when configuration changes), so it may not contain unpick‐
4149 leable values – delete them from the namespace with del if appropri‐
4150 ate. Modules are removed automatically, so you don’t need to del
4151 your imports after use.
4152 · There is a special object named tags available in the config file.
4154 It can be used to query and change the tags (see tags). Use
4155 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4156 change. Only tags set via the -t command-line option or via
4157 tags.add('tag') can be queried using tags.has('tag'). Note that the
4158 current builder tag is not available in conf.py, as it is created
4159 after the builder is initialized.
4160 Project information
4162 project
4163 The documented project’s name.
4164 author The author name(s) of the document. The default value is
4166 'unknown'.
4167 copyright
4169 A copyright statement in the style '2008, Author Name'.
4170 version
4172 The major project version, used as the replacement for |ver‐
4173 sion|. For example, for the Python documentation, this may be
4174 something like 2.6.
4175 release
4177 The full project version, used as the replacement for |release|
4178 and e.g. in the HTML templates. For example, for the Python
4179 documentation, this may be something like 2.6.0rc1.
4180 If you don’t need the separation provided between version and
4182 release, just set them both to the same value.
4183 General configuration
4185 extensions
4186 A list of strings that are module names of extensions. These can
4187 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4188 ones.
4189 Note that you can extend sys.path within the conf file if your
4191 extensions live in another directory – but make sure you use
4192 absolute paths. If your extension path is relative to the con‐
4193 figuration directory, use os.path.abspath() like so:
4194 import sys, os
4196 sys.path.append(os.path.abspath('sphinxext'))
4198 extensions = ['extname']
4200 That way, you can load an extension called extname from the sub‐
4202 directory sphinxext.
4203 The configuration file itself can be an extension; for that, you
4205 only need to provide a setup() function in it.
4206 source_suffix
4208 The file extensions of source files. Sphinx considers the files
4209 with this suffix as sources. The value can be a dictionary map‐
4210 ping file extensions to file types. For example:
4211 source_suffix = {
4213 '.rst': 'restructuredtext',
4214 '.txt': 'restructuredtext',
4215 '.md': 'markdown',
4216 }
4217 By default, Sphinx only supports 'restructuredtext' file type.
4219 You can add a new file type using source parser extensions.
4220 Please read a document of the extension to know which file type
4221 the extension supports.
4222 The value may also be a list of file extensions: then Sphinx
4224 will consider that they all map to the 'restructuredtext' file
4225 type.
4226 Default is {'.rst': 'restructuredtext'}.
4228 NOTE:
4230 file extensions have to start with a dot (e.g. .rst).
4231 Changed in version 1.3: Can now be a list of extensions.
4233 Changed in version 1.8: Support file type mapping
4236 source_encoding
4239 The encoding of all reST source files. The recommended encod‐
4240 ing, and the default value, is 'utf-8-sig'.
4241 New in version 0.5: Previously, Sphinx accepted only UTF-8
4243 encoded sources.
4244 source_parsers
4247 If given, a dictionary of parser classes for different source
4248 suffices. The keys are the suffix, the values can be either a
4249 class or a string giving a fully-qualified name of a parser
4250 class. The parser class can be either docutils.parsers.Parser
4251 or sphinx.parsers.Parser. Files with a suffix that is not in
4252 the dictionary will be parsed with the default reStructuredText
4253 parser.
4254 For example:
4256 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4258 NOTE:
4260 Refer to /usage/markdown for more information on using Mark‐
4261 down with Sphinx.
4262 New in version 1.3.
4264 Deprecated since version 1.8: Now Sphinx provides an API
4267 Sphinx.add_source_parser() to register a source parser. Please
4268 use it instead.
4269 master_doc
4272 The document name of the “master” document, that is, the docu‐
4273 ment that contains the root toctree directive. Default is
4274 'index'.
4275 Changed in version 2.0: The default is changed to 'index' from
4277 'contents'.
4278 exclude_patterns
4281 A list of glob-style patterns that should be excluded when look‐
4282 ing for source files. [1] They are matched against the source
4283 file names relative to the source directory, using slashes as
4284 directory separators on all platforms.
4285 Example patterns:
4287 · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4289 entry in unused_docs)
4290 · 'library/xml' – ignores the library/xml directory
4292 · 'library/xml*' – ignores all files and directories starting
4294 with library/xml
4295 · '**/.svn' – ignores all .svn directories
4297 exclude_patterns is also consulted when looking for static files
4299 in html_static_path and html_extra_path.
4300 New in version 1.0.
4302 templates_path
4305 A list of paths that contain extra templates (or templates that
4306 overwrite builtin/theme-specific templates). Relative paths are
4307 taken as relative to the configuration directory.
4308 Changed in version 1.3: As these files are not meant to be
4310 built, they are automatically added to exclude_patterns.
4311 template_bridge
4314 A string with the fully-qualified name of a callable (or simply
4315 a class) that returns an instance of TemplateBridge. This
4316 instance is then used to render HTML documents, and possibly the
4317 output of other builders (currently the changes builder). (Note
4318 that the template bridge must be made theme-aware if HTML themes
4319 are to be used.)
4320 rst_epilog
4322 A string of reStructuredText that will be included at the end of
4323 every source file that is read. This is a possible place to add
4324 substitutions that should be available in every file (another
4325 being rst_prolog). An example:
4326 rst_epilog = """
4328 .. |psf| replace:: Python Software Foundation
4329 """
4330 New in version 0.6.
4332 rst_prolog
4335 A string of reStructuredText that will be included at the begin‐
4336 ning of every source file that is read. This is a possible
4337 place to add substitutions that should be available in every
4338 file (another being rst_epilog). An example:
4339 rst_prolog = """
4341 .. |psf| replace:: Python Software Foundation
4342 """
4343 New in version 1.0.
4345 primary_domain
4348 The name of the default domain. Can also be None to disable a
4349 default domain. The default is 'py'. Those objects in other
4350 domains (whether the domain name is given explicitly, or
4351 selected by a default-domain directive) will have the domain
4352 name explicitly prepended when named (e.g., when the default
4353 domain is C, Python functions will be named “Python function”,
4354 not just “function”).
4355 New in version 1.0.
4357 default_role
4360 The name of a reST role (builtin or Sphinx extension) to use as
4361 the default role, that is, for text marked up `like this`. This
4362 can be set to 'py:obj' to make `filter` a cross-reference to the
4363 Python function “filter”. The default is None, which doesn’t
4364 reassign the default role.
4365 The default role can always be set within individual documents
4367 using the standard reST default-role directive.
4368 New in version 0.4.
4370 keep_warnings
4373 If true, keep warnings as “system message” paragraphs in the
4374 built documents. Regardless of this setting, warnings are
4375 always written to the standard error stream when sphinx-build is
4376 run.
4377 The default is False, the pre-0.5 behavior was to always keep
4379 them.
4380 New in version 0.5.
4382 suppress_warnings
4385 A list of warning types to suppress arbitrary warning messages.
4386 Sphinx supports following warning types:
4388 · app.add_node
4390 · app.add_directive
4392 · app.add_role
4394 · app.add_generic_role
4396 · app.add_source_parser
4398 · download.not_readable
4400 · image.not_readable
4402 · ref.term
4404 · ref.ref
4406 · ref.numref
4408 · ref.keyword
4410 · ref.option
4412 · ref.citation
4414 · ref.footnote
4416 · ref.doc
4418 · ref.python
4420 · misc.highlighting_failure
4422 · toc.secnum
4424 · epub.unknown_project_files
4426 · autosectionlabel.*
4428 You can choose from these types.
4430 Now, this option should be considered experimental.
4432 New in version 1.4.
4434 Changed in version 1.5: Added misc.highlighting_failure
4437 Changed in version 1.5.1: Added epub.unknown_project_files
4440 Changed in version 1.6: Added ref.footnote
4443 Changed in version 2.1: Added autosectionlabel.*
4446 needs_sphinx
4449 If set to a major.minor version string like '1.1', Sphinx will
4450 compare it with its version and refuse to build if it is too
4451 old. Default is no requirement.
4452 New in version 1.0.
4454 Changed in version 1.4: also accepts micro version string
4457 needs_extensions
4460 This value can be a dictionary specifying version requirements
4461 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4462 contrib.something': '1.5'}. The version strings should be in
4463 the form major.minor. Requirements do not have to be specified
4464 for all extensions, only for those you want to check.
4465 This requires that the extension specifies its version to Sphinx
4467 (see dev-extensions for how to do that).
4468 New in version 1.3.
4470 manpages_url
4473 A URL to cross-reference manpage directives. If this is defined
4474 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4475 role will link to <https://manpages.debian.org/man(1)>. The pat‐
4476 terns available are:
4477 · page - the manual page (man)
4479 · section - the manual section (1)
4481 · path - the original manual page and section specified
4483 (man(1))
4484 This also supports manpages specified as man.1.
4486 NOTE:
4488 This currently affects only HTML writers but could be
4489 expanded in the future.
4490 New in version 1.7.
4492 nitpicky
4495 If true, Sphinx will warn about all references where the target
4496 cannot be found. Default is False. You can activate this mode
4497 temporarily using the -n command-line switch.
4498 New in version 1.0.
4500 nitpick_ignore
4503 A list of (type, target) tuples (by default empty) that should
4504 be ignored when generating warnings in “nitpicky mode”. Note
4505 that type should include the domain name if present. Example
4506 entries would be ('py:func', 'int') or ('envvar',
4507 'LD_LIBRARY_PATH').
4508 New in version 1.1.
4510 numfig If true, figures, tables and code-blocks are automatically num‐
4513 bered if they have a caption. The numref role is enabled.
4514 Obeyed so far only by HTML and LaTeX builders. Default is False.
4515 NOTE:
4517 The LaTeX builder always assigns numbers whether this option
4518 is enabled or not.
4519 New in version 1.3.
4521 numfig_format
4524 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4525 tion' to strings that are used for format of figure numbers. As
4526 a special character, %s will be replaced to figure number.
4527 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4529 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4530 New in version 1.3.
4532 numfig_secnum_depth
4535 · if set to 0, figures, tables and code-blocks are continuously
4537 numbered starting at 1.
4538 · if 1 (default) numbers will be x.1, x.2, … with x the section
4540 number (top level sectioning; no x. if no section). This nat‐
4541 urally applies only if section numbering has been activated
4542 via the :numbered: option of the toctree directive.
4543 · 2 means that numbers will be x.y.1, x.y.2, … if located in a
4545 sub-section (but still x.1, x.2, … if located directly under a
4546 section and 1, 2, … if not in any top level section.)
4547 · etc…
4549 New in version 1.3.
4551 Changed in version 1.7: The LaTeX builder obeys this setting (if
4554 numfig is set to True).
4555 smartquotes
4558 If true, the Docutils Smart Quotes transform, originally based
4559 on SmartyPants (limited to English) and currently applying to
4560 many languages, will be used to convert quotes and dashes to
4561 typographically correct entities. Default: True.
4562 New in version 1.6.6: It replaces deprecated
4564 html_use_smartypants. It applies by default to all builders
4565 except man and text (see smartquotes_excludes.)
4566 A docutils.conf file located in the configuration directory (or
4569 a global ~/.docutils file) is obeyed unconditionally if it deac‐
4570 tivates smart quotes via the corresponding Docutils option. But
4571 if it activates them, then smartquotes does prevail.
4572 smartquotes_action
4574 This string, for use with Docutils 0.14 or later, customizes the
4575 Smart Quotes transform. See the file smartquotes.py at the
4576 Docutils repository for details. The default 'qDe' educates
4577 normal quote characters ", ', em- and en-Dashes ---, --, and
4578 ellipses ....
4579 New in version 1.6.6.
4581 smartquotes_excludes
4584 This is a dict whose default is:
4585 {'languages': ['ja'], 'builders': ['man', 'text']}
4587 Each entry gives a sufficient condition to ignore the
4589 smartquotes setting and deactivate the Smart Quotes transform.
4590 Accepted keys are as above 'builders' or 'languages'. The val‐
4591 ues are lists.
4592 NOTE:
4594 Currently, in case of invocation of make with multiple tar‐
4595 gets, the first target name is the only one which is tested
4596 against the 'builders' entry and it decides for all. Also, a
4597 make text following make html needs to be issued in the form
4598 make text O="-E" to force re-parsing of source files, as the
4599 cached ones are already transformed. On the other hand the
4600 issue does not arise with direct usage of sphinx-build as it
4601 caches (in its default usage) the parsed source files in per
4602 builder locations.
4603 HINT:
4605 An alternative way to effectively deactivate (or customize)
4606 the smart quotes for a given builder, for example latex, is
4607 to use make this way:
4608 make latex O="-D smartquotes_action="
4610 This can follow some make html with no problem, in contrast
4612 to the situation from the prior note. It requires Docutils
4613 0.14 or later.
4614 New in version 1.6.6.
4616 tls_verify
4619 If true, Sphinx verifies server certifications. Default is
4620 True.
4621 New in version 1.5.
4623 tls_cacerts
4626 A path to a certification file of CA or a path to directory
4627 which contains the certificates. This also allows a dictionary
4628 mapping hostname to the path to certificate file. The certifi‐
4629 cates are used to verify server certifications.
4630 New in version 1.5.
4632 TIP:
4635 Sphinx uses requests as a HTTP library internally. There‐
4636 fore, Sphinx refers a certification file on the directory
4637 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
4638 erts not set.
4639 today
4641 today_fmt
4643 These values determine how to format the current date, used as
4644 the replacement for |today|.
4645 · If you set today to a non-empty value, it is used.
4647 · Otherwise, the current time is formatted using time.strftime()
4649 and the format given in today_fmt.
4650 The default is now today and a today_fmt of '%B %d, %Y' (or, if
4652 translation is enabled with language, an equivalent format for
4653 the selected locale).
4654 highlight_language
4656 The default language to highlight source code in. The default
4657 is 'python3'. The value should be a valid Pygments lexer name,
4658 see code-examples for more details.
4659 New in version 0.5.
4661 Changed in version 1.4: The default is now 'default'. It is sim‐
4664 ilar to 'python3'; it is mostly a superset of 'python' but it
4665 fallbacks to 'none' without warning if failed. 'python3' and
4666 other languages will emit warning if failed. If you prefer
4667 Python 2 only highlighting, you can set it back to 'python'.
4668 highlight_options
4671 A dictionary of options that modify how the lexer specified by
4672 highlight_language generates highlighted source code. These are
4673 lexer-specific; for the options understood by each, see the
4674 Pygments documentation.
4675 New in version 1.3.
4677 pygments_style
4680 The style name to use for Pygments highlighting of source code.
4681 If not set, either the theme’s default style or 'sphinx' is
4682 selected for HTML output.
4683 Changed in version 0.3: If the value is a fully-qualified name
4685 of a custom Pygments style class, this is then used as custom
4686 style.
4687 add_function_parentheses
4690 A boolean that decides whether parentheses are appended to func‐
4691 tion and method role text (e.g. the content of :func:`input`) to
4692 signify that the name is callable. Default is True.
4693 add_module_names
4695 A boolean that decides whether module names are prepended to all
4696 object names (for object types where a “module” of some kind is
4697 defined), e.g. for py:function directives. Default is True.
4698 show_authors
4700 A boolean that decides whether codeauthor and sectionauthor
4701 directives produce any output in the built files.
4702 modindex_common_prefix
4704 A list of prefixes that are ignored for sorting the Python mod‐
4705 ule index (e.g., if this is set to ['foo.'], then foo.bar is
4706 shown under B, not F). This can be handy if you document a
4707 project that consists of a single package. Works only for the
4708 HTML builder currently. Default is [].
4709 New in version 0.6.
4711 trim_footnote_reference_space
4714 Trim spaces before footnote references that are necessary for
4715 the reST parser to recognize the footnote, but do not look too
4716 nice in the output.
4717 New in version 0.6.
4719 trim_doctest_flags
4722 If true, doctest flags (comments looking like # doctest: FLAG,
4723 ...) at the ends of lines and <BLANKLINE> markers are removed
4724 for all code blocks showing interactive Python sessions (i.e.
4725 doctests). Default is True. See the extension doctest for more
4726 possibilities of including doctests.
4727 New in version 1.0.
4729 Changed in version 1.1: Now also removes <BLANKLINE>.
4732 Options for internationalization
4735 These options influence Sphinx’s Native Language Support. See the doc‐
4736 umentation on intl for details.
4737 language
4739 The code for the language the docs are written in. Any text
4740 automatically generated by Sphinx will be in that language.
4741 Also, Sphinx will try to substitute individual paragraphs from
4742 your documents with the translation sets obtained from
4743 locale_dirs. Sphinx will search language-specific figures named
4744 by figure_language_filename and substitute them for original
4745 figures. In the LaTeX builder, a suitable language will be
4746 selected as an option for the Babel package. Default is None,
4747 which means that no translation will be done.
4748 New in version 0.5.
4750 Changed in version 1.4: Support figure substitution
4753 Currently supported languages by Sphinx are:
4756 · bn – Bengali
4758 · ca – Catalan
4760 · cs – Czech
4762 · da – Danish
4764 · de – German
4766 · en – English
4768 · es – Spanish
4770 · et – Estonian
4772 · eu – Basque
4774 · fa – Iranian
4776 · fi – Finnish
4778 · fr – French
4780 · he – Hebrew
4782 · hr – Croatian
4784 · hu – Hungarian
4786 · id – Indonesian
4788 · it – Italian
4790 · ja – Japanese
4792 · ko – Korean
4794 · lt – Lithuanian
4796 · lv – Latvian
4798 · mk – Macedonian
4800 · nb_NO – Norwegian Bokmal
4802 · ne – Nepali
4804 · nl – Dutch
4806 · pl – Polish
4808 · pt_BR – Brazilian Portuguese
4810 · pt_PT – European Portuguese
4812 · ru – Russian
4814 · si – Sinhala
4816 · sk – Slovak
4818 · sl – Slovenian
4820 · sv – Swedish
4822 · tr – Turkish
4824 · uk_UA – Ukrainian
4826 · vi – Vietnamese
4828 · zh_CN – Simplified Chinese
4830 · zh_TW – Traditional Chinese
4832 locale_dirs
4834 New in version 0.5.
4835 Directories in which to search for additional message catalogs
4838 (see language), relative to the source directory. The directo‐
4839 ries on this path are searched by the standard gettext module.
4840 Internal messages are fetched from a text domain of sphinx; so
4842 if you add the directory ./locale to this setting, the message
4843 catalogs (compiled from .po format using msgfmt) must be in
4844 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
4845 individual documents depends on gettext_compact.
4846 The default is ['locales'].
4848 Changed in version 1.5: Use locales directory as a default value
4850 gettext_compact
4853 New in version 1.1.
4854 If true, a document’s text domain is its docname if it is a
4857 top-level project file and its very base directory otherwise.
4858 By default, the document markup/code.rst ends up in the markup
4860 text domain. With this option set to False, it is markup/code.
4861 gettext_uuid
4863 If true, Sphinx generates uuid information for version tracking
4864 in message catalogs. It is used for:
4865 · Add uid line for each msgids in .pot files.
4867 · Calculate similarity between new msgids and previously saved
4869 old msgids. This calculation takes a long time.
4870 If you want to accelerate the calculation, you can use
4872 python-levenshtein 3rd-party package written in C by using pip
4873 install python-levenshtein.
4874 The default is False.
4876 New in version 1.3.
4878 gettext_location
4881 If true, Sphinx generates location information for messages in
4882 message catalogs.
4883 The default is True.
4885 New in version 1.3.
4887 gettext_auto_build
4890 If true, Sphinx builds mo file for each translation catalog
4891 files.
4892 The default is True.
4894 New in version 1.3.
4896 gettext_additional_targets
4899 To specify names to enable gettext extracting and translation
4900 applying for i18n additionally. You can specify below names:
4901 Index index terms
4903 Literal-block
4905 literal blocks: :: and code-block.
4906 Doctest-block
4908 doctest block
4909 Raw raw content
4911 Image image/figure uri and alt
4913 For example: gettext_additional_targets = ['literal-block',
4915 'image'].
4916 The default is [].
4918 New in version 1.3.
4920 figure_language_filename
4923 The filename format for language-specific figures. The default
4924 value is {root}.{language}{ext}. It will be expanded to
4925 dirname/filename.en.png from .. image:: dirname/filename.png.
4926 The available format tokens are:
4927 · {root} - the filename, including any path component, without
4929 the file extension, e.g. dirname/filename
4930 · {path} - the directory path component of the filename, with a
4932 trailing slash if non-empty, e.g. dirname/
4933 · {basename} - the filename without the directory path or file
4935 extension components, e.g. filename
4936 · {ext} - the file extension, e.g. .png
4938 · {language} - the translation language, e.g. en
4940 For example, setting this to {path}{language}/{basename}{ext}
4942 will expand to dirname/en/filename.png instead.
4943 New in version 1.4.
4945 Changed in version 1.5: Added {path} and {basename} tokens.
4948 Options for Math
4951 These options influence Math notations.
4952 math_number_all
4954 Set this option to True if you want all displayed math to be
4955 numbered. The default is False.
4956 math_eqref_format
4958 A string used for formatting the labels of references to equa‐
4959 tions. The {number} place-holder stands for the equation num‐
4960 ber.
4961 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
4963 math_numfig
4965 If True, displayed math equations are numbered across pages when
4966 numfig is enabled. The numfig_secnum_depth setting is
4967 respected. The eq, not numref, role must be used to reference
4968 equation numbers. Default is True.
4969 New in version 1.7.
4971 Options for HTML output
4974 These options influence HTML as well as HTML Help output, and other
4975 builders that use Sphinx’s HTMLWriter class.
4976 html_theme
4978 The “theme” that the HTML output should use. See the section
4979 about theming. The default is 'alabaster'.
4980 New in version 0.6.
4982 html_theme_options
4985 A dictionary of options that influence the look and feel of the
4986 selected theme. These are theme-specific. For the options
4987 understood by the builtin themes, see this section.
4988 New in version 0.6.
4990 html_theme_path
4993 A list of paths that contain custom themes, either as subdirec‐
4994 tories or as zip files. Relative paths are taken as relative to
4995 the configuration directory.
4996 New in version 0.6.
4998 html_style
5001 The style sheet to use for HTML pages. A file of that name must
5002 exist either in Sphinx’s static/ path, or in one of the custom
5003 paths given in html_static_path. Default is the stylesheet
5004 given by the selected theme. If you only want to add or over‐
5005 ride a few things compared to the theme’s stylesheet, use CSS
5006 @import to import the theme’s stylesheet.
5007 html_title
5009 The “title” for HTML documentation generated with Sphinx’s own
5010 templates. This is appended to the <title> tag of individual
5011 pages, and used in the navigation bar as the “topmost” element.
5012 It defaults to '<project> v<revision> documentation'.
5013 html_short_title
5015 A shorter “title” for the HTML docs. This is used in for links
5016 in the header and in the HTML Help docs. If not given, it
5017 defaults to the value of html_title.
5018 New in version 0.4.
5020 html_baseurl
5023 The URL which points to the root of the HTML documentation. It
5024 is used to indicate the location of document like canonical_url.
5025 New in version 1.8.
5027 html_context
5030 A dictionary of values to pass into the template engine’s con‐
5031 text for all pages. Single values can also be put in this dic‐
5032 tionary using the -A command-line option of sphinx-build.
5033 New in version 0.5.
5035 html_logo
5038 If given, this must be the name of an image file (path relative
5039 to the configuration directory) that is the logo of the docs.
5040 It is placed at the top of the sidebar; its width should there‐
5041 fore not exceed 200 pixels. Default: None.
5042 New in version 0.4.1: The image file will be copied to the
5044 _static directory of the output HTML, but only if the file does
5045 not already exist there.
5046 html_favicon
5049 If given, this must be the name of an image file (path relative
5050 to the configuration directory) that is the favicon of the docs.
5051 Modern browsers use this as the icon for tabs, windows and book‐
5052 marks. It should be a Windows-style icon file (.ico), which is
5053 16x16 or 32x32 pixels large. Default: None.
5054 New in version 0.4: The image file will be copied to the _static
5056 directory of the output HTML, but only if the file does not
5057 already exist there.
5058 html_css_files
5061 A list of CSS files. The entry must be a filename string or a
5062 tuple containing the filename string and the attributes dictio‐
5063 nary. The filename must be relative to the html_static_path, or
5064 a full URI with scheme like http://example.org/style.css. The
5065 attributes is used for attributes of <link> tag. It defaults to
5066 an empty list.
5067 Example:
5069 html_css_files = ['custom.css'
5071 'https://example.com/css/custom.css',
5072 ('print.css', {'media': 'print'})]
5073 New in version 1.8.
5075 html_js_files
5078 A list of JavaScript filename. The entry must be a filename
5079 string or a tuple containing the filename string and the
5080 attributes dictionary. The filename must be relative to the
5081 html_static_path, or a full URI with scheme like http://exam‐
5082 ple.org/script.js. The attributes is used for attributes of
5083 <script> tag. It defaults to an empty list.
5084 Example:
5086 html_js_files = ['script.js',
5088 'https://example.com/scripts/custom.js',
5089 ('custom.js', {'async': 'async'})]
5090 New in version 1.8.
5092 html_static_path
5095 A list of paths that contain custom static files (such as style
5096 sheets or script files). Relative paths are taken as relative
5097 to the configuration directory. They are copied to the output’s
5098 _static directory after the theme’s static files, so a file
5099 named default.css will overwrite the theme’s default.css.
5100 As these files are not meant to be built, they are automatically
5102 excluded from source files.
5103 NOTE:
5105 For security reasons, dotfiles under html_static_path will
5106 not be copied. If you would like to copy them intentionally,
5107 please add each filepath to this setting:
5108 html_static_path = ['_static', '_static/.htaccess']
5110 Another way to do that, you can also use html_extra_path. It
5112 allows to copy dotfiles under the directories.
5113 Changed in version 0.4: The paths in html_static_path can now
5115 contain subdirectories.
5116 Changed in version 1.0: The entries in html_static_path can now
5119 be single files.
5120 Changed in version 1.8: The files under html_static_path are
5123 excluded from source files.
5124 html_extra_path
5127 A list of paths that contain extra files not directly related to
5128 the documentation, such as robots.txt or .htaccess. Relative
5129 paths are taken as relative to the configuration directory.
5130 They are copied to the output directory. They will overwrite
5131 any existing file of the same name.
5132 As these files are not meant to be built, they are automatically
5134 excluded from source files.
5135 New in version 1.2.
5137 Changed in version 1.4: The dotfiles in the extra directory will
5140 be copied to the output directory. And it refers
5141 exclude_patterns on copying extra files and directories, and
5142 ignores if path matches to patterns.
5143 html_last_updated_fmt
5146 If this is not None, a ‘Last updated on:’ timestamp is inserted
5147 at every page bottom, using the given strftime() format. The
5148 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5149 equivalent).
5150 html_use_smartypants
5152 If true, quotes and dashes are converted to typographically cor‐
5153 rect entities. Default: True.
5154 Deprecated since version 1.6: To disable smart quotes, use
5156 rather smartquotes.
5157 html_add_permalinks
5160 Sphinx will add “permalinks” for each heading and description
5161 environment as paragraph signs that become visible when the
5162 mouse hovers over them.
5163 This value determines the text for the permalink; it defaults to
5165 "¶". Set it to None or the empty string to disable permalinks.
5166 New in version 0.6: Previously, this was always activated.
5168 Changed in version 1.1: This can now be a string to select the
5171 actual text of the link. Previously, only boolean values were
5172 accepted.
5173 html_sidebars
5176 Custom sidebar templates, must be a dictionary that maps docu‐
5177 ment names to template names.
5178 The keys can contain glob-style patterns [1], in which case all
5180 matching documents will get the specified sidebars. (A warning
5181 is emitted when a more than one glob-style pattern matches for
5182 any document.)
5183 The values can be either lists or single strings.
5185 · If a value is a list, it specifies the complete list of side‐
5187 bar templates to include. If all or some of the default side‐
5188 bars are to be included, they must be put into this list as
5189 well.
5190 The default sidebars (for documents that don’t match any pat‐
5192 tern) are defined by theme itself. Builtin themes are using
5193 these templates by default: ['localtoc.html', 'rela‐
5194 tions.html', 'sourcelink.html', 'searchbox.html'].
5195 · If a value is a single string, it specifies a custom sidebar
5197 to be added between the 'sourcelink.html' and 'searchbox.html'
5198 entries. This is for compatibility with Sphinx versions
5199 before 1.0.
5200 Deprecated since version 1.7: a single string value for
5202 html_sidebars will be removed in 2.0
5203 Builtin sidebar templates that can be rendered are:
5206 · localtoc.html – a fine-grained table of contents of the cur‐
5208 rent document
5209 · globaltoc.html – a coarse-grained table of contents for the
5211 whole documentation set, collapsed
5212 · relations.html – two links to the previous and next documents
5214 · sourcelink.html – a link to the source of the current docu‐
5216 ment, if enabled in html_show_sourcelink
5217 · searchbox.html – the “quick search” box
5219 Example:
5221 html_sidebars = {
5223 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5224 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5225 }
5226 This will render the custom template windowssidebar.html and the
5228 quick search box within the sidebar of the given document, and
5229 render the default sidebars for all other pages (except that the
5230 local TOC is replaced by the global TOC).
5231 New in version 1.0: The ability to use globbing keys and to
5233 specify multiple sidebars.
5234 Note that this value only has no effect if the chosen theme does
5237 not possess a sidebar, like the builtin scrolls and haiku
5238 themes.
5239 html_additional_pages
5241 Additional templates that should be rendered to HTML pages, must
5242 be a dictionary that maps document names to template names.
5243 Example:
5245 html_additional_pages = {
5247 'download': 'customdownload.html',
5248 }
5249 This will render the template customdownload.html as the page
5251 download.html.
5252 html_domain_indices
5254 If true, generate domain-specific indices in addition to the
5255 general index. For e.g. the Python domain, this is the global
5256 module index. Default is True.
5257 This value can be a bool or a list of index names that should be
5259 generated. To find out the index name for a specific index,
5260 look at the HTML file name. For example, the Python module
5261 index has the name 'py-modindex'.
5262 New in version 1.0.
5264 html_use_index
5267 If true, add an index to the HTML documents. Default is True.
5268 New in version 0.4.
5270 html_split_index
5273 If true, the index is generated twice: once as a single page
5274 with all the entries, and once as one page per starting letter.
5275 Default is False.
5276 New in version 0.4.
5278 html_copy_source
5281 If true, the reST sources are included in the HTML build as
5282 _sources/name. The default is True.
5283 html_show_sourcelink
5285 If true (and html_copy_source is true as well), links to the
5286 reST sources will be added to the sidebar. The default is True.
5287 New in version 0.6.
5289 html_sourcelink_suffix
5292 Suffix to be appended to source links (see
5293 html_show_sourcelink), unless they have this suffix already.
5294 Default is '.txt'.
5295 New in version 1.5.
5297 html_use_opensearch
5300 If nonempty, an OpenSearch description file will be output, and
5301 all pages will contain a <link> tag referring to it. Since
5302 OpenSearch doesn’t support relative URLs for its search page
5303 location, the value of this option must be the base URL from
5304 which these documents are served (without trailing slash), e.g.
5305 "https://docs.python.org". The default is ''.
5306 html_file_suffix
5308 This is the file name suffix for generated HTML files. The
5309 default is ".html".
5310 New in version 0.4.
5312 html_link_suffix
5315 Suffix for generated links to HTML files. The default is what‐
5316 ever html_file_suffix is set to; it can be set differently (e.g.
5317 to support different web server setups).
5318 New in version 0.6.
5320 html_show_copyright
5323 If true, “(C) Copyright …” is shown in the HTML footer. Default
5324 is True.
5325 New in version 1.0.
5327 html_show_sphinx
5330 If true, “Created using Sphinx” is shown in the HTML footer.
5331 Default is True.
5332 New in version 0.4.
5334 html_output_encoding
5337 Encoding of HTML output files. Default is 'utf-8'. Note that
5338 this encoding name must both be a valid Python encoding name and
5339 a valid HTML charset value.
5340 New in version 1.0.
5342 html_compact_lists
5345 If true, a list all whose items consist of a single paragraph
5346 and/or a sub-list all whose items etc… (recursive definition)
5347 will not use the <p> element for any of its items. This is stan‐
5348 dard docutils behavior. Default: True.
5349 New in version 1.0.
5351 html_secnumber_suffix
5354 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5355 press the final dot on section numbers.
5356 New in version 1.0.
5358 html_search_language
5361 Language to be used for generating the HTML full-text search
5362 index. This defaults to the global language selected with
5363 language. If there is no support for this language, "en" is
5364 used which selects the English language.
5365 Support is present for these languages:
5367 · da – Danish
5369 · nl – Dutch
5371 · en – English
5373 · fi – Finnish
5375 · fr – French
5377 · de – German
5379 · hu – Hungarian
5381 · it – Italian
5383 · ja – Japanese
5385 · no – Norwegian
5387 · pt – Portuguese
5389 · ro – Romanian
5391 · ru – Russian
5393 · es – Spanish
5395 · sv – Swedish
5397 · tr – Turkish
5399 · zh – Chinese
5401 Accelerating build speed
5403 Each language (except Japanese) provides its own stem‐
5405 ming algorithm. Sphinx uses a Python implementation
5406 by default. You can use a C implementation to accel‐
5407 erate building the index file.
5408 · PorterStemmer (en)
5410 · PyStemmer (all languages)
5412 New in version 1.1: With support for en and ja.
5414 Changed in version 1.3: Added additional languages.
5417 html_search_options
5420 A dictionary with options for the search language support, empty
5421 by default. The meaning of these options depends on the lan‐
5422 guage selected.
5423 The English support has no options.
5425 The Japanese support has these options:
5427 Type
5429 is dotted module path string to specify Splitter imple‐
5430 mentation which should be derived from
5431 sphinx.search.ja.BaseSplitter. If not specified or None
5432 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5433 used.
5434 You can choose from these modules:
5436 ‘sphinx.search.ja.DefaultSplitter’
5438 TinySegmenter algorithm. This is default splitter.
5439 ‘sphinx.search.ja.MecabSplitter’
5441 MeCab binding. To use this splitter, ‘mecab’
5442 python binding or dynamic link library (‘libme‐
5443 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5444 required.
5445 ‘sphinx.search.ja.JanomeSplitter’
5447 Janome binding. To use this splitter, Janome is
5448 required.
5449 Deprecated since version 1.6: 'mecab', 'janome' and
5451 'default' is deprecated. To keep compatibility, 'mecab',
5452 'janome' and 'default' are also acceptable.
5453 Other option values depend on splitter value which you choose.
5456 Options for 'mecab':
5458 dic_enc
5460 is the encoding for the MeCab algorithm.
5461 dict
5463 is the dictionary to use for the MeCab algorithm.
5464 lib
5466 is the library name for finding the MeCab library
5467 via ctypes if the Python binding is not installed.
5468 For example:
5470 html_search_options = {
5472 'type': 'mecab',
5473 'dic_enc': 'utf-8',
5474 'dict': '/path/to/mecab.dic',
5475 'lib': '/path/to/libmecab.so',
5476 }
5477 Options for 'janome':
5479 user_dic
5481 is the user dictionary file path for Janome.
5482 user_dic_enc
5484 is the encoding for the user dictionary file
5485 specified by user_dic option. Default is ‘utf8’.
5486 New in version 1.1.
5488 Changed in version 1.4: html_search_options for Japanese is
5491 re-organized and any custom splitter can be used by type set‐
5492 tings.
5493 The Chinese support has these options:
5496 · dict – the jieba dictionary path if want to use custom dic‐
5498 tionary.
5499 html_search_scorer
5501 The name of a JavaScript file (relative to the configuration
5502 directory) that implements a search results scorer. If empty,
5503 the default will be used.
5504 New in version 1.2.
5506 html_scaled_image_link
5509 If true, images itself links to the original image if it doesn’t
5510 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5511 ‘height’. The default is True.
5512 New in version 1.3.
5514 html_math_renderer
5517 The name of math_renderer extension for HTML output. The
5518 default is 'mathjax'.
5519 New in version 1.8.
5521 html_experimental_html5_writer
5524 Output is processed with HTML5 writer. This feature needs docu‐
5525 tils 0.13 or newer. Default is False.
5526 New in version 1.6.
5528 Deprecated since version 2.0.
5531 html4_writer
5534 Output is processed with HTML4 writer. Default is False.
5535 Options for Single HTML output
5537 singlehtml_sidebars
5538 Custom sidebar templates, must be a dictionary that maps docu‐
5539 ment names to template names. And it only allows a key named
5540 ‘index’. All other keys are ignored. For more information,
5541 refer to html_sidebars. By default, it is same as
5542 html_sidebars.
5543 Options for HTML help output
5545 htmlhelp_basename
5546 Output file base name for HTML help builder. Default is
5547 'pydoc'.
5548 htmlhelp_file_suffix
5550 This is the file name suffix for generated HTML help files. The
5551 default is ".html".
5552 New in version 2.0.
5554 htmlhelp_link_suffix
5557 Suffix for generated links to HTML files. The default is
5558 ".html".
5559 New in version 2.0.
5561 Options for Apple Help output
5564 New in version 1.3.
5565 These options influence the Apple Help output. This builder derives
5568 from the HTML builder, so the HTML options also apply where appropri‐
5569 ate.
5570 NOTE:
5572 Apple Help output will only work on Mac OS X 10.6 and higher, as it
5573 requires the hiutil and codesign command line tools, neither of
5574 which are Open Source.
5575 You can disable the use of these tools using
5577 applehelp_disable_external_tools, but the result will not be a valid
5578 help book until the indexer is run over the .lproj folders within
5579 the bundle.
5580 applehelp_bundle_name
5582 The basename for the Apple Help Book. Defaults to the project
5583 name.
5584 applehelp_bundle_id
5586 The bundle ID for the help book bundle.
5587 WARNING:
5589 You must set this value in order to generate Apple Help.
5590 applehelp_dev_region
5592 The development region. Defaults to 'en-us', which is Apple’s
5593 recommended setting.
5594 applehelp_bundle_version
5596 The bundle version (as a string). Defaults to '1'.
5597 applehelp_icon
5599 The help bundle icon file, or None for no icon. According to
5600 Apple’s documentation, this should be a 16-by-16 pixel version
5601 of the application’s icon with a transparent background, saved
5602 as a PNG file.
5603 applehelp_kb_product
5605 The product tag for use with applehelp_kb_url. Defaults to
5606 '<project>-<release>'.
5607 applehelp_kb_url
5609 The URL for your knowledgebase server, e.g. https://exam‐
5610 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
5611 will replace the values 'product', 'query' and 'lang' at runtime
5612 with the contents of applehelp_kb_product, the text entered by
5613 the user in the search box and the user’s system language
5614 respectively.
5615 Defaults to None for no remote search.
5617 applehelp_remote_url
5619 The URL for remote content. You can place a copy of your Help
5620 Book’s Resources folder at this location and Help Viewer will
5621 attempt to use it to fetch updated content.
5622 e.g. if you set it to https://example.com/help/Foo/ and Help
5624 Viewer wants a copy of index.html for an English speaking cus‐
5625 tomer, it will look at https://exam‐
5626 ple.com/help/Foo/en.lproj/index.html.
5627 Defaults to None for no remote content.
5629 applehelp_index_anchors
5631 If True, tell the help indexer to index anchors in the generated
5632 HTML. This can be useful for jumping to a particular topic
5633 using the AHLookupAnchor function or the openHelpAnchor:inBook:
5634 method in your code. It also allows you to use help:anchor
5635 URLs; see the Apple documentation for more information on this
5636 topic.
5637 applehelp_min_term_length
5639 Controls the minimum term length for the help indexer. Defaults
5640 to None, which means the default will be used.
5641 applehelp_stopwords
5643 Either a language specification (to use the built-in stopwords),
5644 or the path to a stopwords plist, or None if you do not want to
5645 use stopwords. The default stopwords plist can be found at
5646 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
5647 ing, stopwords for the following languages:
5648 ┌──────────┬──────┐
5650 │Language │ Code │
5651 ├──────────┼──────┤
5652 │English │ en │
5653 ├──────────┼──────┤
5654 │German │ de │
5655 ├──────────┼──────┤
5656 │Spanish │ es │
5657 ├──────────┼──────┤
5658 │French │ fr │
5659 ├──────────┼──────┤
5660 │Swedish │ sv │
5661 ├──────────┼──────┤
5662 │Hungarian │ hu │
5663 ├──────────┼──────┤
5664 │Italian │ it │
5665 └──────────┴──────┘
5666 Defaults to language, or if that is not set, to en.
5668 applehelp_locale
5670 Specifies the locale to generate help for. This is used to
5671 determine the name of the .lproj folder inside the Help Book’s
5672 Resources, and is passed to the help indexer.
5673 Defaults to language, or if that is not set, to en.
5675 applehelp_title
5677 Specifies the help book title. Defaults to '<project> Help'.
5678 applehelp_codesign_identity
5680 Specifies the identity to use for code signing, or None if code
5681 signing is not to be performed.
5682 Defaults to the value of the environment variable
5684 CODE_SIGN_IDENTITY, which is set by Xcode for script build
5685 phases, or None if that variable is not set.
5686 applehelp_codesign_flags
5688 A list of additional arguments to pass to codesign when signing
5689 the help book.
5690 Defaults to a list based on the value of the environment vari‐
5692 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
5693 build phases, or the empty list if that variable is not set.
5694 applehelp_indexer_path
5696 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
5697 applehelp_codesign_path
5699 The path to the codesign program. Defaults to '/usr/bin/code‐
5700 sign'.
5701 applehelp_disable_external_tools
5703 If True, the builder will not run the indexer or the code sign‐
5704 ing tool, no matter what other settings are specified.
5705 This is mainly useful for testing, or where you want to run the
5707 Sphinx build on a non-Mac OS X platform and then complete the
5708 final steps on OS X for some reason.
5709 Defaults to False.
5711 Options for epub output
5713 These options influence the epub output. As this builder derives from
5714 the HTML builder, the HTML options also apply where appropriate. The
5715 actual values for some of the options is not really important, they
5716 just have to be entered into the Dublin Core metadata.
5717 epub_basename
5719 The basename for the epub file. It defaults to the project
5720 name.
5721 epub_theme
5723 The HTML theme for the epub output. Since the default themes
5724 are not optimized for small screen space, using the same theme
5725 for HTML and epub output is usually not wise. This defaults to
5726 'epub', a theme designed to save visual space.
5727 epub_theme_options
5729 A dictionary of options that influence the look and feel of the
5730 selected theme. These are theme-specific. For the options
5731 understood by the builtin themes, see this section.
5732 New in version 1.2.
5734 epub_title
5737 The title of the document. It defaults to the html_title option
5738 but can be set independently for epub creation. It defaults to
5739 the project option.
5740 Changed in version 2.0: It defaults to the project option.
5742 epub_description
5745 The description of the document. The default value is 'unknown'.
5746 New in version 1.4.
5748 Changed in version 1.5: Renamed from epub3_description
5751 epub_author
5754 The author of the document. This is put in the Dublin Core
5755 metadata. It defaults to the author option.
5756 epub_contributor
5758 The name of a person, organization, etc. that played a secondary
5759 role in the creation of the content of an EPUB Publication. The
5760 default value is 'unknown'.
5761 New in version 1.4.
5763 Changed in version 1.5: Renamed from epub3_contributor
5766 epub_language
5769 The language of the document. This is put in the Dublin Core
5770 metadata. The default is the language option or 'en' if unset.
5771 epub_publisher
5773 The publisher of the document. This is put in the Dublin Core
5774 metadata. You may use any sensible string, e.g. the project
5775 homepage. The defaults to the author option.
5776 epub_copyright
5778 The copyright of the document. It defaults to the copyright
5779 option but can be set independently for epub creation.
5780 epub_identifier
5782 An identifier for the document. This is put in the Dublin Core
5783 metadata. For published documents this is the ISBN number, but
5784 you can also use an alternative scheme, e.g. the project home‐
5785 page. The default value is 'unknown'.
5786 epub_scheme
5788 The publication scheme for the epub_identifier. This is put in
5789 the Dublin Core metadata. For published books the scheme is
5790 'ISBN'. If you use the project homepage, 'URL' seems reason‐
5791 able. The default value is 'unknown'.
5792 epub_uid
5794 A unique identifier for the document. This is put in the Dublin
5795 Core metadata. You may use a XML’s Name format string. You
5796 can’t use hyphen, period, numbers as a first character. The
5797 default value is 'unknown'.
5798 epub_cover
5800 The cover page information. This is a tuple containing the
5801 filenames of the cover image and the html template. The ren‐
5802 dered html cover page is inserted as the first item in the spine
5803 in content.opf. If the template filename is empty, no html
5804 cover page is created. No cover at all is created if the tuple
5805 is empty. Examples:
5806 epub_cover = ('_static/cover.png', 'epub-cover.html')
5808 epub_cover = ('_static/cover.png', '')
5809 epub_cover = ()
5810 The default value is ().
5812 New in version 1.1.
5814 epub_css_files
5817 A list of CSS files. The entry must be a filename string or a
5818 tuple containing the filename string and the attributes dictio‐
5819 nary. For more information, see html_css_files.
5820 New in version 1.8.
5822 epub_guide
5825 Meta data for the guide element of content.opf. This is a
5826 sequence of tuples containing the type, the uri and the title of
5827 the optional guide information. See the OPF documentation at
5828 http://idpf.org/epub for details. If possible, default entries
5829 for the cover and toc types are automatically inserted. However,
5830 the types can be explicitly overwritten if the default entries
5831 are not appropriate. Example:
5832 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
5834 The default value is ().
5836 epub_pre_files
5838 Additional files that should be inserted before the text gener‐
5839 ated by Sphinx. It is a list of tuples containing the file name
5840 and the title. If the title is empty, no entry is added to
5841 toc.ncx. Example:
5842 epub_pre_files = [
5844 ('index.html', 'Welcome'),
5845 ]
5846 The default value is [].
5848 epub_post_files
5850 Additional files that should be inserted after the text gener‐
5851 ated by Sphinx. It is a list of tuples containing the file name
5852 and the title. This option can be used to add an appendix. If
5853 the title is empty, no entry is added to toc.ncx. The default
5854 value is [].
5855 epub_exclude_files
5857 A list of files that are generated/copied in the build directory
5858 but should not be included in the epub file. The default value
5859 is [].
5860 epub_tocdepth
5862 The depth of the table of contents in the file toc.ncx. It
5863 should be an integer greater than zero. The default value is 3.
5864 Note: A deeply nested table of contents may be difficult to nav‐
5865 igate.
5866 epub_tocdup
5868 This flag determines if a toc entry is inserted again at the
5869 beginning of its nested toc listing. This allows easier naviga‐
5870 tion to the top of a chapter, but can be confusing because it
5871 mixes entries of different depth in one list. The default value
5872 is True.
5873 epub_tocscope
5875 This setting control the scope of the epub table of contents.
5876 The setting can have the following values:
5877 · 'default' – include all toc entries that are not hidden
5879 (default)
5880 · 'includehidden' – include all toc entries
5882 New in version 1.2.
5884 epub_fix_images
5887 This flag determines if sphinx should try to fix image formats
5888 that are not supported by some epub readers. At the moment pal‐
5889 ette images with a small color table are upgraded. You need
5890 Pillow, the Python Image Library, installed to use this option.
5891 The default value is False because the automatic conversion may
5892 lose information.
5893 New in version 1.2.
5895 epub_max_image_width
5898 This option specifies the maximum width of images. If it is set
5899 to a value greater than zero, images with a width larger than
5900 the given value are scaled accordingly. If it is zero, no scal‐
5901 ing is performed. The default value is 0. You need the Python
5902 Image Library (Pillow) installed to use this option.
5903 New in version 1.2.
5905 epub_show_urls
5908 Control whether to display URL addresses. This is very useful
5909 for readers that have no other means to display the linked URL.
5910 The settings can have the following values:
5911 · 'inline' – display URLs inline in parentheses (default)
5913 · 'footnote' – display URLs in footnotes
5915 · 'no' – do not display URLs
5917 The display of inline URLs can be customized by adding CSS rules
5919 for the class link-target.
5920 New in version 1.2.
5922 epub_use_index
5925 If true, add an index to the epub document. It defaults to the
5926 html_use_index option but can be set independently for epub cre‐
5927 ation.
5928 New in version 1.2.
5930 epub_writing_mode
5933 It specifies writing direction. It can accept 'horizontal'
5934 (default) and 'vertical'
5935 ┌────────────────────┬─────────────────────┬─────────────────────┐
5937 │epub_writing_mode │ 'horizontal' │ 'vertical' │
5938 ├────────────────────┼─────────────────────┼─────────────────────┤
5939 │writing-mode [2] │ horizontal-tb │ vertical-rl │
5940 ├────────────────────┼─────────────────────┼─────────────────────┤
5941 │page progression │ left to right │ right to left │
5942 ├────────────────────┼─────────────────────┼─────────────────────┤
5943 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
5944 │Theme support │ tical. │ izontal. │
5945 └────────────────────┴─────────────────────┴─────────────────────┘
5946 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
5948 Options for LaTeX output
5950 These options influence LaTeX output.
5951 latex_engine
5953 The LaTeX engine to build the docs. The setting can have the
5954 following values:
5955 · 'pdflatex' – PDFLaTeX (default)
5957 · 'xelatex' – XeLaTeX
5959 · 'lualatex' – LuaLaTeX
5961 · 'platex' – pLaTeX (default if language is 'ja')
5963 'pdflatex'’s support for Unicode characters is limited.
5965 NOTE:
5967 2.0 adds to 'pdflatex' support in Latin language document of
5968 occasional Cyrillic or Greek letters or words. This is not
5969 automatic, see the discussion of the latex_elements 'fontenc'
5970 key.
5971 If your project uses Unicode characters, setting the engine to
5973 'xelatex' or 'lualatex' and making sure to use an OpenType font
5974 with wide-enough glyph coverage is often easier than trying to
5975 make 'pdflatex' work with the extra Unicode characters. Since
5976 Sphinx 2.0 the default is the GNU FreeFont which covers well
5977 Latin, Cyrillic and Greek.
5978 Changed in version 2.1.0: Use xelatex (and LaTeX package xeCJK)
5980 by default for Chinese documents.
5981 Changed in version 2.2.1: Use xelatex by default for Greek docu‐
5984 ments.
5985 Contrarily to MathJaX math rendering in HTML output, LaTeX
5988 requires some extra configuration to support Unicode literals in
5989 math: the only comprehensive solution (as far as we know) is to
5990 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
5991 code-math}' (e.g. via the latex_elements 'preamble' key). You
5992 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
5993 keep a Unicode literal such as α (U+03B1) for example as is in
5994 output, rather than being rendered as \alpha.
5995 latex_documents
5997 This value determines how to group the document tree into LaTeX
5998 source files. It must be a list of tuples (startdocname, tar‐
5999 getname, title, author, documentclass, toctree_only), where the
6000 items are:
6001 startdocname
6003 String that specifies the document name of the LaTeX
6004 file’s master document. All documents referenced by the
6005 startdoc document in TOC trees will be included in the
6006 LaTeX file. (If you want to use the default master docu‐
6007 ment for your LaTeX build, provide your master_doc here.)
6008 targetname
6010 File name of the LaTeX file in the output directory.
6011 title LaTeX document title. Can be empty to use the title of
6013 the startdoc document. This is inserted as LaTeX markup,
6014 so special characters like a backslash or ampersand must
6015 be represented by the proper LaTeX commands if they are
6016 to be inserted literally.
6017 author Author for the LaTeX document. The same LaTeX markup
6019 caveat as for title applies. Use \\and to separate mul‐
6020 tiple authors, as in: 'John \\and Sarah' (backslashes
6021 must be Python-escaped to reach LaTeX).
6022 documentclass
6024 Normally, one of 'manual' or 'howto' (provided by Sphinx
6025 and based on 'report', resp. 'article'; Japanese docu‐
6026 ments use 'jsbook', resp. 'jreport'.) “howto” (non-Japa‐
6027 nese) documents will not get appendices. Also they have a
6028 simpler title page. Other document classes can be given.
6029 Independently of the document class, the “sphinx” package
6030 is always loaded in order to define Sphinx’s custom LaTeX
6031 commands.
6032 toctree_only
6034 Must be True or False. If true, the startdoc document
6035 itself is not included in the output, only the documents
6036 referenced by it via TOC trees. With this option, you
6037 can put extra stuff in the master document that shows up
6038 in the HTML, but not the LaTeX output.
6039 New in version 1.2: In the past including your own document
6041 class required you to prepend the document class name with the
6042 string “sphinx”. This is not necessary anymore.
6043 New in version 0.3: The 6th item toctree_only. Tuples with 5
6046 items are still accepted.
6047 latex_logo
6050 If given, this must be the name of an image file (relative to
6051 the configuration directory) that is the logo of the docs. It
6052 is placed at the top of the title page. Default: None.
6053 latex_toplevel_sectioning
6055 This value determines the topmost sectioning unit. It should be
6056 chosen from 'part', 'chapter' or 'section'. The default is None;
6057 the topmost sectioning unit is switched by documentclass: sec‐
6058 tion is used if documentclass will be howto, otherwise chapter
6059 will be used.
6060 Note that if LaTeX uses \part command, then the numbering of
6062 sectioning units one level deep gets off-sync with HTML number‐
6063 ing, because LaTeX numbers continuously \chapter (or \section
6064 for howto.)
6065 New in version 1.4.
6067 latex_appendices
6070 A list of document names to append as an appendix to all manu‐
6071 als.
6072 latex_domain_indices
6074 If true, generate domain-specific indices in addition to the
6075 general index. For e.g. the Python domain, this is the global
6076 module index. Default is True.
6077 This value can be a bool or a list of index names that should be
6079 generated, like for html_domain_indices.
6080 New in version 1.0.
6082 latex_show_pagerefs
6085 If true, add page references after internal references. This is
6086 very useful for printed copies of the manual. Default is False.
6087 New in version 1.0.
6089 latex_show_urls
6092 Control whether to display URL addresses. This is very useful
6093 for printed copies of the manual. The setting can have the fol‐
6094 lowing values:
6095 · 'no' – do not display URLs (default)
6097 · 'footnote' – display URLs in footnotes
6099 · 'inline' – display URLs inline in parentheses
6101 New in version 1.0.
6103 Changed in version 1.1: This value is now a string; previously
6106 it was a boolean value, and a true value selected the 'inline'
6107 display. For backwards compatibility, True is still accepted.
6108 latex_use_latex_multicolumn
6111 The default is False: it means that Sphinx’s own macros are used
6112 for merged cells from grid tables. They allow general contents
6113 (literal blocks, lists, blockquotes, …) but may have problems if
6114 the tabularcolumns directive was used to inject LaTeX mark-up of
6115 the type >{..}, <{..}, @{..} as column specification.
6116 Setting to True means to use LaTeX’s standard \multicolumn; this
6118 is incompatible with literal blocks in the horizontally merged
6119 cell, and also with multiple paragraphs in such cell if the ta‐
6120 ble is rendered using tabulary.
6121 New in version 1.6.
6123 latex_use_xindy
6126 If True, the PDF build from the LaTeX files created by Sphinx
6127 will use xindy (doc) rather than makeindex for preparing the
6128 index of general terms (from index usage). This means that
6129 words with UTF-8 characters will get ordered correctly for the
6130 language.
6131 · This option is ignored if latex_engine is 'platex' (Japanese
6133 documents; mendex replaces makeindex then).
6134 · The default is True for 'xelatex' or 'lualatex' as makeindex,
6136 if any indexed term starts with a non-ascii character, creates
6137 .ind files containing invalid bytes for UTF-8 encoding. With
6138 'lualatex' this then breaks the PDF build.
6139 · The default is False for 'pdflatex' but True is recommended
6141 for non-English documents as soon as some indexed terms use
6142 non-ascii characters from the language script.
6143 Sphinx adds to xindy base distribution some dedicated support
6145 for using 'pdflatex' engine with Cyrillic scripts. And whether
6146 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6147 correctly the indexing of Latin names, even with diacritics.
6148 New in version 1.8.
6150 latex_elements
6153 New in version 0.5.
6154 Its documentation has moved to /latex.
6157 latex_docclass
6159 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6160 ment classes that will be used as the base for the two Sphinx
6161 classes. Default is to use 'article' for 'howto' and 'report'
6162 for 'manual'.
6163 New in version 1.0.
6165 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6168 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6169 latex_additional_files
6172 A list of file names, relative to the configuration directory,
6173 to copy to the build directory when building LaTeX output. This
6174 is useful to copy files that Sphinx doesn’t copy automatically,
6175 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6176 ments. Image files that are referenced in source files (e.g.
6177 via .. image::) are copied automatically.
6178 You have to make sure yourself that the filenames don’t collide
6180 with those of any automatically copied files.
6181 New in version 0.6.
6183 Changed in version 1.2: This overrides the files which is pro‐
6186 vided from Sphinx such as sphinx.sty.
6187 Options for text output
6190 These options influence text output.
6191 text_newlines
6193 Determines which end-of-line character(s) are used in text out‐
6194 put.
6195 · 'unix': use Unix-style line endings (\n)
6197 · 'windows': use Windows-style line endings (\r\n)
6199 · 'native': use the line ending style of the platform the docu‐
6201 mentation is built on
6202 Default: 'unix'.
6204 New in version 1.1.
6206 text_sectionchars
6209 A string of 7 characters that should be used for underlining
6210 sections. The first character is used for first-level headings,
6211 the second for second-level headings and so on.
6212 The default is '*=-~"+`'.
6214 New in version 1.1.
6216 text_add_secnumbers
6219 A boolean that decides whether section numbers are included in
6220 text output. Default is True.
6221 New in version 1.7.
6223 text_secnumber_suffix
6226 Suffix for section numbers in text output. Default: ". ". Set
6227 to " " to suppress the final dot on section numbers.
6228 New in version 1.7.
6230 Options for manual page output
6233 These options influence manual page output.
6234 man_pages
6236 This value determines how to group the document tree into manual
6237 pages. It must be a list of tuples (startdocname, name,
6238 description, authors, section), where the items are:
6239 startdocname
6241 String that specifies the document name of the manual
6242 page’s master document. All documents referenced by the
6243 startdoc document in TOC trees will be included in the
6244 manual file. (If you want to use the default master doc‐
6245 ument for your manual pages build, use your master_doc
6246 here.)
6247 name Name of the manual page. This should be a short string
6249 without spaces or special characters. It is used to
6250 determine the file name as well as the name of the manual
6251 page (in the NAME section).
6252 description
6254 Description of the manual page. This is used in the NAME
6255 section.
6256 authors
6258 A list of strings with authors, or a single string. Can
6259 be an empty string or list if you do not want to automat‐
6260 ically generate an AUTHORS section in the manual page.
6261 section
6263 The manual page section. Used for the output file name
6264 as well as in the manual page header.
6265 New in version 1.0.
6267 man_show_urls
6270 If true, add URL addresses after links. Default is False.
6271 New in version 1.1.
6273 Options for Texinfo output
6276 These options influence Texinfo output.
6277 texinfo_documents
6279 This value determines how to group the document tree into Tex‐
6280 info source files. It must be a list of tuples (startdocname,
6281 targetname, title, author, dir_entry, description, category,
6282 toctree_only), where the items are:
6283 startdocname
6285 String that specifies the document name of the the Tex‐
6286 info file’s master document. All documents referenced by
6287 the startdoc document in TOC trees will be included in
6288 the Texinfo file. (If you want to use the default master
6289 document for your Texinfo build, provide your master_doc
6290 here.)
6291 targetname
6293 File name (no extension) of the Texinfo file in the out‐
6294 put directory.
6295 title Texinfo document title. Can be empty to use the title of
6297 the startdoc document. Inserted as Texinfo markup, so
6298 special characters like @ and {} will need to be escaped
6299 to be inserted literally.
6300 author Author for the Texinfo document. Inserted as Texinfo
6302 markup. Use @* to separate multiple authors, as in:
6303 'John@*Sarah'.
6304 dir_entry
6306 The name that will appear in the top-level DIR menu file.
6307 description
6309 Descriptive text to appear in the top-level DIR menu
6310 file.
6311 category
6313 Specifies the section which this entry will appear in the
6314 top-level DIR menu file.
6315 toctree_only
6317 Must be True or False. If true, the startdoc document
6318 itself is not included in the output, only the documents
6319 referenced by it via TOC trees. With this option, you
6320 can put extra stuff in the master document that shows up
6321 in the HTML, but not the Texinfo output.
6322 New in version 1.1.
6324 texinfo_appendices
6327 A list of document names to append as an appendix to all manu‐
6328 als.
6329 New in version 1.1.
6331 texinfo_domain_indices
6334 If true, generate domain-specific indices in addition to the
6335 general index. For e.g. the Python domain, this is the global
6336 module index. Default is True.
6337 This value can be a bool or a list of index names that should be
6339 generated, like for html_domain_indices.
6340 New in version 1.1.
6342 texinfo_show_urls
6345 Control how to display URL addresses.
6346 · 'footnote' – display URLs in footnotes (default)
6348 · 'no' – do not display URLs
6350 · 'inline' – display URLs inline in parentheses
6352 New in version 1.1.
6354 texinfo_no_detailmenu
6357 If true, do not generate a @detailmenu in the “Top” node’s menu
6358 containing entries for each sub-node in the document. Default
6359 is False.
6360 New in version 1.2.
6362 texinfo_elements
6365 A dictionary that contains Texinfo snippets that override those
6366 Sphinx usually puts into the generated .texi files.
6367 · Keys that you may want to override include:
6369 'paragraphindent'
6371 Number of spaces to indent the first line of each para‐
6372 graph, default 2. Specify 0 for no indentation.
6373 'exampleindent'
6375 Number of spaces to indent the lines for examples or
6376 literal blocks, default 4. Specify 0 for no indenta‐
6377 tion.
6378 'preamble'
6380 Texinfo markup inserted near the beginning of the file.
6381 'copying'
6383 Texinfo markup inserted within the @copying block and
6384 displayed after the title. The default value consists
6385 of a simple title page identifying the project.
6386 · Keys that are set by other options and therefore should not be
6388 overridden are:
6389 'author' 'body' 'date' 'direntry' 'filename' 'project'
6391 'release' 'title'
6392 New in version 1.1.
6394 Options for QtHelp output
6397 These options influence qthelp output. As this builder derives from
6398 the HTML builder, the HTML options also apply where appropriate.
6399 qthelp_basename
6401 The basename for the qthelp file. It defaults to the project
6402 name.
6403 qthelp_namespace
6405 The namespace for the qthelp file. It defaults to
6406 org.sphinx.<project_name>.<project_version>.
6407 qthelp_theme
6409 The HTML theme for the qthelp output. This defaults to 'nonav'.
6410 qthelp_theme_options
6412 A dictionary of options that influence the look and feel of the
6413 selected theme. These are theme-specific. For the options
6414 understood by the builtin themes, see this section.
6415 Options for the linkcheck builder
6417 linkcheck_ignore
6418 A list of regular expressions that match URIs that should not be
6419 checked when doing a linkcheck build. Example:
6420 linkcheck_ignore = [r'http://localhost:\d+/']
6422 New in version 1.1.
6424 linkcheck_retries
6427 The number of times the linkcheck builder will attempt to check
6428 a URL before declaring it broken. Defaults to 1 attempt.
6429 New in version 1.4.
6431 linkcheck_timeout
6434 A timeout value, in seconds, for the linkcheck builder. The
6435 default is to use Python’s global socket timeout.
6436 New in version 1.1.
6438 linkcheck_workers
6441 The number of worker threads to use when checking links.
6442 Default is 5 threads.
6443 New in version 1.1.
6445 linkcheck_anchors
6448 If true, check the validity of #anchors in links. Since this
6449 requires downloading the whole document, it’s considerably
6450 slower when enabled. Default is True.
6451 New in version 1.2.
6453 linkcheck_anchors_ignore
6456 A list of regular expressions that match anchors Sphinx should
6457 skip when checking the validity of anchors in links. This allows
6458 skipping anchors that a website’s JavaScript adds to control
6459 dynamic pages or when triggering an internal REST request.
6460 Default is ["^!"].
6461 NOTE:
6463 If you want to ignore anchors of a specific page or of pages
6464 that match a specific pattern (but still check occurrences of
6465 the same page(s) that don’t have anchors), use
6466 linkcheck_ignore instead, for example as follows:
6467 linkcheck_ignore = [
6469 'http://www.sphinx-doc.org/en/1.7/intro.html#'
6470 ]
6471 New in version 1.5.
6473 Options for the XML builder
6476 xml_pretty
6477 If true, pretty-print the XML. Default is True.
6478 New in version 1.2.
6480
6483 [1] A note on available globbing syntax: you can use the standard
6484 shell constructs *, ?, [...] and [!...] with the feature that
6485 these all don’t match slashes. A double star ** can be used to
6486 match any sequence of characters including slashes.
6487 Options for the C++ domain
6489 cpp_index_common_prefix
6490 A list of prefixes that will be ignored when sorting C++ objects
6491 in the global index. For example ['awesome_lib::'].
6492 New in version 1.5.
6494 cpp_id_attributes
6497 A list of strings that the parser additionally should accept as
6498 attributes. This can for example be used when attributes have
6499 been #define d for portability.
6500 New in version 1.5.
6502 cpp_paren_attributes
6505 A list of strings that the parser additionally should accept as
6506 attributes with one argument. That is, if my_align_as is in the
6507 list, then my_align_as(X) is parsed as an attribute for all
6508 strings X that have balanced braces ((), [], and {}). This can
6509 for example be used when attributes have been #define d for
6510 portability.
6511 New in version 1.5.
6513 Example of configuration file
6516 # test documentation build configuration file, created by
6517 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
6518 #
6519 # This file is execfile()d with the current directory set to its
6520 # containing dir.
6521 #
6522 # Note that not all possible configuration values are present in this
6523 # autogenerated file.
6524 #
6525 # All configuration values have a default; values that are commented out
6526 # serve to show the default.
6527 # If extensions (or modules to document with autodoc) are in another directory,
6529 # add these directories to sys.path here. If the directory is relative to the
6530 # documentation root, use os.path.abspath to make it absolute, like shown here.
6531 #
6532 # import os
6533 # import sys
6534 # sys.path.insert(0, os.path.abspath('.'))
6535 # -- General configuration ------------------------------------------------
6537 # If your documentation needs a minimal Sphinx version, state it here.
6539 #
6540 # needs_sphinx = '1.0'
6541 # Add any Sphinx extension module names here, as strings. They can be
6543 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
6544 # ones.
6545 extensions = []
6546 # Add any paths that contain templates here, relative to this directory.
6548 templates_path = ['_templates']
6549 # The suffix(es) of source filenames.
6551 # You can specify multiple suffix as a list of string:
6552 #
6553 # source_suffix = ['.rst', '.md']
6554 source_suffix = '.rst'
6555 # The encoding of source files.
6557 #
6558 # source_encoding = 'utf-8-sig'
6559 # The master toctree document.
6561 master_doc = 'index'
6562 # General information about the project.
6564 project = u'test'
6565 copyright = u'2016, test'
6566 author = u'test'
6567 # The version info for the project you're documenting, acts as replacement for
6569 # |version| and |release|, also used in various other places throughout the
6570 # built documents.
6571 #
6572 # The short X.Y version.
6573 version = u'test'
6574 # The full version, including alpha/beta/rc tags.
6575 release = u'test'
6576 # The language for content autogenerated by Sphinx. Refer to documentation
6578 # for a list of supported languages.
6579 #
6580 # This is also used if you do content translation via gettext catalogs.
6581 # Usually you set "language" from the command line for these cases.
6582 language = None
6583 # There are two options for replacing |today|: either, you set today to some
6585 # non-false value, then it is used:
6586 #
6587 # today = ''
6588 #
6589 # Else, today_fmt is used as the format for a strftime call.
6590 #
6591 # today_fmt = '%B %d, %Y'
6592 # List of patterns, relative to source directory, that match files and
6594 # directories to ignore when looking for source files.
6595 # These patterns also affect html_static_path and html_extra_path
6596 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
6597 # The reST default role (used for this markup: `text`) to use for all
6599 # documents.
6600 #
6601 # default_role = None
6602 # If true, '()' will be appended to :func: etc. cross-reference text.
6604 #
6605 # add_function_parentheses = True
6606 # If true, the current module name will be prepended to all description
6608 # unit titles (such as .. function::).
6609 #
6610 # add_module_names = True
6611 # If true, sectionauthor and moduleauthor directives will be shown in the
6613 # output. They are ignored by default.
6614 #
6615 # show_authors = False
6616 # The name of the Pygments (syntax highlighting) style to use.
6618 pygments_style = 'sphinx'
6619 # A list of ignored prefixes for module index sorting.
6621 # modindex_common_prefix = []
6622 # If true, keep warnings as "system message" paragraphs in the built documents.
6624 # keep_warnings = False
6625 # If true, `todo` and `todoList` produce output, else they produce nothing.
6627 todo_include_todos = False
6628 # -- Options for HTML output ----------------------------------------------
6631 # The theme to use for HTML and HTML Help pages. See the documentation for
6633 # a list of builtin themes.
6634 #
6635 html_theme = 'alabaster'
6636 # Theme options are theme-specific and customize the look and feel of a theme
6638 # further. For a list of options available for each theme, see the
6639 # documentation.
6640 #
6641 # html_theme_options = {}
6642 # Add any paths that contain custom themes here, relative to this directory.
6644 # html_theme_path = []
6645 # The name for this set of Sphinx documents.
6647 # "<project> v<release> documentation" by default.
6648 #
6649 # html_title = u'test vtest'
6650 # A shorter title for the navigation bar. Default is the same as html_title.
6652 #
6653 # html_short_title = None
6654 # The name of an image file (relative to this directory) to place at the top
6656 # of the sidebar.
6657 #
6658 # html_logo = None
6659 # The name of an image file (relative to this directory) to use as a favicon of
6661 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
6662 # pixels large.
6663 #
6664 # html_favicon = None
6665 # Add any paths that contain custom static files (such as style sheets) here,
6667 # relative to this directory. They are copied after the builtin static files,
6668 # so a file named "default.css" will overwrite the builtin "default.css".
6669 html_static_path = ['_static']
6670 # Add any extra paths that contain custom files (such as robots.txt or
6672 # .htaccess) here, relative to this directory. These files are copied
6673 # directly to the root of the documentation.
6674 #
6675 # html_extra_path = []
6676 # If not None, a 'Last updated on:' timestamp is inserted at every page
6678 # bottom, using the given strftime format.
6679 # The empty string is equivalent to '%b %d, %Y'.
6680 #
6681 # html_last_updated_fmt = None
6682 # Custom sidebar templates, maps document names to template names.
6684 #
6685 # html_sidebars = {}
6686 # Additional templates that should be rendered to pages, maps page names to
6688 # template names.
6689 #
6690 # html_additional_pages = {}
6691 # If false, no module index is generated.
6693 #
6694 # html_domain_indices = True
6695 # If false, no index is generated.
6697 #
6698 # html_use_index = True
6699 # If true, the index is split into individual pages for each letter.
6701 #
6702 # html_split_index = False
6703 # If true, links to the reST sources are added to the pages.
6705 #
6706 # html_show_sourcelink = True
6707 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
6709 #
6710 # html_show_sphinx = True
6711 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
6713 #
6714 # html_show_copyright = True
6715 # If true, an OpenSearch description file will be output, and all pages will
6717 # contain a <link> tag referring to it. The value of this option must be the
6718 # base URL from which the finished HTML is served.
6719 #
6720 # html_use_opensearch = ''
6721 # This is the file name suffix for HTML files (e.g. ".xhtml").
6723 # html_file_suffix = None
6724 # Language to be used for generating the HTML full-text search index.
6726 # Sphinx supports the following languages:
6727 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
6728 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
6729 #
6730 # html_search_language = 'en'
6731 # A dictionary with options for the search language support, empty by default.
6733 # 'ja' uses this config value.
6734 # 'zh' user can custom change `jieba` dictionary path.
6735 #
6736 # html_search_options = {'type': 'default'}
6737 # The name of a javascript file (relative to the configuration directory) that
6739 # implements a search results scorer. If empty, the default will be used.
6740 #
6741 # html_search_scorer = 'scorer.js'
6742 # Output file base name for HTML help builder.
6744 htmlhelp_basename = 'testdoc'
6745 # -- Options for LaTeX output ---------------------------------------------
6747 latex_elements = {
6749 # The paper size ('letterpaper' or 'a4paper').
6750 #
6751 # 'papersize': 'letterpaper',
6752 # The font size ('10pt', '11pt' or '12pt').
6754 #
6755 # 'pointsize': '10pt',
6756 # Additional stuff for the LaTeX preamble.
6758 #
6759 # 'preamble': '',
6760 # Latex figure (float) alignment
6762 #
6763 # 'figure_align': 'htbp',
6764 }
6765 # Grouping the document tree into LaTeX files. List of tuples
6767 # (source start file, target name, title,
6768 # author, documentclass [howto, manual, or own class]).
6769 latex_documents = [
6770 (master_doc, 'test.tex', u'test Documentation',
6771 u'test', 'manual'),
6772 ]
6773 # The name of an image file (relative to this directory) to place at the top of
6775 # the title page.
6776 #
6777 # latex_logo = None
6778 # If true, show page references after internal links.
6780 #
6781 # latex_show_pagerefs = False
6782 # If true, show URL addresses after external links.
6784 #
6785 # latex_show_urls = False
6786 # Documents to append as an appendix to all manuals.
6788 #
6789 # latex_appendices = []
6790 # If false, no module index is generated.
6792 #
6793 # latex_domain_indices = True
6794 # -- Options for manual page output ---------------------------------------
6797 # One entry per manual page. List of tuples
6799 # (source start file, name, description, authors, manual section).
6800 man_pages = [
6801 (master_doc, 'test', u'test Documentation',
6802 [author], 1)
6803 ]
6804 # If true, show URL addresses after external links.
6806 #
6807 # man_show_urls = False
6808 # -- Options for Texinfo output -------------------------------------------
6811 # Grouping the document tree into Texinfo files. List of tuples
6813 # (source start file, target name, title, author,
6814 # dir menu entry, description, category)
6815 texinfo_documents = [
6816 (master_doc, 'test', u'test Documentation',
6817 author, 'test', 'One line description of project.',
6818 'Miscellaneous'),
6819 ]
6820 # Documents to append as an appendix to all manuals.
6822 #
6823 # texinfo_appendices = []
6824 # If false, no module index is generated.
6826 #
6827 # texinfo_domain_indices = True
6828 # How to display URL addresses: 'footnote', 'no', or 'inline'.
6830 #
6831 # texinfo_show_urls = 'footnote'
6832 # If true, do not generate a @detailmenu in the "Top" node's menu.
6834 #
6835 # texinfo_no_detailmenu = False
6836 # -- A random example -----------------------------------------------------
6838 import sys, os
6840 sys.path.insert(0, os.path.abspath('.'))
6841 exclude_patterns = ['zzz']
6842 numfig = True
6844 #language = 'ja'
6845 extensions.append('sphinx.ext.todo')
6847 extensions.append('sphinx.ext.autodoc')
6848 #extensions.append('sphinx.ext.autosummary')
6849 extensions.append('sphinx.ext.intersphinx')
6850 extensions.append('sphinx.ext.mathjax')
6851 extensions.append('sphinx.ext.viewcode')
6852 extensions.append('sphinx.ext.graphviz')
6853 autosummary_generate = True
6856 html_theme = 'default'
6857 #source_suffix = ['.rst', '.txt']
6858
6861 These are the built-in Sphinx builders. More builders can be added by
6862 extensions.
6863 The builder’s “name” must be given to the -b command-line option of
6865 sphinx-build to select a builder.
6866 class sphinx.builders.html.StandaloneHTMLBuilder
6868 This is the standard HTML builder. Its output is a directory
6869 with HTML files, complete with style sheets and optionally the
6870 reST sources. There are quite a few configuration values that
6871 customize the output of this builder, see the chapter
6872 html-options for details.
6873 name = 'html'
6875 format = 'html'
6877 supported_image_types = ['image/svg+xml', 'image/png',
6879 'image/gif', 'image/jpeg']
6880 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
6882 This is a subclass of the standard HTML builder. Its output is
6883 a directory with HTML files, where each file is called
6884 index.html and placed in a subdirectory named like its page
6885 name. For example, the document markup/rest.rst will not result
6886 in an output file markup/rest.html, but markup/rest/index.html.
6887 When generating links between pages, the index.html is omitted,
6888 so that the URL would look like markup/rest/.
6889 name = 'dirhtml'
6891 format = 'html'
6893 supported_image_types = ['image/svg+xml', 'image/png',
6895 'image/gif', 'image/jpeg']
6896 New in version 0.6.
6898 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
6901 This is an HTML builder that combines the whole project in one
6902 output file. (Obviously this only works with smaller projects.)
6903 The file is named like the master document. No indices will be
6904 generated.
6905 name = 'singlehtml'
6907 format = 'html'
6909 supported_image_types = ['image/svg+xml', 'image/png',
6911 'image/gif', 'image/jpeg']
6912 New in version 1.0.
6914 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
6917 This builder produces the same output as the standalone HTML
6918 builder, but also generates HTML Help support files that allow
6919 the Microsoft HTML Help Workshop to compile them into a CHM
6920 file.
6921 name = 'htmlhelp'
6923 format = 'html'
6925 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
6927 class sphinxcontrib.qthelp.QtHelpBuilder
6929 This builder produces the same output as the standalone HTML
6930 builder, but also generates Qt help collection support files
6931 that allow the Qt collection generator to compile them.
6932 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
6934 sphinx.builders package.
6935 name = 'qthelp'
6938 format = 'html'
6940 supported_image_types = ['image/svg+xml', 'image/png',
6942 'image/gif', 'image/jpeg']
6943 class sphinxcontrib.applehelp.AppleHelpBuilder
6945 This builder produces an Apple Help Book based on the same out‐
6946 put as the standalone HTML builder.
6947 If the source directory contains any .lproj folders, the one
6949 corresponding to the selected language will have its contents
6950 merged with the generated output. These folders will be ignored
6951 by all other documentation types.
6952 In order to generate a valid help book, this builder requires
6954 the command line tool hiutil, which is only available on Mac OS
6955 X 10.6 and above. You can disable the indexing step by setting
6956 applehelp_disable_external_tools to True, in which case the out‐
6957 put will not be valid until hiutil has been run on all of the
6958 .lproj folders within the bundle.
6959 name = 'applehelp'
6961 format = 'html'
6963 supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
6965 'image/tiff', 'image/jp2', 'image/svg+xml']
6966 New in version 1.3.
6968 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
6971 sphinx.builders package.
6972 class sphinxcontrib.devhelp.DevhelpBuilder
6975 This builder produces the same output as the standalone HTML
6976 builder, but also generates GNOME Devhelp support file that
6977 allows the GNOME Devhelp reader to view them.
6978 name = 'devhelp'
6980 format = 'html'
6982 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
6984 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
6986 sphinx.builders package.
6987 class sphinx.builders.epub3.Epub3Builder
6990 This builder produces the same output as the standalone HTML
6991 builder, but also generates an epub file for ebook readers. See
6992 epub-faq for details about it. For definition of the epub for‐
6993 mat, have a look at http://idpf.org/epub or
6994 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
6995 files.
6996 name = 'epub'
6998 format = 'html'
7000 supported_image_types = ['image/svg+xml', 'image/png',
7002 'image/gif', 'image/jpeg']
7003 New in version 1.4.
7005 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7008 used for the default builder of epub.
7009 class sphinx.builders.latex.LaTeXBuilder
7012 This builder produces a bunch of LaTeX files in the output
7013 directory. You have to specify which documents are to be
7014 included in which LaTeX files via the latex_documents configura‐
7015 tion value. There are a few configuration values that customize
7016 the output of this builder, see the chapter latex-options for
7017 details.
7018 The produced LaTeX file uses several LaTeX packages that may not
7020 be present in a “minimal” TeX distribution installation.
7021 On Ubuntu xenial, the following packages need to be installed
7023 for successful PDF builds:
7024 · texlive-latex-recommended
7026 · texlive-fonts-recommended
7028 · texlive-latex-extra
7030 · latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
7032 for functioning of make latexpdf)
7033 Additional packages are needed in some circumstances (see the
7035 discussion of the 'fontpkg' key of latex_elements for more
7036 information):
7037 · to support occasional Cyrillic letters or words, and a for‐
7039 tiori if language is set to a Cyrillic language, the package
7040 texlive-lang-cyrillic is required, and, with unmodified
7041 'fontpkg', also cm-super or cm-super-minimal,
7042 · to support occasional Greek letters or words (in text, not in
7044 math directive contents), texlive-lang-greek is required, and,
7045 with unmodified 'fontpkg', also cm-super or cm-super-minimal,
7046 · for 'xelatex' or 'lualatex' (see latex_engine), texlive-xetex
7048 resp. texlive-luatex, and, if leaving unchanged 'fontpkg',
7049 fonts-freefont-otf.
7050 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
7052 distribution is based on a TeXLive 2015 snapshot dated March
7053 2016.
7054 Changed in version 1.6: Formerly, testing had been done on
7056 Ubuntu precise (TeXLive 2009).
7057 Changed in version 2.0: Formerly, testing had been done on
7060 Ubuntu trusty (TeXLive 2013).
7061 NOTE:
7064 Since 1.6, make latexpdf uses latexmk (not on Windows). This
7065 makes sure the needed number of runs is automatically exe‐
7066 cuted to get the cross-references, bookmarks, indices, and
7067 tables of contents right.
7068 One can pass to latexmk options via the LATEXMKOPTS Makefile
7070 variable. For example:
7071 make latexpdf LATEXMKOPTS="-silent"
7073 reduces console output to a minimum.
7075 Also, if latexmk is at version 4.52b or higher (January 2017)
7077 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
7078 case of numerous graphics inclusions.
7079 To pass options directly to the (pdf|xe|lua)latex binary, use
7081 variable LATEXOPTS, for example:
7082 make latexpdf LATEXOPTS="--halt-on-error"
7084 name = 'latex'
7086 format = 'latex'
7088 supported_image_types = ['application/pdf', 'image/png',
7090 'image/jpeg']
7091 Note that a direct PDF builder is being provided by rinohtype. The
7093 builder’s name is rinoh. Refer to the rinohtype manual for details.
7094 class sphinx.builders.text.TextBuilder
7096 This builder produces a text file for each reST file – this is
7097 almost the same as the reST source, but with much of the markup
7098 stripped for better readability.
7099 name = 'text'
7101 format = 'text'
7103 supported_image_types = []
7105 New in version 0.4.
7107 class sphinx.builders.manpage.ManualPageBuilder
7110 This builder produces manual pages in the groff format. You
7111 have to specify which documents are to be included in which man‐
7112 ual pages via the man_pages configuration value.
7113 name = 'man'
7115 format = 'man'
7117 supported_image_types = []
7119 New in version 1.0.
7121 class sphinx.builders.texinfo.TexinfoBuilder
7124 This builder produces Texinfo files that can be processed into
7125 Info files by the makeinfo program. You have to specify which
7126 documents are to be included in which Texinfo files via the tex‐
7127 info_documents configuration value.
7128 The Info format is the basis of the on-line help system used by
7130 GNU Emacs and the terminal-based program info. See texinfo-faq
7131 for more details. The Texinfo format is the official documenta‐
7132 tion system used by the GNU project. More information on Tex‐
7133 info can be found at https://www.gnu.org/software/texinfo/.
7134 name = 'texinfo'
7136 format = 'texinfo'
7138 supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
7140 New in version 1.1.
7142 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
7145 This builder uses a module that implements the Python serializa‐
7146 tion API (pickle, simplejson, phpserialize, and others) to dump
7147 the generated HTML documentation. The pickle builder is a sub‐
7148 class of it.
7149 A concrete subclass of this builder serializing to the PHP seri‐
7151 alization format could look like this:
7152 import phpserialize
7154 class PHPSerializedBuilder(SerializingHTMLBuilder):
7156 name = 'phpserialized'
7157 implementation = phpserialize
7158 out_suffix = '.file.phpdump'
7159 globalcontext_filename = 'globalcontext.phpdump'
7160 searchindex_filename = 'searchindex.phpdump'
7161 implementation
7163 A module that implements dump(), load(), dumps() and
7164 loads() functions that conform to the functions with the
7165 same names from the pickle module. Known modules imple‐
7166 menting this interface are simplejson, phpserialize,
7167 plistlib, and others.
7168 out_suffix
7170 The suffix for all regular files.
7171 globalcontext_filename
7173 The filename for the file that contains the “global con‐
7174 text”. This is a dict with some general configuration
7175 values such as the name of the project.
7176 searchindex_filename
7178 The filename for the search index Sphinx generates.
7179 See Serialization builder details for details about the output
7181 format.
7182 New in version 0.5.
7184 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
7187 This builder produces a directory with pickle files containing
7188 mostly HTML fragments and TOC information, for use of a web
7189 application (or custom postprocessing tool) that doesn’t use the
7190 standard HTML templates.
7191 See Serialization builder details for details about the output
7193 format.
7194 name = 'pickle'
7196 The old name web still works as well.
7197 format = 'html'
7199 supported_image_types = ['image/svg+xml', 'image/png',
7201 'image/gif', 'image/jpeg']
7202 The file suffix is .fpickle. The global context is called glob‐
7204 alcontext.pickle, the search index searchindex.pickle.
7205 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
7207 This builder produces a directory with JSON files containing
7208 mostly HTML fragments and TOC information, for use of a web
7209 application (or custom postprocessing tool) that doesn’t use the
7210 standard HTML templates.
7211 See Serialization builder details for details about the output
7213 format.
7214 name = 'json'
7216 format = 'html'
7218 supported_image_types = ['image/svg+xml', 'image/png',
7220 'image/gif', 'image/jpeg']
7221 The file suffix is .fjson. The global context is called global‐
7223 context.json, the search index searchindex.json.
7224 New in version 0.5.
7226 class sphinx.builders.gettext.MessageCatalogBuilder
7229 This builder produces gettext-style message catalogs. Each
7230 top-level file or subdirectory grows a single .pot catalog tem‐
7231 plate.
7232 See the documentation on intl for further reference.
7234 name = 'gettext'
7236 format = ''
7238 supported_image_types = []
7240 New in version 1.1.
7242 class sphinx.builders.changes.ChangesBuilder
7245 This builder produces an HTML overview of all versionadded, ver‐
7246 sionchanged and deprecated directives for the current version.
7247 This is useful to generate a ChangeLog file, for example.
7248 name = 'changes'
7250 format = ''
7252 supported_image_types = []
7254 class sphinx.builders.dummy.DummyBuilder
7256 This builder produces no output. The input is only parsed and
7257 checked for consistency. This is useful for linting purposes.
7258 name = 'dummy'
7260 supported_image_types = []
7262 New in version 1.4.
7264 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
7267 This builder scans all documents for external links, tries to
7268 open them with requests, and writes an overview which ones are
7269 broken and redirected to standard output and to output.txt in
7270 the output directory.
7271 name = 'linkcheck'
7273 format = ''
7275 supported_image_types = []
7277 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
7279 comes to use requests module.
7280 class sphinx.builders.xml.XMLBuilder
7283 This builder produces Docutils-native XML files. The output can
7284 be transformed with standard XML tools such as XSLT processors
7285 into arbitrary final forms.
7286 name = 'xml'
7288 format = 'xml'
7290 supported_image_types = []
7292 New in version 1.2.
7294 class sphinx.builders.xml.PseudoXMLBuilder
7297 This builder is used for debugging the Sphinx/Docutils “Reader
7298 to Transform to Writer” pipeline. It produces compact
7299 pretty-printed “pseudo-XML”, files where nesting is indicated by
7300 indentation (no end-tags). External attributes for all elements
7301 are output, and internal attributes for any leftover “pending”
7302 elements are also given.
7303 name = 'pseudoxml'
7305 format = 'pseudoxml'
7307 supported_image_types = []
7309 New in version 1.2.
7311 Built-in Sphinx extensions that offer more builders are:
7314 · doctest
7316 · coverage
7318 Serialization builder details
7320 All serialization builders outputs one file per source file and a few
7321 special files. They also copy the reST source files in the directory
7322 _sources under the output directory.
7323 The PickleHTMLBuilder is a builtin subclass that implements the pickle
7325 serialization interface.
7326 The files per source file have the extensions of out_suffix, and are
7328 arranged in directories just as the source files are. They unserialize
7329 to a dictionary (or dictionary like structure) with these keys:
7330 body The HTML “body” (that is, the HTML rendering of the source
7332 file), as rendered by the HTML translator.
7333 title The title of the document, as HTML (may contain markup).
7335 toc The table of contents for the file, rendered as an HTML <ul>.
7337 display_toc
7339 A boolean that is True if the toc contains more than one entry.
7340 current_page_name
7342 The document name of the current file.
7343 parents, prev and next
7345 Information about related chapters in the TOC tree. Each rela‐
7346 tion is a dictionary with the keys link (HREF for the relation)
7347 and title (title of the related document, as HTML). parents is
7348 a list of relations, while prev and next are a single relation.
7349 sourcename
7351 The name of the source file under _sources.
7352 The special files are located in the root output directory. They are:
7354 SerializingHTMLBuilder.globalcontext_filename
7356 A pickled dict with these keys:
7357 project, copyright, release, version
7359 The same values as given in the configuration file.
7360 style html_style.
7362 last_updated
7364 Date of last build.
7365 builder
7367 Name of the used builder, in the case of pickles this is
7368 always 'pickle'.
7369 titles A dictionary of all documents’ titles, as HTML strings.
7371 SerializingHTMLBuilder.searchindex_filename
7373 An index that can be used for searching the documentation. It
7374 is a pickled list with these entries:
7375 · A list of indexed docnames.
7377 · A list of document titles, as HTML strings, in the same order
7379 as the first list.
7380 · A dict mapping word roots (processed by an English-language
7382 stemmer) to a list of integers, which are indices into the
7383 first list.
7384 environment.pickle
7386 The build environment. This is always a pickle file, indepen‐
7387 dent of the builder and a copy of the environment that was used
7388 when the builder was started.
7389 Todo
7391 Document common members.
7392 Unlike the other pickle files this pickle file requires that the
7394 sphinx package is available on unpickling.
7395
7397 Since many projects will need special features in their documentation,
7398 Sphinx allows adding “extensions” to the build process, each of which
7399 can modify almost any aspect of document processing.
7400 This chapter describes the extensions bundled with Sphinx. For the API
7402 documentation on writing your own extension, refer to dev-extensions.
7403 Built-in extensions
7405 These extensions are built in and can be activated by respective
7406 entries in the extensions configuration value:
7407 sphinx.ext.autodoc – Include documentation from docstrings
7409 This extension can import the modules you are documenting, and pull in
7410 documentation from docstrings in a semi-automatic way.
7411 NOTE:
7413 For Sphinx (actually, the Python interpreter that executes Sphinx)
7414 to find your module, it must be importable. That means that the
7415 module or the package must be in one of the directories on sys.path
7416 – adapt your sys.path in the configuration file accordingly.
7417 WARNING:
7419 autodoc imports the modules to be documented. If any modules have
7420 side effects on import, these will be executed by autodoc when
7421 sphinx-build is run.
7422 If you document scripts (as opposed to library modules), make sure
7424 their main routine is protected by a if __name__ == '__main__' con‐
7425 dition.
7426 For this to work, the docstrings must of course be written in correct
7428 reStructuredText. You can then use all of the usual Sphinx markup in
7429 the docstrings, and it will end up correctly in the documentation.
7430 Together with hand-written documentation, this technique eases the pain
7431 of having to maintain two locations for documentation, while at the
7432 same time avoiding auto-generated-looking pure API documentation.
7433 If you prefer NumPy or Google style docstrings over reStructuredText,
7435 you can also enable the napoleon extension. napoleon is a preprocessor
7436 that converts your docstrings to correct reStructuredText before
7437 autodoc processes them.
7438 Directives
7440 autodoc provides several directives that are versions of the usual
7441 py:module, py:class and so forth. On parsing time, they import the
7442 corresponding module and extract the docstring of the given objects,
7443 inserting them into the page source under a suitable py:module,
7444 py:class etc. directive.
7445 NOTE:
7447 Just as py:class respects the current py:module, autoclass will also
7448 do so. Likewise, automethod will respect the current py:class.
7449 .. automodule::
7451 .. autoclass::
7453 .. autoexception::
7455 Document a module, class or exception. All three directives
7456 will by default only insert the docstring of the object itself:
7457 .. autoclass:: Noodle
7459 will produce source like this:
7461 .. class:: Noodle
7463 Noodle's docstring.
7465 The “auto” directives can also contain content of their own, it
7467 will be inserted into the resulting non-auto directive source
7468 after the docstring (but before any automatic member documenta‐
7469 tion).
7470 Therefore, you can also mix automatic and non-automatic member
7472 documentation, like so:
7473 .. autoclass:: Noodle
7475 :members: eat, slurp
7476 .. method:: boil(time=10)
7478 Boil the noodle *time* minutes.
7480 Options and advanced usage
7482 · If you want to automatically document members, there’s a mem‐
7484 bers option:
7485 .. automodule:: noodle
7487 :members:
7488 will document all module members (recursively), and
7490 .. autoclass:: Noodle
7492 :members:
7493 will document all non-private member functions and properties
7495 (that is, those whose name doesn’t start with _).
7496 For modules, __all__ will be respected when looking for mem‐
7498 bers unless you give the ignore-module-all flag option. With‐
7499 out ignore-module-all, the order of the members will also be
7500 the order in __all__.
7501 You can also give an explicit list of members; only these will
7503 then be documented:
7504 .. autoclass:: Noodle
7506 :members: eat, slurp
7507 · If you want to make the members option (or other options
7509 described below) the default, see autodoc_default_options.
7510 TIP:
7512 You can use a negated form, 'no-flag', as an option of
7513 autodoc directive, to disable it temporarily. For example:
7514 .. automodule:: foo
7516 :no-undoc-members:
7517 · Members without docstrings will be left out, unless you give
7519 the undoc-members flag option:
7520 .. automodule:: noodle
7522 :members:
7523 :undoc-members:
7524 · “Private” members (that is, those named like _private or
7526 __private) will be included if the private-members flag option
7527 is given.
7528 New in version 1.1.
7530 · Python “special” members (that is, those named like __spe‐
7533 cial__) will be included if the special-members flag option is
7534 given:
7535 .. autoclass:: my.Class
7537 :members:
7538 :private-members:
7539 :special-members:
7540 would document both “private” and “special” members of the
7542 class.
7543 New in version 1.1.
7545 Changed in version 1.2: The option can now take arguments,
7548 i.e. the special members to document.
7549 · For classes and exceptions, members inherited from base
7552 classes will be left out when documenting all members, unless
7553 you give the inherited-members flag option, in addition to
7554 members:
7555 .. autoclass:: Noodle
7557 :members:
7558 :inherited-members:
7559 This can be combined with undoc-members to document all avail‐
7561 able members of the class or module.
7562 Note: this will lead to markup errors if the inherited members
7564 come from a module whose docstrings are not reST formatted.
7565 New in version 0.3.
7567 · It’s possible to override the signature for explicitly docu‐
7570 mented callable objects (functions, methods, classes) with the
7571 regular syntax that will override the signature gained from
7572 introspection:
7573 .. autoclass:: Noodle(type)
7575 .. automethod:: eat(persona)
7577 This is useful if the signature from the method is hidden by a
7579 decorator.
7580 New in version 0.4.
7582 · The automodule, autoclass and autoexception directives also
7585 support a flag option called show-inheritance. When given, a
7586 list of base classes will be inserted just below the class
7587 signature (when used with automodule, this will be inserted
7588 for every class that is documented in the module).
7589 New in version 0.4.
7591 · All autodoc directives support the noindex flag option that
7594 has the same effect as for standard py:function etc. direc‐
7595 tives: no index entries are generated for the documented
7596 object (and all autodocumented members).
7597 New in version 0.4.
7599 · automodule also recognizes the synopsis, platform and depre‐
7602 cated options that the standard py:module directive supports.
7603 New in version 0.5.
7605 · automodule and autoclass also has an member-order option that
7608 can be used to override the global value of
7609 autodoc_member_order for one directive.
7610 New in version 0.6.
7612 · The directives supporting member documentation also have a
7615 exclude-members option that can be used to exclude single mem‐
7616 ber names from documentation, if all members are to be docu‐
7617 mented.
7618 New in version 0.6.
7620 · In an automodule directive with the members option set, only
7623 module members whose __module__ attribute is equal to the mod‐
7624 ule name as given to automodule will be documented. This is
7625 to prevent documentation of imported classes or functions.
7626 Set the imported-members option if you want to prevent this
7627 behavior and document all available members. Note that
7628 attributes from imported modules will not be documented,
7629 because attribute documentation is discovered by parsing the
7630 source file of the current module.
7631 New in version 1.2.
7633 · Add a list of modules in the autodoc_mock_imports to prevent
7636 import errors to halt the building process when some external
7637 dependencies are not importable at build time.
7638 New in version 1.3.
7640 .. autofunction::
7643 .. autodecorator::
7645 .. autodata::
7647 .. automethod::
7649 .. autoattribute::
7651 These work exactly like autoclass etc., but do not offer the
7652 options used for automatic member documentation.
7653 autodata and autoattribute support the annotation option. The
7655 option controls how the value of variable is shown. If speci‐
7656 fied without arguments, only the name of the variable will be
7657 printed, and its value is not shown:
7658 .. autodata:: CD_DRIVE
7660 :annotation:
7661 If the option specified with arguments, it is printed after the
7663 name as a value of the variable:
7664 .. autodata:: CD_DRIVE
7666 :annotation: = your CD device name
7667 By default, without annotation option, Sphinx tries to obtain
7669 the value of the variable and print it after the name.
7670 For module data members and class attributes, documentation can
7672 either be put into a comment with special formatting (using a #:
7673 to start the comment instead of just #), or in a docstring after
7674 the definition. Comments need to be either on a line of their
7675 own before the definition, or immediately after the assignment
7676 on the same line. The latter form is restricted to one line
7677 only.
7678 This means that in the following class definition, all
7680 attributes can be autodocumented:
7681 class Foo:
7683 """Docstring for class Foo."""
7684 #: Doc comment for class attribute Foo.bar.
7686 #: It can have multiple lines.
7687 bar = 1
7688 flox = 1.5 #: Doc comment for Foo.flox. One line only.
7690 baz = 2
7692 """Docstring for class attribute Foo.baz."""
7693 def __init__(self):
7695 #: Doc comment for instance attribute qux.
7696 self.qux = 3
7697 self.spam = 4
7699 """Docstring for instance attribute spam."""
7700 Changed in version 0.6: autodata and autoattribute can now
7702 extract docstrings.
7703 Changed in version 1.1: Comment docs are now allowed on the same
7706 line after an assignment.
7707 Changed in version 1.2: autodata and autoattribute have an anno‐
7710 tation option.
7711 Changed in version 2.0: autodecorator added.
7714 NOTE:
7717 If you document decorated functions or methods, keep in mind
7718 that autodoc retrieves its docstrings by importing the module
7719 and inspecting the __doc__ attribute of the given function or
7720 method. That means that if a decorator replaces the deco‐
7721 rated function with another, it must copy the original
7722 __doc__ to the new function.
7723 From Python 2.5, functools.wraps() can be used to create
7725 well-behaved decorating functions.
7726 Configuration
7728 There are also config values that you can set:
7729 autoclass_content
7731 This value selects what content will be inserted into the main
7732 body of an autoclass directive. The possible values are:
7733 "class"
7735 Only the class’ docstring is inserted. This is the
7736 default. You can still document __init__ as a separate
7737 method using automethod or the members option to
7738 autoclass.
7739 "both" Both the class’ and the __init__ method’s docstring are
7741 concatenated and inserted.
7742 "init" Only the __init__ method’s docstring is inserted.
7744 New in version 0.3.
7746 If the class has no __init__ method or if the __init__ method’s
7749 docstring is empty, but the class has a __new__ method’s doc‐
7750 string, it is used instead.
7751 New in version 1.4.
7753 autodoc_member_order
7756 This value selects if automatically documented members are
7757 sorted alphabetical (value 'alphabetical'), by member type
7758 (value 'groupwise') or by source order (value 'bysource'). The
7759 default is alphabetical.
7760 Note that for source order, the module must be a Python module
7762 with the source code available.
7763 New in version 0.6.
7765 Changed in version 1.0: Support for 'bysource'.
7768 autodoc_default_flags
7771 This value is a list of autodoc directive flags that should be
7772 automatically applied to all autodoc directives. The supported
7773 flags are 'members', 'undoc-members', 'private-members', 'spe‐
7774 cial-members', 'inherited-members', 'show-inheritance',
7775 'ignore-module-all' and 'exclude-members'.
7776 New in version 1.0.
7778 Deprecated since version 1.8: Integrated into
7781 autodoc_default_options.
7782 autodoc_default_options
7785 The default options for autodoc directives. They are applied to
7786 all autodoc directives automatically. It must be a dictionary
7787 which maps option names to the values. For example:
7788 autodoc_default_options = {
7790 'members': 'var1, var2',
7791 'member-order': 'bysource',
7792 'special-members': '__init__',
7793 'undoc-members': True,
7794 'exclude-members': '__weakref__'
7795 }
7796 Setting None or True to the value is equivalent to giving only
7798 the option name to the directives.
7799 The supported options are 'members', 'member-order', 'undoc-mem‐
7801 bers', 'private-members', 'special-members', 'inherited-mem‐
7802 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
7803 bers' and 'exclude-members'.
7804 New in version 1.8.
7806 Changed in version 2.0: Accepts True as a value.
7809 Changed in version 2.1: Added 'imported-members'.
7812 autodoc_docstring_signature
7815 Functions imported from C modules cannot be introspected, and
7816 therefore the signature for such functions cannot be automati‐
7817 cally determined. However, it is an often-used convention to
7818 put the signature into the first line of the function’s doc‐
7819 string.
7820 If this boolean value is set to True (which is the default),
7822 autodoc will look at the first line of the docstring for func‐
7823 tions and methods, and if it looks like a signature, use the
7824 line as the signature and remove it from the docstring content.
7825 New in version 1.1.
7827 autodoc_mock_imports
7830 This value contains a list of modules to be mocked up. This is
7831 useful when some external dependencies are not met at build time
7832 and break the building process. You may only specify the root
7833 package of the dependencies themselves and omit the sub-modules:
7834 autodoc_mock_imports = ["django"]
7836 Will mock all imports under the django package.
7838 New in version 1.3.
7840 Changed in version 1.6: This config value only requires to
7843 declare the top-level modules that should be mocked.
7844 autodoc_typehints
7847 This value controls how to represents typehints. The setting
7848 takes the following values:
7849 · 'signature' – Show typehints as its signature (default)
7851 · 'none' – Do not show typehints
7853 autodoc_warningiserror
7855 This value controls the behavior of sphinx-build -W during
7856 importing modules. If False is given, autodoc forcedly sup‐
7857 presses the error if the imported module emits warnings. By
7858 default, True.
7859 autodoc_inherit_docstrings
7861 This value controls the docstrings inheritance. If set to True
7862 the docstring for classes or methods, if not explicitly set, is
7863 inherited form parents.
7864 The default is True.
7866 New in version 1.7.
7868 suppress_warnings
7871 autodoc supports to suppress warning messages via suppress_warn‐
7872 ings. It allows following warnings types in addition:
7873 · autodoc
7875 · autodoc.import_object
7877 Docstring preprocessing
7879 autodoc provides the following additional events:
7880 autodoc-process-docstring(app, what, name, obj, options, lines)
7882 New in version 0.4.
7883 Emitted when autodoc has read and processed a docstring. lines
7886 is a list of strings – the lines of the processed docstring –
7887 that the event handler can modify in place to change what Sphinx
7888 puts into the output.
7889 Parameters
7891 · app – the Sphinx application object
7893 · what – the type of the object which the docstring
7895 belongs to (one of "module", "class", "exception",
7896 "function", "method", "attribute")
7897 · name – the fully qualified name of the object
7899 · obj – the object itself
7901 · options – the options given to the directive: an object
7903 with attributes inherited_members, undoc_members,
7904 show_inheritance and noindex that are true if the flag
7905 option of same name was given to the auto directive
7906 · lines – the lines of the docstring, see above
7908 autodoc-process-signature(app, what, name, obj, options, signature,
7910 return_annotation)
7911 New in version 0.5.
7912 Emitted when autodoc has formatted a signature for an object.
7915 The event handler can return a new tuple (signature,
7916 return_annotation) to change what Sphinx puts into the output.
7917 Parameters
7919 · app – the Sphinx application object
7921 · what – the type of the object which the docstring
7923 belongs to (one of "module", "class", "exception",
7924 "function", "method", "attribute")
7925 · name – the fully qualified name of the object
7927 · obj – the object itself
7929 · options – the options given to the directive: an object
7931 with attributes inherited_members, undoc_members,
7932 show_inheritance and noindex that are true if the flag
7933 option of same name was given to the auto directive
7934 · signature – function signature, as a string of the form
7936 "(parameter_1, parameter_2)", or None if introspection
7937 didn’t succeed and signature wasn’t specified in the
7938 directive.
7939 · return_annotation – function return annotation as a
7941 string of the form " -> annotation", or None if there
7942 is no return annotation
7943 The sphinx.ext.autodoc module provides factory functions for commonly
7945 needed docstring processing in event autodoc-process-docstring:
7946 sphinx.ext.autodoc.cut_lines(pre: int, post: int = 0, what: str = None)
7948 -> Callable
7949 Return a listener that removes the first pre and last post lines
7950 of every docstring. If what is a sequence of strings, only doc‐
7951 strings of a type in what will be processed.
7952 Use like this (e.g. in the setup() function of conf.py):
7954 from sphinx.ext.autodoc import cut_lines
7956 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
7957 This can (and should) be used in place of automodule_skip_lines.
7959 sphinx.ext.autodoc.between(marker: str, what: Sequence[str] = None,
7961 keepempty: bool = False, exclude: bool = False) -> Callable
7962 Return a listener that either keeps, or if exclude is True
7963 excludes, lines between lines that match the marker regular
7964 expression. If no line matches, the resulting docstring would
7965 be empty, so no change will be made unless keepempty is true.
7966 If what is a sequence of strings, only docstrings of a type in
7968 what will be processed.
7969 Skipping members
7971 autodoc allows the user to define a custom method for determining
7972 whether a member should be included in the documentation by using the
7973 following event:
7974 autodoc-skip-member(app, what, name, obj, skip, options)
7976 New in version 0.5.
7977 Emitted when autodoc has to decide whether a member should be
7980 included in the documentation. The member is excluded if a han‐
7981 dler returns True. It is included if the handler returns False.
7982 If more than one enabled extension handles the autodoc-skip-mem‐
7984 ber event, autodoc will use the first non-None value returned by
7985 a handler. Handlers should return None to fall back to the
7986 skipping behavior of autodoc and other enabled extensions.
7987 Parameters
7989 · app – the Sphinx application object
7991 · what – the type of the object which the docstring
7993 belongs to (one of "module", "class", "exception",
7994 "function", "method", "attribute")
7995 · name – the fully qualified name of the object
7997 · obj – the object itself
7999 · skip – a boolean indicating if autodoc will skip this
8001 member if the user handler does not override the deci‐
8002 sion
8003 · options – the options given to the directive: an object
8005 with attributes inherited_members, undoc_members,
8006 show_inheritance and noindex that are true if the flag
8007 option of same name was given to the auto directive
8008 sphinx.ext.autosectionlabel – Allow reference sections using its title
8010 New in version 1.4.
8011 This extension allows you to refer sections its title. This affects to
8014 the reference role (ref).
8015 For example:
8017 A Plain Title
8019 -------------
8020 This is the text of the section.
8022 It refers to the section title, see :ref:`A Plain Title`.
8024 Internally, this extension generates the labels for each section. If
8026 same section names are used in whole of document, any one is used for a
8027 target by default. The autosectionlabel_prefix_document configuration
8028 variable can be used to make headings which appear multiple times but
8029 in different documents unique.
8030 Configuration
8032 autosectionlabel_prefix_document
8033 True to prefix each section label with the name of the document
8034 it is in, followed by a colon. For example, index:Introduction
8035 for a section called Introduction that appears in document
8036 index.rst. Useful for avoiding ambiguity when the same section
8037 heading appears in different documents.
8038 autosectionlabel_maxdepth
8040 If set, autosectionlabel chooses the sections for labeling by
8041 its depth. For example, when set 1 to autosectionlabel_maxdepth,
8042 labels are generated only for top level sections, and deeper
8043 sections are not labeled. It defaults to None (disabled).
8044 sphinx.ext.autosummary – Generate autodoc summaries
8046 New in version 0.6.
8047 This extension generates function/method/attribute summary lists, simi‐
8050 lar to those output e.g. by Epydoc and other API doc generation tools.
8051 This is especially useful when your docstrings are long and detailed,
8052 and putting each one of them on a separate page makes them easier to
8053 read.
8054 The sphinx.ext.autosummary extension does this in two parts:
8056 1. There is an autosummary directive for generating summary listings
8058 that contain links to the documented items, and short summary blurbs
8059 extracted from their docstrings.
8060 2. Optionally, the convenience script sphinx-autogen or the new
8062 autosummary_generate config value can be used to generate short
8063 “stub” files for the entries listed in the autosummary directives.
8064 These files by default contain only the corresponding
8065 sphinx.ext.autodoc directive, but can be customized with templates.
8066 .. autosummary::
8068 Insert a table that contains links to documented items, and a
8069 short summary blurb (the first sentence of the docstring) for
8070 each of them.
8071 The autosummary directive can also optionally serve as a toctree
8073 entry for the included items. Optionally, stub .rst files for
8074 these items can also be automatically generated.
8075 For example,
8077 .. currentmodule:: sphinx
8079 .. autosummary::
8081 environment.BuildEnvironment
8083 util.relative_uri
8084 produces a table like this:
8086 ┌──────────────────────────┬────────────────────────────┐
8088 │environment.BuildEnviron‐ │ The environment in which │
8089 │ment([app]) │ the ReST files are trans‐ │
8090 │ │ lated. │
8091 ├──────────────────────────┼────────────────────────────┤
8092 │util.relative_uri(base, │ Return a relative URL from │
8093 │to) │ base to to. │
8094 └──────────────────────────┴────────────────────────────┘
8095 Autosummary preprocesses the docstrings and signatures with the
8097 same autodoc-process-docstring and autodoc-process-signature
8098 hooks as autodoc.
8099 Options
8101 · If you want the autosummary table to also serve as a toctree
8103 entry, use the toctree option, for example:
8104 .. autosummary::
8106 :toctree: DIRNAME
8107 sphinx.environment.BuildEnvironment
8109 sphinx.util.relative_uri
8110 The toctree option also signals to the sphinx-autogen script
8112 that stub pages should be generated for the entries listed in
8113 this directive. The option accepts a directory name as an
8114 argument; sphinx-autogen will by default place its output in
8115 this directory. If no argument is given, output is placed in
8116 the same directory as the file that contains the directive.
8117 · If you don’t want the autosummary to show function signatures
8119 in the listing, include the nosignatures option:
8120 .. autosummary::
8122 :nosignatures:
8123 sphinx.environment.BuildEnvironment
8125 sphinx.util.relative_uri
8126 · You can specify a custom template with the template option.
8128 For example,
8129 .. autosummary::
8131 :template: mytemplate.rst
8132 sphinx.environment.BuildEnvironment
8134 would use the template mytemplate.rst in your templates_path
8136 to generate the pages for all entries listed. See Customizing
8137 templates below.
8138 New in version 1.0.
8140 sphinx-autogen – generate autodoc stub pages
8143 The sphinx-autogen script can be used to conveniently generate stub
8144 documentation pages for items included in autosummary listings.
8145 For example, the command
8147 $ sphinx-autogen -o generated *.rst
8149 will read all autosummary tables in the *.rst files that have the :toc‐
8151 tree: option set, and output corresponding stub pages in directory gen‐
8152 erated for all documented items. The generated pages by default con‐
8153 tain text of the form:
8154 sphinx.util.relative_uri
8156 ========================
8157 .. autofunction:: sphinx.util.relative_uri
8159 If the -o option is not given, the script will place the output files
8161 in the directories specified in the :toctree: options.
8162 For more information, refer to the sphinx-autogen documentation
8164 Generating stub pages automatically
8166 If you do not want to create stub pages with sphinx-autogen, you can
8167 also use these config values:
8168 autosummary_generate
8170 Boolean indicating whether to scan all found documents for auto‐
8171 summary directives, and to generate stub pages for each.
8172 Can also be a list of documents for which stub pages should be
8174 generated.
8175 The new files will be placed in the directories specified in the
8177 :toctree: options of the directives.
8178 autosummary_mock_imports
8180 This value contains a list of modules to be mocked up. See
8181 autodoc_mock_imports for more details. It defaults to
8182 autodoc_mock_imports.
8183 New in version 2.0.
8185 autosummary_imported_members
8188 A boolean flag indicating whether to document classes and func‐
8189 tions imported in modules. Default is False
8190 New in version 2.1.
8192 Customizing templates
8195 New in version 1.0.
8196 You can customize the stub page templates, in a similar way as the HTML
8199 Jinja templates, see templating. (TemplateBridge is not supported.)
8200 NOTE:
8202 If you find yourself spending much time tailoring the stub tem‐
8203 plates, this may indicate that it’s a better idea to write custom
8204 narrative documentation instead.
8205 Autosummary uses the following Jinja template files:
8207 · autosummary/base.rst – fallback template
8209 · autosummary/module.rst – template for modules
8211 · autosummary/class.rst – template for classes
8213 · autosummary/function.rst – template for functions
8215 · autosummary/attribute.rst – template for class attributes
8217 · autosummary/method.rst – template for class methods
8219 The following variables available in the templates:
8221 name Name of the documented object, excluding the module and class
8223 parts.
8224 objname
8226 Name of the documented object, excluding the module parts.
8227 fullname
8229 Full name of the documented object, including module and class
8230 parts.
8231 module Name of the module the documented object belongs to.
8233 class Name of the class the documented object belongs to. Only avail‐
8235 able for methods and attributes.
8236 underline
8238 A string containing len(full_name) * '='. Use the underline fil‐
8239 ter instead.
8240 members
8242 List containing names of all members of the module or class.
8243 Only available for modules and classes.
8244 inherited_members
8246 List containing names of all inherited members of class. Only
8247 available for classes.
8248 New in version 1.8.0.
8250 functions
8253 List containing names of “public” functions in the module.
8254 Here, “public” here means that the name does not start with an
8255 underscore. Only available for modules.
8256 classes
8258 List containing names of “public” classes in the module. Only
8259 available for modules.
8260 exceptions
8262 List containing names of “public” exceptions in the module.
8263 Only available for modules.
8264 methods
8266 List containing names of “public” methods in the class. Only
8267 available for classes.
8268 attributes
8270 List containing names of “public” attributes in the class. Only
8271 available for classes.
8272 Additionally, the following filters are available
8274 escape(s)
8276 Escape any special characters in the text to be used in format‐
8277 ting RST contexts. For instance, this prevents asterisks making
8278 things bold. This replaces the builtin Jinja escape filter that
8279 does html-escaping.
8280 underline(s, line='=')
8282 Add a title underline to a piece of text.
8283 For instance, {{ fullname | escape | underline }} should be used to
8285 produce the title of a page.
8286 NOTE:
8288 You can use the autosummary directive in the stub pages. Stub pages
8289 are generated also based on these directives.
8290 sphinx.ext.coverage – Collect doc coverage stats
8292 This extension features one additional builder, the CoverageBuilder.
8293 class sphinx.ext.coverage.CoverageBuilder
8295 To use this builder, activate the coverage extension in your
8296 configuration file and give -b coverage on the command line.
8297 Todo
8299 Write this section.
8300 Several configuration values can be used to specify what the builder
8302 should check:
8303 coverage_ignore_modules
8305 coverage_ignore_functions
8307 coverage_ignore_classes
8309 coverage_ignore_pyobjects
8311 List of Python regular expressions.
8312 If any of these regular expressions matches any part of the full
8314 import path of a Python object, that Python object is excluded
8315 from the documentation coverage report.
8316 New in version 2.1.
8318 coverage_c_path
8321 coverage_c_regexes
8323 coverage_ignore_c_items
8325 coverage_write_headline
8327 Set to False to not write headlines.
8328 New in version 1.1.
8330 coverage_skip_undoc_in_source
8333 Skip objects that are not documented in the source with a doc‐
8334 string. False by default.
8335 New in version 1.1.
8337 sphinx.ext.doctest – Test snippets in the documentation
8340 This extension allows you to test snippets in the documentation in a
8341 natural way. It works by collecting specially-marked up code blocks
8342 and running them as doctest tests.
8343 Within one document, test code is partitioned in groups, where each
8345 group consists of:
8346 · zero or more setup code blocks (e.g. importing the module to test)
8348 · one or more test blocks
8350 When building the docs with the doctest builder, groups are collected
8352 for each document and run one after the other, first executing setup
8353 code blocks, then the test blocks in the order they appear in the file.
8354 There are two kinds of test blocks:
8356 · doctest-style blocks mimic interactive sessions by interleaving
8358 Python code (including the interpreter prompt) and output.
8359 · code-output-style blocks consist of an ordinary piece of Python code,
8361 and optionally, a piece of output for that code.
8362 Directives
8364 The group argument below is interpreted as follows: if it is empty, the
8365 block is assigned to the group named default. If it is *, the block is
8366 assigned to all groups (including the default group). Otherwise, it
8367 must be a comma-separated list of group names.
8368 .. testsetup:: [group]
8370 A setup code block. This code is not shown in the output for
8371 other builders, but executed before the doctests of the group(s)
8372 it belongs to.
8373 .. testcleanup:: [group]
8375 A cleanup code block. This code is not shown in the output for
8376 other builders, but executed after the doctests of the group(s)
8377 it belongs to.
8378 New in version 1.1.
8380 .. doctest:: [group]
8383 A doctest-style code block. You can use standard doctest flags
8384 for controlling how actual output is compared with what you give
8385 as output. The default set of flags is specified by the
8386 doctest_default_flags configuration variable.
8387 This directive supports three options:
8389 · hide, a flag option, hides the doctest block in other
8391 builders. By default it is shown as a highlighted doctest
8392 block.
8393 · options, a string option, can be used to give a comma-sepa‐
8395 rated list of doctest flags that apply to each example in the
8396 tests. (You still can give explicit flags per example, with
8397 doctest comments, but they will show up in other builders
8398 too.)
8399 · pyversion, a string option, can be used to specify the
8401 required Python version for the example to be tested. For
8402 instance, in the following case the example will be tested
8403 only for Python versions greater than 3.3:
8404 .. doctest::
8406 :pyversion: > 3.3
8407 The following operands are supported:
8409 · ~=: Compatible release clause
8411 · ==: Version matching clause
8413 · !=: Version exclusion clause
8415 · <=, >=: Inclusive ordered comparison clause
8417 · <, >: Exclusive ordered comparison clause
8419 · ===: Arbitrary equality clause.
8421 pyversion option is followed PEP-440: Version Specifiers.
8423 New in version 1.6.
8425 Changed in version 1.7: Supported PEP-440 operands and nota‐
8428 tions
8429 Note that like with standard doctests, you have to use
8432 <BLANKLINE> to signal a blank line in the expected output. The
8433 <BLANKLINE> is removed when building presentation output (HTML,
8434 LaTeX etc.).
8435 Also, you can give inline doctest options, like in doctest:
8437 >>> datetime.date.now() # doctest: +SKIP
8439 datetime.date(2008, 1, 1)
8440 They will be respected when the test is run, but stripped from
8442 presentation output.
8443 .. testcode:: [group]
8445 A code block for a code-output-style test.
8446 This directive supports one option:
8448 · hide, a flag option, hides the code block in other builders.
8450 By default it is shown as a highlighted code block.
8451 NOTE:
8453 Code in a testcode block is always executed all at once, no
8454 matter how many statements it contains. Therefore, output
8455 will not be generated for bare expressions – use print.
8456 Example:
8457 .. testcode::
8459 1+1 # this will give no output!
8461 print 2+2 # this will give output
8462 .. testoutput::
8464 4
8466 Also, please be aware that since the doctest module does not
8468 support mixing regular output and an exception message in the
8469 same snippet, this applies to testcode/testoutput as well.
8470 .. testoutput:: [group]
8472 The corresponding output, or the exception message, for the last
8473 testcode block.
8474 This directive supports two options:
8476 · hide, a flag option, hides the output block in other builders.
8478 By default it is shown as a literal block without highlight‐
8479 ing.
8480 · options, a string option, can be used to give doctest flags
8482 (comma-separated) just like in normal doctest blocks.
8483 Example:
8485 .. testcode::
8487 print 'Output text.'
8489 .. testoutput::
8491 :hide:
8492 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
8493 Output text.
8495 The following is an example for the usage of the directives. The test
8497 via doctest and the test via testcode and testoutput are equivalent.
8498 The parrot module
8500 =================
8501 .. testsetup:: *
8503 import parrot
8505 The parrot module is a module about parrots.
8507 Doctest example:
8509 .. doctest::
8511 >>> parrot.voom(3000)
8513 This parrot wouldn't voom if you put 3000 volts through it!
8514 Test-Output example:
8516 .. testcode::
8518 parrot.voom(3000)
8520 This would output:
8522 .. testoutput::
8524 This parrot wouldn't voom if you put 3000 volts through it!
8526 Skipping tests conditionally
8528 skipif, a string option, can be used to skip directives conditionally.
8529 This may be useful e.g. when a different set of tests should be run
8530 depending on the environment (hardware, network/VPN, optional dependen‐
8531 cies or different versions of dependencies). The skipif option is sup‐
8532 ported by all of the doctest directives. Below are typical use cases
8533 for skipif when used for different directives:
8534 · testsetup and testcleanup
8536 · conditionally skip test setup and/or cleanup
8538 · customize setup/cleanup code per environment
8540 · doctest
8542 · conditionally skip both a test and its output verification
8544 · testcode
8546 · conditionally skip a test
8548 · customize test code per environment
8550 · testoutput
8552 · conditionally skip output assertion for a skipped test
8554 · expect different output depending on the environment
8556 The value of the skipif option is evaluated as a Python expression. If
8558 the result is a true value, the directive is omitted from the test run
8559 just as if it wasn’t present in the file at all.
8560 Instead of repeating an expression, the doctest_global_setup configura‐
8562 tion option can be used to assign it to a variable which can then be
8563 used instead.
8564 Here’s an example which skips some tests if Pandas is not installed:
8566 conf.py
8568 extensions = ['sphinx.ext.doctest']
8570 doctest_global_setup = '''
8571 try:
8572 import pandas as pd
8573 except ImportError:
8574 pd = None
8575 '''
8576 contents.rst
8578 .. testsetup::
8580 :skipif: pd is None
8581 data = pd.Series([42])
8583 .. doctest::
8585 :skipif: pd is None
8586 >>> data.iloc[0]
8588 42
8589 .. testcode::
8591 :skipif: pd is None
8592 print(data.iloc[-1])
8594 .. testoutput::
8596 :skipif: pd is None
8597 42
8599 Configuration
8601 The doctest extension uses the following configuration values:
8602 doctest_default_flags
8604 By default, these options are enabled:
8605 · ELLIPSIS, allowing you to put ellipses in the expected output
8607 that match anything in the actual output;
8608 · IGNORE_EXCEPTION_DETAIL, causing everything following the
8610 leftmost colon and any module information in the exception
8611 name to be ignored;
8612 · DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
8614 “1” is given – the default behavior of accepting this substi‐
8615 tution is a relic of pre-Python 2.2 times.
8616 New in version 1.5.
8618 doctest_path
8621 A list of directories that will be added to sys.path when the
8622 doctest builder is used. (Make sure it contains absolute
8623 paths.)
8624 doctest_global_setup
8626 Python code that is treated like it were put in a testsetup
8627 directive for every file that is tested, and for every group.
8628 You can use this to e.g. import modules you will always need in
8629 your doctests.
8630 New in version 0.6.
8632 doctest_global_cleanup
8635 Python code that is treated like it were put in a testcleanup
8636 directive for every file that is tested, and for every group.
8637 You can use this to e.g. remove any temporary files that the
8638 tests leave behind.
8639 New in version 1.1.
8641 doctest_test_doctest_blocks
8644 If this is a nonempty string (the default is 'default'), stan‐
8645 dard reST doctest blocks will be tested too. They will be
8646 assigned to the group name given.
8647 reST doctest blocks are simply doctests put into a paragraph of
8649 their own, like so:
8650 Some documentation text.
8652 >>> print 1
8654 1
8655 Some more documentation text.
8657 (Note that no special :: is used to introduce a doctest block;
8659 docutils recognizes them from the leading >>>. Also, no addi‐
8660 tional indentation is used, though it doesn’t hurt.)
8661 If this value is left at its default value, the above snippet is
8663 interpreted by the doctest builder exactly like the following:
8664 Some documentation text.
8666 .. doctest::
8668 >>> print 1
8670 1
8671 Some more documentation text.
8673 This feature makes it easy for you to test doctests in doc‐
8675 strings included with the autodoc extension without marking them
8676 up with a special directive.
8677 Note though that you can’t have blank lines in reST doctest
8679 blocks. They will be interpreted as one block ending and
8680 another one starting. Also, removal of <BLANKLINE> and #
8681 doctest: options only works in doctest blocks, though you may
8682 set trim_doctest_flags to achieve that in all code blocks with
8683 Python console content.
8684 sphinx.ext.extlinks – Markup to shorten external links
8686 Module author: Georg Brandl
8687 New in version 1.0.
8689 This extension is meant to help with the common pattern of having many
8692 external links that point to URLs on one and the same site, e.g. links
8693 to bug trackers, version control web interfaces, or simply subpages in
8694 other websites. It does so by providing aliases to base URLs, so that
8695 you only need to give the subpage name when creating a link.
8696 Let’s assume that you want to include many links to issues at the
8698 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
8699 Typing this URL again and again is tedious, so you can use extlinks to
8700 avoid repeating yourself.
8701 The extension adds a config value:
8703 extlinks
8705 This config value must be a dictionary of external sites, map‐
8706 ping unique short alias names to a base URL and a prefix. For
8707 example, to create an alias for the above mentioned issues, you
8708 would add
8709 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
8711 'issue ')}
8712 Now, you can use the alias name as a new role, e.g.
8714 :issue:`123`. This then inserts a link to
8715 https://github.com/sphinx-doc/sphinx/issues/123. As you can
8716 see, the target given in the role is substituted in the base URL
8717 in the place of %s.
8718 The link caption depends on the second item in the tuple, the
8720 prefix:
8721 · If the prefix is None, the link caption is the full URL.
8723 · If the prefix is the empty string, the link caption is the
8725 partial URL given in the role content (123 in this case.)
8726 · If the prefix is a non-empty string, the link caption is the
8728 partial URL, prepended by the prefix – in the above example,
8729 the link caption would be issue 123.
8730 You can also use the usual “explicit title” syntax supported by
8732 other roles that generate links, i.e. :issue:`this issue <123>`.
8733 In this case, the prefix is not relevant.
8734 NOTE:
8736 Since links are generated from the role in the reading stage, they
8737 appear as ordinary links to e.g. the linkcheck builder.
8738 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
8740 New in version 1.4.
8741 Changed in version 2.0: Support CNAME file
8744 This extension creates .nojekyll file on generated HTML directory to
8747 publish the document on GitHub Pages.
8748 It also creates a CNAME file for custom domains when html_baseurl set.
8750 sphinx.ext.graphviz – Add Graphviz graphs
8752 New in version 0.6.
8753 This extension allows you to embed Graphviz graphs in your documents.
8756 It adds these directives:
8758 .. graphviz::
8760 Directive to embed graphviz code. The input code for dot is
8761 given as the content. For example:
8762 .. graphviz::
8764 digraph foo {
8766 "bar" -> "baz";
8767 }
8768 In HTML output, the code will be rendered to a PNG or SVG image
8770 (see graphviz_output_format). In LaTeX output, the code will be
8771 rendered to an embeddable PDF file.
8772 You can also embed external dot files, by giving the file name
8774 as an argument to graphviz and no additional content:
8775 .. graphviz:: external.dot
8777 As for all file references in Sphinx, if the filename is abso‐
8779 lute, it is taken as relative to the source directory.
8780 Changed in version 1.1: Added support for external files.
8782 options
8785 :alt: alternate text (text)
8787 The alternate text of the graph. By default, the graph
8788 code is used to the alternate text.
8789 New in version 1.0.
8791 :align: alignment of the graph (left, center or right)
8794 The horizontal alignment of the graph.
8795 New in version 1.5.
8797 :caption: caption of the graph (text)
8800 The caption of the graph.
8801 New in version 1.1.
8803 :layout: layout type of the graph (text)
8806 The layout of the graph (ex. dot, neato and so on). A
8807 path to the graphviz commands are also allowed. By
8808 default, graphviz_dot is used.
8809 New in version 1.4.
8811 Changed in version 2.2: Renamed from graphviz_dot
8814 :name: label (text)
8817 The label of the graph.
8818 New in version 1.6.
8820 .. graph::
8823 Directive for embedding a single undirected graph. The name is
8824 given as a directive argument, the contents of the graph are the
8825 directive content. This is a convenience directive to generate
8826 graph <name> { <content> }.
8827 For example:
8829 .. graph:: foo
8831 "bar" -- "baz";
8833 NOTE:
8835 The graph name is passed unchanged to Graphviz. If it con‐
8836 tains non-alphanumeric characters (e.g. a dash), you will
8837 have to double-quote it.
8838 options
8840 Same as graphviz.
8842 :alt: alternate text (text)
8844 New in version 1.0.
8845 :align: alignment of the graph (left, center or right)
8848 New in version 1.5.
8849 :caption: caption of the graph (text)
8852 New in version 1.1.
8853 :layout: layout type of the graph (text)
8856 New in version 1.4.
8857 Changed in version 2.2: Renamed from graphviz_dot
8860 :name: label (text)
8863 New in version 1.6.
8864 .. digraph::
8867 Directive for embedding a single directed graph. The name is
8868 given as a directive argument, the contents of the graph are the
8869 directive content. This is a convenience directive to generate
8870 digraph <name> { <content> }.
8871 For example:
8873 .. digraph:: foo
8875 "bar" -> "baz" -> "quux";
8877 options
8879 Same as graphviz.
8881 :alt: alternate text (text)
8883 New in version 1.0.
8884 :align: alignment of the graph (left, center or right)
8887 New in version 1.5.
8888 :caption: caption of the graph (text)
8891 New in version 1.1.
8892 :layout: layout type of the graph (text)
8895 New in version 1.4.
8896 Changed in version 2.2: Renamed from graphviz_dot
8899 :name: label (text)
8902 New in version 1.6.
8903 There are also these config values:
8906 graphviz_dot
8908 The command name with which to invoke dot. The default is
8909 'dot'; you may need to set this to a full path if dot is not in
8910 the executable search path.
8911 Since this setting is not portable from system to system, it is
8913 normally not useful to set it in conf.py; rather, giving it on
8914 the sphinx-build command line via the -D option should be
8915 preferable, like this:
8916 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
8918 graphviz_dot_args
8920 Additional command-line arguments to give to dot, as a list.
8921 The default is an empty list. This is the right place to set
8922 global graph, node or edge attributes via dot’s -G, -N and -E
8923 options.
8924 graphviz_output_format
8926 The output format for Graphviz when building HTML files. This
8927 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
8928 used, in order to make the URL links work properly, an appropri‐
8929 ate target attribute must be set, such as "_top" and "_blank".
8930 For example, the link in the following graph should work in the
8931 svg output:
8932 .. graphviz::
8934 digraph example {
8936 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
8937 b [label="other"];
8938 a -> b;
8939 }
8940 New in version 1.0: Previously, output always was PNG.
8942 sphinx.ext.ifconfig – Include content based on configuration
8945 This extension is quite simple, and features only one directive:
8946 WARNING:
8948 This directive is designed to control only content of document. It
8949 could not control sections, labels and so on.
8950 .. ifconfig::
8952 Include content of the directive only if the Python expression
8953 given as an argument is True, evaluated in the namespace of the
8954 project’s configuration (that is, all registered variables from
8955 conf.py are available).
8956 For example, one could write
8958 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
8960 This stuff is only included in the built docs for unstable versions.
8962 To make a custom config value known to Sphinx, use add_con‐
8964 fig_value() in the setup function in conf.py, e.g.:
8965 def setup(app):
8967 app.add_config_value('releaselevel', '', 'env')
8968 The second argument is the default value, the third should
8970 always be 'env' for such values (it selects if Sphinx re-reads
8971 the documents if the value changes).
8972 sphinx.ext.imgconverter – A reference image converter using Imagemagick
8974 New in version 1.6.
8975 This extension converts images in your document to appropriate format
8978 for builders. For example, it allows you to use SVG images with LaTeX
8979 builder. As a result, you don’t mind what image format the builder
8980 supports.
8981 Internally, this extension uses Imagemagick to convert images.
8983 NOTE:
8985 Imagemagick rasterizes a SVG image on conversion. As a result, the
8986 image becomes not scalable. To avoid that, please use other image
8987 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
8988 or rsvg-convert).
8989 Configuration
8991 image_converter
8992 A path to convert command. By default, the imgconverter uses
8993 the command from search paths.
8994 image_converter_args
8996 Additional command-line arguments to give to convert, as a list.
8997 The default is an empty list [].
8998 sphinx.ext.inheritance_diagram – Include inheritance diagrams
9000 New in version 0.6.
9001 This extension allows you to include inheritance diagrams, rendered via
9004 the Graphviz extension.
9005 It adds this directive:
9007 .. inheritance-diagram::
9009 This directive has one or more arguments, each giving a module
9010 or class name. Class names can be unqualified; in that case
9011 they are taken to exist in the currently described module (see
9012 py:module).
9013 For each given class, and each class in each given module, the
9015 base classes are determined. Then, from all classes and their
9016 base classes, a graph is generated which is then rendered via
9017 the graphviz extension to a directed graph.
9018 This directive supports an option called parts that, if given,
9020 must be an integer, advising the directive to keep that many
9021 dot-separated parts in the displayed names (from right to left).
9022 For example, parts=1 will only display class names, without the
9023 names of the modules that contain them.
9024 Changed in version 2.0: The value of for parts can also be nega‐
9026 tive, indicating how many parts to drop from the left. For
9027 example, if all your class names start with lib., you can give
9028 :parts: -1 to remove that prefix from the displayed node names.
9029 The directive also supports a private-bases flag option; if
9032 given, private base classes (those whose name starts with _)
9033 will be included.
9034 You can use caption option to give a caption to the diagram.
9036 Changed in version 1.1: Added private-bases option; previously,
9038 all bases were always included.
9039 Changed in version 1.5: Added caption option
9042 It also supports a top-classes option which requires one or more
9045 class names separated by comma. If specified inheritance traver‐
9046 sal will stop at the specified class names. Given the following
9047 Python module:
9048 """
9050 A
9051 / \
9052 B C
9053 / \ / \
9054 E D F
9055 """
9056 class A:
9058 pass
9059 class B(A):
9061 pass
9062 class C(A):
9064 pass
9065 class D(B, C):
9067 pass
9068 class E(B):
9070 pass
9071 class F(C):
9073 pass
9074 If you have specified a module in the inheritance diagram like
9076 this:
9077 .. inheritance-diagram:: dummy.test
9079 :top-classes: dummy.test.B, dummy.test.C
9080 any base classes which are ancestors to top-classes and are also
9082 defined in the same module will be rendered as stand alone
9083 nodes. In this example class A will be rendered as stand alone
9084 node in the graph. This is a known issue due to how this exten‐
9085 sion works internally.
9086 If you don’t want class A (or any other ancestors) to be visible
9088 then specify only the classes you would like to generate the
9089 diagram for like this:
9090 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
9092 :top-classes: dummy.test.B, dummy.test.C
9093 Changed in version 1.7: Added top-classes option to limit the
9095 scope of inheritance graphs.
9096 Examples
9099 The following are different inheritance diagrams for the internal
9100 InheritanceDiagram class that implements the directive.
9101 With full names:
9103 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9105 Showing class names only:
9107 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9109 :parts: 1
9110 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
9112 est superclass still part of Sphinx), and dropping the common left-most
9113 part (sphinx) from all names:
9114 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9116 :top-classes: sphinx.util.docutils.SphinxDirective
9117 :parts: -1
9118 Configuration
9120 inheritance_graph_attrs
9121 A dictionary of graphviz graph attributes for inheritance dia‐
9122 grams.
9123 For example:
9125 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
9127 fontsize=14, ratio='compress')
9128 inheritance_node_attrs
9130 A dictionary of graphviz node attributes for inheritance dia‐
9131 grams.
9132 For example:
9134 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
9136 color='dodgerblue1', style='filled')
9137 inheritance_edge_attrs
9139 A dictionary of graphviz edge attributes for inheritance dia‐
9140 grams.
9141 inheritance_alias
9143 Allows mapping the full qualified name of the class to custom
9144 values (useful when exposing the underlying path of a class is
9145 not desirable, e.g. it’s a private class and should not be
9146 instantiated by the user).
9147 For example:
9149 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
9151 sphinx.ext.intersphinx – Link to other projects’ documentation
9153 New in version 0.5.
9154 This extension can generate automatic links to the documentation of
9157 objects in other projects.
9158 Usage is simple: whenever Sphinx encounters a cross-reference that has
9160 no matching target in the current documentation set, it looks for tar‐
9161 gets in the documentation sets configured in intersphinx_mapping. A
9162 reference like :py:class:`zipfile.ZipFile` can then link to the Python
9163 documentation for the ZipFile class, without you having to specify
9164 where it is located exactly.
9165 When using the “new” format (see below), you can even force lookup in a
9167 foreign set by prefixing the link target appropriately. A link like
9168 :ref:`comparison manual <python:comparisons>` will then link to the
9169 label “comparisons” in the doc set “python”, if it exists.
9170 Behind the scenes, this works as follows:
9172 · Each Sphinx HTML build creates a file named objects.inv that contains
9174 a mapping from object names to URIs relative to the HTML set’s root.
9175 · Projects using the Intersphinx extension can specify the location of
9177 such mapping files in the intersphinx_mapping config value. The map‐
9178 ping will then be used to resolve otherwise missing references to
9179 objects into links to the other documentation.
9180 · By default, the mapping file is assumed to be at the same location as
9182 the rest of the documentation; however, the location of the mapping
9183 file can also be specified individually, e.g. if the docs should be
9184 buildable without Internet access.
9185 Configuration
9187 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
9188 sions config value, and use these config values to activate linking:
9189 intersphinx_mapping
9191 This config value contains the locations and names of other
9192 projects that should be linked to in this documentation.
9193 Relative local paths for target locations are taken as relative
9195 to the base of the built documentation, while relative local
9196 paths for inventory locations are taken as relative to the
9197 source directory.
9198 When fetching remote inventory files, proxy settings will be
9200 read from the $HTTP_PROXY environment variable.
9201 Old format for this config value
9203 This is the format used before Sphinx 1.0. It is still recog‐
9205 nized.
9206 A dictionary mapping URIs to either None or an URI. The keys
9208 are the base URI of the foreign Sphinx documentation sets and
9209 can be local paths or HTTP URIs. The values indicate where the
9210 inventory file can be found: they can be None (at the same loca‐
9211 tion as the base URI) or another local or HTTP URI.
9212 New format for this config value
9214 New in version 1.0.
9216 A dictionary mapping unique identifiers to a tuple (target,
9219 inventory). Each target is the base URI of a foreign Sphinx
9220 documentation set and can be a local path or an HTTP URI. The
9221 inventory indicates where the inventory file can be found: it
9222 can be None (at the same location as the base URI) or another
9223 local or HTTP URI.
9224 The unique identifier can be used to prefix cross-reference tar‐
9226 gets, so that it is clear which intersphinx set the target
9227 belongs to. A link like :ref:`comparison manual <python:compar‐
9228 isons>` will link to the label “comparisons” in the doc set
9229 “python”, if it exists.
9230 Example
9232 To add links to modules and objects in the Python standard
9234 library documentation, use:
9235 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
9237 This will download the corresponding objects.inv file from the
9239 Internet and generate links to the pages under the given URI.
9240 The downloaded inventory is cached in the Sphinx environment, so
9241 it must be re-downloaded whenever you do a full rebuild.
9242 A second example, showing the meaning of a non-None value of the
9244 second tuple item:
9245 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9247 'python-inv.txt')}
9248 This will read the inventory from python-inv.txt in the source
9250 directory, but still generate links to the pages under
9251 https://docs.python.org/3. It is up to you to update the inven‐
9252 tory file as new objects are added to the Python documentation.
9253 Multiple target for the inventory
9255 New in version 1.3.
9257 Alternative files can be specified for each inventory. One can
9260 give a tuple for the second inventory tuple item as shown in the
9261 following example. This will read the inventory iterating
9262 through the (second) tuple items until the first successful
9263 fetch. The primary use case for this to specify mirror sites for
9264 server downtime of the primary inventory:
9265 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9267 (None, 'python-inv.txt'))}
9268 intersphinx_cache_limit
9270 The maximum number of days to cache remote inventories. The
9271 default is 5, meaning five days. Set this to a negative value
9272 to cache inventories for unlimited time.
9273 intersphinx_timeout
9275 The number of seconds for timeout. The default is None, meaning
9276 do not timeout.
9277 NOTE:
9279 timeout is not a time limit on the entire response download;
9280 rather, an exception is raised if the server has not issued a
9281 response for timeout seconds.
9282 Showing all links of an Intersphinx mapping file
9284 To show all Intersphinx links and their targets of an Intersphinx map‐
9285 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
9286 helpful when searching for the root cause of a broken Intersphinx link
9287 in a documentation project. The following example prints the Inter‐
9288 sphinx mapping of the Python 3 documentation:
9289 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
9291 sphinx.ext.linkcode – Add external links to source code
9293 Module author: Pauli Virtanen
9294 New in version 1.2.
9296 This extension looks at your object descriptions (.. class::, .. func‐
9299 tion:: etc.) and adds external links to code hosted somewhere on the
9300 web. The intent is similar to the sphinx.ext.viewcode extension, but
9301 assumes the source code can be found somewhere on the Internet.
9302 In your configuration, you need to specify a linkcode_resolve function
9304 that returns an URL based on the object.
9305 Configuration
9307 linkcode_resolve
9308 This is a function linkcode_resolve(domain, info), which should
9309 return the URL to source code corresponding to the object in
9310 given domain with given information.
9311 The function should return None if no link is to be added.
9313 The argument domain specifies the language domain the object is
9315 in. info is a dictionary with the following keys guaranteed to
9316 be present (dependent on the domain):
9317 · py: module (name of the module), fullname (name of the object)
9319 · c: names (list of names for the object)
9321 · cpp: names (list of names for the object)
9323 · javascript: object (name of the object), fullname (name of the
9325 item)
9326 Example:
9328 def linkcode_resolve(domain, info):
9330 if domain != 'py':
9331 return None
9332 if not info['module']:
9333 return None
9334 filename = info['module'].replace('.', '/')
9335 return "https://somesite/sourcerepo/%s.py" % filename
9336 Math support for HTML outputs in Sphinx
9338 New in version 0.5.
9339 Changed in version 1.8: Math support for non-HTML builders is inte‐
9342 grated to sphinx-core. So mathbase extension is no longer needed.
9343 Since mathematical notation isn’t natively supported by HTML in any
9346 way, Sphinx gives a math support to HTML document with several exten‐
9347 sions. These use the reStructuredText math directive and role.
9348 sphinx.ext.imgmath – Render math as images
9350 New in version 1.4.
9351 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
9354 SVG images. This of course means that the computer where the docs are
9355 built must have both programs available.
9356 There are various configuration values you can set to influence how the
9358 images are built:
9359 imgmath_image_format
9361 The output image format. The default is 'png'. It should be
9362 either 'png' or 'svg'. The image is produced by first executing
9363 latex on the TeX mathematical mark-up then (depending on the
9364 requested format) either dvipng or dvisvgm.
9365 imgmath_use_preview
9367 dvipng and dvisvgm both have the ability to collect from LaTeX
9368 the “depth” of the rendered math: an inline image should use
9369 this “depth” in a vertical-align style to get correctly aligned
9370 with surrounding text.
9371 This mechanism requires the LaTeX preview package (available as
9373 preview-latex-style on Ubuntu xenial). Therefore, the default
9374 for this option is False but it is strongly recommended to set
9375 it to True.
9376 Changed in version 2.2: This option can be used with the 'svg'
9378 imgmath_image_format.
9379 imgmath_add_tooltips
9382 Default: True. If false, do not add the LaTeX code as an “alt”
9383 attribute for math images.
9384 imgmath_font_size
9386 The font size (in pt) of the displayed math. The default value
9387 is 12. It must be a positive integer.
9388 imgmath_latex
9390 The command name with which to invoke LaTeX. The default is
9391 'latex'; you may need to set this to a full path if latex is not
9392 in the executable search path.
9393 Since this setting is not portable from system to system, it is
9395 normally not useful to set it in conf.py; rather, giving it on
9396 the sphinx-build command line via the -D option should be
9397 preferable, like this:
9398 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
9400 This value should only contain the path to the latex executable,
9402 not further arguments; use imgmath_latex_args for that purpose.
9403 HINT:
9405 Some fancy LaTeX mark-up (an example was reported which used
9406 TikZ to add various decorations to the equation) require mul‐
9407 tiple runs of the LaTeX executable. To handle this, set this
9408 configuration setting to 'latexmk' (or a full path to it) as
9409 this Perl script reliably chooses dynamically how many latex
9410 runs are needed.
9411 imgmath_latex_args
9413 Additional arguments to give to latex, as a list. The default
9414 is an empty list.
9415 imgmath_latex_preamble
9417 Additional LaTeX code to put into the preamble of the LaTeX
9418 files used to translate the math snippets. This is left empty
9419 by default. Use it e.g. to add packages which modify the fonts
9420 used for math, such as '\\usepackage{newtxsf}' for sans-serif
9421 fonts, or '\\usepackage{fouriernc}' for serif fonts. Indeed,
9422 the default LaTeX math fonts have rather thin glyphs which (in
9423 HTML output) often do not match well with the font for text.
9424 imgmath_dvipng
9426 The command name to invoke dvipng. The default is 'dvipng'; you
9427 may need to set this to a full path if dvipng is not in the exe‐
9428 cutable search path. This option is only used when img‐
9429 math_image_format is set to 'png'.
9430 imgmath_dvipng_args
9432 Additional arguments to give to dvipng, as a list. The default
9433 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
9434 which makes the image a bit darker and larger then it is by
9435 default (this compensates somewhat for the thinness of default
9436 LaTeX math fonts), and produces PNGs with a transparent back‐
9437 ground. This option is used only when imgmath_image_format is
9438 'png'.
9439 imgmath_dvisvgm
9441 The command name to invoke dvisvgm. The default is 'dvisvgm';
9442 you may need to set this to a full path if dvisvgm is not in the
9443 executable search path. This option is only used when img‐
9444 math_image_format is 'svg'.
9445 imgmath_dvisvgm_args
9447 Additional arguments to give to dvisvgm, as a list. The default
9448 value is ['--no-fonts'], which means that dvisvgm will render
9449 glyphs as path elements (cf the dvisvgm FAQ). This option is
9450 used only when imgmath_image_format is 'svg'.
9451 sphinx.ext.mathjax – Render math via JavaScript
9453 New in version 1.1.
9454 This extension puts math as-is into the HTML files. The JavaScript
9457 package MathJax is then loaded and transforms the LaTeX markup to read‐
9458 able math live in the browser.
9459 Because MathJax (and the necessary fonts) is very large, it is not
9461 included in Sphinx but is set to automatically include it from a
9462 third-party site.
9463 ATTENTION:
9465 You should use the math directive and role, not the native MathJax
9466 $$, \(, etc.
9467 mathjax_path
9469 The path to the JavaScript file to include in the HTML files in
9470 order to load MathJax.
9471 The default is the https:// URL that loads the JS files from the
9473 cdnjs Content Delivery Network. See the MathJax Getting Started
9474 page for details. If you want MathJax to be available offline or
9475 without including resources from a third-party site, you have to
9476 download it and set this value to a different path.
9477 The path can be absolute or relative; if it is relative, it is
9479 relative to the _static directory of the built docs.
9480 For example, if you put MathJax into the static path of the
9482 Sphinx docs, this value would be MathJax/MathJax.js. If you
9483 host more than one Sphinx documentation set on one server, it is
9484 advisable to install MathJax in a shared location.
9485 You can also give a full https:// URL different from the CDN
9487 URL.
9488 mathjax_options
9490 The options to script tag for mathjax. For example, you can set
9491 integrity option with following setting:
9492 mathjax_options = {
9494 'integrity': 'sha384-......',
9495 }
9496 The default is empty ({}).
9498 mathjax_config
9500 The inline configuration options for mathjax. The value is used
9501 as a parameter of MathJax.Hub.Config(). For more information,
9502 please read Using in-line configuration options.
9503 For example:
9505 mathjax_config = {
9507 'extensions': ['tex2jax.js'],
9508 'jax': ['input/TeX', 'output/HTML-CSS'],
9509 }
9510 The default is empty (not configured).
9512 sphinx.ext.jsmath – Render math via JavaScript
9514 This extension works just as the MathJax extension does, but uses the
9515 older package jsMath. It provides this config value:
9516 jsmath_path
9518 The path to the JavaScript file to include in the HTML files in
9519 order to load JSMath. There is no default.
9520 The path can be absolute or relative; if it is relative, it is
9522 relative to the _static directory of the built docs.
9523 For example, if you put JSMath into the static path of the
9525 Sphinx docs, this value would be jsMath/easy/load.js. If you
9526 host more than one Sphinx documentation set on one server, it is
9527 advisable to install jsMath in a shared location.
9528 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
9530 Module author: Rob Ruana
9531 New in version 1.3.
9533 Overview
9536 Are you tired of writing docstrings that look like this:
9537 :param path: The path of the file to wrap
9539 :type path: str
9540 :param field_storage: The :class:`FileStorage` instance to wrap
9541 :type field_storage: FileStorage
9542 :param temporary: Whether or not to delete the file when the File
9543 instance is destructed
9544 :type temporary: bool
9545 :returns: A buffered writable file descriptor
9546 :rtype: BufferedFileStorage
9547 reStructuredText is great, but it creates visually dense, hard to read
9549 docstrings. Compare the jumble above to the same thing rewritten
9550 according to the Google Python Style Guide:
9551 Args:
9553 path (str): The path of the file to wrap
9554 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
9555 temporary (bool): Whether or not to delete the file when the File
9556 instance is destructed
9557 Returns:
9559 BufferedFileStorage: A buffered writable file descriptor
9560 Much more legible, no?
9562 Napoleon is a extension that enables Sphinx to parse both NumPy and
9564 Google style docstrings - the style recommended by Khan Academy.
9565 Napoleon is a pre-processor that parses NumPy and Google style doc‐
9567 strings and converts them to reStructuredText before Sphinx attempts to
9568 parse them. This happens in an intermediate step while Sphinx is pro‐
9569 cessing the documentation, so it doesn’t modify any of the docstrings
9570 in your actual source code files.
9571 Getting Started
9573 1. After setting up Sphinx to build your docs, enable napoleon in the
9574 Sphinx conf.py file:
9575 # conf.py
9577 # Add napoleon to the extensions list
9579 extensions = ['sphinx.ext.napoleon']
9580 2. Use sphinx-apidoc to build your API documentation:
9582 $ sphinx-apidoc -f -o docs/source projectdir
9584 Docstrings
9586 Napoleon interprets every docstring that autodoc can find, including
9587 docstrings on: modules, classes, attributes, methods, functions, and
9588 variables. Inside each docstring, specially formatted Sections are
9589 parsed and converted to reStructuredText.
9590 All standard reStructuredText formatting still works as expected.
9592 Docstring Sections
9594 All of the following section headers are supported:
9595 · Args (alias of Parameters)
9597 · Arguments (alias of Parameters)
9599 · Attention
9601 · Attributes
9603 · Caution
9605 · Danger
9607 · Error
9609 · Example
9611 · Examples
9613 · Hint
9615 · Important
9617 · Keyword Args (alias of Keyword Arguments)
9619 · Keyword Arguments
9621 · Methods
9623 · Note
9625 · Notes
9627 · Other Parameters
9629 · Parameters
9631 · Return (alias of Returns)
9633 · Returns
9635 · Raises
9637 · References
9639 · See Also
9641 · Tip
9643 · Todo
9645 · Warning
9647 · Warnings (alias of Warning)
9649 · Warns
9651 · Yield (alias of Yields)
9653 · Yields
9655 Google vs NumPy
9657 Napoleon supports two styles of docstrings: Google and NumPy. The main
9658 difference between the two styles is that Google uses indentation to
9659 separate sections, whereas NumPy uses underlines.
9660 Google style:
9662 def func(arg1, arg2):
9664 """Summary line.
9665 Extended description of function.
9667 Args:
9669 arg1 (int): Description of arg1
9670 arg2 (str): Description of arg2
9671 Returns:
9673 bool: Description of return value
9674 """
9676 return True
9677 NumPy style:
9679 def func(arg1, arg2):
9681 """Summary line.
9682 Extended description of function.
9684 Parameters
9686 ----------
9687 arg1 : int
9688 Description of arg1
9689 arg2 : str
9690 Description of arg2
9691 Returns
9693 -------
9694 bool
9695 Description of return value
9696 """
9698 return True
9699 NumPy style tends to require more vertical space, whereas Google style
9701 tends to use more horizontal space. Google style tends to be easier to
9702 read for short and simple docstrings, whereas NumPy style tends be eas‐
9703 ier to read for long and in-depth docstrings.
9704 The Khan Academy recommends using Google style.
9706 The choice between styles is largely aesthetic, but the two styles
9708 should not be mixed. Choose one style for your project and be consis‐
9709 tent with it.
9710 SEE ALSO:
9712 For complete examples:
9713 · example_google
9715 · example_numpy
9717 Type Annotations
9719 PEP 484 introduced a standard way to express types in Python code.
9720 This is an alternative to expressing types directly in docstrings. One
9721 benefit of expressing types according to PEP 484 is that type checkers
9722 and IDEs can take advantage of them for static code analysis.
9723 Google style with Python 3 type annotations:
9725 def func(arg1: int, arg2: str) -> bool:
9727 """Summary line.
9728 Extended description of function.
9730 Args:
9732 arg1: Description of arg1
9733 arg2: Description of arg2
9734 Returns:
9736 Description of return value
9737 """
9739 return True
9740 Google style with types in docstrings:
9742 def func(arg1, arg2):
9744 """Summary line.
9745 Extended description of function.
9747 Args:
9749 arg1 (int): Description of arg1
9750 arg2 (str): Description of arg2
9751 Returns:
9753 bool: Description of return value
9754 """
9756 return True
9757 NOTE:
9759 Python 2/3 compatible annotations aren’t currently supported by
9760 Sphinx and won’t show up in the docs.
9761 Configuration
9763 Listed below are all the settings used by napoleon and their default
9764 values. These settings can be changed in the Sphinx conf.py file. Make
9765 sure that “sphinx.ext.napoleon” is enabled in conf.py:
9766 # conf.py
9768 # Add any Sphinx extension module names here, as strings
9770 extensions = ['sphinx.ext.napoleon']
9771 # Napoleon settings
9773 napoleon_google_docstring = True
9774 napoleon_numpy_docstring = True
9775 napoleon_include_init_with_doc = False
9776 napoleon_include_private_with_doc = False
9777 napoleon_include_special_with_doc = True
9778 napoleon_use_admonition_for_examples = False
9779 napoleon_use_admonition_for_notes = False
9780 napoleon_use_admonition_for_references = False
9781 napoleon_use_ivar = False
9782 napoleon_use_param = True
9783 napoleon_use_rtype = True
9784 napoleon_google_docstring
9786 True to parse Google style docstrings. False to disable support
9787 for Google style docstrings. Defaults to True.
9788 napoleon_numpy_docstring
9790 True to parse NumPy style docstrings. False to disable support
9791 for NumPy style docstrings. Defaults to True.
9792 napoleon_include_init_with_doc
9794 True to list __init___ docstrings separately from the class doc‐
9795 string. False to fall back to Sphinx’s default behavior, which
9796 considers the __init___ docstring as part of the class documen‐
9797 tation. Defaults to False.
9798 If True:
9800 def __init__(self):
9802 \"\"\"
9803 This will be included in the docs because it has a docstring
9804 \"\"\"
9805 def __init__(self):
9807 # This will NOT be included in the docs
9808 napoleon_include_private_with_doc
9810 True to include private members (like _membername) with doc‐
9811 strings in the documentation. False to fall back to Sphinx’s
9812 default behavior. Defaults to False.
9813 If True:
9815 def _included(self):
9817 """
9818 This will be included in the docs because it has a docstring
9819 """
9820 pass
9821 def _skipped(self):
9823 # This will NOT be included in the docs
9824 pass
9825 napoleon_include_special_with_doc
9827 True to include special members (like __membername__) with doc‐
9828 strings in the documentation. False to fall back to Sphinx’s
9829 default behavior. Defaults to True.
9830 If True:
9832 def __str__(self):
9834 """
9835 This will be included in the docs because it has a docstring
9836 """
9837 return unicode(self).encode('utf-8')
9838 def __unicode__(self):
9840 # This will NOT be included in the docs
9841 return unicode(self.__class__.__name__)
9842 napoleon_use_admonition_for_examples
9844 True to use the .. admonition:: directive for the Example and
9845 Examples sections. False to use the .. rubric:: directive
9846 instead. One may look better than the other depending on what
9847 HTML theme is used. Defaults to False.
9848 This NumPy style snippet will be converted as follows:
9850 Example
9852 -------
9853 This is just a quick example
9854 If True:
9856 .. admonition:: Example
9858 This is just a quick example
9860 If False:
9862 .. rubric:: Example
9864 This is just a quick example
9866 napoleon_use_admonition_for_notes
9868 True to use the .. admonition:: directive for Notes sections.
9869 False to use the .. rubric:: directive instead. Defaults to
9870 False.
9871 NOTE:
9873 The singular Note section will always be converted to a ..
9874 note:: directive.
9875 SEE ALSO:
9877 napoleon_use_admonition_for_examples
9878 napoleon_use_admonition_for_references
9880 True to use the .. admonition:: directive for References sec‐
9881 tions. False to use the .. rubric:: directive instead. Defaults
9882 to False.
9883 SEE ALSO:
9885 napoleon_use_admonition_for_examples
9886 napoleon_use_ivar
9888 True to use the :ivar: role for instance variables. False to use
9889 the .. attribute:: directive instead. Defaults to False.
9890 This NumPy style snippet will be converted as follows:
9892 Attributes
9894 ----------
9895 attr1 : int
9896 Description of `attr1`
9897 If True:
9899 :ivar attr1: Description of `attr1`
9901 :vartype attr1: int
9902 If False:
9904 .. attribute:: attr1
9906 Description of `attr1`
9908 :type: int
9910 napoleon_use_param
9912 True to use a :param: role for each function parameter. False to
9913 use a single :parameters: role for all the parameters. Defaults
9914 to True.
9915 This NumPy style snippet will be converted as follows:
9917 Parameters
9919 ----------
9920 arg1 : str
9921 Description of `arg1`
9922 arg2 : int, optional
9923 Description of `arg2`, defaults to 0
9924 If True:
9926 :param arg1: Description of `arg1`
9928 :type arg1: str
9929 :param arg2: Description of `arg2`, defaults to 0
9930 :type arg2: int, optional
9931 If False:
9933 :parameters: * **arg1** (*str*) --
9935 Description of `arg1`
9936 * **arg2** (*int, optional*) --
9937 Description of `arg2`, defaults to 0
9938 napoleon_use_keyword
9940 True to use a :keyword: role for each function keyword argument.
9941 False to use a single :keyword arguments: role for all the key‐
9942 words. Defaults to True.
9943 This behaves similarly to napoleon_use_param. Note unlike docu‐
9945 tils, :keyword: and :param: will not be treated the same way -
9946 there will be a separate “Keyword Arguments” section, rendered
9947 in the same fashion as “Parameters” section (type links created
9948 if possible)
9949 SEE ALSO:
9951 napoleon_use_param
9952 napoleon_use_rtype
9954 True to use the :rtype: role for the return type. False to out‐
9955 put the return type inline with the description. Defaults to
9956 True.
9957 This NumPy style snippet will be converted as follows:
9959 Returns
9961 -------
9962 bool
9963 True if successful, False otherwise
9964 If True:
9966 :returns: True if successful, False otherwise
9968 :rtype: bool
9969 If False:
9971 :returns: *bool* -- True if successful, False otherwise
9973 sphinx.ext.todo – Support for todo items
9975 Module author: Daniel Bültmann
9976 New in version 0.5.
9978 There are two additional directives when using this extension:
9981 .. todo::
9983 Use this directive like, for example, note.
9984 It will only show up in the output if todo_include_todos is
9986 True.
9987 New in version 1.3.2: This directive supports an class option
9989 that determines the class attribute for HTML output. If not
9990 given, the class defaults to admonition-todo.
9991 .. todolist::
9994 This directive is replaced by a list of all todo directives in
9995 the whole documentation, if todo_include_todos is True.
9996 These can be configured as seen below.
9998 Configuration
10000 todo_include_todos
10001 If this is True, todo and todolist produce output, else they
10002 produce nothing. The default is False.
10003 todo_emit_warnings
10005 If this is True, todo emits a warning for each TODO entries.
10006 The default is False.
10007 New in version 1.5.
10009 todo_link_only
10012 If this is True, todolist produce output without file path and
10013 line, The default is False.
10014 New in version 1.4.
10016 autodoc provides the following an additional event:
10019 todo-defined(app, node)
10021 New in version 1.5.
10022 Emitted when a todo is defined. node is the defined
10025 sphinx.ext.todo.todo_node node.
10026 sphinx.ext.viewcode – Add links to highlighted source code
10028 Module author: Georg Brandl
10029 New in version 1.0.
10031 This extension looks at your Python object descriptions (.. class::, ..
10034 function:: etc.) and tries to find the source files where the objects
10035 are contained. When found, a separate HTML page will be output for
10036 each module with a highlighted version of the source code, and a link
10037 will be added to all object descriptions that leads to the source code
10038 of the described object. A link back from the source to the descrip‐
10039 tion will also be inserted.
10040 WARNING:
10042 Basically, viewcode extension will import the modules being linked
10043 to. If any modules have side effects on import, these will be exe‐
10044 cuted when sphinx-build is run.
10045 If you document scripts (as opposed to library modules), make sure
10047 their main routine is protected by a if __name__ == '__main__' con‐
10048 dition.
10049 In addition, if you don’t want to import the modules by viewcode,
10051 you can tell the location of the location of source code to viewcode
10052 using the viewcode-find-source event.
10053 If viewcode_follow_imported_members is enabled, you will also need
10055 to resolve imported attributes using the viewcode-follow-imported
10056 event.
10057 This extension works only on HTML related builders like html, apple‐
10059 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
10060 epub builder doesn’t support this extension (see viewcode_enable_epub).
10061 Configuration
10063 viewcode_follow_imported_members
10064 If this is True, viewcode extension will emit
10065 viewcode-follow-imported event to resolve the name of the module
10066 by other extensions. The default is True.
10067 New in version 1.3.
10069 Changed in version 1.8: Renamed from viewcode_import to view‐
10072 code_follow_imported_members.
10073 viewcode_enable_epub
10076 If this is True, viewcode extension is also enabled even if you
10077 use epub builders. This extension generates pages outside toc‐
10078 tree, but this is not preferred as epub format.
10079 Until 1.4.x, this extension is always enabled. If you want to
10081 generate epub as same as 1.4.x, you should set True, but epub
10082 format checker’s score becomes worse.
10083 The default is False.
10085 New in version 1.5.
10087 WARNING:
10090 Not all epub readers support pages generated by viewcode
10091 extension. These readers ignore links to pages are not under
10092 toctree.
10093 Some reader’s rendering result are corrupted and epubcheck’s
10095 score becomes worse even if the reader supports.
10096 viewcode-find-source(app, modname)
10098 New in version 1.8.
10099 Find the source code for a module. An event handler for this
10102 event should return a tuple of the source code itself and a dic‐
10103 tionary of tags. The dictionary maps the name of a class, func‐
10104 tion, attribute, etc to a tuple of its type, the start line num‐
10105 ber, and the end line number. The type should be one of
10106 “class”, “def”, or “other”.
10107 Parameters
10109 · app – The Sphinx application object.
10111 · modname – The name of the module to find source code
10113 for.
10114 viewcode-follow-imported(app, modname, attribute)
10116 New in version 1.8.
10117 Find the name of the original module for an attribute.
10120 Parameters
10122 · app – The Sphinx application object.
10124 · modname – The name of the module that the attribute
10126 belongs to.
10127 · attribute – The name of the member to follow.
10129 Third-party extensions
10131 Todo
10132 This should reference the GitHub organization now
10133 You can find several extensions contributed by users in the Sphinx Con‐
10135 trib repository. It is open for anyone who wants to maintain an exten‐
10136 sion publicly; just send a short message asking for write permissions.
10137 There are also several extensions hosted elsewhere. The Sphinx exten‐
10139 sion survey and awesome-sphinxdoc contains a comprehensive list.
10140 If you write an extension that you think others will find useful or you
10142 think should be included as a part of Sphinx, please write to the
10143 project mailing list (join here).
10144 Where to put your own extensions?
10146 Extensions local to a project should be put within the project’s direc‐
10147 tory structure. Set Python’s module search path, sys.path, accordingly
10148 so that Sphinx can find them. For example, if your extension foo.py
10149 lies in the exts subdirectory of the project root, put into conf.py:
10150 import sys, os
10152 sys.path.append(os.path.abspath('exts'))
10154 extensions = ['foo']
10156 You can also install extensions anywhere else on sys.path, e.g. in the
10158 site-packages directory.
10159
10161 Sphinx provides a number of builders for HTML and HTML-based formats.
10162 Builders
10164 Todo
10165 Populate when the ‘builders’ document is split up.
10166 Themes
10168 New in version 0.6.
10169 NOTE:
10172 This section provides information about using pre-existing HTML
10173 themes. If you wish to create your own theme, refer to /theming.
10174 Sphinx supports changing the appearance of its HTML output via themes.
10176 A theme is a collection of HTML templates, stylesheet(s) and other
10177 static files. Additionally, it has a configuration file which speci‐
10178 fies from which theme to inherit, which highlighting style to use, and
10179 what options exist for customizing the theme’s look and feel.
10180 Themes are meant to be project-unaware, so they can be used for differ‐
10182 ent projects without change.
10183 Using a theme
10185 Using a theme provided with Sphinx is easy. Since these do not need to
10186 be installed, you only need to set the html_theme config value. For
10187 example, to enable the classic theme, add the following to conf.py:
10188 html_theme = "classic"
10190 You can also set theme-specific options using the html_theme_options
10192 config value. These options are generally used to change the look and
10193 feel of the theme. For example, to place the sidebar on the right side
10194 and a black background for the relation bar (the bar with the naviga‐
10195 tion links at the page’s top and bottom), add the following conf.py:
10196 html_theme_options = {
10198 "rightsidebar": "true",
10199 "relbarbgcolor": "black"
10200 }
10201 If the theme does not come with Sphinx, it can be in two static forms
10203 or as a Python package. For the static forms, either a directory (con‐
10204 taining theme.conf and other needed files), or a zip file with the same
10205 contents is supported. The directory or zipfile must be put where
10206 Sphinx can find it; for this there is the config value html_theme_path.
10207 This can be a list of directories, relative to the directory containing
10208 conf.py, that can contain theme directories or zip files. For example,
10209 if you have a theme in the file blue.zip, you can put it right in the
10210 directory containing conf.py and use this configuration:
10211 html_theme = "blue"
10213 html_theme_path = ["."]
10214 The third form is a Python package. If a theme you want to use is dis‐
10216 tributed as a Python package, you can use it after installing
10217 # installing theme package
10219 $ pip install sphinxjp.themes.dotted
10220 Once installed, this can be used in the same manner as a directory or
10222 zipfile-based theme:
10223 html_theme = "dotted"
10225 For more information on the design of themes, including information
10227 about writing your own themes, refer to /theming.
10228 Builtin themes
10230 ┌───────────────────────────┬────────────────────────────┐
10231 │Theme overview │ │
10232 ├───────────────────────────┼────────────────────────────┤
10233 │[image: alabaster] [image] │ [image: classic] [image] │
10234 │ │ │
10235 │ │ │
10236 │alabaster │ classic │
10237 ├───────────────────────────┼────────────────────────────┤
10238 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
10239 │ │ │
10240 │ │ │
10241 │sphinxdoc │ scrolls │
10242 ├───────────────────────────┼────────────────────────────┤
10243 │[image: agogo] [image] │ [image: traditional] │
10244 │ │ [image] │
10245 │ │ │
10246 │agogo │ │
10247 │ │ traditional │
10248 ├───────────────────────────┼────────────────────────────┤
10249 │[image: nature] [image] │ [image: haiku] [image] │
10250 │ │ │
10251 │ │ │
10252 │nature │ haiku │
10253 ├───────────────────────────┼────────────────────────────┤
10254 │[image: pyramid] [image] │ [image: bizstyle] [image] │
10255 │ │ │
10256 │ │ │
10257 │pyramid │ bizstyle │
10258 └───────────────────────────┴────────────────────────────┘
10259 Sphinx comes with a selection of themes to choose from.
10261 These themes are:
10263 basic This is a basically unstyled layout used as the base for the
10265 other themes, and usable as the base for custom themes as well.
10266 The HTML contains all important elements like sidebar and rela‐
10267 tion bar. There are these options (which are inherited by the
10268 other themes):
10269 · nosidebar (true or false): Don’t include the sidebar.
10271 Defaults to False.
10272 · sidebarwidth (int or str): Width of the sidebar in pixels.
10274 This can be an int, which is interpreted as pixels or a valid
10275 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
10276 pixels.
10277 · body_min_width (int or str): Minimal width of the document
10279 body. This can be an int, which is interpreted as pixels or a
10280 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
10281 you don’t want a width limit. Defaults may depend on the theme
10282 (often 450px).
10283 · body_max_width (int or str): Maximal width of the document
10285 body. This can be an int, which is interpreted as pixels or a
10286 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
10287 if you don’t want a width limit. Defaults may depend on the
10288 theme (often 800px).
10289 alabaster
10291 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
10292 itz (especially as used in his Requests project), which was
10293 itself originally based on @mitsuhiko’s theme used for Flask &
10294 related projects. Refer to its installation page for informa‐
10295 tion on how to configure html_sidebars for its use.
10296 classic
10298 This is the classic theme, which looks like the Python 2 docu‐
10299 mentation. It can be customized via these options:
10300 · rightsidebar (true or false): Put the sidebar on the right
10302 side. Defaults to False.
10303 · stickysidebar (true or false): Make the sidebar “fixed” so
10305 that it doesn’t scroll out of view for long body content.
10306 This may not work well with all browsers. Defaults to False.
10307 · collapsiblesidebar (true or false): Add an experimental
10309 JavaScript snippet that makes the sidebar collapsible via a
10310 button on its side. Defaults to False.
10311 · externalrefs (true or false): Display external links differ‐
10313 ently from internal links. Defaults to False.
10314 There are also various color and font options that can change
10316 the color scheme without having to write a custom stylesheet:
10317 · footerbgcolor (CSS color): Background color for the footer
10319 line.
10320 · footertextcolor (CSS color): Text color for the footer line.
10322 · sidebarbgcolor (CSS color): Background color for the sidebar.
10324 · sidebarbtncolor (CSS color): Background color for the sidebar
10326 collapse button (used when collapsiblesidebar is True).
10327 · sidebartextcolor (CSS color): Text color for the sidebar.
10329 · sidebarlinkcolor (CSS color): Link color for the sidebar.
10331 · relbarbgcolor (CSS color): Background color for the relation
10333 bar.
10334 · relbartextcolor (CSS color): Text color for the relation bar.
10336 · relbarlinkcolor (CSS color): Link color for the relation bar.
10338 · bgcolor (CSS color): Body background color.
10340 · textcolor (CSS color): Body text color.
10342 · linkcolor (CSS color): Body link color.
10344 · visitedlinkcolor (CSS color): Body color for visited links.
10346 · headbgcolor (CSS color): Background color for headings.
10348 · headtextcolor (CSS color): Text color for headings.
10350 · headlinkcolor (CSS color): Link color for headings.
10352 · codebgcolor (CSS color): Background color for code blocks.
10354 · codetextcolor (CSS color): Default text color for code blocks,
10356 if not set differently by the highlighting style.
10357 · bodyfont (CSS font-family): Font for normal text.
10359 · headfont (CSS font-family): Font for headings.
10361 sphinxdoc
10363 The theme originally used by this documentation. It features a
10364 sidebar on the right side. There are currently no options beyond
10365 nosidebar and sidebarwidth.
10366 NOTE:
10368 The Sphinx documentation now uses an adjusted version of the
10369 sphinxdoc theme.
10370 scrolls
10372 A more lightweight theme, based on the Jinja documentation. The
10373 following color options are available:
10374 · headerbordercolor
10376 · subheadlinecolor
10378 · linkcolor
10380 · visitedlinkcolor
10382 · admonitioncolor
10384 agogo A theme created by Andi Albrecht. The following options are
10386 supported:
10387 · bodyfont (CSS font family): Font for normal text.
10389 · headerfont (CSS font family): Font for headings.
10391 · pagewidth (CSS length): Width of the page content, default
10393 70em.
10394 · documentwidth (CSS length): Width of the document (without
10396 sidebar), default 50em.
10397 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
10399 · bgcolor (CSS color): Background color.
10401 · headerbg (CSS value for “background”): background for the
10403 header area, default a grayish gradient.
10404 · footerbg (CSS value for “background”): background for the
10406 footer area, default a light gray gradient.
10407 · linkcolor (CSS color): Body link color.
10409 · headercolor1, headercolor2 (CSS color): colors for <h1> and
10411 <h2> headings.
10412 · headerlinkcolor (CSS color): Color for the backreference link
10414 in headings.
10415 · textalign (CSS text-align value): Text alignment for the body,
10417 default is justify.
10418 nature A greenish theme. There are currently no options beyond noside‐
10420 bar and sidebarwidth.
10421 pyramid
10423 A theme from the Pyramid web framework project, designed by
10424 Blaise Laflamme. There are currently no options beyond noside‐
10425 bar and sidebarwidth.
10426 haiku A theme without sidebar inspired by the Haiku OS user guide.
10428 The following options are supported:
10429 · full_logo (true or false, default False): If this is true, the
10431 header will only show the html_logo. Use this for large
10432 logos. If this is false, the logo (if present) will be shown
10433 floating right, and the documentation title will be put in the
10434 header.
10435 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
10437 linkcolor (CSS colors): Colors for various body elements.
10438 traditional
10440 A theme resembling the old Python documentation. There are cur‐
10441 rently no options beyond nosidebar and sidebarwidth.
10442 epub A theme for the epub builder. This theme tries to save visual
10444 space which is a sparse resource on ebook readers. The follow‐
10445 ing options are supported:
10446 · relbar1 (true or false, default True): If this is true, the
10448 relbar1 block is inserted in the epub output, otherwise it is
10449 omitted.
10450 · footer (true or false, default True): If this is true, the
10452 footer block is inserted in the epub output, otherwise it is
10453 omitted.
10454 bizstyle
10456 A simple bluish theme. The following options are supported
10457 beyond nosidebar and sidebarwidth:
10458 · rightsidebar (true or false): Put the sidebar on the right
10460 side. Defaults to False.
10461 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
10463 theme.
10464 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
10467 sic’. ‘default’ is still available, however it will emit a notice that
10468 it is an alias for the new ‘alabaster’ theme.
10469 Third Party Themes
10472 ┌───────────────────────────┬───┐
10473 │Theme overview │ │
10474 └───────────────────────────┴───┘
10475 │[image: sphinx_rtd_theme] │ │
10478 │[image] │ │
10479 │ │ │
10480 │ │ │
10481 │sphinx_rtd_theme │ │
10482 └───────────────────────────┴───┘
10483 There are many third-party themes available. Some of these are general
10485 use, while others are specific to an individual project. A section of
10486 third-party themes is listed below. Many more can be found on PyPI,
10487 GitHub and sphinx-themes.org.
10488 sphinx_rtd_theme
10490 Read the Docs Sphinx Theme. This is a mobile-friendly sphinx
10491 theme that was made for readthedocs.org. View a working demo
10492 over on readthedocs.org. You can get install and options infor‐
10493 mation at Read the Docs Sphinx Theme page.
10494 Changed in version 1.4: sphinx_rtd_theme has become optional.
10496
10499 New in version 1.1.
10500 Complementary to translations provided for Sphinx-generated messages
10503 such as navigation bars, Sphinx provides mechanisms facilitating docu‐
10504 ment translations in itself. See the intl-options for details on con‐
10505 figuration.
10506 [image] Workflow visualization of translations in Sphinx. (The
10507 stick-figure is taken from an XKCD comic.).UNINDENT
10508 · Sphinx internationalization details
10510 · Translating with sphinx-intl
10512 · Quick guide
10514 · Translating
10516 · Update your po files by new pot files
10518 · Using Transifex service for team translation
10520 · Contributing to Sphinx reference translation
10522 Sphinx internationalization details
10524 gettext [1] is an established standard for internationalization and
10525 localization. It naively maps messages in a program to a translated
10526 string. Sphinx uses these facilities to translate whole documents.
10527 Initially project maintainers have to collect all translatable strings
10529 (also referred to as messages) to make them known to translators.
10530 Sphinx extracts these through invocation of sphinx-build -b gettext.
10531 Every single element in the doctree will end up in a single message
10533 which results in lists being equally split into different chunks while
10534 large paragraphs will remain as coarsely-grained as they were in the
10535 original document. This grants seamless document updates while still
10536 providing a little bit of context for translators in free-text pas‐
10537 sages. It is the maintainer’s task to split up paragraphs which are
10538 too large as there is no sane automated way to do that.
10539 After Sphinx successfully ran the MessageCatalogBuilder you will find a
10541 collection of .pot files in your output directory. These are catalog
10542 templates and contain messages in your original language only.
10543 They can be delivered to translators which will transform them to .po
10545 files — so called message catalogs — containing a mapping from the
10546 original messages to foreign-language strings.
10547 gettext compiles them into a binary format known as binary catalogs
10549 through msgfmt for efficiency reasons. If you make these files discov‐
10550 erable with locale_dirs for your language, Sphinx will pick them up
10551 automatically.
10552 An example: you have a document usage.rst in your Sphinx project. The
10554 gettext builder will put its messages into usage.pot. Imagine you have
10555 Spanish translations [2] stored in usage.po — for your builds to be
10556 translated you need to follow these instructions:
10557 · Compile your message catalog to a locale directory, say locale, so it
10559 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
10560 (where es is the language code for Spanish.)
10561 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
10563 · Set locale_dirs to ["locale/"].
10565 · Set language to es (also possible via -D).
10567 · Run your desired build.
10569 Translating with sphinx-intl
10571 Quick guide
10572 sphinx-intl is a useful tool to work with Sphinx translation flow.
10573 This section describe an easy way to translate with sphinx-intl.
10574 1. Install sphinx-intl.
10576 $ pip install sphinx-intl
10578 2. Add configurations to conf.py.
10580 locale_dirs = ['locale/'] # path is example but recommended.
10582 gettext_compact = False # optional.
10583 This case-study assumes that locale_dirs is set to locale/ and get‐
10585 text_compact is set to False (the Sphinx document is already config‐
10586 ured as such).
10587 3. Extract translatable messages into pot files.
10589 $ make gettext
10591 The generated pot files will be placed in the _build/gettext direc‐
10593 tory.
10594 4. Generate po files.
10596 We’ll use the pot files generated in the above step.
10598 $ sphinx-intl update -p _build/gettext -l de -l ja
10600 Once completed, the generated po files will be placed in the below
10602 directories:
10603 · ./locale/de/LC_MESSAGES/
10605 · ./locale/ja/LC_MESSAGES/
10607 5. Translate po files.
10609 AS noted above, these are located in the ./locale/<lang>/LC_MESSAGES
10611 directory. An example of one such file, from Sphinx, builders.po,
10612 is given below.
10613 # a5600c3d2e3d48fc8c261ea0284db79b
10615 #: ../../builders.rst:4
10616 msgid "Available builders"
10617 msgstr "<FILL HERE BY TARGET LANGUAGE>"
10618 Another case, msgid is multi-line text and contains reStructuredText
10620 syntax:
10621 # 302558364e1d41c69b3277277e34b184
10623 #: ../../builders.rst:9
10624 msgid ""
10625 "These are the built-in Sphinx builders. More builders can be added by "
10626 ":ref:`extensions <extensions>`."
10627 msgstr ""
10628 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
10629 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
10630 Please be careful not to break reST notation. Most po-editors will
10632 help you with that.
10633 6. Build translated document.
10635 You need a language parameter in conf.py or you may also specify the
10637 parameter on the command line.
10638 For for BSD/GNU make, run:
10640 $ make -e SPHINXOPTS="-D language='de'" html
10642 For Windows cmd.exe, run:
10644 > set SPHINXOPTS=-D language=de
10646 > .\make.bat html
10647 For PowerShell, run:
10649 > Set-Item env:SPHINXOPTS "-D language=de"
10651 > .\make.bat html
10652 Congratulations! You got the translated documentation in the
10654 _build/html directory.
10655 New in version 1.3: sphinx-build that is invoked by make command will
10657 build po files into mo files.
10658 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
10660 mand before make command.
10661 Translating
10664 Update your po files by new pot files
10665 If a document is updated, it is necessary to generate updated pot files
10666 and to apply differences to translated po files. In order to apply the
10667 updates from a pot file to the po file, use the sphinx-intl update com‐
10668 mand.
10669 $ sphinx-intl update -p _build/locale
10671 Using Transifex service for team translation
10673 Transifex is one of several services that allow collaborative transla‐
10674 tion via a web interface. It has a nifty Python-based command line
10675 client that makes it easy to fetch and push translations.
10676 1. Install transifex-client.
10678 You need tx command to upload resources (pot files).
10680 $ pip install transifex-client
10682 SEE ALSO:
10684 Transifex Client documentation
10685 2. Create your transifex account and create new project for your docu‐
10687 ment.
10688 Currently, transifex does not allow for a translation project to
10690 have more than one version of the document, so you’d better include
10691 a version number in your project name.
10692 For example:
10694 Project ID
10696 sphinx-document-test_1_0
10697 Project URL
10699 https://www.transifex.com/projects/p/sphinx-docu‐
10700 ment-test_1_0/
10701 3. Create config files for tx command.
10703 This process will create .tx/config in the current directory, as
10705 well as a ~/.transifexrc file that includes auth information.
10706 $ tx init
10708 Creating .tx folder...
10709 Transifex instance [https://www.transifex.com]:
10710 ...
10711 Please enter your transifex username: <transifex-username>
10712 Password: <transifex-password>
10713 ...
10714 Done.
10715 4. Upload pot files to transifex service.
10717 Register pot files to .tx/config file:
10719 $ cd /your/document/root
10721 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
10722 --transifex-project-name sphinx-document-test_1_0
10723 and upload pot files:
10725 $ tx push -s
10727 Pushing translations for resource sphinx-document-test_1_0.builders:
10728 Pushing source file (locale/pot/builders.pot)
10729 Resource does not exist. Creating...
10730 ...
10731 Done.
10732 5. Forward the translation on transifex.
10734 6. Pull translated po files and make translated HTML.
10736 Get translated catalogs and build mo files. For example, to build mo
10738 files for German (de):
10739 $ cd /your/document/root
10741 $ tx pull -l de
10742 Pulling translations for resource sphinx-document-test_1_0.builders (...)
10743 -> de: locale/de/LC_MESSAGES/builders.po
10744 ...
10745 Done.
10746 Invoke make html (for BSD/GNU make):
10748 $ make -e SPHINXOPTS="-D language='de'" html
10750 That’s all!
10752 TIP:
10754 Translating locally and on Transifex
10755 If you want to push all language’s po files, you can be done by
10757 using tx push -t command. Watch out! This operation overwrites
10758 translations in transifex.
10759 In other words, if you have updated each in the service and local po
10761 files, it would take much time and effort to integrate them.
10762 Contributing to Sphinx reference translation
10764 The recommended way for new contributors to translate Sphinx reference
10765 is to join the translation team on Transifex.
10766 There is sphinx translation page for Sphinx (master) documentation.
10768 1. Login to transifex service.
10770 2. Go to sphinx translation page.
10772 3. Click Request language and fill form.
10774 4. Wait acceptance by transifex sphinx translation maintainers.
10776 5. (After acceptance) Translate on transifex.
10778
10780 [1] See the GNU gettext utilities for details on that software suite.
10781 [2] Because nobody expects the Spanish Inquisition!
10783
10785 Sphinx supports integration with setuptools and distutils through a
10786 custom command - BuildDoc.
10787 Using setuptools integration
10789 The Sphinx build can then be triggered from distutils, and some Sphinx
10790 options can be set in setup.py or setup.cfg instead of Sphinx’s own
10791 configuration file.
10792 For instance, from setup.py:
10794 # this is only necessary when not using setuptools/distribute
10796 from sphinx.setup_command import BuildDoc
10797 cmdclass = {'build_sphinx': BuildDoc}
10798 name = 'My project'
10800 version = '1.2'
10801 release = '1.2.0'
10802 setup(
10803 name=name,
10804 author='Bernard Montgomery',
10805 version=release,
10806 cmdclass=cmdclass,
10807 # these are optional and override conf.py settings
10808 command_options={
10809 'build_sphinx': {
10810 'project': ('setup.py', name),
10811 'version': ('setup.py', version),
10812 'release': ('setup.py', release),
10813 'source_dir': ('setup.py', 'doc')}},
10814 )
10815 NOTE:
10817 If you set Sphinx options directly in the setup() command, replace
10818 hyphens in variable names with underscores. In the example above,
10819 source-dir becomes source_dir.
10820 Or add this section in setup.cfg:
10822 [build_sphinx]
10824 project = 'My project'
10825 version = 1.2
10826 release = 1.2.0
10827 source-dir = 'doc'
10828 Once configured, call this by calling the relevant command on setup.py:
10830 $ python setup.py build_sphinx
10832 Options for setuptools integration
10834 fresh-env
10835 A boolean that determines whether the saved environment should
10836 be discarded on build. Default is false.
10837 This can also be set by passing the -E flag to setup.py:
10839 $ python setup.py build_sphinx -E
10841 all-files
10843 A boolean that determines whether all files should be built from
10844 scratch. Default is false.
10845 This can also be set by passing the -a flag to setup.py:
10847 $ python setup.py build_sphinx -a
10849 source-dir
10851 The target source directory. This can be relative to the set‐
10852 up.py or setup.cfg file, or it can be absolute. It defaults to
10853 ./doc or ./docs if either contains a file named conf.py (check‐
10854 ing ./doc first); otherwise it defaults to the current direc‐
10855 tory.
10856 This can also be set by passing the -s flag to setup.py:
10858 $ python setup.py build_sphinx -s $SOURCE_DIR
10860 build-dir
10862 The target build directory. This can be relative to the setup.py
10863 or setup.cfg file, or it can be absolute. Default is
10864 ./build/sphinx.
10865 config-dir
10867 Location of the configuration directory. This can be relative to
10868 the setup.py or setup.cfg file, or it can be absolute. Default
10869 is to use source-dir.
10870 This can also be set by passing the -c flag to setup.py:
10872 $ python setup.py build_sphinx -c $CONFIG_DIR
10874 New in version 1.0.
10876 builder
10879 The builder or list of builders to use. Default is html.
10880 This can also be set by passing the -b flag to setup.py:
10882 $ python setup.py build_sphinx -b $BUILDER
10884 Changed in version 1.6: This can now be a comma- or space-sepa‐
10886 rated list of builders
10887 warning-is-error
10890 A boolean that ensures Sphinx warnings will result in a failed
10891 build. Default is false.
10892 This can also be set by passing the -W flag to setup.py:
10894 $ python setup.py build_sphinx -W
10896 New in version 1.5.
10898 project
10901 The documented project’s name. Default is ''.
10902 New in version 1.0.
10904 version
10907 The short X.Y version. Default is ''.
10908 New in version 1.0.
10910 release
10913 The full version, including alpha/beta/rc tags. Default is ''.
10914 New in version 1.0.
10916 today How to format the current date, used as the replacement for
10919 |today|. Default is ''.
10920 New in version 1.0.
10922 link-index
10925 A boolean that ensures index.html will be linked to the master
10926 doc. Default is false.
10927 This can also be set by passing the -i flag to setup.py:
10929 $ python setup.py build_sphinx -i
10931 New in version 1.0.
10933 copyright
10936 The copyright string. Default is ''.
10937 New in version 1.3.
10939 nitpicky
10942 Run in nit-picky mode. Currently, this generates warnings for
10943 all missing references. See the config value nitpick_ignore for
10944 a way to exclude some references as “known missing”.
10945 New in version 1.8.
10947 pdb A boolean to configure pdb on exception. Default is false.
10950 New in version 1.5.
10952
10955 New in version 1.1.
10956 Sphinx provides a Python API to easily integrate Sphinx documentation
10959 into your web application. To learn more read the websupportquick‐
10960 start.
10961 Web Support Quick Start
10963 Building Documentation Data
10964 To make use of the web support package in your application you’ll need
10965 to build the data it uses. This data includes pickle files represent‐
10966 ing documents, search indices, and node data that is used to track
10967 where comments and other things are in a document. To do this you will
10968 need to create an instance of the WebSupport class and call its build()
10969 method:
10970 from sphinxcontrib.websupport import WebSupport
10972 support = WebSupport(srcdir='/path/to/rst/sources/',
10974 builddir='/path/to/build/outdir',
10975 search='xapian')
10976 support.build()
10978 This will read reStructuredText sources from srcdir and place the nec‐
10980 essary data in builddir. The builddir will contain two sub-directo‐
10981 ries: one named “data” that contains all the data needed to display
10982 documents, search through documents, and add comments to documents.
10983 The other directory will be called “static” and contains static files
10984 that should be served from “/static”.
10985 NOTE:
10987 If you wish to serve static files from a path other than “/static”,
10988 you can do so by providing the staticdir keyword argument when cre‐
10989 ating the WebSupport object.
10990 Integrating Sphinx Documents Into Your Webapp
10992 Now that the data is built, it’s time to do something useful with it.
10993 Start off by creating a WebSupport object for your application:
10994 from sphinxcontrib.websupport import WebSupport
10996 support = WebSupport(datadir='/path/to/the/data',
10998 search='xapian')
10999 You’ll only need one of these for each set of documentation you will be
11001 working with. You can then call its get_document() method to access
11002 individual documents:
11003 contents = support.get_document('contents')
11005 This will return a dictionary containing the following items:
11007 · body: The main body of the document as HTML
11009 · sidebar: The sidebar of the document as HTML
11011 · relbar: A div containing links to related documents
11013 · title: The title of the document
11015 · css: Links to CSS files used by Sphinx
11017 · script: JavaScript containing comment options
11019 This dict can then be used as context for templates. The goal is to be
11021 easy to integrate with your existing templating system. An example
11022 using Jinja2 is:
11023 {%- extends "layout.html" %}
11025 {%- block title %}
11027 {{ document.title }}
11028 {%- endblock %}
11029 {% block css %}
11031 {{ super() }}
11032 {{ document.css|safe }}
11033 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
11034 {% endblock %}
11035 {%- block script %}
11037 {{ super() }}
11038 {{ document.script|safe }}
11039 {%- endblock %}
11040 {%- block relbar %}
11042 {{ document.relbar|safe }}
11043 {%- endblock %}
11044 {%- block body %}
11046 {{ document.body|safe }}
11047 {%- endblock %}
11048 {%- block sidebar %}
11050 {{ document.sidebar|safe }}
11051 {%- endblock %}
11052 Authentication
11054 To use certain features such as voting, it must be possible to authen‐
11055 ticate users. The details of the authentication are left to your
11056 application. Once a user has been authenticated you can pass the
11057 user’s details to certain WebSupport methods using the username and
11058 moderator keyword arguments. The web support package will store the
11059 username with comments and votes. The only caveat is that if you allow
11060 users to change their username you must update the websupport package’s
11061 data:
11062 support.update_username(old_username, new_username)
11064 username should be a unique string which identifies a user, and modera‐
11066 tor should be a boolean representing whether the user has moderation
11067 privileges. The default value for moderator is False.
11068 An example Flask function that checks whether a user is logged in and
11070 then retrieves a document is:
11071 from sphinxcontrib.websupport.errors import *
11073 @app.route('/<path:docname>')
11075 def doc(docname):
11076 username = g.user.name if g.user else ''
11077 moderator = g.user.moderator if g.user else False
11078 try:
11079 document = support.get_document(docname, username, moderator)
11080 except DocumentNotFoundError:
11081 abort(404)
11082 return render_template('doc.html', document=document)
11083 The first thing to notice is that the docname is just the request path.
11085 This makes accessing the correct document easy from a single view. If
11086 the user is authenticated, then the username and moderation status are
11087 passed along with the docname to get_document(). The web support pack‐
11088 age will then add this data to the COMMENT_OPTIONS that are used in the
11089 template.
11090 NOTE:
11092 This only works if your documentation is served from your document
11093 root. If it is served from another directory, you will need to pre‐
11094 fix the url route with that directory, and give the docroot keyword
11095 argument when creating the web support object:
11096 support = WebSupport(..., docroot='docs')
11098 @app.route('/docs/<path:docname>')
11100 Performing Searches
11102 To use the search form built-in to the Sphinx sidebar, create a func‐
11103 tion to handle requests to the URL ‘search’ relative to the documenta‐
11104 tion root. The user’s search query will be in the GET parameters, with
11105 the key q. Then use the get_search_results() method to retrieve search
11106 results. In Flask that would be like this:
11107 @app.route('/search')
11109 def search():
11110 q = request.args.get('q')
11111 document = support.get_search_results(q)
11112 return render_template('doc.html', document=document)
11113 Note that we used the same template to render our search results as we
11115 did to render our documents. That’s because get_search_results()
11116 returns a context dict in the same format that get_document() does.
11117 Comments & Proposals
11119 Now that this is done it’s time to define the functions that handle the
11120 AJAX calls from the script. You will need three functions. The first
11121 function is used to add a new comment, and will call the web support
11122 method add_comment():
11123 @app.route('/docs/add_comment', methods=['POST'])
11125 def add_comment():
11126 parent_id = request.form.get('parent', '')
11127 node_id = request.form.get('node', '')
11128 text = request.form.get('text', '')
11129 proposal = request.form.get('proposal', '')
11130 username = g.user.name if g.user is not None else 'Anonymous'
11131 comment = support.add_comment(text, node_id='node_id',
11132 parent_id='parent_id',
11133 username=username, proposal=proposal)
11134 return jsonify(comment=comment)
11135 You’ll notice that both a parent_id and node_id are sent with the
11137 request. If the comment is being attached directly to a node, parent_id
11138 will be empty. If the comment is a child of another comment, then
11139 node_id will be empty. Then next function handles the retrieval of com‐
11140 ments for a specific node, and is aptly named get_data():
11141 @app.route('/docs/get_comments')
11143 def get_comments():
11144 username = g.user.name if g.user else None
11145 moderator = g.user.moderator if g.user else False
11146 node_id = request.args.get('node', '')
11147 data = support.get_data(node_id, username, moderator)
11148 return jsonify(**data)
11149 The final function that is needed will call process_vote(), and will
11151 handle user votes on comments:
11152 @app.route('/docs/process_vote', methods=['POST'])
11154 def process_vote():
11155 if g.user is None:
11156 abort(401)
11157 comment_id = request.form.get('comment_id')
11158 value = request.form.get('value')
11159 if value is None or comment_id is None:
11160 abort(400)
11161 support.process_vote(comment_id, g.user.id, value)
11162 return "success"
11163 Comment Moderation
11165 By default, all comments added through add_comment() are automatically
11166 displayed. If you wish to have some form of moderation, you can pass
11167 the displayed keyword argument:
11168 comment = support.add_comment(text, node_id='node_id',
11170 parent_id='parent_id',
11171 username=username, proposal=proposal,
11172 displayed=False)
11173 You can then create a new view to handle the moderation of comments.
11175 It will be called when a moderator decides a comment should be accepted
11176 and displayed:
11177 @app.route('/docs/accept_comment', methods=['POST'])
11179 def accept_comment():
11180 moderator = g.user.moderator if g.user else False
11181 comment_id = request.form.get('id')
11182 support.accept_comment(comment_id, moderator=moderator)
11183 return 'OK'
11184 Rejecting comments happens via comment deletion.
11186 To perform a custom action (such as emailing a moderator) when a new
11188 comment is added but not displayed, you can pass callable to the Web‐
11189 Support class when instantiating your support object:
11190 def moderation_callback(comment):
11192 """Do something..."""
11193 support = WebSupport(..., moderation_callback=moderation_callback)
11195 The moderation callback must take one argument, which will be the same
11197 comment dict that is returned by add_comment().
11198 The WebSupport Class
11200 class sphinxcontrib.websupport.WebSupport
11201 The main API class for the web support package. All interac‐
11202 tions with the web support package should occur through this
11203 class.
11204 The class takes the following keyword arguments:
11206 srcdir The directory containing reStructuredText source files.
11208 builddir
11210 The directory that build data and static files should be
11211 placed in. This should be used when creating a
11212 WebSupport object that will be used to build data.
11213 datadir
11215 The directory that the web support data is in. This
11216 should be used when creating a WebSupport object that
11217 will be used to retrieve data.
11218 search This may contain either a string (e.g. ‘xapian’) refer‐
11220 encing a built-in search adapter to use, or an instance
11221 of a subclass of BaseSearch.
11222 storage
11224 This may contain either a string representing a database
11225 uri, or an instance of a subclass of StorageBackend. If
11226 this is not provided, a new sqlite database will be cre‐
11227 ated.
11228 moderation_callback
11230 A callable to be called when a new comment is added that
11231 is not displayed. It must accept one argument: a dictio‐
11232 nary representing the comment that was added.
11233 staticdir
11235 If the static files should be created in a different
11236 location and not in '/static', this should be a string
11237 with the name of that location (e.g. builddir +
11238 '/static_files').
11239 NOTE:
11241 If you specify staticdir, you will typically want to
11242 adjust staticroot accordingly.
11243 staticroot
11245 If the static files are not served from '/static', this
11246 should be a string with the name of that location (e.g.
11247 '/static_files').
11248 docroot
11250 If the documentation is not served from the base path of
11251 a URL, this should be a string specifying that path (e.g.
11252 'docs').
11253 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
11255 support from sphinx.websupport. Please add sphinxcontrib-websupport
11256 package in your dependency and use moved class instead.
11257 Methods
11260 WebSupport.build()
11261 Build the documentation. Places the data into the outdir direc‐
11262 tory. Use it like this:
11263 support = WebSupport(srcdir, builddir, search='xapian')
11265 support.build()
11266 This will read reStructured text files from srcdir. Then it will
11268 build the pickles and search index, placing them into builddir.
11269 It will also save node data to the database.
11270 WebSupport.get_document(docname, username='', moderator=False)
11272 Load and return a document from a pickle. The document will be a
11273 dict object which can be used to render a template:
11274 support = WebSupport(datadir=datadir)
11276 support.get_document('index', username, moderator)
11277 In most cases docname will be taken from the request path and
11279 passed directly to this function. In Flask, that would be some‐
11280 thing like this:
11281 @app.route('/<path:docname>')
11283 def index(docname):
11284 username = g.user.name if g.user else ''
11285 moderator = g.user.moderator if g.user else False
11286 try:
11287 document = support.get_document(docname, username,
11288 moderator)
11289 except DocumentNotFoundError:
11290 abort(404)
11291 render_template('doc.html', document=document)
11292 The document dict that is returned contains the following items
11294 to be used during template rendering.
11295 · body: The main body of the document as HTML
11297 · sidebar: The sidebar of the document as HTML
11299 · relbar: A div containing links to related documents
11301 · title: The title of the document
11303 · css: Links to css files used by Sphinx
11305 · script: Javascript containing comment options
11307 This raises DocumentNotFoundError if a document matching docname
11309 is not found.
11310 Parameters
11312 docname – the name of the document to load.
11313 WebSupport.get_data(node_id, username=None, moderator=False)
11315 Get the comments and source associated with node_id. If username
11316 is given vote information will be included with the returned
11317 comments. The default CommentBackend returns a dict with two
11318 keys, source, and comments. source is raw source of the node and
11319 is used as the starting point for proposals a user can add. com‐
11320 ments is a list of dicts that represent a comment, each having
11321 the following items:
11322 ┌──────────────┬────────────────────────────┐
11324 │Key │ Contents │
11325 ├──────────────┼────────────────────────────┤
11326 │text │ The comment text. │
11327 ├──────────────┼────────────────────────────┤
11328 │username │ The username that was │
11329 │ │ stored with the comment. │
11330 ├──────────────┼────────────────────────────┤
11331 │id │ The comment’s unique iden‐ │
11332 │ │ tifier. │
11333 ├──────────────┼────────────────────────────┤
11334 │rating │ The comment’s current rat‐ │
11335 │ │ ing. │
11336 ├──────────────┼────────────────────────────┤
11337 │age │ The time in seconds since │
11338 │ │ the comment was added. │
11339 └──────────────┴────────────────────────────┘
11340 │time │ A dict containing time │
11348 │ │ information. It contains │
11349 │ │ the following keys: year, │
11350 │ │ month, day, hour, minute, │
11351 │ │ second, iso, and delta. │
11352 │ │ iso is the time formatted │
11353 │ │ in ISO 8601 format. delta │
11354 │ │ is a printable form of how │
11355 │ │ old the comment is (e.g. │
11356 │ │ “3 hours ago”). │
11357 ├──────────────┼────────────────────────────┤
11358 │vote │ If user_id was given, this │
11359 │ │ will be an integer repre‐ │
11360 │ │ senting the vote. 1 for an │
11361 │ │ upvote, -1 for a downvote, │
11362 │ │ or 0 if unvoted. │
11363 ├──────────────┼────────────────────────────┤
11364 │node │ The id of the node that │
11365 │ │ the comment is attached │
11366 │ │ to. If the comment’s par‐ │
11367 │ │ ent is another comment │
11368 │ │ rather than a node, this │
11369 │ │ will be null. │
11370 ├──────────────┼────────────────────────────┤
11371 │parent │ The id of the comment that │
11372 │ │ this comment is attached │
11373 │ │ to if it is not attached │
11374 │ │ to a node. │
11375 ├──────────────┼────────────────────────────┤
11376 │children │ A list of all children, in │
11377 │ │ this format. │
11378 ├──────────────┼────────────────────────────┤
11379 │proposal_diff │ An HTML representation of │
11380 │ │ the differences between │
11381 │ │ the the current source and │
11382 │ │ the user’s proposed │
11383 │ │ source. │
11384 └──────────────┴────────────────────────────┘
11385 Parameters
11387 · node_id – the id of the node to get comments for.
11389 · username – the username of the user viewing the com‐
11391 ments.
11392 · moderator – whether the user is a moderator.
11394 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
11396 username=None, time=None, proposal=None, moderator=False)
11397 Add a comment to a node or another comment. Returns the comment
11398 in the same format as get_comments(). If the comment is being
11399 attached to a node, pass in the node’s id (as a string) with the
11400 node keyword argument:
11401 comment = support.add_comment(text, node_id=node_id)
11403 If the comment is the child of another comment, provide the par‐
11405 ent’s id (as a string) with the parent keyword argument:
11406 comment = support.add_comment(text, parent_id=parent_id)
11408 If you would like to store a username with the comment, pass in
11410 the optional username keyword argument:
11411 comment = support.add_comment(text, node=node_id,
11413 username=username)
11414 Parameters
11416 · parent_id – the prefixed id of the comment’s parent.
11418 · text – the text of the comment.
11420 · displayed – for moderation purposes
11422 · username – the username of the user making the comment.
11424 · time – the time the comment was created, defaults to
11426 now.
11427 WebSupport.process_vote(comment_id, username, value)
11429 Process a user’s vote. The web support package relies on the API
11430 user to perform authentication. The API user will typically
11431 receive a comment_id and value from a form, and then make sure
11432 the user is authenticated. A unique username must be passed in,
11433 which will also be used to retrieve the user’s past voting data.
11434 An example, once again in Flask:
11435 @app.route('/docs/process_vote', methods=['POST'])
11437 def process_vote():
11438 if g.user is None:
11439 abort(401)
11440 comment_id = request.form.get('comment_id')
11441 value = request.form.get('value')
11442 if value is None or comment_id is None:
11443 abort(400)
11444 support.process_vote(comment_id, g.user.name, value)
11445 return "success"
11446 Parameters
11448 · comment_id – the comment being voted on
11450 · username – the unique username of the user voting
11452 · value – 1 for an upvote, -1 for a downvote, 0 for an
11454 unvote.
11455 WebSupport.get_search_results(q)
11457 Perform a search for the query q, and create a set of search
11458 results. Then render the search results as html and return a
11459 context dict like the one created by get_document():
11460 document = support.get_search_results(q)
11462 Parameters
11464 q – the search query
11465 Search Adapters
11467 To create a custom search adapter you will need to subclass the
11468 BaseSearch class. Then create an instance of the new class and pass
11469 that as the search keyword argument when you create the WebSupport
11470 object:
11471 support = WebSupport(srcdir=srcdir,
11473 builddir=builddir,
11474 search=MySearch())
11475 For more information about creating a custom search adapter, please see
11477 the documentation of the BaseSearch class below.
11478 class sphinxcontrib.websupport.search.BaseSearch
11480 Defines an interface for search adapters.
11481 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
11483 support.search from sphinx.websupport.search.
11484 Methods
11487 The following methods are defined in the BaseSearch class. Some methods
11488 do not need to be overridden, but some (add_document() and
11489 handle_query()) must be overridden in your subclass. For a working
11490 example, look at the built-in adapter for whoosh.
11491 BaseSearch.init_indexing(changed=[])
11493 Called by the builder to initialize the search indexer. changed
11494 is a list of pagenames that will be reindexed. You may want to
11495 remove these from the search index before indexing begins.
11496 Parameters
11498 changed – a list of pagenames that will be re-indexed
11499 BaseSearch.finish_indexing()
11501 Called by the builder when writing has been completed. Use this
11502 to perform any finalization or cleanup actions after indexing is
11503 complete.
11504 BaseSearch.feed(pagename, filename, title, doctree)
11506 Called by the builder to add a doctree to the index. Converts
11507 the doctree to text and passes it to add_document(). You proba‐
11508 bly won’t want to override this unless you need access to the
11509 doctree. Override add_document() instead.
11510 Parameters
11512 · pagename – the name of the page to be indexed
11514 · filename – the name of the original source file
11516 · title – the title of the page to be indexed
11518 · doctree – is the docutils doctree representation of the
11520 page
11521 BaseSearch.add_document(pagename, filename, title, text)
11523 Called by feed() to add a document to the search index. This
11524 method should should do everything necessary to add a single
11525 document to the search index.
11526 pagename is name of the page being indexed. It is the combina‐
11528 tion of the source files relative path and filename, minus the
11529 extension. For example, if the source file is
11530 “ext/builders.rst”, the pagename would be “ext/builders”. This
11531 will need to be returned with search results when processing a
11532 query.
11533 Parameters
11535 · pagename – the name of the page being indexed
11537 · filename – the name of the original source file
11539 · title – the page’s title
11541 · text – the full text of the page
11543 BaseSearch.query(q)
11545 Called by the web support api to get search results. This method
11546 compiles the regular expression to be used when extracting con‐
11547 text, then calls handle_query(). You won’t want to override
11548 this unless you don’t want to use the included extract_context()
11549 method. Override handle_query() instead.
11550 Parameters
11552 q – the search query string.
11553 BaseSearch.handle_query(q)
11555 Called by query() to retrieve search results for a search query
11556 q. This should return an iterable containing tuples of the fol‐
11557 lowing format:
11558 (<path>, <title>, <context>)
11560 path and title are the same values that were passed to
11562 add_document(), and context should be a short text snippet of
11563 the text surrounding the search query in the document.
11564 The extract_context() method is provided as a simple way to cre‐
11566 ate the context.
11567 Parameters
11569 q – the search query
11570 BaseSearch.extract_context(text, length=240)
11572 Extract the context for the search query from the document’s
11573 full text.
11574 Parameters
11576 · text – the full text of the document to create the con‐
11578 text for
11579 · length – the length of the context snippet to return.
11581 Storage Backends
11583 To create a custom storage backend you will need to subclass the
11584 StorageBackend class. Then create an instance of the new class and
11585 pass that as the storage keyword argument when you create the WebSup‐
11586 port object:
11587 support = WebSupport(srcdir=srcdir,
11589 builddir=builddir,
11590 storage=MyStorage())
11591 For more information about creating a custom storage backend, please
11593 see the documentation of the StorageBackend class below.
11594 class sphinxcontrib.websupport.storage.StorageBackend
11596 Defines an interface for storage backends.
11597 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
11599 trib.websupport.storage from sphinx.websupport.storage.
11600 Methods
11603 StorageBackend.pre_build()
11604 Called immediately before the build process begins. Use this to
11605 prepare the StorageBackend for the addition of nodes.
11606 StorageBackend.add_node(id, document, source)
11608 Add a node to the StorageBackend.
11609 Parameters
11611 · id – a unique id for the comment.
11613 · document – the name of the document the node belongs
11615 to.
11616 · source – the source files name.
11618 StorageBackend.post_build()
11620 Called after a build has completed. Use this to finalize the
11621 addition of nodes if needed.
11622 StorageBackend.add_comment(text, displayed, username, time, proposal,
11624 node_id, parent_id, moderator)
11625 Called when a comment is being added.
11626 Parameters
11628 · text – the text of the comment
11630 · displayed – whether the comment should be displayed
11632 · username – the name of the user adding the comment
11634 · time – a date object with the time the comment was
11636 added
11637 · proposal – the text of the proposal the user made
11639 · node_id – the id of the node that the comment is being
11641 added to
11642 · parent_id – the id of the comment’s parent comment.
11644 · moderator – whether the user adding the comment is a
11646 moderator
11647 StorageBackend.delete_comment(comment_id, username, moderator)
11649 Delete a comment.
11650 Raises UserNotAuthorizedError if moderator is False and username
11652 doesn’t match the username on the comment.
11653 Parameters
11655 · comment_id – The id of the comment being deleted.
11657 · username – The username of the user requesting the
11659 deletion.
11660 · moderator – Whether the user is a moderator.
11662 StorageBackend.get_data(node_id, username, moderator)
11664 Called to retrieve all data for a node. This should return a
11665 dict with two keys, source and comments as described by WebSup‐
11666 port’s get_data() method.
11667 Parameters
11669 · node_id – The id of the node to get data for.
11671 · username – The name of the user requesting the data.
11673 · moderator – Whether the requestor is a moderator.
11675 StorageBackend.process_vote(comment_id, username, value)
11677 Process a vote that is being cast. value will be either -1, 0,
11678 or 1.
11679 Parameters
11681 · comment_id – The id of the comment being voted on.
11683 · username – The username of the user casting the vote.
11685 · value – The value of the vote being cast.
11687 StorageBackend.update_username(old_username, new_username)
11689 If a user is allowed to change their username this method should
11690 be called so that there is not stagnate data in the storage sys‐
11691 tem.
11692 Parameters
11694 · old_username – The username being changed.
11696 · new_username – What the username is being changed to.
11698 StorageBackend.accept_comment(comment_id)
11700 Called when a moderator accepts a comment. After the method is
11701 called the comment should be displayed to all users.
11702 Parameters
11704 comment_id – The id of the comment being accepted.
11705
11707 These are the applications provided as part of Sphinx.
11708 Core Applications
11710 sphinx-quickstart
11711 Synopsis
11712 sphinx-quickstart
11713 Description
11715 sphinx-quickstart is an interactive tool that asks some questions about
11716 your project and then generates a complete documentation directory and
11717 sample Makefile to be used with sphinx-build(1).
11718 Options
11720 -q, --quiet
11721 Quiet mode that will skip interactive wizard to specify options.
11722 This option requires -p, -a and -v options.
11723 -h, --help, --version
11725 Display usage summary or Sphinx version.
11726 Structure Options
11728 --sep If specified, separate source and build directories.
11730 --dot=DOT
11732 Inside the root directory, two more directories will be created;
11733 “_templates” for custom HTML templates and “_static” for custom
11734 stylesheets and other static files. You can enter another prefix
11735 (such as “.”) to replace the underscore.
11736 Project Basic Options
11738 -p PROJECT, --project=PROJECT
11740 Project name will be set. (see project).
11741 -a AUTHOR, --author=AUTHOR
11743 Author names. (see copyright).
11744 -v VERSION
11746 Version of project. (see version).
11747 -r RELEASE, --release=RELEASE
11749 Release of project. (see release).
11750 -l LANGUAGE, --language=LANGUAGE
11752 Document language. (see language).
11753 --suffix=SUFFIX
11755 Source file suffix. (see source_suffix).
11756 --master=MASTER
11758 Master document name. (see master_doc).
11759 Extension Options
11761 --ext-autodoc
11763 Enable sphinx.ext.autodoc extension.
11764 --ext-doctest
11766 Enable sphinx.ext.doctest extension.
11767 --ext-intersphinx
11769 Enable sphinx.ext.intersphinx extension.
11770 --ext-todo
11772 Enable sphinx.ext.todo extension.
11773 --ext-coverage
11775 Enable sphinx.ext.coverage extension.
11776 --ext-imgmath
11778 Enable sphinx.ext.imgmath extension.
11779 --ext-mathjax
11781 Enable sphinx.ext.mathjax extension.
11782 --ext-ifconfig
11784 Enable sphinx.ext.ifconfig extension.
11785 --ext-viewcode
11787 Enable sphinx.ext.viewcode extension.
11788 --ext-githubpages
11790 Enable sphinx.ext.githubpages extension.
11791 --extensions=EXTENSIONS
11793 Enable arbitrary extensions.
11794 Makefile and Batchfile Creation Options
11796 --use-make-mode (-m), --no-use-make-mode (-M)
11798 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
11799 use, which generates a more concise Makefile/make.bat.
11800 Changed in version 1.5: make-mode is default.
11802 --makefile, --no-makefile
11805 Create (or not create) makefile.
11806 --batchfile, --no-batchfile
11808 Create (or not create) batchfile
11809 Project templating
11811 New in version 1.5: Project templating options for sphinx-quickstart
11813 -t, --templatedir=TEMPLATEDIR
11816 Template directory for template files. You can modify the tem‐
11817 plates of sphinx project files generated by quickstart. Follow‐
11818 ing Jinja2 template files are allowed:
11819 · master_doc.rst_t
11821 · conf.py_t
11823 · Makefile_t
11825 · Makefile.new_t
11827 · make.bat_t
11829 · make.bat.new_t
11831 In detail, please refer the system template files Sphinx pro‐
11833 vides. (sphinx/templates/quickstart)
11834 -d NAME=VALUE
11836 Define a template variable
11837 See also
11839 sphinx-build(1)
11840 sphinx-build
11842 Synopsis
11843 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
11844 Description
11846 sphinx-build generates documentation from the files in <sourcedir> and
11847 places it in the <outputdir>.
11848 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
11850 tings. sphinx-quickstart(1) may be used to generate template files,
11851 including conf.py.
11852 sphinx-build can create documentation in different formats. A format
11854 is selected by specifying the builder name on the command line; it
11855 defaults to HTML. Builders can also perform other tasks related to
11856 documentation processing.
11857 By default, everything that is outdated is built. Output only for
11859 selected files can be built by specifying individual filenames.
11860 For a list of available options, refer to sphinx-build -b.
11862 Options
11864 -b buildername
11865 The most important option: it selects a builder. The most com‐
11866 mon builders are:
11867 html Build HTML pages. This is the default builder.
11869 dirhtml
11871 Build HTML pages, but with a single directory per docu‐
11872 ment. Makes for prettier URLs (no .html) if served from
11873 a webserver.
11874 singlehtml
11876 Build a single HTML with the whole content.
11877 htmlhelp, qthelp, devhelp, epub
11879 Build HTML files with additional information for building
11880 a documentation collection in one of these formats.
11881 applehelp
11883 Build an Apple Help Book. Requires hiutil and codesign,
11884 which are not Open Source and presently only available on
11885 Mac OS X 10.6 and higher.
11886 latex Build LaTeX sources that can be compiled to a PDF docu‐
11888 ment using pdflatex.
11889 man Build manual pages in groff format for UNIX systems.
11891 texinfo
11893 Build Texinfo files that can be processed into Info files
11894 using makeinfo.
11895 text Build plain text files.
11897 gettext
11899 Build gettext-style message catalogs (.pot files).
11900 doctest
11902 Run all doctests in the documentation, if the doctest
11903 extension is enabled.
11904 linkcheck
11906 Check the integrity of all external links.
11907 xml Build Docutils-native XML files.
11909 pseudoxml
11911 Build compact pretty-printed “pseudo-XML” files display‐
11912 ing the internal structure of the intermediate document
11913 trees.
11914 See /usage/builders/index for a list of all builders shipped
11916 with Sphinx. Extensions can add their own builders.
11917 -M buildername
11919 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
11920 vides the same build functionality as a default Makefile or
11921 Make.bat. In addition to all Sphinx /usage/builders/index, the
11922 following build pipelines are available:
11923 latexpdf
11925 Build LaTeX files and run them through pdflatex, or as
11926 per latex_engine setting. If language is set to 'ja',
11927 will use automatically the platex/dvipdfmx latex to PDF
11928 pipeline.
11929 info Build Texinfo files and run them through makeinfo.
11931 IMPORTANT:
11933 Sphinx only recognizes the -M option if it is placed first.
11934 New in version 1.2.1.
11936 -a If given, always write all output files. The default is to only
11939 write output files for new and changed source files. (This may
11940 not apply to all builders.)
11941 -E Don’t use a saved environment (the structure caching all
11943 cross-references), but rebuild it completely. The default is to
11944 only read and parse source files that are new or have changed
11945 since the last run.
11946 -t tag Define the tag tag. This is relevant for only directives that
11948 only include their content if this tag is set.
11949 New in version 0.6.
11951 -d path
11954 Since Sphinx has to read and parse all source files before it
11955 can write an output file, the parsed source files are cached as
11956 “doctree pickles”. Normally, these files are put in a directory
11957 called .doctrees under the build directory; with this option you
11958 can select a different cache directory (the doctrees can be
11959 shared between all builders).
11960 -j N Distribute the build over N processes in parallel, to make
11962 building on multiprocessor machines more effective. Note that
11963 not all parts and not all builders of Sphinx can be paral‐
11964 lelized. If auto argument is given, Sphinx uses the number of
11965 CPUs as N.
11966 New in version 1.2: This option should be considered experimen‐
11968 tal.
11969 Changed in version 1.7: Support auto argument.
11972 -c path
11975 Don’t look for the conf.py in the source directory, but use the
11976 given configuration directory instead. Note that various other
11977 files and paths given by configuration values are expected to be
11978 relative to the configuration directory, so they will have to be
11979 present at this location too.
11980 New in version 0.3.
11982 -C Don’t look for a configuration file; only take options via the
11985 -D option.
11986 New in version 0.5.
11988 -D setting=value
11991 Override a configuration value set in the conf.py file. The
11992 value must be a number, string, list or dictionary value.
11993 For lists, you can separate elements with a comma like this: -D
11995 html_theme_path=path1,path2.
11996 For dictionary values, supply the setting name and key like
11998 this: -D latex_elements.docclass=scrartcl.
11999 For boolean values, use 0 or 1 as the value.
12001 Changed in version 0.6: The value can now be a dictionary value.
12003 Changed in version 1.3: The value can now also be a list value.
12006 -A name=value
12009 Make the name assigned to value in the HTML templates.
12010 New in version 0.5.
12012 -n Run in nit-picky mode. Currently, this generates warnings for
12015 all missing references. See the config value nitpick_ignore for
12016 a way to exclude some references as “known missing”.
12017 -N Do not emit colored output.
12019 -v Increase verbosity (loglevel). This option can be given up to
12021 three times to get more debug logging output. It implies -T.
12022 New in version 1.2.
12024 -q Do not output anything on standard output, only write warnings
12027 and errors to standard error.
12028 -Q Do not output anything on standard output, also suppress warn‐
12030 ings. Only errors are written to standard error.
12031 -w file
12033 Write warnings (and errors) to the given file, in addition to
12034 standard error.
12035 -W Turn warnings into errors. This means that the build stops at
12037 the first warning and sphinx-build exits with exit status 1.
12038 --keep-going
12040 With -W option, keep going processing when getting warnings to
12041 the end of build, and sphinx-build exits with exit status 1.
12042 New in version 1.8.
12044 -T Display the full traceback when an unhandled exception occurs.
12047 Otherwise, only a summary is displayed and the traceback infor‐
12048 mation is saved to a file for further analysis.
12049 New in version 1.2.
12051 -P (Useful for debugging only.) Run the Python debugger, pdb, if
12054 an unhandled exception occurs while building.
12055 -h, --help, --version
12057 Display usage summary or Sphinx version.
12058 New in version 1.2.
12060 You can also give one or more filenames on the command line after the
12063 source and build directories. Sphinx will then try to build only these
12064 output files (and their dependencies).
12065 Environment Variables
12067 The sphinx-build refers following environment variables:
12068 MAKE A path to make command. A command name is also allowed.
12070 sphinx-build uses it to invoke sub-build process on make-mode.
12071 Makefile Options
12073 The Makefile and make.bat files created by sphinx-quickstart usually
12075 run sphinx-build only with the -b and -d options. However, they sup‐
12076 port the following variables to customize behavior:
12077 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
12079 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
12080 NOTE:
12082 Usage of this environment variable got broken at Sphinx 1.5
12083 as a4 or letter ended up as option to LaTeX document in place
12084 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
12085 SPHINXBUILD
12087 The command to use instead of sphinx-build.
12088 BUILDDIR
12090 The build directory to use instead of the one chosen in
12091 sphinx-quickstart.
12092 SPHINXOPTS
12094 Additional options for sphinx-build. These options can also be
12095 set via the shortcut variable O (capital ‘o’).
12096 Deprecation Warnings
12098 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
12099 when building a user’s document, some Sphinx extension is using depre‐
12100 cated features. In that case, please report it to author of the exten‐
12101 sion.
12102 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
12104 ronment variable to your environment. For example:
12105 · PYTHONWARNINGS= make html (Linux/Mac)
12107 · export PYTHONWARNINGS= and do make html (Linux/Mac)
12109 · set PYTHONWARNINGS= and do make html (Windows)
12111 · modify your Makefile/make.bat and set the environment variable
12113 See also
12115 sphinx-quickstart(1)
12116 Additional Applications
12118 sphinx-apidoc
12119 Synopsis
12120 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PAT‐
12121 TERN, …]
12122 Description
12124 sphinx-apidoc is a tool for automatic generation of Sphinx sources
12125 that, using the autodoc extension, document a whole package in the
12126 style of other automatic API documentation tools.
12127 MODULE_PATH is the path to a Python package to document, and OUT‐
12129 PUT_PATH is the directory where the generated sources are placed. Any
12130 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
12131 that will be excluded from generation.
12132 WARNING:
12134 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
12135 document all found modules. If any modules have side effects on
12136 import, these will be executed by autodoc when sphinx-build is run.
12137 If you document scripts (as opposed to library modules), make sure
12139 their main routine is protected by a if __name__ == '__main__' con‐
12140 dition.
12141 Options
12143 -o <OUTPUT_PATH>
12144 Directory to place the output files. If it does not exist, it is
12145 created.
12146 -f, --force
12148 Force overwriting of any existing generated files.
12149 -l, --follow-links
12151 Follow symbolic links.
12152 -n, --dry-run
12154 Do not create any files.
12155 -s <suffix>
12157 Suffix for the source files generated. Defaults to rst.
12158 -d <MAXDEPTH>
12160 Maximum depth for the generated table of contents file.
12161 --tocfile
12163 Filename for a table of contents file. Defaults to modules.
12164 -T, --no-toc
12166 Do not create a table of contents file. Ignored when --full is
12167 provided.
12168 -F, --full
12170 Generate a full Sphinx project (conf.py, Makefile etc.) using
12171 the same mechanism as sphinx-quickstart.
12172 -e, --separate
12174 Put documentation for each module on its own page.
12175 New in version 1.2.
12177 -E, --no-headings
12180 Do not create headings for the modules/packages. This is useful,
12181 for example, when docstrings already contain headings.
12182 -P, --private
12184 Include “_private” modules.
12185 New in version 1.2.
12187 --implicit-namespaces
12190 By default sphinx-apidoc processes sys.path searching for mod‐
12191 ules only. Python 3.3 introduced PEP 420 implicit namespaces
12192 that allow module path structures such as foo/bar/module.py or
12193 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
12194 not modules).
12195 Interpret paths recursively according to PEP-0420.
12197 -M, --module-first
12199 Put module documentation before submodule documentation.
12200 These options are used when --full is specified:
12202 -a Append module_path to sys.path.
12204 -H <project>
12206 Sets the project name to put in generated files (see project).
12207 -A <author>
12209 Sets the author name(s) to put in generated files (see copy‐
12210 right).
12211 -V <version>
12213 Sets the project version to put in generated files (see ver‐
12214 sion).
12215 -R <release>
12217 Sets the project release to put in generated files (see
12218 release).
12219 Project templating
12221 New in version 2.2: Project templating options for sphinx-apidoc
12223 -t, --templatedir=TEMPLATEDIR
12226 Template directory for template files. You can modify the tem‐
12227 plates of sphinx project files generated by apidoc. Following
12228 Jinja2 template files are allowed:
12229 · module.rst_t
12231 · package.rst_t
12233 · toc.rst_t
12235 · master_doc.rst_t
12237 · conf.py_t
12239 · Makefile_t
12241 · Makefile.new_t
12243 · make.bat_t
12245 · make.bat.new_t
12247 In detail, please refer the system template files Sphinx pro‐
12249 vides. (sphinx/templates/apidoc and sphinx/templates/quick‐
12250 start)
12251 Environment
12253 SPHINX_APIDOC_OPTIONS
12254 A comma-separated list of option to append to generated automod‐
12255 ule directives. Defaults to members,undoc-members,show-inheri‐
12256 tance.
12257 See also
12259 sphinx-build(1), sphinx-autogen(1)
12260 sphinx-autogen
12262 Synopsis
12263 sphinx-autogen [options] <sourcefile> …
12264 Description
12266 sphinx-autogen is a tool for automatic generation of Sphinx sources
12267 that, using the autodoc extension, document items included in autosum‐
12268 mary listing(s).
12269 sourcefile is the path to one or more reStructuredText documents con‐
12271 taining autosummary entries with the :toctree:: option set. sourcefile
12272 can be an fnmatch-style pattern.
12273 Options
12275 -o <outputdir>
12276 Directory to place the output file. If it does not exist, it is
12277 created. Defaults to the value passed to the :toctree: option.
12278 -s <suffix>, --suffix <suffix>
12280 Default suffix to use for generated files. Defaults to rst.
12281 -t <templates>, --templates <templates>
12283 Custom template directory. Defaults to None.
12284 -i, --imported-members
12286 Document imported members.
12287 Example
12289 Given the following directory structure:
12290 docs
12292 ├── index.rst
12293 └── ...
12294 foobar
12295 ├── foo
12296 │ └── __init__.py
12297 └── bar
12298 ├── __init__.py
12299 └── baz
12300 └── __init__.py
12301 and assuming docs/index.rst contained the following:
12303 Modules
12305 =======
12306 .. autosummary::
12308 :toctree: modules
12309 foobar.foo
12311 foobar.bar
12312 foobar.bar.baz
12313 If you run the following:
12315 $ PYTHONPATH=. sphinx-autodoc doc/index.rst
12317 then the following stub files will be created in docs:
12319 docs
12321 ├── index.rst
12322 └── modules
12323 ├── foobar.bar.rst
12324 ├── foobar.bar.baz.rst
12325 └── foobar.foo.rst
12326 and each of those files will contain a autodoc directive and some other
12328 information.
12329 See also
12331 sphinx-build(1), sphinx-apidoc(1)
12332
12334 New in version 0.6.
12335 NOTE:
12338 This document provides information about creating your own theme. If
12339 you simply wish to use a pre-existing HTML themes, refer to
12340 /usage/theming.
12341 Sphinx supports changing the appearance of its HTML output via themes.
12343 A theme is a collection of HTML templates, stylesheet(s) and other
12344 static files. Additionally, it has a configuration file which speci‐
12345 fies from which theme to inherit, which highlighting style to use, and
12346 what options exist for customizing the theme’s look and feel.
12347 Themes are meant to be project-unaware, so they can be used for differ‐
12349 ent projects without change.
12350 Creating themes
12352 Themes take the form of either a directory or a zipfile (whose name is
12353 the theme name), containing the following:
12354 · A theme.conf file.
12356 · HTML templates, if needed.
12358 · A static/ directory containing any static files that will be copied
12360 to the output static directory on build. These can be images,
12361 styles, script files.
12362 The theme.conf file is in INI format [1] (readable by the standard
12364 Python ConfigParser module) and has the following structure:
12365 [theme]
12367 inherit = base theme
12368 stylesheet = main CSS name
12369 pygments_style = stylename
12370 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
12371 [options]
12373 variable = default value
12374 · The inherit setting gives the name of a “base theme”, or none. The
12376 base theme will be used to locate missing templates (most themes will
12377 not have to supply most templates if they use basic as the base
12378 theme), its options will be inherited, and all of its static files
12379 will be used as well. If you want to also inherit the stylesheet,
12380 include it via CSS’ @import in your own.
12381 · The stylesheet setting gives the name of a CSS file which will be
12383 referenced in the HTML header. If you need more than one CSS file,
12384 either include one from the other via CSS’ @import, or use a custom
12385 HTML template that adds <link rel="stylesheet"> tags as necessary.
12386 Setting the html_style config value will override this setting.
12387 · The pygments_style setting gives the name of a Pygments style to use
12389 for highlighting. This can be overridden by the user in the pyg‐
12390 ments_style config value.
12391 · The sidebars setting gives the comma separated list of sidebar tem‐
12393 plates for constructing sidebars. This can be overridden by the user
12394 in the html_sidebars config value.
12395 · The options section contains pairs of variable names and default val‐
12397 ues. These options can be overridden by the user in
12398 html_theme_options and are accessible from all templates as
12399 theme_<name>.
12400 New in version 1.7: sidebar settings
12402 Distribute your theme as a Python package
12405 As a way to distribute your theme, you can use Python package. Python
12406 package brings to users easy setting up ways.
12407 To distribute your theme as a Python package, please define an entry
12409 point called sphinx.html_themes in your setup.py file, and write a set‐
12410 up() function to register your themes using add_html_theme() API in it:
12411 # 'setup.py'
12413 setup(
12414 ...
12415 entry_points = {
12416 'sphinx.html_themes': [
12417 'name_of_theme = your_package',
12418 ]
12419 },
12420 ...
12421 )
12422 # 'your_package.py'
12424 from os import path
12425 def setup(app):
12427 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
12428 If your theme package contains two or more themes, please call
12430 add_html_theme() twice or more.
12431 New in version 1.2: ‘sphinx_themes’ entry_points feature.
12433 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
12436 recated.
12437 New in version 1.6: sphinx.html_themes entry_points feature.
12440 Templating
12443 The guide to templating is helpful if you want to write your own tem‐
12444 plates. What is important to keep in mind is the order in which Sphinx
12445 searches for templates:
12446 · First, in the user’s templates_path directories.
12448 · Then, in the selected theme.
12450 · Then, in its base theme, its base’s base theme, etc.
12452 When extending a template in the base theme with the same name, use the
12454 theme name as an explicit directory: {% extends "basic/layout.html" %}.
12455 From a user templates_path template, you can still use the “exclamation
12456 mark” syntax as described in the templating document.
12457 Static templates
12459 Since theme options are meant for the user to configure a theme more
12460 easily, without having to write a custom stylesheet, it is necessary to
12461 be able to template static files as well as HTML files. Therefore,
12462 Sphinx supports so-called “static templates”, like this:
12463 If the name of a file in the static/ directory of a theme (or in the
12465 user’s static path, for that matter) ends with _t, it will be processed
12466 by the template engine. The _t will be left from the final file name.
12467 For example, the classic theme has a file static/classic.css_t which
12468 uses templating to put the color options into the stylesheet. When a
12469 documentation is built with the classic theme, the output directory
12470 will contain a _static/classic.css file where all template tags have
12471 been processed.
12472 [1] It is not an executable Python file, as opposed to conf.py,
12474 because that would pose an unnecessary security risk if themes are
12475 shared.
12476
12478 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
12479 is a text-based engine, and inspired by Django templates, so anyone
12480 having used Django will already be familiar with it. It also has
12481 excellent documentation for those who need to make themselves familiar
12482 with it.
12483 Do I need to use Sphinx’s templates to produce HTML?
12485 No. You have several other options:
12486 · You can write a TemplateBridge subclass that calls your template
12488 engine of choice, and set the template_bridge configuration value
12489 accordingly.
12490 · You can write a custom builder that derives from StandaloneHTML‐
12492 Builder and calls your template engine of choice.
12493 · You can use the PickleHTMLBuilder that produces pickle files with the
12495 page contents, and postprocess them using a custom tool, or use them
12496 in your Web application.
12497 Jinja/Sphinx Templating Primer
12499 The default templating language in Sphinx is Jinja. It’s Django/Smarty
12500 inspired and easy to understand. The most important concept in Jinja
12501 is template inheritance, which means that you can overwrite only spe‐
12502 cific blocks within a template, customizing it while also keeping the
12503 changes at a minimum.
12504 To customize the output of your documentation you can override all the
12506 templates (both the layout templates and the child templates) by adding
12507 files with the same name as the original filename into the template
12508 directory of the structure the Sphinx quickstart generated for you.
12509 Sphinx will look for templates in the folders of templates_path first,
12511 and if it can’t find the template it’s looking for there, it falls back
12512 to the selected theme’s templates.
12513 A template contains variables, which are replaced with values when the
12515 template is evaluated, tags, which control the logic of the template
12516 and blocks which are used for template inheritance.
12517 Sphinx’s basic theme provides base templates with a couple of blocks it
12519 will fill with data. These are located in the themes/basic subdirec‐
12520 tory of the Sphinx installation directory, and used by all builtin
12521 Sphinx themes. Templates with the same name in the templates_path
12522 override templates supplied by the selected theme.
12523 For example, to add a new link to the template area containing related
12525 links all you have to do is to add a new template called layout.html
12526 with the following contents:
12527 {% extends "!layout.html" %}
12529 {% block rootrellink %}
12530 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
12531 {{ super() }}
12532 {% endblock %}
12533 By prefixing the name of the overridden template with an exclamation
12535 mark, Sphinx will load the layout template from the underlying HTML
12536 theme.
12537 Important: If you override a block, call {{ super() }} somewhere to
12539 render the block’s original content in the extended template – unless
12540 you don’t want that content to show up.
12541 Working with the builtin templates
12543 The builtin basic theme supplies the templates that all builtin Sphinx
12544 themes are based on. It has the following elements you can override or
12545 use:
12546 Blocks
12548 The following blocks exist in the layout.html template:
12549 doctype
12551 The doctype of the output format. By default this is XHTML 1.0
12552 Transitional as this is the closest to what Sphinx and Docutils
12553 generate and it’s a good idea not to change it unless you want
12554 to switch to HTML 5 or a different but compatible XHTML doctype.
12555 linktags
12557 This block adds a couple of <link> tags to the head section of
12558 the template.
12559 extrahead
12561 This block is empty by default and can be used to add extra con‐
12562 tents into the <head> tag of the generated HTML file. This is
12563 the right place to add references to JavaScript or extra CSS
12564 files.
12565 relbar1 / relbar2
12567 This block contains the relation bar, the list of related links
12568 (the parent documents on the left, and the links to index, mod‐
12569 ules etc. on the right). relbar1 appears before the document,
12570 relbar2 after the document. By default, both blocks are filled;
12571 to show the relbar only before the document, you would override
12572 relbar2 like this:
12573 {% block relbar2 %}{% endblock %}
12575 rootrellink / relbaritems
12577 Inside the relbar there are three sections: The rootrellink, the
12578 links from the documentation and the custom relbaritems. The
12579 rootrellink is a block that by default contains a list item
12580 pointing to the master document by default, the relbaritems is
12581 an empty block. If you override them to add extra links into
12582 the bar make sure that they are list items and end with the
12583 reldelim1.
12584 document
12586 The contents of the document itself. It contains the block
12587 “body” where the individual content is put by subtemplates like
12588 page.html.
12589 sidebar1 / sidebar2
12591 A possible location for a sidebar. sidebar1 appears before the
12592 document and is empty by default, sidebar2 after the document
12593 and contains the default sidebar. If you want to swap the side‐
12594 bar location override this and call the sidebar helper:
12595 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
12597 {% block sidebar2 %}{% endblock %}
12598 (The sidebar2 location for the sidebar is needed by the sphinx‐
12600 doc.css stylesheet, for example.)
12601 sidebarlogo
12603 The logo location within the sidebar. Override this if you want
12604 to place some content at the top of the sidebar.
12605 footer The block for the footer div. If you want a custom footer or
12607 markup before or after it, override this one.
12608 The following four blocks are only used for pages that do not have
12610 assigned a list of custom sidebars in the html_sidebars config value.
12611 Their use is deprecated in favor of separate sidebar templates, which
12612 can be included via html_sidebars.
12613 sidebartoc
12615 The table of contents within the sidebar.
12616 Deprecated since version 1.0.
12618 sidebarrel
12621 The relation links (previous, next document) within the sidebar.
12622 Deprecated since version 1.0.
12624 sidebarsourcelink
12627 The “Show source” link within the sidebar (normally only shown
12628 if this is enabled by html_show_sourcelink).
12629 Deprecated since version 1.0.
12631 sidebarsearch
12634 The search box within the sidebar. Override this if you want to
12635 place some content at the bottom of the sidebar.
12636 Deprecated since version 1.0.
12638 Configuration Variables
12641 Inside templates you can set a couple of variables used by the layout
12642 template using the {% set %} tag:
12643 reldelim1
12645 The delimiter for the items on the left side of the related bar.
12646 This defaults to ' »' Each item in the related bar ends
12647 with the value of this variable.
12648 reldelim2
12650 The delimiter for the items on the right side of the related
12651 bar. This defaults to ' |'. Each item except of the last one
12652 in the related bar ends with the value of this variable.
12653 Overriding works like this:
12655 {% extends "!layout.html" %}
12657 {% set reldelim1 = ' >' %}
12658 script_files
12660 Add additional script files here, like this:
12661 {% set script_files = script_files + ["_static/myscript.js"] %}
12663 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
12665 instead.
12666 Helper Functions
12669 Sphinx provides various Jinja functions as helpers in the template.
12670 You can use them to generate links or output multiply used elements.
12671 pathto(document)
12673 Return the path to a Sphinx document as a URL. Use this to
12674 refer to built documents.
12675 pathto(file, 1)
12677 Return the path to a file which is a filename relative to the
12678 root of the generated output. Use this to refer to static
12679 files.
12680 hasdoc(document)
12682 Check if a document with the name document exists.
12683 sidebar()
12685 Return the rendered sidebar.
12686 relbar()
12688 Return the rendered relation bar.
12689 warning(message)
12691 Emit a warning message.
12692 Global Variables
12694 These global variables are available in every template and are safe to
12695 use. There are more, but most of them are an implementation detail and
12696 might change in the future.
12697 builder
12699 The name of the builder (e.g. html or htmlhelp).
12700 copyright
12702 The value of copyright.
12703 docstitle
12705 The title of the documentation (the value of html_title), except
12706 when the “single-file” builder is used, when it is set to None.
12707 embedded
12709 True if the built HTML is meant to be embedded in some viewing
12710 application that handles navigation, not the web browser, such
12711 as for HTML help or Qt help formats. In this case, the sidebar
12712 is not included.
12713 favicon
12715 The path to the HTML favicon in the static path, or ''.
12716 file_suffix
12718 The value of the builder’s out_suffix attribute, i.e. the file
12719 name extension that the output files will get. For a standard
12720 HTML builder, this is usually .html.
12721 has_source
12723 True if the reST document sources are copied (if
12724 html_copy_source is True).
12725 language
12727 The value of language.
12728 last_updated
12730 The build date.
12731 logo The path to the HTML logo image in the static path, or ''.
12733 master_doc
12735 The value of master_doc, for usage with pathto().
12736 pagename
12738 The “page name” of the current file, i.e. either the document
12739 name if the file is generated from a reST source, or the equiva‐
12740 lent hierarchical name relative to the output directory ([direc‐
12741 tory/]filename_without_extension).
12742 project
12744 The value of project.
12745 release
12747 The value of release.
12748 rellinks
12750 A list of links to put at the left side of the relbar, next to
12751 “next” and “prev”. This usually contains links to the general
12752 index and other indices, such as the Python module index. If
12753 you add something yourself, it must be a tuple (pagename, link
12754 title, accesskey, link text).
12755 shorttitle
12757 The value of html_short_title.
12758 show_source
12760 True if html_show_sourcelink is True.
12761 sphinx_version
12763 The version of Sphinx used to build.
12764 style The name of the main stylesheet, as given by the theme or
12766 html_style.
12767 title The title of the current document, as used in the <title> tag.
12769 use_opensearch
12771 The value of html_use_opensearch.
12772 version
12774 The value of version.
12775 In addition to these values, there are also all theme options available
12777 (prefixed by theme_), as well as the values given by the user in
12778 html_context.
12779 In documents that are created from source files (as opposed to automat‐
12781 ically-generated files like the module index, or documents that already
12782 are in HTML form), these variables are also available:
12783 body A string containing the content of the page in HTML form as pro‐
12785 duced by the HTML builder, before the theme is applied.
12786 display_toc
12788 A boolean that is True if the toc contains more than one entry.
12789 meta Document metadata (a dictionary), see metadata.
12791 metatags
12793 A string containing the page’s HTML meta tags.
12794 next The next document for the navigation. This variable is either
12796 false or has two attributes link and title. The title contains
12797 HTML markup. For example, to generate a link to the next page,
12798 you can use this snippet:
12799 {% if next %}
12801 <a href="{{ next.link|e }}">{{ next.title }}</a>
12802 {% endif %}
12803 page_source_suffix
12805 The suffix of the file that was rendered. Since we support a
12806 list of source_suffix, this will allow you to properly link to
12807 the original source file.
12808 parents
12810 A list of parent documents for navigation, structured like the
12811 next item.
12812 prev Like next, but for the previous page.
12814 sourcename
12816 The name of the copied source file for the current document.
12817 This is only nonempty if the html_copy_source value is True.
12818 This has empty value on creating automatically-generated files.
12819 title The page title.
12821 toc The local table of contents for the current page, rendered as
12823 HTML bullet lists.
12824 toctree
12826 A callable yielding the global TOC tree containing the current
12827 page, rendered as HTML bullet lists. Optional keyword argu‐
12828 ments:
12829 · collapse (True by default): if true, all TOC entries that are
12831 not ancestors of the current page are collapsed
12832 · maxdepth (defaults to the max depth selected in the toctree
12834 directive): the maximum depth of the tree; set it to -1 to
12835 allow unlimited depth
12836 · titles_only (False by default): if true, put only toplevel
12838 document titles in the tree
12839 · includehidden (False by default): if true, the TOC tree will
12841 also contain hidden entries.
12842
12844 The latex target does not benefit from prepared themes.
12845 The latex-options, and particularly among them the latex_elements vari‐
12847 able provides much of the interface for customization.
12848 For some details of the LaTeX/PDF builder command line invocation,
12850 refer to LaTeXBuilder.
12851 Example
12853 Keep in mind that backslashes must be doubled in Python string literals
12854 to avoid interpretation as escape sequences, or use raw strings (as is
12855 done here).
12856 # inside conf.py
12858 latex_engine = 'xelatex'
12859 latex_elements = {
12860 'fontpkg': r'''
12861 \setmainfont{DejaVu Serif}
12862 \setsansfont{DejaVu Sans}
12863 \setmonofont{DejaVu Sans Mono}
12864 ''',
12865 'preamble': r'''
12866 \usepackage[titles]{tocloft}
12867 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
12868 \setlength{\cftchapnumwidth}{0.75cm}
12869 \setlength{\cftsecindent}{\cftchapnumwidth}
12870 \setlength{\cftsecnumwidth}{1.25cm}
12871 ''',
12872 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
12873 'printindex': r'\footnotesize\raggedright\printindex',
12874 }
12875 latex_show_urls = 'footnote'
12876 The latex_elements configuration setting
12878 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
12879 ally puts into the generated .tex files. Its 'sphinxsetup' key is
12880 described separately.
12881 · Keys that you may want to override include:
12883 'papersize'
12885 Paper size option of the document class ('a4paper' or 'letter‐
12886 paper'), default 'letterpaper'.
12887 'pointsize'
12889 Point size option of the document class ('10pt', '11pt' or
12890 '12pt'), default '10pt'.
12891 'pxunit'
12893 the value of the px when used in image attributes width and
12894 height. The default value is '0.75bp' which achieves 96px=1in
12895 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
12896 use '0.01in' or '0.7227pt' (the latter leads to TeX computing
12897 a more precise value, due to the smaller unit used in the
12898 specification); for 72px=1in, simply use '1bp'; for 90px=1in,
12899 use '0.8bp' or '0.803pt'.
12900 New in version 1.5.
12902 'passoptionstopackages'
12905 A string which will be positioned early in the preamble,
12906 designed to contain \\PassOptionsToPackage{options}{foo} com‐
12907 mands. Default empty.
12908 New in version 1.4.
12910 'babel'
12913 “babel” package inclusion, default '\\usepackage{babel}' (the
12914 suitable document language string is passed as class option,
12915 and english is used if no language.) For Japanese documents,
12916 the default is the empty string.
12917 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX docu‐
12919 ment to use polyglossia, but one should be aware that current
12920 babel has improved its support for Unicode engines in recent
12921 years and for some languages it may make sense to prefer babel
12922 over polyglossia.
12923 HINT:
12925 After modifiying a core LaTeX key like this one, clean up
12926 the LaTeX build repertory before next PDF build, else
12927 left-over auxiliary files are likely to break the build.
12928 Changed in version 1.5: For latex_engine set to 'xelatex', the
12930 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
12931 guage>}'.
12932 Changed in version 1.6: 'lualatex' uses same default setting
12935 as 'xelatex'
12936 Changed in version 1.7.6: For French, xelatex and lualatex
12939 default to using babel, not polyglossia.
12940 'fontpkg'
12943 Font package inclusion, the default is '\\usepackage{times}'
12944 which uses Times for text, Helvetica for sans serif and
12945 Courier for monospace.
12946 Changed in version 1.2: Defaults to '' when the language uses
12948 the Cyrillic script.
12949 Changed in version 2.0: Support for individual Greek and
12952 Cyrillic letters:
12953 · In order to support occasional Cyrillic (физика частиц) or
12955 Greek letters (Σωματιδιακή φυσική) in a document whose lan‐
12956 guage is English or a Latin European one, the default
12957 set-up is enhanced (only for 'pdflatex' engine) to do:
12958 \substitutefont{LGR}{\rmdefault}{cmr}
12960 \substitutefont{LGR}{\sfdefault}{cmss}
12961 \substitutefont{LGR}{\ttdefault}{cmtt}
12962 \substitutefont{X2}{\rmdefault}{cmr}
12963 \substitutefont{X2}{\sfdefault}{cmss}
12964 \substitutefont{X2}{\ttdefault}{cmtt}
12965 but this is activated only under the condition that the
12967 'fontenc' key is configured to load the LGR (Greek) and/or
12968 X2 (Cyrillic) pdflatex-font encodings (if the language is
12969 set to a Cyrillic language, this 'fontpkg' key must be used
12970 as “times” package has no direct support for it; then keep
12971 only LGR lines from the above, if support is needed for
12972 Greek in the text).
12973 The \substitutefont command is from the eponymous LaTeX
12975 package, which is loaded by Sphinx if needed (on Ubuntu
12976 xenial it is part of texlive-latex-extra which is a Sphinx
12977 requirement).
12978 Only if the document actually does contain Unicode Greek
12980 letters (in text) or Cyrillic letters, will the above
12981 default set-up cause additional requirements for the PDF
12982 build. On Ubuntu xenial, texlive-lang-greek,
12983 texlive-lang-cyrillic, and (with the above choice of fonts)
12984 the cm-super (or cm-super-minimal) package.
12985 · For 'xelatex' and 'lualatex', the default is to use the
12987 FreeFont family: this OpenType font family supports both
12988 Cyrillic and Greek scripts and is available as separate
12989 Ubuntu xenial package fonts-freefont-otf, it is not needed
12990 to install the big package texlive-fonts-extra.
12991 · 'platex' (Japanese documents) engine supports individual
12993 Cyrillic and Greek letters with no need of extra user
12994 set-up.
12995 'fncychap'
12998 Inclusion of the “fncychap” package (which makes fancy chapter
12999 titles), default '\\usepackage[Bjarne]{fncychap}' for English
13000 documentation (this option is slightly customized by Sphinx),
13001 '\\usepackage[Sonny]{fncychap}' for internationalized docs
13002 (because the “Bjarne” style uses numbers spelled out in Eng‐
13003 lish). Other “fncychap” styles you can try are “Lenny”,
13004 “Glenn”, “Conny”, “Rejne” and “Bjornstrup”. You can also set
13005 this to '' to disable fncychap.
13006 The default is '' for Japanese documents.
13008 'preamble'
13010 Additional preamble content, default empty. One may move all
13011 needed macros into some file mystyle.tex.txt of the project
13012 source repertory, and get LaTeX to import it at run time:
13013 'preamble': r'\input{mystyle.tex.txt}',
13015 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
13016 'preamble': r'\usepackage{mystyle}',
13017 It is then needed to set appropriately latex_additional_files,
13019 for example:
13020 latex_additional_files = ["mystyle.sty"]
13022 'figure_align'
13024 Latex figure float alignment, default ‘htbp’ (here, top, bot‐
13025 tom, page). Whenever an image doesn’t fit into the current
13026 page, it will be ‘floated’ into the next page but may be pre‐
13027 ceded by any other text. If you don’t like this behavior, use
13028 ‘H’ which will disable floating and position figures strictly
13029 in the order they appear in the source.
13030 New in version 1.3.
13032 'atendofbody'
13035 Additional document content (right before the indices),
13036 default empty.
13037 New in version 1.5.
13039 'footer'
13042 Additional footer content (before the indices), default empty.
13043 Deprecated since version 1.5: Use 'atendofbody' key instead.
13045 · Keys that don’t need to be overridden unless in special cases are:
13048 'extraclassoptions'
13050 The default is the empty string. Example: 'extraclassoptions':
13051 'openany' will allow chapters (for documents of the 'manual'
13052 type) to start on any page.
13053 New in version 1.2.
13055 Changed in version 1.6: Added this documentation.
13058 'maxlistdepth'
13061 LaTeX allows by default at most 6 levels for nesting list and
13062 quote-like environments, with at most 4 enumerated lists, and
13063 4 bullet lists. Setting this key for example to '10' (as a
13064 string) will allow up to 10 nested levels (of all sorts).
13065 Leaving it to the empty string means to obey the LaTeX
13066 default.
13067 WARNING:
13069 · Using this key may prove incompatible with some LaTeX
13071 packages or special document classes which do their own
13072 list customization.
13073 · The key setting is silently ignored if \usepackage{enu‐
13075 mitem} is executed inside the document preamble. Use then
13076 rather the dedicated commands of this LaTeX package.
13077 New in version 1.5.
13079 'inputenc'
13082 “inputenc” package inclusion, defaults to '\\usepack‐
13083 age[utf8]{inputenc}' when using pdflatex. Otherwise empty.
13084 Changed in version 1.4.3: Previously '\\usepackage[utf8]{inpu‐
13086 tenc}' was used for all compilers.
13087 'cmappkg'
13090 “cmap” package inclusion, default '\\usepackage{cmap}'.
13091 New in version 1.2.
13093 'fontenc'
13096 “fontenc” package inclusion, defaults to '\\usepack‐
13097 age[T1]{fontenc}'.
13098 If 'pdflatex' is the latex_engine, one can add LGR for support
13100 of Greek letters in the document, and also X2 (or T2A) for
13101 Cyrillic letters, like this:
13102 r'\usepackage[LGR,X2,T1]{fontenc}'
13104 ATTENTION:
13106 If Greek is main language, do not use this key. Since
13107 Sphinx 2.2.1, xelatex will be used automatically as
13108 latex_engine. Formerly, Sphinx did not support producing
13109 PDF via LaTeX with Greek as main language.
13110 Prior to 2.0, Unicode Greek letters were escaped to use
13112 LaTeX math mark-up. This is not the case anymore, and the
13113 above must be used (only in case of 'pdflatex' engine) if
13114 the source contains such Unicode Greek.
13115 On Ubuntu xenial, packages texlive-lang-greek and cm-super
13117 (for the latter, only if the 'fontpkg' setting is left to
13118 its default) are needed for LGR to work. In place of
13119 cm-super one can install smaller cm-super-minimal, but it
13120 requires the LaTeX document to execute \usepack‐
13121 age[10pt]{type1ec} before loading fontenc. Thus, use this
13122 key with this extra at its start if needed.
13123 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
13125 when latex_engine is 'xelatex'.
13126 Changed in version 1.6: 'lualatex' uses fontspec per default
13129 like 'xelatex'.
13130 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
13133 tures[\rmfamily,\sffamily]{} to disable TeX ligatures.
13134 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
13137 support of occasional Greek or Cyrillic ('pdflatex' only, as
13138 this support is provided natively by 'platex' and only
13139 requires suitable font with 'xelatex'/'lualatex').
13140 'textgreek'
13143 The default ('pdflatex' only) is '\\usepackage{textalpha}',
13144 but only if 'fontenc' was modified by user to include LGR
13145 option. If not, the key value will be forced to be the empty
13146 string.
13147 This is needed for pdfLaTeX to support Unicode input of Greek
13149 letters such as φύσις. Expert users may want to load the tex‐
13150 talpha package with its option normalize-symbols.
13151 HINT:
13153 Unicode Greek (but no further Unicode symbols) in math can
13154 be supported by 'pdflatex' from setting this key to
13155 r'\usepackage{textalpha,alphabeta}'. Then :math:`α`
13156 (U+03B1) will render as \alpha. For wider Unicode support
13157 in math input, see the discussion of latex_engine.
13158 With 'platex' (Japanese), 'xelatex' or 'lualatex', this key
13160 is ignored.
13161 New in version 2.0.
13163 'geometry'
13166 “geometry” package inclusion, the default definition is:
13167 '\\usepackage{geometry}'
13168 with an additional [dvipdfm] for Japanese documents. The
13170 Sphinx LaTeX style file executes:
13171 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
13172 par=0.5in}{geometry}
13173 which can be customized via corresponding ‘sphinxsetup’
13175 options.
13176 New in version 1.5.
13178 Changed in version 1.5.2: dvipdfm option if latex_engine is
13181 'platex'.
13182 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
13185 Changed in version 1.5.3: The location in the LaTeX file has
13188 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
13189 hence also after insertion of 'fontpkg' key. This is in order
13190 to handle the paper layout options in a special way for Japa‐
13191 nese documents: the text width will be set to an integer mul‐
13192 tiple of the zenkaku width, and the text height to an integer
13193 multiple of the baseline. See the hmargin documentation for
13194 more.
13195 'hyperref'
13198 “hyperref” package inclusion; also loads package “hypcap” and
13199 issues \urlstyle{same}. This is done after sphinx.sty file is
13200 loaded and before executing the contents of 'preamble' key.
13201 ATTENTION:
13203 Loading of packages “hyperref” and “hypcap” is mandatory.
13204 New in version 1.5: Previously this was done from inside
13206 sphinx.sty.
13207 'maketitle'
13210 “maketitle” call, default '\\sphinxmaketitle'. Override if you
13211 want to generate a differently styled title page.
13212 HINT:
13214 If the key value is set to r'\newcommand\sphinxbackofti‐
13215 tlepage{<Extra material>}\sphinxmaketitle', then <Extra
13216 material> will be typeset on back of title page ('manual'
13217 docclass only).
13218 Changed in version 1.8.3: Original \maketitle from document
13220 class is not overwritten, hence is re-usable as part of some
13221 custom setting for this key.
13222 New in version 1.8.3: \sphinxbackoftitlepage optional macro.
13225 It can also be defined inside 'preamble' key rather than this
13226 one.
13227 'releasename'
13230 value that prefixes 'release' element on title page, default
13231 'Release'. As for title and author used in the tuples of
13232 latex_documents, it is inserted as LaTeX markup.
13233 'tableofcontents'
13235 “tableofcontents” call, default '\\sphinxtableofcontents' (it
13236 is a wrapper of unmodified \tableofcontents, which may itself
13237 be customized by user loaded packages.) Override if you want
13238 to generate a different table of contents or put content
13239 between the title page and the TOC.
13240 Changed in version 1.5: Previously the meaning of \tableofcon‐
13242 tents itself was modified by Sphinx. This created an incompat‐
13243 ibility with dedicated packages modifying it also such as
13244 “tocloft” or “etoc”.
13245 'transition'
13248 Commands used to display transitions, default
13249 '\n\n\\bigskip\\hrule\\bigskip\n\n'. Override if you want to
13250 display transitions differently.
13251 New in version 1.2.
13253 Changed in version 1.6: Remove unneeded {} after \\hrule.
13256 'printindex'
13259 “printindex” call, the last thing in the file, default
13260 '\\printindex'. Override if you want to generate the index
13261 differently or append some content after the index. For exam‐
13262 ple '\\footnotesize\\raggedright\\printindex' is advisable
13263 when the index is full of long entries.
13264 'fvset'
13266 Customization of fancyvrb LaTeX package. Sphinx does by
13267 default 'fvset': '\\fvset{fontsize=\\small}', to adjust for
13268 the large character width of the monospace font, used in
13269 code-blocks. You may need to modify this if you use custom
13270 fonts.
13271 New in version 1.8.
13273 Changed in version 2.0: Due to new default font choice for
13276 'xelatex' and 'lualatex' (FreeFont), Sphinx does \\fvset{font‐
13277 size=\\small} also with these engines (and not \\fvset{font‐
13278 size=auto}).
13279 · Keys that are set by other options and therefore should not be over‐
13282 ridden are:
13283 'docclass' 'classoptions' 'title' 'release' 'author' 'makeindex'
13285 'sphinxsetup' key
13287 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
13288 tomization interface:
13289 latex_elements = {
13291 'sphinxsetup': 'key1=value1, key2=value2, ...',
13292 }
13293 It defaults to empty. If non-empty, it will be passed as argument to
13295 the \sphinxsetup macro inside the document preamble, like this:
13296 \usepackage{sphinx}
13298 \sphinxsetup{key1=value1, key2=value2,...}
13299 New in version 1.5.
13301 HINT:
13304 It is possible to insert further uses of the \sphinxsetup LaTeX
13305 macro directly into the body of the document, via the help of the
13306 raw directive. Here is how this present chapter is styled in the
13307 PDF output:
13308 .. raw:: latex
13310 \begingroup
13312 \sphinxsetup{%
13313 verbatimwithframe=false,
13314 VerbatimColor={named}{OldLace},
13315 TitleColor={named}{DarkGoldenrod},
13316 hintBorderColor={named}{LightCoral},
13317 attentionborder=3pt,
13318 attentionBorderColor={named}{Crimson},
13319 attentionBgColor={named}{FloralWhite},
13320 noteborder=2pt,
13321 noteBorderColor={named}{Olive},
13322 cautionborder=3pt,
13323 cautionBorderColor={named}{Cyan},
13324 cautionBgColor={named}{LightCyan}}
13325 at the start of the chapter and:
13327 .. raw:: latex
13329 \endgroup
13331 at its end.
13333 The colors used in the above are provided by the svgnames option of
13335 the “xcolor” package:
13336 latex_elements = {
13338 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
13339 }
13340 LaTeX boolean keys require lowercase true or false values. Spaces
13342 around the commas and equal signs are ignored, spaces inside LaTeX
13343 macros may be significant.
13344 hmargin, vmargin
13346 The dimensions of the horizontal (resp. vertical) margins,
13347 passed as hmargin (resp. vmargin) option to the geometry pack‐
13348 age. The default is 1in, which is equivalent to {1in,1in}. Exam‐
13349 ple:
13350 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
13352 Japanese documents currently accept only the one-dimension for‐
13354 mat for these parameters. The geometry package is then passed
13355 suitable options to get the text width set to an exact multiple
13356 of the zenkaku width, and the text height set to an integer mul‐
13357 tiple of the baselineskip, with the closest fit for the margins.
13358 HINT:
13360 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
13361 use the nomag extra document class option (cf. 'extraclas‐
13362 soptions' key of latex_elements) or so-called TeX “true”
13363 units:
13364 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
13366 New in version 1.5.3.
13368 marginpar
13371 The \marginparwidth LaTeX dimension, defaults to 0.5in. For Ja‐
13372 panese documents, the value is modified to be the closest inte‐
13373 ger multiple of the zenkaku width.
13374 New in version 1.5.3.
13376 verbatimwithframe
13379 default true. Boolean to specify if code-blocks and literal
13380 includes are framed. Setting it to false does not deactivate use
13381 of package “framed”, because it is still in use for the optional
13382 background colour.
13383 verbatimwrapslines
13385 default true. Tells whether long lines in code-block’s contents
13386 should wrap.
13387 literalblockcappos
13389 default t for “top”. Decides the caption position. Alternative
13390 is b (“bottom”).
13391 New in version 1.7.
13393 verbatimhintsturnover
13396 default true. If true, code-blocks display “continued on next
13397 page”, “continued from previous page” hints in case of page‐
13398 breaks.
13399 New in version 1.6.3.
13401 Changed in version 1.7: the default changed from false to true.
13404 verbatimcontinuedalign, verbatimcontinuesalign
13407 default r. Horizontal position relative to the framed contents:
13408 either l (left aligned), r (right aligned) or c (centered).
13409 New in version 1.7.
13411 parsedliteralwraps
13414 default true. Tells whether long lines in parsed-literal’s con‐
13415 tents should wrap.
13416 New in version 1.5.2: set this option value to false to recover
13418 former behaviour.
13419 inlineliteralwraps
13422 default true. Allows linebreaks inside inline literals: but
13423 extra potential break-points (additionally to those allowed by
13424 LaTeX at spaces or for hyphenation) are currently inserted only
13425 after the characters . , ; ? ! /. Due to TeX internals, white
13426 space in the line will be stretched (or shrunk) in order to
13427 accomodate the linebreak.
13428 New in version 1.5: set this option value to false to recover
13430 former behaviour.
13431 verbatimvisiblespace
13434 default \textcolor{red}{\textvisiblespace}. When a long code
13435 line is split, the last space character from the source code
13436 line right before the linebreak location is typeset using this.
13437 verbatimcontinued
13439 A LaTeX macro inserted at start of continuation code lines. Its
13440 (complicated…) default typesets a small red hook pointing to the
13441 right:
13442 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
13444 Changed in version 1.5: The breaking of long code lines was
13446 added at 1.4.2. The default definition of the continuation sym‐
13447 bol was changed at 1.5 to accomodate various font sizes (e.g.
13448 code-blocks can be in footnotes).
13449 TitleColor
13452 default {rgb}{0.126,0.263,0.361}. The colour for titles (as con‐
13453 figured via use of package “titlesec”.)
13454 WARNING:
13456 Colours set via 'sphinxsetup' must obey the syntax of the argument
13457 of the color/xcolor packages \definecolor command.
13458 InnerLinkColor
13460 default {rgb}{0.208,0.374,0.486}. A colour passed to hyperref as
13461 value of linkcolor and citecolor.
13462 OuterLinkColor
13464 default {rgb}{0.216,0.439,0.388}. A colour passed to hyperref as
13465 value of filecolor, menucolor, and urlcolor.
13466 VerbatimColor
13468 default {rgb}{1,1,1}. The background colour for code-blocks. The
13469 default is white.
13470 VerbatimBorderColor
13472 default {rgb}{0,0,0}. The frame color, defaults to black.
13473 VerbatimHighlightColor
13475 default {rgb}{0.878,1,1}. The color for highlighted lines.
13476 New in version 1.6.6.
13478 NOTE:
13481 Starting with this colour key, and for all others coming next, the
13482 actual names declared to “color” or “xcolor” are prefixed with
13483 “sphinx”.
13484 verbatimsep
13486 default \fboxsep. The separation between code lines and the
13487 frame.
13488 verbatimborder
13490 default \fboxrule. The width of the frame around code-blocks.
13491 shadowsep
13493 default 5pt. The separation between contents and frame for
13494 contents and topic boxes.
13495 shadowsize
13497 default 4pt. The width of the lateral “shadow” to the right.
13498 shadowrule
13500 default \fboxrule. The width of the frame around topic boxes.
13501 noteBorderColor, hintBorderColor,
13503 importantBorderColor, tipBorderColor default {rgb}{0,0,0}
13504 (black). The colour for the two horizontal rules used by Sphinx
13505 in LaTeX for styling a note type admonition.
13506 noteborder, hintborder, importantborder, tipborder
13508 default 0.5pt. The width of the two horizontal rules.
13509 warningBorderColor, cautionBorderColor,
13511 attentionBorderColor, dangerBorderColor, errorBorderColor
13512 default {rgb}{0,0,0} (black). The colour for the admonition
13513 frame.
13514 warningBgColor, cautionBgColor,
13516 attentionBgColor, dangerBgColor, errorBgColor default
13517 {rgb}{1,1,1} (white). The background colours for the respective
13518 admonitions.
13519 warningborder, cautionborder,
13521 attentionborder, dangerborder, errorborder default 1pt. The
13522 width of the frame.
13523 AtStartFootnote
13525 default \mbox{ }. LaTeX macros inserted at the start of the
13526 footnote text at bottom of page, after the footnote number.
13527 BeforeFootnote
13529 default \leavevmode\unskip. LaTeX macros inserted before the
13530 footnote mark. The default removes possible space before it
13531 (else, TeX could insert a linebreak there).
13532 New in version 1.5.
13534 HeaderFamily
13537 default \sffamily\bfseries. Sets the font used by headings.
13538 LaTeX macros and environments
13540 Here are some macros from the package file sphinx.sty and class files
13541 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
13542 ing redefinitions. Check the respective files for the defaults.
13543 Macros
13545 · text styling commands:
13546 · \sphinxstrong,
13548 · \sphinxbfcode,
13550 · \sphinxemail,
13552 · \sphinxtablecontinued,
13554 · \sphinxtitleref,
13556 · \sphinxmenuselection,
13558 · \sphinxaccelerator,
13560 · \sphinxcrossref,
13562 · \sphinxtermref,
13564 · \sphinxoptional.
13566 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
13568 possibilities of conflict with LaTeX packages.
13569 · more text styling:
13572 · \sphinxstyleindexentry,
13574 · \sphinxstyleindexextra,
13576 · \sphinxstyleindexpageref,
13578 · \sphinxstyletopictitle,
13580 · \sphinxstylesidebartitle,
13582 · \sphinxstyleothertitle,
13584 · \sphinxstylesidebarsubtitle,
13586 · \sphinxstyletheadfamily,
13588 · \sphinxstyleemphasis,
13590 · \sphinxstyleliteralemphasis,
13592 · \sphinxstylestrong,
13594 · \sphinxstyleliteralstrong,
13596 · \sphinxstyleabbreviation,
13598 · \sphinxstyleliteralintitle,
13600 · \sphinxstylecodecontinued,
13602 · \sphinxstylecodecontinues.
13604 New in version 1.5: these macros were formerly hard-coded as non cus‐
13606 tomizable \texttt, \emph, etc…
13607 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
13610 ily and allows multiple paragraphs in header cells of tables.
13611 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
13614 continues.
13615 · \sphinxtableofcontents: it is a wrapper (defined differently in
13618 sphinxhowto.cls and in sphinxmanual.cls) of standard \tableofcon‐
13619 tents. The macro \sphinxtableofcontentshook is executed during its
13620 expansion right before \tableofcontents itself.
13621 Changed in version 1.5: formerly, the meaning of \tableofcontents was
13623 modified by Sphinx.
13624 Changed in version 2.0: hard-coded redefinitions of \l@section and
13627 \l@subsection formerly done during loading of 'manual' docclass are
13628 now executed later via \sphinxtableofcontentshook. This macro is
13629 also executed by the 'howto' docclass, but defaults to empty with it.
13630 · \sphinxmaketitle: it is defined in the class files sphinxmanual.cls
13633 and sphinxhowto.cls and is used as default setting of 'maketitle'
13634 latex_elements key.
13635 Changed in version 1.8.3: formerly, \maketitle from LaTeX document
13637 class was modified by Sphinx.
13638 · \sphinxbackoftitlepage: for 'manual' docclass, and if it is defined,
13641 it gets executed at end of \sphinxmaketitle, before the final
13642 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
13643 latex_elements to add a custom definition of \sphinxbackoftitlepage.
13644 New in version 1.8.3.
13646 · \sphinxcite: it is a wrapper of standard \cite for citation refer‐
13649 ences.
13650 Environments
13652 · a figure may have an optional legend with arbitrary body elements:
13653 they are rendered in a sphinxlegend environment. The default defini‐
13654 tion issues \small, and ends with \par.
13655 New in version 1.5.6: formerly, the \small was hardcoded in LaTeX
13657 writer and the ending \par was lacking.
13658 · environments associated with admonitions:
13661 · sphinxnote,
13663 · sphinxhint,
13665 · sphinximportant,
13667 · sphinxtip,
13669 · sphinxwarning,
13671 · sphinxcaution,
13673 · sphinxattention,
13675 · sphinxdanger,
13677 · sphinxerror.
13679 They may be \renewenvironment ‘d individually, and must then be
13681 defined with one argument (it is the heading of the notice, for exam‐
13682 ple Warning: for warning directive, if English is the document lan‐
13683 guage). Their default definitions use either the sphinxheavybox (for
13684 the last 5 ones) or the sphinxlightbox environments, configured to
13685 use the parameters (colours, border thickness) specific to each type,
13686 which can be set via 'sphinxsetup' string.
13687 Changed in version 1.5: use of public environment names, separate
13689 customizability of the parameters, such as noteBorderColor, notebor‐
13690 der, warningBgColor, warningBorderColor, warningborder, …
13691 · the contents directive (with :local: option) and the topic directive
13694 are implemented by environment sphinxShadowBox.
13695 New in version 1.4.2: former code refactored into an environment
13697 allowing page breaks.
13698 Changed in version 1.5: options shadowsep, shadowsize, shadowrule.
13701 · the literal blocks (via :: or code-block), are implemented using
13704 sphinxVerbatim environment which is a wrapper of Verbatim environment
13705 from package fancyvrb.sty. It adds the handling of the top caption
13706 and the wrapping of long lines, and a frame which allows pagebreaks.
13707 Inside tables the used environment is sphinxVerbatimintable (it does
13708 not draw a frame, but allows a caption).
13709 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
13711 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
13712 intable is used inside tables.
13713 New in version 1.5: options verbatimwithframe, verbatimwrapslines,
13716 verbatimsep, verbatimborder.
13717 New in version 1.6.6: support for :emphasize-lines: option
13720 New in version 1.6.6: easier customizability of the formatting via
13723 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
13724 · the bibliography uses sphinxthebibliography and the Python Module
13727 index as well as the general index both use sphinxtheindex; these
13728 environments are wrappers of the thebibliography and respectively
13729 theindex environments as provided by the document class (or pack‐
13730 ages).
13731 Changed in version 1.5: formerly, the original environments were mod‐
13733 ified by Sphinx.
13734 Miscellany
13737 · the section, subsection, … headings are set using titlesec’s
13738 \titleformat command.
13739 · for the 'manual' docclass, the chapter headings can be customized
13741 using fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
13742 sphinx.sty has custom re-definitions in case of fncychap option
13743 Bjarne.
13744 Changed in version 1.5: formerly, use of fncychap with other styles
13746 than Bjarne was dysfunctional.
13747 HINT:
13750 As an experimental feature, Sphinx can use user-defined template
13751 file for LaTeX source if you have a file named _tem‐
13752 plates/latex.tex_t in your project.
13753 New in version 1.5: currently all template variables are unstable
13755 and undocumented.
13756 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
13759 can be added to _templates/ to configure some aspects of table ren‐
13760 dering (such as the caption position).
13761 New in version 1.6: currently all template variables are unstable
13763 and undocumented.
13764
13767 Since many projects will need special features in their documentation,
13768 Sphinx is designed to be extensible on several levels.
13769 This is what you can do in an extension: First, you can add new
13771 builders to support new output formats or actions on the parsed docu‐
13772 ments. Then, it is possible to register custom reStructuredText roles
13773 and directives, extending the markup. And finally, there are so-called
13774 “hook points” at strategic places throughout the build process, where
13775 an extension can register a hook and run specialized code.
13776 An extension is simply a Python module. When an extension is loaded,
13778 Sphinx imports this module and executes its setup() function, which in
13779 turn notifies Sphinx of everything the extension offers – see the
13780 extension tutorial for examples.
13781 The configuration file itself can be treated as an extension if it con‐
13783 tains a setup() function. All other extensions to load must be listed
13784 in the extensions configuration value.
13785 Discovery of builders by entry point
13787 New in version 1.6.
13788 Builder extensions can be discovered by means of entry points so that
13791 they do not have to be listed in the extensions configuration value.
13792 Builder extensions should define an entry point in the sphinx.builders
13794 group. The name of the entry point needs to match your builder’s name
13795 attribute, which is the name passed to the sphinx-build -b option. The
13796 entry point value should equal the dotted name of the extension module.
13797 Here is an example of how an entry point for ‘mybuilder’ can be defined
13798 in the extension’s setup.py:
13799 setup(
13801 # ...
13802 entry_points={
13803 'sphinx.builders': [
13804 'mybuilder = my.extension.module',
13805 ],
13806 }
13807 )
13808 Note that it is still necessary to register the builder using
13810 add_builder() in the extension’s setup() function.
13811 Important objects
13813 There are several key objects whose API you will use while writing an
13814 extension. These are:
13815 Application
13817 The application object (usually called app) is an instance of
13818 Sphinx. It controls most high-level functionality, such as the
13819 setup of extensions, event dispatching and producing output
13820 (logging).
13821 If you have the environment object, the application is available
13823 as env.app.
13824 Environment
13826 The build environment object (usually called env) is an instance
13827 of BuildEnvironment. It is responsible for parsing the source
13828 documents, stores all metadata about the document collection and
13829 is serialized to disk after each build.
13830 Its API provides methods to do with access to metadata, resolv‐
13832 ing references, etc. It can also be used by extensions to cache
13833 information that should persist for incremental rebuilds.
13834 If you have the application or builder object, the environment
13836 is available as app.env or builder.env.
13837 Builder
13839 The builder object (usually called builder) is an instance of a
13840 specific subclass of Builder. Each builder class knows how to
13841 convert the parsed documents into an output format, or otherwise
13842 process them (e.g. check external links).
13843 If you have the application object, the builder is available as
13845 app.builder.
13846 Config The config object (usually called config) provides the values of
13848 configuration values set in conf.py as attributes. It is an
13849 instance of Config.
13850 The config is available as app.config or env.config.
13852 To see an example of use of these objects, refer to ../develop‐
13854 ment/tutorials/index.
13855 Build Phases
13857 One thing that is vital in order to understand extension mechanisms is
13858 the way in which a Sphinx project is built: this works in several
13859 phases.
13860 Phase 0: Initialization
13862 In this phase, almost nothing of interest to us happens. The source
13863 directory is searched for source files, and extensions are initial‐
13864 ized. Should a stored build environment exist, it is loaded, other‐
13865 wise a new one is created.
13866 Phase 1: Reading
13868 In Phase 1, all source files (and on subsequent builds, those that
13869 are new or changed) are read and parsed. This is the phase where
13870 directives and roles are encountered by docutils, and the corre‐
13871 sponding code is executed. The output of this phase is a doctree
13872 for each source file; that is a tree of docutils nodes. For docu‐
13873 ment elements that aren’t fully known until all existing files are
13874 read, temporary nodes are created.
13875 There are nodes provided by docutils, which are documented in the
13877 docutils documentation. Additional nodes are provided by Sphinx and
13878 documented here.
13879 During reading, the build environment is updated with all meta- and
13881 cross reference data of the read documents, such as labels, the
13882 names of headings, described Python objects and index entries. This
13883 will later be used to replace the temporary nodes.
13884 The parsed doctrees are stored on the disk, because it is not possi‐
13886 ble to hold all of them in memory.
13887 Phase 2: Consistency checks
13889 Some checking is done to ensure no surprises in the built documents.
13890 Phase 3: Resolving
13892 Now that the metadata and cross-reference data of all existing docu‐
13893 ments is known, all temporary nodes are replaced by nodes that can
13894 be converted into output using components called transforms. For
13895 example, links are created for object references that exist, and
13896 simple literal nodes are created for those that don’t.
13897 Phase 4: Writing
13899 This phase converts the resolved doctrees to the desired output for‐
13900 mat, such as HTML or LaTeX. This happens via a so-called docutils
13901 writer that visits the individual nodes of each doctree and produces
13902 some output in the process.
13903 NOTE:
13905 Some builders deviate from this general build plan, for example, the
13906 builder that checks external links does not need anything more than
13907 the parsed doctrees and therefore does not have phases 2–4.
13908 To see an example of application, refer to ../development/tutori‐
13910 als/todo.
13911 Extension metadata
13913 New in version 1.3.
13914 The setup() function can return a dictionary. This is treated by
13917 Sphinx as metadata of the extension. Metadata keys currently recog‐
13918 nized are:
13919 · 'version': a string that identifies the extension version. It is
13921 used for extension version requirement checking (see needs_exten‐
13922 sions) and informational purposes. If not given, "unknown version"
13923 is substituted.
13924 · 'env_version': an integer that identifies the version of env data
13926 structure if the extension stores any data to environment. It is
13927 used to detect the data structure has been changed from last build.
13928 The extensions have to increment the version when data structure has
13929 changed. If not given, Sphinx considers the extension does not
13930 stores any data to environment.
13931 · 'parallel_read_safe': a boolean that specifies if parallel reading of
13933 source files can be used when the extension is loaded. It defaults
13934 to False, i.e. you have to explicitly specify your extension to be
13935 parallel-read-safe after checking that it is.
13936 · 'parallel_write_safe': a boolean that specifies if parallel writing
13938 of output files can be used when the extension is loaded. Since
13939 extensions usually don’t negatively influence the process, this
13940 defaults to True.
13941 APIs used for writing extensions
13943 Application API
13944 Each Sphinx extension is a Python module with at least a setup() func‐
13945 tion. This function is called at initialization time with one argu‐
13946 ment, the application object representing the Sphinx process.
13947 class sphinx.application.Sphinx
13949 This application object has the public API described in the fol‐
13950 lowing.
13951 Extension setup
13953 These methods are usually called in an extension’s setup() function.
13954 Examples of using the Sphinx extension API can be seen in the
13956 sphinx.ext package.
13957 Sphinx.setup_extension(name)
13959 Import and setup a Sphinx extension module.
13960 Load the extension given by the module name. Use this if your
13962 extension needs the features provided by another extension.
13963 No-op if called twice.
13964 Sphinx.require_sphinx(version)
13966 Check the Sphinx version if requested.
13967 Compare version (which must be a major.minor version string,
13969 e.g. '1.1') with the version of the running Sphinx, and abort
13970 the build when it is too old.
13971 New in version 1.0.
13973 Sphinx.connect(event, callback)
13976 Register callback to be called when event is emitted.
13977 For details on available core events and the arguments of call‐
13979 back functions, please see Sphinx core events.
13980 The method returns a “listener ID” that can be used as an argu‐
13982 ment to disconnect().
13983 Sphinx.disconnect(listener_id)
13985 Unregister callback by listener_id.
13986 Sphinx.add_builder(builder)
13988 Register a new builder.
13989 builder must be a class that inherits from Builder.
13991 Changed in version 1.8: Add override keyword.
13993 Sphinx.add_config_value(name, default, rebuild)
13996 Register a configuration value.
13997 This is necessary for Sphinx to recognize new values and set
13999 default values accordingly. The name should be prefixed with
14000 the extension name, to avoid clashes. The default value can be
14001 any Python object. The string value rebuild must be one of
14002 those values:
14003 · 'env' if a change in the setting only takes effect when a doc‐
14005 ument is parsed – this means that the whole environment must
14006 be rebuilt.
14007 · 'html' if a change in the setting needs a full rebuild of HTML
14009 documents.
14010 · '' if a change in the setting will not need any special
14012 rebuild.
14013 Changed in version 0.6: Changed rebuild from a simple boolean
14015 (equivalent to '' or 'env') to a string. However, booleans are
14016 still accepted and converted internally.
14017 Changed in version 0.4: If the default value is a callable, it
14020 will be called with the config object as its argument in order
14021 to get the default value. This can be used to implement config
14022 values whose default depends on other values.
14023 Sphinx.add_event(name)
14026 Register an event called name.
14027 This is needed to be able to emit it.
14029 Sphinx.set_translator(name, translator_class)
14031 Register or override a Docutils translator class.
14032 This is used to register a custom output translator or to
14034 replace a builtin translator. This allows extensions to use
14035 custom translator and define custom nodes for the translator
14036 (see add_node()).
14037 New in version 1.3.
14039 Changed in version 1.8: Add override keyword.
14042 Sphinx.add_node(node, **kwds)
14045 Register a Docutils node class.
14046 This is necessary for Docutils internals. It may also be used
14048 in the future to validate nodes in the parsed documents.
14049 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
14051 page writers can be given as keyword arguments: the keyword
14052 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
14053 info' or any other supported translators, the value a 2-tuple of
14054 (visit, depart) methods. depart can be None if the visit func‐
14055 tion raises docutils.nodes.SkipNode. Example:
14056 class math(docutils.nodes.Element): pass
14058 def visit_math_html(self, node):
14060 self.body.append(self.starttag(node, 'math'))
14061 def depart_math_html(self, node):
14062 self.body.append('</math>')
14063 app.add_node(math, html=(visit_math_html, depart_math_html))
14065 Obviously, translators for which you don’t specify visitor meth‐
14067 ods will choke on the node when encountered in a document to
14068 translate.
14069 Changed in version 0.5: Added the support for keyword arguments
14071 giving visit functions.
14072 Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
14075 Register a Docutils node class as a numfig target.
14076 Sphinx numbers the node automatically. And then the users can
14078 refer it using numref.
14079 figtype is a type of enumerable nodes. Each figtypes have indi‐
14081 vidual numbering sequences. As a system figtypes, figure, table
14082 and code-block are defined. It is able to add custom nodes to
14083 these default figtypes. It is also able to define new custom
14084 figtype if new figtype is given.
14085 title_getter is a getter function to obtain the title of node.
14087 It takes an instance of the enumerable node, and it must return
14088 its title as string. The title is used to the default title of
14089 references for ref. By default, Sphinx searches docu‐
14090 tils.nodes.caption or docutils.nodes.title from the node as a
14091 title.
14092 Other keyword arguments are used for node visitor functions. See
14094 the Sphinx.add_node() for details.
14095 New in version 1.4.
14097 Sphinx.add_directive(name, func, content, arguments, **options)
14100 Sphinx.add_directive(name, directiveclass)
14102 Register a Docutils directive.
14103 name must be the prospective directive name. There are two pos‐
14105 sible ways to write a directive:
14106 · In the docutils 0.4 style, obj is the directive function.
14108 content, arguments and options are set as attributes on the
14109 function and determine whether the directive has content,
14110 arguments and options, respectively. This style is depre‐
14111 cated.
14112 · In the docutils 0.5 style, obj is the directive class. It
14114 must already have attributes named has_content, required_argu‐
14115 ments, optional_arguments, final_argument_whitespace and
14116 option_spec that correspond to the options for the function
14117 way. See the Docutils docs for details.
14118 The directive class must inherit from the class docu‐
14120 tils.parsers.rst.Directive.
14121 For example, the (already existing) literalinclude directive
14123 would be added like this:
14124 from docutils.parsers.rst import Directive, directives
14126 class LiteralIncludeDirective(Directive):
14128 has_content = True
14129 required_arguments = 1
14130 optional_arguments = 0
14131 final_argument_whitespace = True
14132 option_spec = {
14133 'class': directives.class_option,
14134 'name': directives.unchanged,
14135 }
14136 def run(self):
14138 ...
14139 add_directive('literalinclude', LiteralIncludeDirective)
14141 Changed in version 0.6: Docutils 0.5-style directive classes are
14143 now supported.
14144 Deprecated since version 1.8: Docutils 0.4-style (function
14147 based) directives support is deprecated.
14148 Changed in version 1.8: Add override keyword.
14151 Sphinx.add_role(name, role)
14154 Register a Docutils role.
14155 name must be the role name that occurs in the source, role the
14157 role function. Refer to the Docutils documentation for more
14158 information.
14159 Changed in version 1.8: Add override keyword.
14161 Sphinx.add_generic_role(name, nodeclass)
14164 Register a generic Docutils role.
14165 Register a Docutils role that does nothing but wrap its contents
14167 in the node given by nodeclass.
14168 New in version 0.6.
14170 Changed in version 1.8: Add override keyword.
14173 Sphinx.add_domain(domain)
14176 Register a domain.
14177 Make the given domain (which must be a class; more precisely, a
14179 subclass of Domain) known to Sphinx.
14180 New in version 1.0.
14182 Changed in version 1.8: Add override keyword.
14185 Sphinx.override_domain(domain)
14188 Override a registered domain.
14189 Make the given domain class known to Sphinx, assuming that there
14191 is already a domain with its .name. The new domain must be a
14192 subclass of the existing one.
14193 New in version 1.0.
14195 Deprecated since version 1.8: Integrated to add_domain().
14198 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
14201 **options)
14202 Sphinx.add_directive_to_domain(domain, name, directiveclass)
14204 Register a Docutils directive in a domain.
14205 Like add_directive(), but the directive is added to the domain
14207 named domain.
14208 New in version 1.0.
14210 Changed in version 1.8: Add override keyword.
14213 Sphinx.add_role_to_domain(domain, name, role)
14216 Register a Docutils role in a domain.
14217 Like add_role(), but the role is added to the domain named
14219 domain.
14220 New in version 1.0.
14222 Changed in version 1.8: Add override keyword.
14225 Sphinx.add_index_to_domain(domain, index)
14228 Register a custom index for a domain.
14229 Add a custom index class to the domain named domain. index must
14231 be a subclass of Index.
14232 New in version 1.0.
14234 Changed in version 1.8: Add override keyword.
14237 Sphinx.add_object_type(directivename, rolename, indextemplate='',
14240 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
14241 Register a new object type.
14242 This method is a very convenient way to add a new object type
14244 that can be cross-referenced. It will do this:
14245 · Create a new directive (called directivename) for documenting
14247 an object. It will automatically add index entries if index‐
14248 template is nonempty; if given, it must contain exactly one
14249 instance of %s. See the example below for how the template
14250 will be interpreted.
14251 · Create a new role (called rolename) to cross-reference to
14253 these object descriptions.
14254 · If you provide parse_node, it must be a function that takes a
14256 string and a docutils node, and it must populate the node with
14257 children parsed from the string. It must then return the name
14258 of the item to be used in cross-referencing and index entries.
14259 See the conf.py file in the source for this documentation for
14260 an example.
14261 · The objname (if not given, will default to directivename)
14263 names the type of object. It is used when listing objects,
14264 e.g. in search results.
14265 For example, if you have this call in a custom Sphinx extension:
14267 app.add_object_type('directive', 'dir', 'pair: %s; directive')
14269 you can use this markup in your documents:
14271 .. rst:directive:: function
14273 Document a function.
14275 <...>
14277 See also the :rst:dir:`function` directive.
14279 For the directive, an index entry will be generated as if you
14281 had prepended
14282 .. index:: pair: function; directive
14284 The reference node will be of class literal (so it will be ren‐
14286 dered in a proportional font, as appropriate for code) unless
14287 you give the ref_nodeclass argument, which must be a docutils
14288 node class. Most useful are docutils.nodes.emphasis or docu‐
14289 tils.nodes.strong – you can also use docutils.nodes.generated if
14290 you want no further text decoration. If the text should be
14291 treated as literal (e.g. no smart quote replacement), but not
14292 have typewriter styling, use sphinx.addnodes.literal_emphasis or
14293 sphinx.addnodes.literal_strong.
14294 For the role content, you have the same syntactical possibili‐
14296 ties as for standard Sphinx roles (see xref-syntax).
14297 Changed in version 1.8: Add override keyword.
14299 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
14302 ref_nodeclass=None, objname='')
14303 Register a new crossref object type.
14304 This method is very similar to add_object_type() except that the
14306 directive it generates must be empty, and will produce no out‐
14307 put.
14308 That means that you can add semantic targets to your sources,
14310 and refer to them using custom roles instead of generic ones
14311 (like ref). Example call:
14312 app.add_crossref_type('topic', 'topic', 'single: %s',
14314 docutils.nodes.emphasis)
14315 Example usage:
14317 .. topic:: application API
14319 The application API
14321 -------------------
14322 Some random text here.
14324 See also :topic:`this section <application API>`.
14326 (Of course, the element following the topic directive needn’t be
14328 a section.)
14329 Changed in version 1.8: Add override keyword.
14331 Sphinx.add_transform(transform)
14334 Register a Docutils transform to be applied after parsing.
14335 Add the standard docutils Transform subclass transform to the
14337 list of transforms that are applied after Sphinx parses a reST
14338 document.
14339 priority range categories for Sphinx transforms
14341 ┌─────────┬────────────────────────────┐
14342 │Priority │ Main purpose in Sphinx │
14343 └─────────┴────────────────────────────┘
14344 │0-99 │ Fix invalid nodes by docu‐ │
14348 │ │ tils. Translate a doctree. │
14349 ├─────────┼────────────────────────────┤
14350 │100-299 │ Preparation │
14351 ├─────────┼────────────────────────────┤
14352 │300-399 │ early │
14353 ├─────────┼────────────────────────────┤
14354 │400-699 │ main │
14355 ├─────────┼────────────────────────────┤
14356 │700-799 │ Post processing. Deadline │
14357 │ │ to modify text and refer‐ │
14358 │ │ encing. │
14359 ├─────────┼────────────────────────────┤
14360 │800-899 │ Collect referencing and │
14361 │ │ referenced nodes. Domain │
14362 │ │ processing. │
14363 ├─────────┼────────────────────────────┤
14364 │900-999 │ Finalize and clean up. │
14365 └─────────┴────────────────────────────┘
14366 refs: Transform Priority Range Categories
14368 Sphinx.add_post_transform(transform)
14370 Register a Docutils transform to be applied before writing.
14371 Add the standard docutils Transform subclass transform to the
14373 list of transforms that are applied before Sphinx writes a docu‐
14374 ment.
14375 Sphinx.add_js_file(filename, **kwargs)
14377 Register a JavaScript file to include in the HTML output.
14378 Add filename to the list of JavaScript files that the default
14380 HTML template will include. The filename must be relative to
14381 the HTML static path , or a full URI with scheme. The keyword
14382 arguments are also accepted for attributes of <script> tag.
14383 Example:
14385 app.add_js_file('example.js')
14387 # => <script src="_static/example.js"></script>
14388 app.add_js_file('example.js', async="async")
14390 # => <script src="_static/example.js" async="async"></script>
14391 New in version 0.5.
14393 Changed in version 1.8: Renamed from app.add_javascript(). And
14396 it allows keyword arguments as attributes of script tag.
14397 Sphinx.add_css_file(filename, **kwargs)
14400 Register a stylesheet to include in the HTML output.
14401 Add filename to the list of CSS files that the default HTML tem‐
14403 plate will include. The filename must be relative to the HTML
14404 static path, or a full URI with scheme. The keyword arguments
14405 are also accepted for attributes of <link> tag.
14406 Example:
14408 app.add_css_file('custom.css')
14410 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
14411 app.add_css_file('print.css', media='print')
14413 # => <link rel="stylesheet" href="_static/print.css"
14414 # type="text/css" media="print" />
14415 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
14417 # => <link rel="alternate stylesheet" href="_static/fancy.css"
14418 # type="text/css" title="fancy" />
14419 New in version 1.0.
14421 Changed in version 1.6: Optional alternate and/or title
14424 attributes can be supplied with the alternate (of boolean type)
14425 and title (a string) arguments. The default is no title and
14426 alternate = False. For more information, refer to the
14427 documentation.
14428 Changed in version 1.8: Renamed from app.add_stylesheet(). And
14431 it allows keyword arguments as attributes of link tag.
14432 Sphinx.add_latex_package(packagename, options=None)
14435 Register a package to include in the LaTeX source code.
14436 Add packagename to the list of packages that LaTeX source code
14438 will include. If you provide options, it will be taken to usep‐
14439 ackage declaration.
14440 app.add_latex_package('mypackage')
14442 # => \usepackage{mypackage}
14443 app.add_latex_package('mypackage', 'foo,bar')
14444 # => \usepackage[foo,bar]{mypackage}
14445 New in version 1.3.
14447 Sphinx.add_lexer(alias, lexer)
14450 Register a new lexer for source code.
14451 Use lexer to highlight code blocks with the given language
14453 alias.
14454 New in version 0.6.
14456 Changed in version 2.1: Take a lexer class as an argument. An
14459 instance of lexers are still supported until Sphinx-3.x.
14460 Sphinx.add_autodocumenter(cls)
14463 Register a new documenter class for the autodoc extension.
14464 Add cls as a new documenter class for the sphinx.ext.autodoc
14466 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
14467 menter. This allows to auto-document new types of objects. See
14468 the source of the autodoc module for examples on how to subclass
14469 Documenter.
14470 Todo
14472 Add real docs for Documenter and subclassing
14473 New in version 0.6.
14475 Changed in version 2.2: Add override keyword.
14478 Sphinx.add_autodoc_attrgetter(type, getter)
14481 Register a new getattr-like function for the autodoc extension.
14482 Add getter, which must be a function with an interface compati‐
14484 ble to the getattr() builtin, as the autodoc attribute getter
14485 for objects that are instances of typ. All cases where autodoc
14486 needs to get an attribute of a type are then handled by this
14487 function instead of getattr().
14488 New in version 0.6.
14490 Sphinx.add_search_language(cls)
14493 Register a new language for the HTML search index.
14494 Add cls, which must be a subclass of sphinx.search.Search‐
14496 Language, as a support language for building the HTML full-text
14497 search index. The class must have a lang attribute that indi‐
14498 cates the language it should be used for. See html_search_lan‐
14499 guage.
14500 New in version 1.1.
14502 Sphinx.add_source_suffix(suffix, filetype)
14505 Register a suffix of source files.
14506 Same as source_suffix. The users can override this using the
14508 setting.
14509 New in version 1.8.
14511 Sphinx.add_source_parser(parser)
14514 Register a parser class.
14515 New in version 1.4.
14517 Changed in version 1.8: suffix argument is deprecated. It only
14520 accepts parser argument. Use add_source_suffix() API to regis‐
14521 ter suffix instead.
14522 Changed in version 1.8: Add override keyword.
14525 Sphinx.add_env_collector(collector)
14528 Register an environment collector class.
14529 Refer to collector-api.
14531 New in version 1.6.
14533 Sphinx.add_html_theme(name, theme_path)
14536 Register a HTML Theme.
14537 The name is a name of theme, and path is a full path to the
14539 theme (refs: distribute-your-theme).
14540 New in version 1.6.
14542 Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
14545 Register a math renderer for HTML.
14546 The name is a name of math renderer. Both inline_renderers and
14548 block_renderers are used as visitor functions for the HTML
14549 writer: the former for inline math node (nodes.math), the latter
14550 for block math node (nodes.math_block). Regarding visitor func‐
14551 tions, see add_node() for details.
14552 New in version 1.8.
14554 Sphinx.add_message_catalog(catalog, locale_dir)
14557 Register a message catalog.
14558 The catalog is a name of catalog, and locale_dir is a base path
14560 of message catalog. For more details, see
14561 sphinx.locale.get_translation().
14562 New in version 1.8.
14564 Sphinx.is_parallel_allowed(typ)
14567 Check parallel processing is allowed or not.
14568 typ is a type of processing; 'read' or 'write'.
14570 exception sphinx.application.ExtensionError
14572 All these methods raise this exception if something went wrong
14573 with the extension API.
14574 Emitting events
14576 class sphinx.application.Sphinx
14577 emit(event, *arguments)
14579 Emit event and pass arguments to the callback functions.
14580 Return the return values of all callbacks as a list. Do
14582 not emit core Sphinx events in extensions!
14583 emit_firstresult(event, *arguments)
14585 Emit event and pass arguments to the callback functions.
14586 Return the result of the first callback that doesn’t
14588 return None.
14589 New in version 0.5.
14591 Sphinx runtime information
14594 The application object also provides runtime information as attributes.
14595 Sphinx.project
14597 Target project. See Project.
14598 Sphinx.srcdir
14600 Source directory.
14601 Sphinx.confdir
14603 Directory containing conf.py.
14604 Sphinx.doctreedir
14606 Directory for storing pickled doctrees.
14607 Sphinx.outdir
14609 Directory for storing built document.
14610 Sphinx core events
14612 These events are known to the core. The arguments shown are given to
14613 the registered event handlers. Use Sphinx.connect() in an extension’s
14614 setup function (note that conf.py can also have a setup function) to
14615 connect handlers to the events. Example:
14616 def source_read_handler(app, docname, source):
14618 print('do something here...')
14619 def setup(app):
14621 app.connect('source-read', source_read_handler)
14622 builder-inited(app)
14624 Emitted when the builder object has been created. It is avail‐
14625 able as app.builder.
14626 config-inited(app, config)
14628 Emitted when the config object has been initialized.
14629 New in version 1.8.
14631 env-get-outdated(app, env, added, changed, removed)
14634 Emitted when the environment determines which source files have
14635 changed and should be re-read. added, changed and removed are
14636 sets of docnames that the environment has determined. You can
14637 return a list of docnames to re-read in addition to these.
14638 New in version 1.1.
14640 env-purge-doc(app, env, docname)
14643 Emitted when all traces of a source file should be cleaned from
14644 the environment, that is, if the source file is removed or
14645 before it is freshly read. This is for extensions that keep
14646 their own caches in attributes of the environment.
14647 For example, there is a cache of all modules on the environment.
14649 When a source file has been changed, the cache’s entries for the
14650 file are cleared, since the module declarations could have been
14651 removed from the file.
14652 New in version 0.5.
14654 env-before-read-docs(app, env, docnames)
14657 Emitted after the environment has determined the list of all
14658 added and changed files and just before it reads them. It
14659 allows extension authors to reorder the list of docnames
14660 (inplace) before processing, or add more docnames that Sphinx
14661 did not consider changed (but never add any docnames that are
14662 not in env.found_docs).
14663 You can also remove document names; do this with caution since
14665 it will make Sphinx treat changed files as unchanged.
14666 New in version 1.3.
14668 source-read(app, docname, source)
14671 Emitted when a source file has been read. The source argument
14672 is a list whose single element is the contents of the source
14673 file. You can process the contents and replace this item to
14674 implement source-level transformations.
14675 For example, if you want to use $ signs to delimit inline math,
14677 like in LaTeX, you can use a regular expression to replace $...$
14678 by :math:`...`.
14679 New in version 0.5.
14681 doctree-read(app, doctree)
14684 Emitted when a doctree has been parsed and read by the environ‐
14685 ment, and is about to be pickled. The doctree can be modified
14686 in-place.
14687 missing-reference(app, env, node, contnode)
14689 Emitted when a cross-reference to a Python module or object can‐
14690 not be resolved. If the event handler can resolve the refer‐
14691 ence, it should return a new docutils node to be inserted in the
14692 document tree in place of the node node. Usually this node is a
14693 reference node containing contnode as a child.
14694 Parameters
14696 · env – The build environment (app.builder.env).
14698 · node – The pending_xref node to be resolved. Its
14700 attributes reftype, reftarget, modname and classname
14701 attributes determine the type and target of the refer‐
14702 ence.
14703 · contnode – The node that carries the text and format‐
14705 ting inside the future reference and should be a child
14706 of the returned reference node.
14707 New in version 0.5.
14709 doctree-resolved(app, doctree, docname)
14712 Emitted when a doctree has been “resolved” by the environment,
14713 that is, all references have been resolved and TOCs have been
14714 inserted. The doctree can be modified in place.
14715 Here is the place to replace custom nodes that don’t have visi‐
14717 tor methods in the writers, so that they don’t cause errors when
14718 the writers encounter them.
14719 env-merge-info(app, env, docnames, other)
14721 This event is only emitted when parallel reading of documents is
14722 enabled. It is emitted once for every subprocess that has read
14723 some documents.
14724 You must handle this event in an extension that stores data in
14726 the environment in a custom location. Otherwise the environment
14727 in the main process will not be aware of the information stored
14728 in the subprocess.
14729 other is the environment object from the subprocess, env is the
14731 environment from the main process. docnames is a set of docu‐
14732 ment names that have been read in the subprocess.
14733 For a sample of how to deal with this event, look at the stan‐
14735 dard sphinx.ext.todo extension. The implementation is often
14736 similar to that of env-purge-doc, only that information is not
14737 removed, but added to the main environment from the other envi‐
14738 ronment.
14739 New in version 1.3.
14741 env-updated(app, env)
14744 Emitted when the update() method of the build environment has
14745 completed, that is, the environment and all doctrees are now
14746 up-to-date.
14747 You can return an iterable of docnames from the handler. These
14749 documents will then be considered updated, and will be
14750 (re-)written during the writing phase.
14751 New in version 0.5.
14753 Changed in version 1.3: The handlers’ return value is now used.
14756 env-check-consistency(app, env)
14759 Emitted when Consistency checks phase. You can check consis‐
14760 tency of metadata for whole of documents.
14761 New in version 1.6: As a experimental event
14763 html-collect-pages(app)
14766 Emitted when the HTML builder is starting to write non-document
14767 pages. You can add pages to write by returning an iterable from
14768 this event consisting of (pagename, context, templatename).
14769 New in version 1.0.
14771 html-page-context(app, pagename, templatename, context, doctree)
14774 Emitted when the HTML builder has created a context dictionary
14775 to render a template with – this can be used to add custom ele‐
14776 ments to the context.
14777 The pagename argument is the canonical name of the page being
14779 rendered, that is, without .html suffix and using slashes as
14780 path separators. The templatename is the name of the template
14781 to render, this will be 'page.html' for all pages from reST doc‐
14782 uments.
14783 The context argument is a dictionary of values that are given to
14785 the template engine to render the page and can be modified to
14786 include custom values. Keys must be strings.
14787 The doctree argument will be a doctree when the page is created
14789 from a reST documents; it will be None when the page is created
14790 from an HTML template alone.
14791 You can return a string from the handler, it will then replace
14793 'page.html' as the HTML template for this page.
14794 New in version 0.4.
14796 Changed in version 1.3: The return value can now specify a tem‐
14799 plate name.
14800 build-finished(app, exception)
14803 Emitted when a build has finished, before Sphinx exits, usually
14804 used for cleanup. This event is emitted even when the build
14805 process raised an exception, given as the exception argument.
14806 The exception is reraised in the application after the event
14807 handlers have run. If the build process raised no exception,
14808 exception will be None. This allows to customize cleanup
14809 actions depending on the exception status.
14810 New in version 0.5.
14812 Checking the Sphinx version
14815 Use this to adapt your extension to API changes in Sphinx.
14816 sphinx.version_info = (2, 2, 2, 'final', 0)
14818 Version info for better programmatic use.
14819 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
14821 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
14822 alpha, beta, rc, final. final always has 0 as the last element.
14823 New in version 1.2: Before version 1.2, check the string
14825 sphinx.__version__.
14826 The Config object
14829 class sphinx.config.Config(*args)
14830 Configuration file abstraction.
14831 The config object makes the values of all config values avail‐
14833 able as attributes.
14834 It is exposed via the sphinx.application.Application.config and
14836 sphinx.environment.Environment.config attributes. For example,
14837 to get the value of language, use either app.config.language or
14838 env.config.language.
14839 The template bridge
14841 class sphinx.application.TemplateBridge
14842 This class defines the interface for a “template bridge”, that
14843 is, a class that renders templates given a template name and a
14844 context.
14845 init(builder, theme=None, dirs=None)
14847 Called by the builder to initialize the template system.
14848 builder is the builder object; you’ll probably want to
14850 look at the value of builder.config.templates_path.
14851 theme is a sphinx.theming.Theme object or None; in the
14853 latter case, dirs can be list of fixed directories to
14854 look for templates.
14855 newest_template_mtime()
14857 Called by the builder to determine if output files are
14858 outdated because of template changes. Return the mtime
14859 of the newest template file that was changed. The
14860 default implementation returns 0.
14861 render(template, context)
14863 Called by the builder to render a template given as a
14864 filename with a specified context (a Python dictionary).
14865 render_string(template, context)
14867 Called by the builder to render a template given as a
14868 string with a specified context (a Python dictionary).
14869 Exceptions
14871 exception sphinx.errors.SphinxError
14872 Base class for Sphinx errors.
14873 This is the base class for “nice” exceptions. When such an
14875 exception is raised, Sphinx will abort the build and present the
14876 exception category and message to the user.
14877 Extensions are encouraged to derive from this exception for
14879 their custom errors.
14880 Exceptions not derived from SphinxError are treated as unex‐
14882 pected and shown to the user with a part of the traceback (and
14883 the full traceback saved in a temporary file).
14884 category
14886 Description of the exception “category”, used in convert‐
14887 ing the exception to a string (“category: message”).
14888 Should be set accordingly in subclasses.
14889 exception sphinx.errors.ConfigError
14891 Configuration error.
14892 exception sphinx.errors.ExtensionError(message, orig_exc=None)
14894 Extension error.
14895 exception sphinx.errors.ThemeError
14897 Theme error.
14898 exception sphinx.errors.VersionRequirementError
14900 Incompatible Sphinx version error.
14901 Project API
14903 class sphinx.project.Project(srcdir, source_suffix)
14904 A project is source code set of Sphinx document.
14905 discover(exclude_paths=[])
14907 Find all document files in the source directory and put
14908 them in docnames.
14909 doc2path(docname, basedir=True)
14911 Return the filename for the document name.
14912 If basedir is True, return as an absolute path. Else,
14914 return as a relative path to the source directory.
14915 path2doc(filename)
14917 Return the docname for the filename if the file is docu‐
14918 ment.
14919 filename should be absolute or relative to the source
14921 directory.
14922 restore(other)
14924 Take over a result of last build.
14925 docnames = None
14927 The name of documents belongs to this project.
14928 source_suffix = None
14930 source_suffix. Same as source_suffix.
14931 srcdir = None
14933 Source directory.
14934 Build environment API
14936 class sphinx.environment.BuildEnvironment
14937 Attributes
14938 app Reference to the Sphinx (application) object.
14940 config Reference to the Config object.
14942 project
14944 Target project. See Project.
14945 srcdir Source directory.
14947 doctreedir
14949 Directory for storing pickled doctrees.
14950 events An EventManager object.
14952 found_docs
14954 A set of all existing docnames.
14955 metadata
14957 Dictionary mapping docnames to “metadata” (see metadata).
14958 titles Dictionary mapping docnames to the docutils node for
14960 their main title.
14961 docname
14963 Returns the docname of the document currently being
14964 parsed.
14965 Utility methods
14967 doc2path(docname: str, base: Union[bool, str] = True, suffix:
14969 str = None) -> str
14970 Return the filename for the document name.
14971 If base is True, return absolute path under self.srcdir.
14973 If base is None, return relative path to self.srcdir. If
14974 base is a path string, return absolute path under that.
14975 If suffix is not None, add it instead of con‐
14976 fig.source_suffix.
14977 relfn2path(filename: str, docname: str = None) -> Tuple[str,
14979 str]
14980 Return paths to a file referenced from a document, rela‐
14981 tive to documentation root and absolute.
14982 In the input “filename”, absolute filenames are taken as
14984 relative to the source dir, while relative filenames are
14985 relative to the dir of the containing document.
14986 note_dependency(filename: str) -> None
14988 Add filename as a dependency of the current document.
14989 This means that the document will be rebuilt if this file
14991 changes.
14992 filename should be absolute or relative to the source
14994 directory.
14995 new_serialno(category: str = '') -> int
14997 Return a serial number, e.g. for index entry targets.
14998 The number is guaranteed to be unique in the current doc‐
15000 ument.
15001 note_reread() -> None
15003 Add the current document to the list of documents that
15004 will automatically be re-read at the next build.
15005 Builder API
15007 Todo
15008 Expand this.
15009 class sphinx.builders.Builder
15011 This is the base class for all builders.
15012 These attributes should be set on builder classes:
15014 name = ''
15016 The builder’s name, for the -b command line option.
15017 format = ''
15019 The builder’s output format, or ‘’ if no document output
15020 is produced.
15021 epilog = ''
15023 The message emitted upon successful build completion.
15024 This can be a printf-style template string with the fol‐
15025 lowing keys: outdir, project
15026 supported_image_types = []
15028 The list of MIME types of image formats supported by the
15029 builder. Image files are searched in the order in which
15030 they appear here.
15031 supported_remote_images = False
15033 The builder supports remote images or not.
15034 supported_data_uri_images = False
15036 The builder supports data URIs or not.
15037 default_translator_class = None
15039 default translator class for the builder. This can be
15040 overridden by app.set_translator().
15041 These methods are predefined and will be called from the appli‐
15043 cation:
15044 get_relative_uri(from_: str, to: str, typ: str = None) -> str
15046 Return a relative URI between two source filenames.
15047 May raise environment.NoUri if there’s no way to return a
15049 sensible URI.
15050 build_all() -> None
15052 Build all source files.
15053 build_specific(filenames: List[str]) -> None
15055 Only rebuild as much as needed for changes in the file‐
15056 names.
15057 build_update() -> None
15059 Only rebuild what was changed or added since last build.
15060 build(docnames: Iterable[str], summary: str = None, method: str
15062 = 'update') -> None
15063 Main build method.
15064 First updates the environment, and then calls write().
15066 These methods can be overridden in concrete builder classes:
15068 init() -> None
15070 Load necessary templates and perform initialization. The
15071 default implementation does nothing.
15072 get_outdated_docs() -> Union[str, Iterable[str]]
15074 Return an iterable of output files that are outdated, or
15075 a string describing what an update build will build.
15076 If the builder does not output individual files corre‐
15078 sponding to source files, return a string here. If it
15079 does, return an iterable of those files that need to be
15080 written.
15081 get_target_uri(docname: str, typ: str = None) -> str
15083 Return the target URI for a document name.
15084 typ can be used to qualify the link characteristic for
15086 individual builders.
15087 prepare_writing(docnames: Set[str]) -> None
15089 A place where you can add logic before write_doc() is run
15090 write_doc(docname: str, doctree: docutils.nodes.document) ->
15092 None
15093 Where you actually write something to the filesystem.
15094 finish() -> None
15096 Finish the building process.
15097 The default implementation does nothing.
15099 Attributes
15101 events An EventManager object.
15103 Environment Collector API
15105 class sphinx.environment.collectors.EnvironmentCollector
15106 An EnvironmentCollector is a specific data collector from each
15107 document.
15108 It gathers data and stores BuildEnvironment as a database.
15110 Examples of specific data would be images, download files, sec‐
15111 tion titles, metadatas, index entries and toctrees, etc.
15112 clear_doc(app: sphinx.application.Sphinx, env: sphinx.environ‐
15114 ment.BuildEnvironment, docname: str) -> None
15115 Remove specified data of a document.
15116 This method is called on the removal of the document.
15118 get_outdated_docs(app: sphinx.application.Sphinx, env:
15120 sphinx.environment.BuildEnvironment, added: Set[str], changed:
15121 Set[str], removed: Set[str]) -> List[str]
15122 Return a list of docnames to re-read.
15123 This methods is called before reading the documents.
15125 get_updated_docs(app: sphinx.application.Sphinx, env:
15127 sphinx.environment.BuildEnvironment) -> List[str]
15128 Return a list of docnames to re-read.
15129 This methods is called after reading the whole of docu‐
15131 ments (experimental).
15132 merge_other(app: sphinx.application.Sphinx, env: sphinx.environ‐
15134 ment.BuildEnvironment, docnames: Set[str], other: sphinx.envi‐
15135 ronment.BuildEnvironment) -> None
15136 Merge in specified data regarding docnames from a differ‐
15137 ent BuildEnvironment object which coming from a subpro‐
15138 cess in parallel builds.
15139 process_doc(app: sphinx.application.Sphinx, doctree: docu‐
15141 tils.nodes.document) -> None
15142 Process a document and gather specific data from it.
15143 This method is called after the document is read.
15145 Docutils markup API
15147 This section describes the API for adding ReST markup elements (roles
15148 and directives).
15149 Roles
15151 Directives
15152 Directives are handled by classes derived from docu‐
15153 tils.parsers.rst.Directive. They have to be registered by an extension
15154 using Sphinx.add_directive() or Sphinx.add_directive_to_domain().
15155 class docutils.parsers.rst.Directive
15157 The markup syntax of the new directive is determined by the fol‐
15158 low five class attributes:
15159 required_arguments = 0
15161 Number of required directive arguments.
15162 optional_arguments = 0
15164 Number of optional arguments after the required argu‐
15165 ments.
15166 final_argument_whitespace = False
15168 May the final argument contain whitespace?
15169 option_spec = None
15171 Mapping of option names to validator functions.
15172 Option validator functions take a single parameter, the
15174 option argument (or None if not given), and should vali‐
15175 date it or convert it to the proper form. They raise
15176 ValueError or TypeError to indicate failure.
15177 There are several predefined and possibly useful valida‐
15179 tors in the docutils.parsers.rst.directives module.
15180 has_content = False
15182 May the directive have content?
15183 New directives must implement the run() method:
15185 run() This method must process the directive arguments, options
15187 and content, and return a list of Docutils/Sphinx nodes
15188 that will be inserted into the document tree at the point
15189 where the directive was encountered.
15190 Instance attributes that are always set on the directive are:
15192 name The directive name (useful when registering the same
15194 directive class under multiple names).
15195 arguments
15197 The arguments given to the directive, as a list.
15198 options
15200 The options given to the directive, as a dictionary map‐
15201 ping option names to validated/converted values.
15202 content
15204 The directive content, if given, as a ViewList.
15205 lineno The absolute line number on which the directive appeared.
15207 This is not always a useful value; use srcline instead.
15208 content_offset
15210 Internal offset of the directive content. Used when
15211 calling nested_parse (see below).
15212 block_text
15214 The string containing the entire directive.
15215 state
15217 state_machine
15219 The state and state machine which controls the parsing.
15220 Used for nested_parse.
15221 ViewLists
15223 Docutils represents document source lines in a class docutils.statema‐
15224 chine.ViewList. This is a list with extended functionality – for one,
15225 slicing creates views of the original list, and also the list contains
15226 information about the source line numbers.
15227 The Directive.content attribute is a ViewList. If you generate content
15229 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
15230 tant for content generation are the following points:
15231 · The constructor takes a list of strings (lines) and a source (docu‐
15233 ment) name.
15234 · The .append() method takes a line and a source name as well.
15236 Parsing directive content as ReST
15238 Many directives will contain more markup that must be parsed. To do
15239 this, use one of the following APIs from the Directive.run() method:
15240 · self.state.nested_parse
15242 · sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
15244 the parsed content.
15245 Both APIs parse the content into a given node. They are used like this:
15247 node = docutils.nodes.paragraph()
15249 # either
15250 nested_parse_with_titles(self.state, self.result, node)
15251 # or
15252 self.state.nested_parse(self.result, 0, node)
15253 NOTE:
15255 sphinx.util.docutils.switch_source_input() allows to change a target
15256 file during nested_parse. It is useful to mixed contents. For
15257 example, sphinx. ext.autodoc uses it to parse docstrings:
15258 from sphinx.util.docutils import switch_source_input
15260 # Switch source_input between parsing content.
15262 # Inside this context, all parsing errors and warnings are reported as
15263 # happened in new source_input (in this case, ``self.result``).
15264 with switch_source_input(self.state, self.result):
15265 node = docutils.nodes.paragraph()
15266 self.state.nested_parse(self.result, 0, node)
15267 Deprecated since version 1.7: Until Sphinx-1.6,
15269 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
15270 now, it is replaced by switch_source_input().
15271 If you don’t need the wrapping node, you can use any concrete node type
15274 and return node.children from the Directive.
15275 SEE ALSO:
15277 Creating directives HOWTO of the Docutils documentation
15278 Domain API
15280 class sphinx.domains.Domain(env: BuildEnvironment)
15281 A Domain is meant to be a group of “object” description direc‐
15282 tives for objects of a similar nature, and corresponding roles
15283 to create references to them. Examples would be Python modules,
15284 classes, functions etc., elements of a templating language,
15285 Sphinx roles and directives, etc.
15286 Each domain has a separate storage for information about exist‐
15288 ing objects and how to reference them in self.data, which must
15289 be a dictionary. It also must implement several functions that
15290 expose the object information in a uniform way to parts of
15291 Sphinx that allow the user to reference or search for objects in
15292 a domain-agnostic way.
15293 About self.data: since all object and cross-referencing informa‐
15295 tion is stored on a BuildEnvironment instance, the domain.data
15296 object is also stored in the env.domaindata dict under the key
15297 domain.name. Before the build process starts, every active
15298 domain is instantiated and given the environment object; the
15299 domaindata dict must then either be nonexistent or a dictionary
15300 whose ‘version’ key is equal to the domain class’ data_version
15301 attribute. Otherwise, OSError is raised and the pickled envi‐
15302 ronment is discarded.
15303 add_object_type(name: str, objtype: sphinx.domains.ObjType) ->
15305 None
15306 Add an object type.
15307 check_consistency() -> None
15309 Do consistency checks (experimental).
15310 clear_doc(docname: str) -> None
15312 Remove traces of a document in the domain-specific inven‐
15313 tories.
15314 directive(name: str) -> Callable
15316 Return a directive adapter class that always gives the
15317 registered directive its full name (‘domain:name’) as
15318 self.name.
15319 get_enumerable_node_type(node: docutils.nodes.Node) -> str
15321 Get type of enumerable nodes (experimental).
15322 get_full_qualified_name(node: docutils.nodes.Element) -> str
15324 Return full qualified name for given node.
15325 get_objects() -> Iterable[Tuple[str, str, str, str, str, int]]
15327 Return an iterable of “object descriptions”.
15328 Object descriptions are tuples with six items:
15330 name Fully qualified name.
15332 dispname
15334 Name to display when searching/linking.
15335 type Object type, a key in self.object_types.
15337 docname
15339 The document where it is to be found.
15340 anchor The anchor name for the object.
15342 priority
15344 How “important” the object is (determines place‐
15345 ment in search results). One of:
15346 1 Default priority (placed before full-text
15348 matches).
15349 0 Object is important (placed before
15351 default-priority objects).
15352 2 Object is unimportant (placed after
15354 full-text matches).
15355 -1 Object should not show up in search at all.
15357 get_type_name(type: sphinx.domains.ObjType, primary: bool =
15359 False) -> str
15360 Return full name for given ObjType.
15361 merge_domaindata(docnames: List[str], otherdata: Dict) -> None
15363 Merge in data regarding docnames from a different domain‐
15364 data inventory (coming from a subprocess in parallel
15365 builds).
15366 process_doc(env: BuildEnvironment, docname: str, document: docu‐
15368 tils.nodes.document) -> None
15369 Process a document after it is read by the environment.
15370 process_field_xref(pnode: sphinx.addnodes.pending_xref) -> None
15372 Process a pending xref created in a doc field. For exam‐
15373 ple, attach information about the current scope.
15374 resolve_any_xref(env: BuildEnvironment, fromdocname: str,
15376 builder: Builder, target: str, node: sphinx.addnodes.pend‐
15377 ing_xref, contnode: docutils.nodes.Element) -> List[Tuple[str,
15378 docutils.nodes.Element]]
15379 Resolve the pending_xref node with the given target.
15380 The reference comes from an “any” or similar role, which
15382 means that we don’t know the type. Otherwise, the argu‐
15383 ments are the same as for resolve_xref().
15384 The method must return a list (potentially empty) of
15386 tuples ('domain:role', newnode), where 'domain:role' is
15387 the name of a role that could have created the same ref‐
15388 erence, e.g. 'py:func'. newnode is what resolve_xref()
15389 would return.
15390 New in version 1.3.
15392 resolve_xref(env: BuildEnvironment, fromdocname: str, builder:
15395 Builder, typ: str, target: str, node: sphinx.addnodes.pend‐
15396 ing_xref, contnode: docutils.nodes.Element) -> docu‐
15397 tils.nodes.Element
15398 Resolve the pending_xref node with the given typ and tar‐
15399 get.
15400 This method should return a new node, to replace the xref
15402 node, containing the contnode which is the markup content
15403 of the cross-reference.
15404 If no resolution can be found, None can be returned; the
15406 xref node will then given to the missing-reference event,
15407 and if that yields no resolution, replaced by contnode.
15408 The method can also raise sphinx.environment.NoUri to
15410 suppress the missing-reference event being emitted.
15411 role(name: str) -> Callable[[str, str, str, int, docu‐
15413 tils.parsers.rst.states.Inliner, Dict[str, Any], List[str]],
15414 Tuple[List[docutils.nodes.Node], List[docutils.nodes.system_mes‐
15415 sage]]]
15416 Return a role adapter function that always gives the reg‐
15417 istered role its full name (‘domain:name’) as the first
15418 argument.
15419 dangling_warnings = {}
15421 role name -> a warning message if reference is missing
15422 data = None
15424 data value
15425 data_version = 0
15427 data version, bump this when the format of self.data
15428 changes
15429 directives = {}
15431 directive name -> directive class
15432 enumerable_nodes = {}
15434 node_class -> (enum_node_type, title_getter)
15435 indices = []
15437 a list of Index subclasses
15438 initial_data = {}
15440 data value for a fresh environment
15441 label = ''
15443 domain label: longer, more descriptive (used in messages)
15444 name = ''
15446 domain name: should be short, but unique
15447 object_types = {}
15449 type (usually directive) name -> ObjType instance
15450 roles = {}
15452 role name -> role callable
15453 class sphinx.domains.ObjType(lname: str, *roles, **attrs)
15455 An ObjType is the description for a type of object that a domain
15456 can document. In the object_types attribute of Domain sub‐
15457 classes, object type names are mapped to instances of this
15458 class.
15459 Constructor arguments:
15461 · lname: localized name of the type (do not include domain name)
15463 · roles: all the roles that can refer to an object of this type
15465 · attrs: object attributes – currently only “searchprio” is
15467 known, which defines the object’s priority in the full-text
15468 search index, see Domain.get_objects().
15469 class sphinx.domains.Index(domain: sphinx.domains.Domain)
15471 An Index is the description for a domain-specific index. To add
15472 an index to a domain, subclass Index, overriding the three name
15473 attributes:
15474 · name is an identifier used for generating file names.
15476 · localname is the section title for the index.
15478 · shortname is a short name for the index, for use in the rela‐
15480 tion bar in HTML output. Can be empty to disable entries in
15481 the relation bar.
15482 and providing a generate() method. Then, add the index class to
15484 your domain’s indices list. Extensions can add indices to
15485 existing domains using add_index_to_domain().
15486 generate(docnames: Iterable[str] = None) ->
15488 Tuple[List[Tuple[str, List[sphinx.domains.IndexEntry]]], bool]
15489 Get entries for the index.
15490 If docnames is given, restrict to entries referring to
15492 these docnames.
15493 The return value is a tuple of (content, collapse):
15495 collapse
15497 A boolean that determines if sub-entries should
15498 start collapsed (for output formats that support
15499 collapsing sub-entries).
15500 content:
15502 A sequence of (letter, entries) tuples, where let‐
15503 ter is the “heading” for the given entries, usu‐
15504 ally the starting letter, and entries is a
15505 sequence of single entries. Each entry is a
15506 sequence [name, subtype, docname, anchor, extra,
15507 qualifier, descr]. The items in this sequence have
15508 the following meaning:
15509 name The name of the index entry to be dis‐
15511 played.
15512 subtype
15514 The sub-entry related type. One of:
15515 0 A normal entry.
15517 1 An entry with sub-entries.
15519 2 A sub-entry.
15521 docname
15523 docname where the entry is located.
15524 anchor Anchor for the entry within docname
15526 extra Extra info for the entry.
15528 qualifier
15530 Qualifier for the description.
15531 descr Description for the entry.
15533 Qualifier and description are not rendered for some out‐
15535 put formats such as LaTeX.
15536 Parser API
15538 The docutils documentation describes parsers as follows:
15539 The Parser analyzes the input document and creates a node tree rep‐
15540 resentation.
15541 In Sphinx, the parser modules works as same as docutils. The parsers
15543 are registered to Sphinx by extensions using Application APIs;
15544 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
15545 The source suffix is a mapping from file suffix to file type. For
15547 example, .rst file is mapped to 'restructuredtext' type. Sphinx uses
15548 the file type to looking for parsers from registered list. On search‐
15549 ing, Sphinx refers to the Parser.supported attribute and picks up a
15550 parser which contains the file type in the attribute.
15551 The users can override the source suffix mappings using source_suffix
15553 like following:
15554 # a mapping from file suffix to file types
15556 source_suffix = {
15557 '.rst': 'restructuredtext',
15558 '.md': 'markdown',
15559 }
15560 You should indicate file types your parser supports. This will allow
15562 users to configure their settings appropriately.
15563 class sphinx.parsers.Parser
15565 A base class of source parsers. The additional parsers should
15566 inherit this class instead of docutils.parsers.Parser. Compared
15567 with docutils.parsers.Parser, this class improves accessibility
15568 to Sphinx APIs.
15569 The subclasses can access following objects and functions:
15571 self.app
15573 The application object (sphinx.application.Sphinx)
15574 self.config
15576 The config object (sphinx.config.Config)
15577 self.env
15579 The environment object (sphinx.environment.BuildEnviron‐
15580 ment)
15581 self.warn()
15583 Emit a warning. (Same as sphinx.applica‐
15584 tion.Sphinx.warn())
15585 self.info()
15587 Emit a informational message. (Same as sphinx.applica‐
15588 tion.Sphinx.info())
15589 Deprecated since version 1.6: warn() and info() is deprecated.
15591 Use sphinx.util.logging instead.
15592 Doctree node classes added by Sphinx
15595 Nodes for domain-specific object descriptions
15596 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
15597 Node for object descriptions.
15598 This node is similar to a “definition list” with one definition.
15600 It contains one or more desc_signature and a desc_content.
15601 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
15603 **attributes)
15604 Node for object signatures.
15605 The “term” part of the custom Sphinx definition list.
15607 As default the signature is a single line signature, but set
15609 is_multiline = True to describe a multi-line signature. In that
15610 case all child nodes must be desc_signature_line nodes.
15611 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
15613 dren, **attributes)
15614 Node for a line in a multi-line object signatures.
15615 It should only be used in a desc_signature with is_multiline
15617 set. Set add_permalink = True for the line that should get the
15618 permalink.
15619 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
15621 **attributes)
15622 Node for additional name parts (module name, class name).
15623 class sphinx.addnodes.desc_type(rawsource='', text='', *children,
15625 **attributes)
15626 Node for return types or object type names.
15627 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
15629 **attributes)
15630 Node for a “returns” annotation (a la -> in Python).
15631 class sphinx.addnodes.desc_name(rawsource='', text='', *children,
15633 **attributes)
15634 Node for the main object name.
15635 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
15637 dren, **attributes)
15638 Node for a general parameter list.
15639 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
15641 **attributes)
15642 Node for a single parameter.
15643 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
15645 **attributes)
15646 Node for marking optional parts of the parameter list.
15647 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
15649 **attributes)
15650 Node for signature annotations (not Python 3-style annotations).
15651 class sphinx.addnodes.desc_content(rawsource='', *children,
15653 **attributes)
15654 Node for object description content.
15655 This is the “definition” part of the custom Sphinx definition
15657 list.
15658 New admonition-like constructs
15660 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
15661 **attributes)
15662 Node for version change entries.
15663 Currently used for “versionadded”, “versionchanged” and “depre‐
15665 cated” directives.
15666 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
15668 Custom “see also” admonition.
15669 Other paragraph-level nodes
15671 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
15672 dren, **attributes)
15673 Node for a compact paragraph (which never makes a <p> node).
15674 New inline nodes
15676 class sphinx.addnodes.index(rawsource='', text='', *children,
15677 **attributes)
15678 Node for index entries.
15679 This node is created by the index directive and has one
15681 attribute, entries. Its value is a list of 5-tuples of (entry‐
15682 type, entryname, target, ignored, key).
15683 entrytype is one of “single”, “pair”, “double”, “triple”.
15685 key is categorization characters (usually a single character)
15687 for general index page. For the details of this, please see
15688 also: glossary and issue #2320.
15689 class sphinx.addnodes.pending_xref(rawsource='', *children,
15691 **attributes)
15692 Node for cross-references that cannot be resolved without com‐
15693 plete information about all documents.
15694 These nodes are resolved before writing output, in BuildEnviron‐
15696 ment.resolve_references.
15697 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
15699 dren, **attributes)
15700 Node that behaves like emphasis, but further text processors are
15701 not applied (e.g. smartypants for HTML output).
15702 class sphinx.addnodes.abbreviation(rawsource='', text='', *children,
15704 **attributes)
15705 Node for abbreviations with explanations.
15706 Deprecated since version 2.0.
15708 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
15711 dren, **attributes)
15712 Node for download references, similar to pending_xref.
15713 Special nodes
15715 class sphinx.addnodes.only(rawsource='', *children, **attributes)
15716 Node for “only” directives (conditional inclusion based on
15717 tags).
15718 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
15720 Node for meta directive – same as docutils’ standard meta node,
15721 but pickleable.
15722 class sphinx.addnodes.highlightlang(rawsource='', *children,
15724 **attributes)
15725 Inserted to set the highlight language and line number options
15726 for subsequent code blocks.
15727 You should not need to generate the nodes below in extensions.
15729 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
15731 Node to insert a glossary.
15732 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
15734 Node for inserting a “TOC tree”.
15735 class sphinx.addnodes.start_of_file(rawsource='', *children,
15737 **attributes)
15738 Node to mark start of a new file, used in the LaTeX builder
15739 only.
15740 class sphinx.addnodes.productionlist(rawsource='', *children,
15742 **attributes)
15743 Node for grammar production lists.
15744 Contains production nodes.
15746 class sphinx.addnodes.production(rawsource='', text='', *children,
15748 **attributes)
15749 Node for a single grammar production rule.
15750 Logging API
15752 sphinx.util.logging.getLogger(name)
15753 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
15754 Sphinx logger always uses sphinx.* namespace to be independent
15756 from settings of root logger. It ensures logging is consistent
15757 even if a third-party extension or imported application resets
15758 logger settings.
15759 Example usage:
15761 >>> from sphinx.util import logging
15763 >>> logger = logging.getLogger(__name__)
15764 >>> logger.info('Hello, this is an extension!')
15765 Hello, this is an extension!
15766 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
15768 LoggerAdapter allowing type and subtype keywords.
15769 error(msg, *args, **kwargs)
15771 critical(msg, *args, **kwargs)
15773 warning(msg, *args, **kwargs)
15775 Logs a message on this logger with the specified level.
15776 Basically, the arguments are as with python’s logging
15777 module.
15778 In addition, Sphinx logger supports following keyword
15780 arguments:
15781 type, *subtype*
15783 Categories of warning logs. It is used to sup‐
15784 press warnings by suppress_warnings setting.
15785 location
15787 Where the warning happened. It is used to include
15788 the path and line number in each log. It allows
15789 docname, tuple of docname and line number and
15790 nodes:
15791 logger = sphinx.util.logging.getLogger(__name__)
15793 logger.warning('Warning happened!', location='index')
15794 logger.warning('Warning happened!', location=('chapter1/index', 10))
15795 logger.warning('Warning happened!', location=some_node)
15796 color The color of logs. By default, error level logs
15798 are colored as "darkred", critical level ones is
15799 not colored, and warning level ones are colored as
15800 "red".
15801 log(level, msg, *args, **kwargs)
15803 info(msg, *args, **kwargs)
15805 verbose(msg, *args, **kwargs)
15807 debug(msg, *args, **kwargs)
15809 Logs a message to this logger with the specified level.
15810 Basically, the arguments are as with python’s logging
15811 module.
15812 In addition, Sphinx logger supports following keyword
15814 arguments:
15815 nonl If true, the logger does not fold lines at the end
15817 of the log message. The default is False.
15818 location
15820 Where the message emitted. For more detail, see
15821 SphinxLoggerAdapter.warning().
15822 color The color of logs. By default, info and verbose
15824 level logs are not colored, and debug level ones
15825 are colored as "darkgray".
15826 sphinx.util.logging.pending_logging()
15828 Contextmanager to pend logging all logs temporary.
15829 For example:
15831 >>> with pending_logging():
15833 >>> logger.warning('Warning message!') # not flushed yet
15834 >>> some_long_process()
15835 >>>
15836 Warning message! # the warning is flushed here
15837 sphinx.util.logging.pending_warnings()
15839 Contextmanager to pend logging warnings temporary.
15840 Similar to pending_logging().
15842 sphinx.util.logging.prefixed_warnings()
15844 Prepend prefix to all records for a while.
15845 For example:
15847 >>> with prefixed_warnings("prefix:"):
15849 >>> logger.warning('Warning message!') # => prefix: Warning message!
15850 New in version 2.0.
15852 i18n API
15855 sphinx.locale.init(locale_dirs, language, catalog='sphinx', names‐
15856 pace='general')
15857 Look for message catalogs in locale_dirs and ensure that there
15858 is at least a NullTranslations catalog set in translators. If
15859 called multiple times or if several .mo files are found, their
15860 contents are merged together (thus making init reentrant).
15861 sphinx.locale.init_console(locale_dir, catalog)
15863 Initialize locale for console.
15864 New in version 1.8.
15866 sphinx.locale.get_translation(catalog, namespace='general')
15869 Get a translation function based on the catalog and namespace.
15870 The extension can use this API to translate the messages on the
15872 extension:
15873 import os
15875 from sphinx.locale import get_translation
15876 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
15878 _ = get_translation(MESSAGE_CATALOG_NAME)
15879 text = _('Hello Sphinx!')
15880 def setup(app):
15883 package_dir = path.abspath(path.dirname(__file__))
15884 locale_dir = os.path.join(package_dir, 'locales')
15885 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
15886 With this code, sphinx searches a message catalog from ${pack‐
15888 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
15889 language is used for the searching.
15890 New in version 1.8.
15892 sphinx.locale._(message, *args)
15895 Translation function for messages on documentation (menu,
15896 labels, themes and so on). This function follows language set‐
15897 ting.
15898 sphinx.locale.__(message, *args)
15900 Translation function for console messages This function follows
15901 locale setting (LC_ALL, LC_MESSAGES and so on).
15902 Extension internationalization (i18n) and localization (l10n) using i18n
15904 API
15905 New in version 1.8.
15906 An extension may naturally come with message translations. This is
15909 briefly summarized in sphinx.locale.get_translation() help.
15910 In practice, you have to:
15912 1. Choose a name for your message catalog, which must be unique. Usu‐
15914 ally the name of your extension is used for the name of message cat‐
15915 alog.
15916 2. Mark in your extension sources all messages as translatable, via
15918 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
15919 src/__init__.py
15921 from sphinx.locale import get_translation
15923 MESSAGE_CATALOG_NAME = 'myextension'
15925 _ = get_translation(MESSAGE_CATALOG_NAME)
15926 translated_text = _('Hello Sphinx!')
15928 1. Set up your extension to be aware of its dedicated translations:
15930 src/__init__.py
15932 def setup(app):
15934 package_dir = path.abspath(path.dirname(__file__))
15935 locale_dir = os.path.join(package_dir, 'locales')
15936 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
15937 1. Generate message catalog template *.pot file, usually in locale/
15939 source directory, for example via Babel:
15940 $ pybabel extract --output=src/locale/myextension.pot src/
15942 2. Create message catalogs (*.po) for each language which your exten‐
15944 sion will provide localization, for example via Babel:
15945 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
15947 3. Translate message catalogs for each language manually
15949 4. Compile message catalogs into *.mo files, for example via Babel:
15951 $ pybabel compile --directory=src/locale --domain=myextension
15953 5. Ensure that message catalog files are distributed when your package
15955 will be installed, by adding equivalent line in your extension MANI‐
15956 FEST.in:
15957 MANIFEST.in
15959 recursive-include src *.pot *.po *.mo
15961 When the messages on your extension has been changed, you need to also
15963 update message catalog template and message catalogs, for example via
15964 Babel:
15965 $ pybabel extract --output=src/locale/myextension.pot src/
15967 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
15968 Utilities
15970 Sphinx provides utility classes and functions to develop extensions.
15971 Base classes for components
15973 These base classes are useful to allow your extensions to obtain Sphinx
15974 components (e.g. Config, BuildEnvironment and so on) easily.
15975 NOTE:
15977 The subclasses of them might not work with bare docutils because
15978 they are strongly coupled with Sphinx.
15979 class sphinx.transforms.SphinxTransform(document, startnode=None)
15981 A base class of Transforms.
15982 Compared with docutils.transforms.Transform, this class improves
15984 accessibility to Sphinx APIs.
15985 property app
15987 Reference to the Sphinx object.
15988 property config
15990 Reference to the Config object.
15991 property env
15993 Reference to the BuildEnvironment object.
15994 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
15996 startnode=None)
15997 A base class of post-transforms.
15998 Post transforms are invoked to modify the document to restruc‐
16000 ture it for outputting. They do resolving references, convert
16001 images, special transformation for each output formats and so
16002 on. This class helps to implement these post transforms.
16003 apply(**kwargs)
16005 Override to apply the transform to the document tree.
16006 is_supported()
16008 Check this transform working for current builder.
16009 run(**kwargs)
16011 main method of post transforms.
16012 Subclasses should override this method instead of
16014 apply().
16015 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
16017 content, lineno, content_offset, block_text, state, state_machine)
16018 A base class for Sphinx directives.
16019 This class provides helper methods for Sphinx directives.
16021 NOTE:
16023 The subclasses of this class might not work with docutils.
16024 This class is strongly coupled with Sphinx.
16025 set_source_info(node: docutils.nodes.Node) -> None
16027 Set source and line number to the node.
16028 property config
16030 Reference to the Config object.
16031 property env
16033 Reference to the BuildEnvironment object.
16034 class sphinx.util.docutils.SphinxRole
16036 A base class for Sphinx roles.
16037 This class provides helper methods for Sphinx roles.
16039 NOTE:
16041 The subclasses of this class might not work with docutils.
16042 This class is strongly coupled with Sphinx.
16043 property config
16045 Reference to the Config object.
16046 content = None
16048 A list of strings, the directive content for customiza‐
16049 tion
16050 property env
16052 Reference to the BuildEnvironment object.
16053 inliner = None
16055 The docutils.parsers.rst.states.Inliner object.
16056 lineno = None
16058 The line number where the interpreted text begins.
16059 name = None
16061 The role name actually used in the document.
16062 options = None
16064 A dictionary of directive options for customization
16065 rawtext = None
16067 A string containing the entire interpreted text input.
16068 text = None
16070 The interpreted text content.
16071 class sphinx.util.docutils.ReferenceRole
16073 A base class for reference roles.
16074 The reference roles can accpet link title <target> style as a
16076 text for the role. The parsed result; link title and target
16077 will be stored to self.title and self.target.
16078 has_explicit_title = None
16080 A boolean indicates the role has explicit title or not.
16081 target = None
16083 The link target for the interpreted text.
16084 title = None
16086 The link title for the interpreted text.
16087 class sphinx.transforms.post_transforms.images.ImageConverter(*args,
16089 **kwargs)
16090 A base class for image converters.
16091 An image converter is kind of Docutils transform module. It is
16093 used to convert image files which does not supported by builder
16094 to appropriate format for that builder.
16095 For example, LaTeX builder supports PDF, PNG and JPEG as image
16097 formats. However it does not support SVG images. For such
16098 case, to use image converters allows to embed these unsupported
16099 images into the document. One of image converters;
16100 sphinx.ext.imgconverter can convert a SVG image to PNG format
16101 using Imagemagick internally.
16102 There are three steps to make your custom image converter:
16104 1. Make a subclass of ImageConverter class
16106 2. Override conversion_rules, is_available() and convert()
16108 3. Register your image converter to Sphinx using
16110 Sphinx.add_post_transform()
16111 convert(_from, _to)
16113 Convert a image file to expected format.
16114 _from is a path for source image file, and _to is a path
16116 for destination file.
16117 is_available()
16119 Return the image converter is available or not.
16120 conversion_rules = []
16122 A conversion rules the image converter supports. It is
16123 represented as a list of pair of source image format
16124 (mimetype) and destination one:
16125 conversion_rules = [
16127 ('image/svg+xml', 'image/png'),
16128 ('image/gif', 'image/png'),
16129 ('application/pdf', 'image/png'),
16130 ]
16131 Utility components
16133 class sphinx.events.EventManager(app=None)
16134 Event manager for Sphinx.
16135 add(name)
16137 Register a custom Sphinx event.
16138 connect(name, callback)
16140 Connect a handler to specific event.
16141 disconnect(listener_id)
16143 Disconnect a handler.
16144 emit(name, *args)
16146 Emit a Sphinx event.
16147 emit_firstresult(name, *args)
16149 Emit a Sphinx event and returns first result.
16150 This returns the result of the first handler that doesn’t
16152 return None.
16153 Deprecated APIs
16155 On developing Sphinx, we are always careful to the compatibility of our
16156 APIs. But, sometimes, the change of interface are needed for some rea‐
16157 sons. In such cases, we’ve marked them as deprecated. And they are
16158 kept during the two major versions (for more details, please see depre‐
16159 cation-policy).
16160 The following is a list of deprecated interfaces.
16162 deprecated APIs
16164┌─────────────────────────────────────────────────────┬────────────┬───────────┬───────────────────────────────────────┐
16165│Target │ Deprecated │ (will be) │ Alternatives │
16166│ │ │ Removed │ │
16167├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16168│sphinx.domains.math.Math‐ │ 2.2 │ 4.0 │ sphinx.domains.math.Math‐ │
16169│Domain.add_equa‐ │ │ │ Do‐ │
16170│tion() │ │ │ main.note_equa‐ │
16171│ │ │ │ tion() │
16172├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16173│sphinx.domains.math.Math‐ │ 2.2 │ 4.0 │ sphinx.domains.math.Math‐ │
16174│Domain.get_next_equa‐ │ │ │ Domain.note_equation() │
16175│tion_number() │ │ │ │
16176├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16177│The info and warn argu‐ │ 2.2 │ 4.0 │ logging.info() and log‐ │
16178│ments of sphinx.ext.auto‐ │ │ │ ging.warning() │
16179│summary.generate.gener‐ │ │ │ │
16180│ate_autosummary_docs() │ │ │ │
16181├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16182│sphinx.ext.autosum‐ │ 2.2 │ 4.0 │ logging.info() │
16183│mary.generate._sim‐ │ │ │ │
16184│ple_info() │ │ │ │
16185├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16186│sphinx.ext.autosum‐ │ 2.2 │ 4.0 │ logging.warning() │
16187│mary.generate._sim‐ │ │ │ │
16188│ple_warn() │ │ │ │
16189├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16190│sphinx.ext.todo.merge_info() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
16191├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16192│sphinx.ext.todo.process_todo_nodes() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
16193├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16194│sphinx.ext.todo.process_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
16195├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16196│sphinx.ext.todo.purge_todos() │ 2.2 │ 4.0 │ sphinx.ext.todo.TodoDomain │
16197├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16198│sphinx.builders.latex.LaTeXBuilder.apply_trans‐ │ 2.1 │ 4.0 │ N/A │
16199│forms() │ │ │ │
16200├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16201│sphinx.builders._epub_base.EpubBuilder.esc() │ 2.1 │ 4.0 │ html.escape() │
16202├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16203│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.direc‐ │
16204│ │ │ │ tives.other.Acks │
16205└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16206│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.direc‐ │
16208│ │ │ │ tives.other.Author │
16209├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16210│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.direc‐ │
16211│ │ │ │ tives.other.Centered │
16212├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16213│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.direc‐ │
16214│ │ │ │ tives.other.Class │
16215├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16216│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.direc‐ │
16217│ │ │ │ tives.code.CodeBlock │
16218├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16219│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.direc‐ │
16220│ │ │ │ tives.patches.Figure │
16221├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16222│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.direc‐ │
16223│ │ │ │ tives.other.HList │
16224├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16225│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.direc‐ │
16226│ │ │ │ tives.code.Highlight │
16227├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16228│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.direc‐ │
16229│ │ │ │ tives.other.Include │
16230├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16231│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.direc‐ │
16232│ │ │ │ tives.other.Index │
16233├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16234│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.direc‐ │
16235│ │ │ │ tives.code.LiteralInclude │
16236├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16237│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.direc‐ │
16238│ │ │ │ tives.patches.Meta │
16239├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16240│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.direc‐ │
16241│ │ │ │ tives.other.Only │
16242├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16243│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.direc‐ │
16244│ │ │ │ tives.other.SeeAlso │
16245├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16246│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.direc‐ │
16247│ │ │ │ tives.other.TabularColumns │
16248├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16249│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.direc‐ │
16250│ │ │ │ tives.other.TocTree │
16251├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16252│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.direc‐ │
16253│ │ │ │ tives.other.VersionChange │
16254├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16255│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAt‐ │
16256│ │ │ │ tribute, │
16257│ │ │ │ sphinx.domains.python.PyMethod, │
16258│ │ │ │ sphinx.domains.python.PyClass‐ │
16259│ │ │ │ Method, │
16260│ │ │ │ sphinx.domains.python.PyOb‐ │
16261│ │ │ │ ject and │
16262│ │ │ │ sphinx.domains.python.PyStat‐ │
16263│ │ │ │ icMethod │
16264├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16265│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunc‐ │
16266│ │ │ │ tion, │
16267│ │ │ │ sphinx.domains.python.PyObject │
16268│ │ │ │ and │
16269│ │ │ │ sphinx.domains.python.PyVari‐ │
16270│ │ │ │ able │
16271├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16272│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16273│main._resolve_citation_xref() │ │ │ tionDomain.resolve_xref() │
16274├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16275│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16276│tions() │ │ │ tionDomain.note_citation() │
16277├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16278│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16279│tion_refs() │ │ │ tionDomain.note_citation_refer‐ │
16280│ │ │ │ ence() │
16281├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16282│sphinx.domains.std.StandardDomain.note_labels() │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
16283│ │ │ │ main.process_doc() │
16284├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16285│sphinx.environment.NoUri │ 2.1 │ 4.0 │ sphinx.errors.NoUri │
16286├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16287│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
16288├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16289│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
16290├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16291│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
16292├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16293│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
16294│ │ │ │ Finder │
16295├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16296│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
16297│ │ │ │ Loader │
16298├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16299│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
16300├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16301│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
16302├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16303│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
16304├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16305│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
16306├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16307│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
16308├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16309│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16310│ │ │ │ tionReferenceTransform │
16311├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16312│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16313│ │ │ │ tionDefinitionTransform │
16314├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16315│sphinx.util.docfields.DocFieldTransformer.pre‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDe‐ │
16316│process_fieldtypes() │ │ │ scription.get_field_type_map() │
16317├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16318│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
16319├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16320│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.doc‐ │
16321│ │ │ │ name_to_domain() │
16322├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16323│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
16324├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16325│sphinx.util.i18n.find_catalog_source_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
16326├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16327│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
16328│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
16329│tureMixin.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
16330│tureMixin._find_signature(), and autodoc.Class‐ │ │ │ │
16331│Documenter.get_doc() │ │ │ │
16332└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16333│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
16340│EpubBuilder.build_container(), Epub‐ │ │ │ │
16341│Builder.build_content(), Epub‐ │ │ │ │
16342│Builder.build_toc() and Epub‐ │ │ │ │
16343│Builder.build_epub() │ │ │ │
16344├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16345│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
16346│tion_doc() │ │ │ │
16347├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16348│nodetype argument of sphinx.search.WordCollec‐ │ 2.0 │ 4.0 │ N/A │
16349│tor.is_meta_keywords() │ │ │ │
16350├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16351│suffix argument of BuildEnvironment.doc2path() │ 2.0 │ 4.0 │ N/A │
16352├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16353│string style base argument of BuildEnviron‐ │ 2.0 │ 4.0 │ os.path.join() │
16354│ment.doc2path() │ │ │ │
16355├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16356│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
16357├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16358│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
16359├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16360│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
16361├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16362│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
16363│date_config_value() │ │ │ date_config_values() │
16364├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16365│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16366│ │ │ │ inghtml.JSONHTMLBuilder │
16367├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16368│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16369│ │ │ │ inghtml.PickleHTMLBuilder │
16370├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16371│sphinx.builders.html.SerializingHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16372│ │ │ │ inghtml.SerializingHTMLBuilder │
16373├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16374│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
16375│ │ │ │ FileHTMLBuilder │
16376├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16377│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16378│ │ │ │ inghtml.PickleHTMLBuilder │
16379├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16380│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
16381├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16382│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
16383│Builder.open_file() │ │ │ │
16384├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16385│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
16386├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16387│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
16388├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16389│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
16390├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16391│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
16392├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16393│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
16394├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16395│sphinx.domains.cpp.DefinitionError.description │ 2.0 │ 4.0 │ str(exc) │
16396├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16397│sphinx.domains.cpp.NoOldIdError.description │ 2.0 │ 4.0 │ str(exc) │
16398├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16399│sphinx.domains.cpp.UnsupportedMultiCharacter‐ │ 2.0 │ 4.0 │ str(exc) │
16400│CharLiteral.decoded │ │ │ │
16401├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16402│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
16403├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16404│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
16405├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16406│sphinx.ext.autosummary.Autosummary.warnings │ 2.0 │ 4.0 │ N/A │
16407├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16408│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
16409├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16410│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
16411├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16412│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
16413├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16414│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
16415├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16416│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
16417├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16418│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
16419│ │ │ │ sphinx.roles.MenuSelection │
16420├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16421│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
16422├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16423│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
16424│ │ │ │ sphinx.roles.RFC │
16425├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16426│sphinx.testing.util.remove_unicode_literal() │ 2.0 │ 4.0 │ N/A │
16427├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16428│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
16429├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16430│sphinx.util.force_decode() │ 2.0 │ 4.0 │ N/A │
16431├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16432│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
16433├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16434│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
16435├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16436│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
16437│ │ │ │ inghtml.jsonimpl │
16438├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16439│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
16440├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16441│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
16442├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16443│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
16444├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16445│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
16446├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16447│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
16448├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16449│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
16450├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16451│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
16452├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16453│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
16454├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16455│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
16456├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16457│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
16458├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16459│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
16460├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16461│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
16462│ │ │ │ nal_safe() │
16463├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16464│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
16465├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16466│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
16467└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16468│Omitting the filename argument in an overrid‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
16472│dent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
16473├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16474│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
16475│ │ │ │ bel │
16476├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16477│sphinx.writers.latex.LaTeXTranslator.babel_def‐ │ 2.0 │ 4.0 │ N/A │
16478│macro() │ │ │ │
16479├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16480│sphinx.application.Sphinx._setting_up_extension │ 2.0 │ 3.0 │ N/A │
16481├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16482│The importer argument of │ 2.0 │ 3.0 │ N/A │
16483│sphinx.ext.autodoc.importer._MockModule │ │ │ │
16484├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16485│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
16486├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16487│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
16488├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16489│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
16490├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16491│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
16492├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16493│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
16494│istry.add_source_input() │ │ │ │
16495├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16496│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
16497│tor._make_visit_admonition() │ │ │ │
16498├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16499│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
16500│lect_footnotes() │ │ │ │
16501├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16502│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
16503│tor._make_visit_admonition() │ │ │ │
16504├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16505│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
16506│tor._make_depart_admonition() │ │ │ │
16507├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16508│sphinx.writers.latex.LaTeXTranslator.gener‐ │ 2.0 │ 4.0 │ N/A │
16509│ate_numfig_format() │ │ │ │
16510├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16511│highlightlang │ 1.8 │ 4.0 │ highlight │
16512├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16513│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
16514├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16515│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
16516├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16517│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
16518├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16519│content arguments of │ 1.8 │ 3.0 │ N/A │
16520│sphinx.util.image.guess_mimetype() │ │ │ │
16521├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16522│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
16523│sphinx.util.i18n.find_catalog_source_files() │ │ │ │
16524├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16525│sphinx.io.SphinxI18nReader.set_lineno_for_reporter() │ 1.8 │ 3.0 │ N/A │
16526├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16527│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
16528├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16529│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
16530│ │ │ │ Changes │
16531├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16532│sphinx.highlighting.PygmentsBridge.unhighlight() │ 1.8 │ 3.0 │ N/A │
16533├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16534│trim_doctest_flags arguments of sphinx.highlight‐ │ 1.8 │ 3.0 │ N/A │
16535│ing.PygmentsBridge │ │ │ │
16536├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16537│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
16538├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16539│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
16540├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16541│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
16542│ │ │ │ rective │
16543├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16544│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
16545│ │ │ │ tils.parsers.rst.roles.math_role() │
16546├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16547│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
16548├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16549│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
16550├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16551│sphinx.ext.mathbase.get_node_equation_number() │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
16552│ │ │ │ tion_number() │
16553├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16554│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
16555│ │ │ │ math() │
16556├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16557│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
16558├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16559│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
16560├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16561│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.latex.nodes.math_ref‐ │
16562│ │ │ │ erence │
16563├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16564│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
16565├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16566│sphinx.writers.latex.Table.caption_footnotetexts │ 1.8 │ 3.0 │ N/A │
16567├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16568│sphinx.writers.latex.Table.header_footnotetexts │ 1.8 │ 3.0 │ N/A │
16569├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16570│sphinx.writers.latex.LaTeXTranslator.footnotestack │ 1.8 │ 3.0 │ N/A │
16571├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16572│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
16573│tainer_literal_block │ │ │ │
16574├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16575│sphinx.writers.latex.LaTeXTranslator.next_sec‐ │ 1.8 │ 3.0 │ N/A │
16576│tion_ids │ │ │ │
16577├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16578│sphinx.writers.latex.LaTeXTranslator.next_hyper‐ │ 1.8 │ 3.0 │ N/A │
16579│link_ids │ │ │ │
16580├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16581│sphinx.writers.latex.LaTeXTranslator.restrict_foot‐ │ 1.8 │ 3.0 │ N/A │
16582│note() │ │ │ │
16583├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16584│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
16585│strict_footnote() │ │ │ │
16586├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16587│sphinx.writers.latex.LaTeXTranslator.push_hyper‐ │ 1.8 │ 3.0 │ N/A │
16588│link_ids() │ │ │ │
16589├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16590│sphinx.writers.latex.LaTeXTranslator.pop_hyper‐ │ 1.8 │ 3.0 │ N/A │
16591│link_ids() │ │ │ │
16592├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16593│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
16594├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16595│sphinx.writers.latex.LaTeXTranslator.hlsettingstack │ 1.8 │ 3.0 │ N/A │
16596├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16597│sphinx.writers.latex.ExtBabel.get_shorthandoff() │ 1.8 │ 3.0 │ N/A │
16598├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16599│sphinx.writers.html.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
16600└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16601│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16604│lang_base() │ │ │ │
16605├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16606│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16607│langopts() │ │ │ │
16608├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16609│sphinx.writers.html.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
16610│nenothreshold() │ │ │ │
16611├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16612│sphinx.writers.html5.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
16613├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16614│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16615│lang_base() │ │ │ │
16616├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16617│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16618│langopts() │ │ │ │
16619├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16620│sphinx.writers.html5.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
16621│nenothreshold() │ │ │ │
16622├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16623│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
16624│tor.check_latex_elements() │ │ │ │
16625├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16626│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
16627├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16628│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
16629├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16630│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_confval_types() │
16631├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16632│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
16633│fig.__init__() │ │ │ │
16634├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16635│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
16636├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16637│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
16638├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16639│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
16640├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16641│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
16642├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16643│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
16644├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16645│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
16646├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16647│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
16648├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16649│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
16650├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16651│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
16652├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16653│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
16654├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16655│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
16656├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16657│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
16658├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16659│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
16660├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16661│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
16662├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16663│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
16664├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16665│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
16666├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16667│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
16668├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16669│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
16670├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16671│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
16672├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16673│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
16674├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16675│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
16676├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16677│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
16678├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16679│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
16680├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16681│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
16682├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16683│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
16684├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16685│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
16686├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16687│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
16688├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16689│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
16690├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16691│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
16692├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16693│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.inspect_main() │
16694├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16695│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
16696├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16697│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
16698├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16699│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
16700│ │ │ │ tils.switch_source_input() │
16701├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16702│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
16703├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16704│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
16705├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16706│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
16707├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16708│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
16709├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16710│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
16711├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16712│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
16713│ │ │ │ ment.adapters.toctree) │
16714├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16715│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
16716│ │ │ │ sphinx.environment.adapters.toctree) │
16717├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16718│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
16719│ │ │ │ sphinx.environment.adapters.toctree) │
16720├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16721│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
16722│ │ │ │ sphinx.environment.adapters.indexen‐ │
16723│ │ │ │ tries) │
16724├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16725│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
16726├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16727│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
16728├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16729│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
16730├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16731│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
16732└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16733│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
16736├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16737│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
16738│ │ │ │ tive_helper() │
16739├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16740│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
16741├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16742│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__version_info__ │
16743└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16744 NOTE:
16746 On deprecating on public APIs (internal functions and classes), we
16747 also follow the policy as much as possible.
16748
16750 Refer to the following tutorials to get started with extension develop‐
16751 ment.
16752 Developing a “Hello world” extension
16754 The objective of this tutorial is to create a very basic extension that
16755 adds a new directive. This directive will output a paragraph containing
16756 “hello world”.
16757 Only basic information is provided in this tutorial. For more informa‐
16759 tion, refer to the other tutorials that go into more details.
16760 WARNING:
16762 For this extension, you will need some basic understanding of
16763 docutils and Python.
16764 Overview
16766 We want the extension to add the following to Sphinx:
16767 · A helloworld directive, that will simply output the text “hello
16769 world”.
16770 Prerequisites
16772 We will not be distributing this plugin via PyPI and will instead
16773 include it as part of an existing project. This means you will need to
16774 use an existing project or create a new one using sphinx-quickstart.
16775 We assume you are using separate source (source) and build (build)
16777 folders. Your extension file could be in any folder of your project. In
16778 our case, let’s do the following:
16779 1. Create an _ext folder in source
16781 2. Create a new Python file in the _ext folder called helloworld.py
16783 Here is an example of the folder structure you might obtain:
16785 └── source
16787 ├── _ext
16788 │ └── helloworld.py
16789 ├── _static
16790 ├── conf.py
16791 ├── somefolder
16792 ├── index.rst
16793 ├── somefile.rst
16794 └── someotherfile.rst
16795 Writing the extension
16797 Open helloworld.py and paste the following code in it:
16798 from docutils import nodes
16800 from docutils.parsers.rst import Directive
16801 class HelloWorld(Directive):
16804 def run(self):
16806 paragraph_node = nodes.paragraph(text='Hello World!')
16807 return [paragraph_node]
16808 def setup(app):
16811 app.add_directive("helloworld", HelloWorld)
16812 return {
16814 'version': '0.1',
16815 'parallel_read_safe': True,
16816 'parallel_write_safe': True,
16817 }
16818 Some essential things are happening in this example, and you will see
16821 them for all directives.
16822 The directive class
16824 Our new directive is declared in the HelloWorld class.
16826 class HelloWorld(Directive):
16828 def run(self):
16830 paragraph_node = nodes.paragraph(text='Hello World!')
16831 return [paragraph_node]
16832 This class extends the docutils’ Directive class. All extensions that
16835 create directives should extend this class.
16836 SEE ALSO:
16838 The docutils documentation on creating directives
16839 This class contains a run method. This method is a requirement and it
16841 is part of every directive. It contains the main logic of the direc‐
16842 tive and it returns a list of docutils nodes to be processed by Sphinx.
16843 These nodes are docutils’ way of representing the content of a docu‐
16844 ment. There are many types of nodes available: text, paragraph, refer‐
16845 ence, table, etc.
16846 SEE ALSO:
16848 The docutils documentation on nodes
16849 The nodes.paragraph class creates a new paragraph node. A paragraph
16851 node typically contains some text that we can set during instantiation
16852 using the text parameter.
16853 The setup function
16855 This function is a requirement. We use it to plug our new directive
16857 into Sphinx.
16858 def setup(app):
16860 app.add_directive("helloworld", HelloWorld)
16861 return {
16863 'version': '0.1',
16864 'parallel_read_safe': True,
16865 'parallel_write_safe': True,
16866 }
16867 The simplest thing you can do it call the add_directive() method, which
16870 is what we’ve done here. For this particular call, the first argument
16871 is the name of the directive itself as used in a reST file. In this
16872 case, we would use helloworld. For example:
16873 Some intro text here...
16875 .. helloworld::
16877 Some more text here...
16879 We also return the extension metadata that indicates the version of our
16881 extension, along with the fact that it is safe to use the extension for
16882 both parallel reading and writing.
16883 Using the extension
16885 The extension has to be declared in your conf.py file to make Sphinx
16886 aware of it. There are two steps necessary here:
16887 1. Add the _ext directory to the Python path using sys.path.append.
16889 This should be placed at the top of the file.
16890 2. Update or create the extensions list and add the extension file name
16892 to the list
16893 For example:
16895 import os
16897 import sys
16898 sys.path.append(os.path.abspath("./_ext"))
16900 extensions = ['helloworld']
16902 TIP:
16904 We’re not distributing this extension as a Python package, we need
16905 to modify the Python path so Sphinx can find our extension. This is
16906 why we need the call to sys.path.append.
16907 You can now use the extension in a file. For example:
16909 Some intro text here...
16911 .. helloworld::
16913 Some more text here...
16915 The sample above would generate:
16917 Some intro text here...
16919 Hello World!
16921 Some more text here...
16923 Further reading
16925 This is the very basic principle of an extension that creates a new
16926 directive.
16927 For a more advanced example, refer to todo.
16929 Developing a “TODO” extension
16931 The objective of this tutorial is to create a more comprehensive exten‐
16932 sion than that created in helloworld. Whereas that guide just covered
16933 writing a custom directive, this guide adds multiple directives, along
16934 with custom nodes, additional config values and custom event handlers.
16935 To this end, we will cover a todo extension that adds capabilities to
16936 include todo entries in the documentation, and to collect these in a
16937 central place. This is similar the sphinxext.todo extension distributed
16938 with Sphinx.
16939 Overview
16941 NOTE:
16942 To understand the design of this extension, refer to impor‐
16943 tant-objects and build-phases.
16944 We want the extension to add the following to Sphinx:
16946 · A todo directive, containing some content that is marked with “TODO”
16948 and only shown in the output if a new config value is set. Todo
16949 entries should not be in the output by default.
16950 · A todolist directive that creates a list of all todo entries through‐
16952 out the documentation.
16953 For that, we will need to add the following elements to Sphinx:
16955 · New directives, called todo and todolist.
16957 · New document tree nodes to represent these directives, conventionally
16959 also called todo and todolist. We wouldn’t need new nodes if the new
16960 directives only produced some content representable by existing
16961 nodes.
16962 · A new config value todo_include_todos (config value names should
16964 start with the extension name, in order to stay unique) that controls
16965 whether todo entries make it into the output.
16966 · New event handlers: one for the doctree-resolved event, to replace
16968 the todo and todolist nodes, and one for env-purge-doc (the reason
16969 for that will be covered later).
16970 Prerequisites
16972 As with helloworld, we will not be distributing this plugin via PyPI so
16973 once again we need a Sphinx project to call this from. You can use an
16974 existing project or create a new one using sphinx-quickstart.
16975 We assume you are using separate source (source) and build (build)
16977 folders. Your extension file could be in any folder of your project. In
16978 our case, let’s do the following:
16979 1. Create an _ext folder in source
16981 2. Create a new Python file in the _ext folder called todo.py
16983 Here is an example of the folder structure you might obtain:
16985 └── source
16987 ├── _ext
16988 │ └── todo.py
16989 ├── _static
16990 ├── conf.py
16991 ├── somefolder
16992 ├── index.rst
16993 ├── somefile.rst
16994 └── someotherfile.rst
16995 Writing the extension
16997 Open todo.py and paste the following code in it, all of which we will
16998 explain in detail shortly:
16999 from docutils import nodes
17001 from docutils.parsers.rst import Directive
17002 from sphinx.locale import _
17004 from sphinx.util.docutils import SphinxDirective
17005 class todo(nodes.Admonition, nodes.Element):
17008 pass
17009 class todolist(nodes.General, nodes.Element):
17012 pass
17013 def visit_todo_node(self, node):
17016 self.visit_admonition(node)
17017 def depart_todo_node(self, node):
17020 self.depart_admonition(node)
17021 class TodolistDirective(Directive):
17024 def run(self):
17026 return [todolist('')]
17027 class TodoDirective(SphinxDirective):
17030 # this enables content in the directive
17032 has_content = True
17033 def run(self):
17035 targetid = 'todo-%d' % self.env.new_serialno('todo')
17036 targetnode = nodes.target('', '', ids=[targetid])
17037 todo_node = todo('\n'.join(self.content))
17039 todo_node += nodes.title(_('Todo'), _('Todo'))
17040 self.state.nested_parse(self.content, self.content_offset, todo_node)
17041 if not hasattr(self.env, 'todo_all_todos'):
17043 self.env.todo_all_todos = []
17044 self.env.todo_all_todos.append({
17046 'docname': self.env.docname,
17047 'lineno': self.lineno,
17048 'todo': todo_node.deepcopy(),
17049 'target': targetnode,
17050 })
17051 return [targetnode, todo_node]
17053 def purge_todos(app, env, docname):
17056 if not hasattr(env, 'todo_all_todos'):
17057 return
17058 env.todo_all_todos = [todo for todo in env.todo_all_todos
17060 if todo['docname'] != docname]
17061 def process_todo_nodes(app, doctree, fromdocname):
17064 if not app.config.todo_include_todos:
17065 for node in doctree.traverse(todo):
17066 node.parent.remove(node)
17067 # Replace all todolist nodes with a list of the collected todos.
17069 # Augment each todo with a backlink to the original location.
17070 env = app.builder.env
17071 for node in doctree.traverse(todolist):
17073 if not app.config.todo_include_todos:
17074 node.replace_self([])
17075 continue
17076 content = []
17078 for todo_info in env.todo_all_todos:
17080 para = nodes.paragraph()
17081 filename = env.doc2path(todo_info['docname'], base=None)
17082 description = (
17083 _('(The original entry is located in %s, line %d and can be found ') %
17084 (filename, todo_info['lineno']))
17085 para += nodes.Text(description, description)
17086 # Create a reference
17088 newnode = nodes.reference('', '')
17089 innernode = nodes.emphasis(_('here'), _('here'))
17090 newnode['refdocname'] = todo_info['docname']
17091 newnode['refuri'] = app.builder.get_relative_uri(
17092 fromdocname, todo_info['docname'])
17093 newnode['refuri'] += '#' + todo_info['target']['refid']
17094 newnode.append(innernode)
17095 para += newnode
17096 para += nodes.Text('.)', '.)')
17097 # Insert into the todolist
17099 content.append(todo_info['todo'])
17100 content.append(para)
17101 node.replace_self(content)
17103 def setup(app):
17106 app.add_config_value('todo_include_todos', False, 'html')
17107 app.add_node(todolist)
17109 app.add_node(todo,
17110 html=(visit_todo_node, depart_todo_node),
17111 latex=(visit_todo_node, depart_todo_node),
17112 text=(visit_todo_node, depart_todo_node))
17113 app.add_directive('todo', TodoDirective)
17115 app.add_directive('todolist', TodolistDirective)
17116 app.connect('doctree-resolved', process_todo_nodes)
17117 app.connect('env-purge-doc', purge_todos)
17118 return {
17120 'version': '0.1',
17121 'parallel_read_safe': True,
17122 'parallel_write_safe': True,
17123 }
17124 This is far more extensive extension than the one detailed in hel‐
17127 loworld, however, we will will look at each piece step-by-step to
17128 explain what’s happening.
17129 The node classes
17131 Let’s start with the node classes:
17133 class todo(nodes.Admonition, nodes.Element):
17135 pass
17136 class todolist(nodes.General, nodes.Element):
17139 pass
17140 def visit_todo_node(self, node):
17143 self.visit_admonition(node)
17144 def depart_todo_node(self, node):
17147 self.depart_admonition(node)
17148 Node classes usually don’t have to do anything except inherit from the
17151 standard docutils classes defined in docutils.nodes. todo inherits
17152 from Admonition because it should be handled like a note or warning,
17153 todolist is just a “general” node.
17154 NOTE:
17156 Many extensions will not have to create their own node classes and
17157 work fine with the nodes already provided by docutils and Sphinx.
17158 The directive classes
17160 A directive class is a class deriving usually from docu‐
17162 tils.parsers.rst.Directive. The directive interface is also covered in
17163 detail in the docutils documentation; the important thing is that the
17164 class should have attributes that configure the allowed markup, and a
17165 run method that returns a list of nodes.
17166 Looking first at the TodolistDirective directive:
17168 class TodolistDirective(Directive):
17170 def run(self):
17172 return [todolist('')]
17173 It’s very simple, creating and returning an instance of our todolist
17176 node class. The TodolistDirective directive itself has neither content
17177 nor arguments that need to be handled. That brings us to the TodoDirec‐
17178 tive directive:
17179 class TodoDirective(SphinxDirective):
17181 # this enables content in the directive
17183 has_content = True
17184 def run(self):
17186 targetid = 'todo-%d' % self.env.new_serialno('todo')
17187 targetnode = nodes.target('', '', ids=[targetid])
17188 todo_node = todo('\n'.join(self.content))
17190 todo_node += nodes.title(_('Todo'), _('Todo'))
17191 self.state.nested_parse(self.content, self.content_offset, todo_node)
17192 if not hasattr(self.env, 'todo_all_todos'):
17194 self.env.todo_all_todos = []
17195 self.env.todo_all_todos.append({
17197 'docname': self.env.docname,
17198 'lineno': self.lineno,
17199 'todo': todo_node.deepcopy(),
17200 'target': targetnode,
17201 })
17202 return [targetnode, todo_node]
17204 Several important things are covered here. First, as you can see, we’re
17207 now subclassing the SphinxDirective helper class instead of the usual
17208 Directive class. This gives us access to the build environment instance
17209 using the self.env property. Without this, we’d have to use the rather
17210 convoluted self.state.document.settings.env. Then, to act as a link
17211 target (from TodolistDirective), the TodoDirective directive needs to
17212 return a target node in addition to the todo node. The target ID (in
17213 HTML, this will be the anchor name) is generated by using env.new_seri‐
17214 alno which returns a new unique integer on each call and therefore
17215 leads to unique target names. The target node is instantiated without
17216 any text (the first two arguments).
17217 On creating admonition node, the content body of the directive are
17219 parsed using self.state.nested_parse. The first argument gives the
17220 content body, and the second one gives content offset. The third argu‐
17221 ment gives the parent node of parsed result, in our case the todo node.
17222 Following this, the todo node is added to the environment. This is
17223 needed to be able to create a list of all todo entries throughout the
17224 documentation, in the place where the author puts a todolist directive.
17225 For this case, the environment attribute todo_all_todos is used (again,
17226 the name should be unique, so it is prefixed by the extension name).
17227 It does not exist when a new environment is created, so the directive
17228 must check and create it if necessary. Various information about the
17229 todo entry’s location are stored along with a copy of the node.
17230 In the last line, the nodes that should be put into the doctree are
17232 returned: the target node and the admonition node.
17233 The node structure that the directive returns looks like this:
17235 +--------------------+
17237 | target node |
17238 +--------------------+
17239 +--------------------+
17240 | todo node |
17241 +--------------------+
17242 \__+--------------------+
17243 | admonition title |
17244 +--------------------+
17245 | paragraph |
17246 +--------------------+
17247 | ... |
17248 +--------------------+
17249 The event handlers
17251 Event handlers are one of Sphinx’s most powerful features, providing a
17253 way to do hook into any part of the documentation process. There are
17254 many events provided by Sphinx itself, as detailed in the API guide,
17255 and we’re going to use a subset of them here.
17256 Let’s look at the event handlers used in the above example. First, the
17258 one for the env-purge-doc event:
17259 def purge_todos(app, env, docname):
17261 if not hasattr(env, 'todo_all_todos'):
17262 return
17263 env.todo_all_todos = [todo for todo in env.todo_all_todos
17265 if todo['docname'] != docname]
17266 Since we store information from source files in the environment, which
17269 is persistent, it may become out of date when the source file changes.
17270 Therefore, before each source file is read, the environment’s records
17271 of it are cleared, and the env-purge-doc event gives extensions a
17272 chance to do the same. Here we clear out all todos whose docname
17273 matches the given one from the todo_all_todos list. If there are todos
17274 left in the document, they will be added again during parsing.
17275 The other handler belongs to the doctree-resolved event:
17277 def process_todo_nodes(app, doctree, fromdocname):
17279 if not app.config.todo_include_todos:
17280 for node in doctree.traverse(todo):
17281 node.parent.remove(node)
17282 # Replace all todolist nodes with a list of the collected todos.
17284 # Augment each todo with a backlink to the original location.
17285 env = app.builder.env
17286 for node in doctree.traverse(todolist):
17288 if not app.config.todo_include_todos:
17289 node.replace_self([])
17290 continue
17291 content = []
17293 for todo_info in env.todo_all_todos:
17295 para = nodes.paragraph()
17296 filename = env.doc2path(todo_info['docname'], base=None)
17297 description = (
17298 _('(The original entry is located in %s, line %d and can be found ') %
17299 (filename, todo_info['lineno']))
17300 para += nodes.Text(description, description)
17301 # Create a reference
17303 newnode = nodes.reference('', '')
17304 innernode = nodes.emphasis(_('here'), _('here'))
17305 newnode['refdocname'] = todo_info['docname']
17306 newnode['refuri'] = app.builder.get_relative_uri(
17307 fromdocname, todo_info['docname'])
17308 newnode['refuri'] += '#' + todo_info['target']['refid']
17309 newnode.append(innernode)
17310 para += newnode
17311 para += nodes.Text('.)', '.)')
17312 # Insert into the todolist
17314 content.append(todo_info['todo'])
17315 content.append(para)
17316 node.replace_self(content)
17318 The doctree-resolved event is emitted at the end of phase 3 (resolving)
17321 and allows custom resolving to be done. The handler we have written for
17322 this event is a bit more involved. If the todo_include_todos config
17323 value (which we’ll describe shortly) is false, all todo and todolist
17324 nodes are removed from the documents. If not, todo nodes just stay
17325 where and how they are. todolist nodes are replaced by a list of todo
17326 entries, complete with backlinks to the location where they come from.
17327 The list items are composed of the nodes from the todo entry and docu‐
17328 tils nodes created on the fly: a paragraph for each entry, containing
17329 text that gives the location, and a link (reference node containing an
17330 italic node) with the backreference. The reference URI is built by
17331 sphinx.builders.Builder.get_relative_uri`() which creates a suitable
17332 URI depending on the used builder, and appending the todo node’s (the
17333 target’s) ID as the anchor name.
17334 The setup function
17336 As noted previously, the setup function is a requirement and is used to
17338 plug directives into Sphinx. However, we also use it to hook up the
17339 other parts of our extension. Let’s look at our setup function:
17340 def setup(app):
17342 app.add_config_value('todo_include_todos', False, 'html')
17343 app.add_node(todolist)
17345 app.add_node(todo,
17346 html=(visit_todo_node, depart_todo_node),
17347 latex=(visit_todo_node, depart_todo_node),
17348 text=(visit_todo_node, depart_todo_node))
17349 app.add_directive('todo', TodoDirective)
17351 app.add_directive('todolist', TodolistDirective)
17352 app.connect('doctree-resolved', process_todo_nodes)
17353 app.connect('env-purge-doc', purge_todos)
17354 return {
17356 'version': '0.1',
17357 'parallel_read_safe': True,
17358 'parallel_write_safe': True,
17359 }
17360 The calls in this function refer to the classes and functions we added
17363 earlier. What the individual calls do is the following:
17364 · add_config_value() lets Sphinx know that it should recognize the new
17366 config value todo_include_todos, whose default value should be False
17367 (this also tells Sphinx that it is a boolean value).
17368 If the third argument was 'html', HTML documents would be full
17370 rebuild if the config value changed its value. This is needed for
17371 config values that influence reading (build phase 1 (reading)).
17372 · add_node() adds a new node class to the build system. It also can
17374 specify visitor functions for each supported output format. These
17375 visitor functions are needed when the new nodes stay until phase 4
17376 (writing). Since the todolist node is always replaced in phase 3
17377 (resolving), it doesn’t need any.
17378 · add_directive() adds a new directive, given by name and class.
17380 · Finally, connect() adds an event handler to the event whose name is
17382 given by the first argument. The event handler function is called
17383 with several arguments which are documented with the event.
17384 With this, our extension is complete.
17386 Using the extension
17388 As before, we need to enable the extension by declaring it in our
17389 conf.py file. There are two steps necessary here:
17390 1. Add the _ext directory to the Python path using sys.path.append.
17392 This should be placed at the top of the file.
17393 2. Update or create the extensions list and add the extension file name
17395 to the list
17396 In addition, we may wish to set the todo_include_todos config value. As
17398 noted above, this defaults to False but we can set it explicitly.
17399 For example:
17401 import os
17403 import sys
17404 sys.path.append(os.path.abspath("./_ext"))
17406 extensions = ['todo']
17408 todo_include_todos = False
17410 You can now use the extension throughout your project. For example:
17412 index.rst
17414 Hello, world
17416 ============
17417 .. toctree::
17419 somefile.rst
17420 someotherfile.rst
17421 Hello world. Below is the list of TODOs.
17423 .. todolist::
17425 somefile.rst
17427 foo
17429 ===
17430 Some intro text here...
17432 .. todo:: Fix this
17434 someotherfile.rst
17436 bar
17438 ===
17439 Some more text here...
17441 .. todo:: Fix that
17443 Because we have configured todo_include_todos to False, we won’t actu‐
17445 ally see anything rendered for the todo and todolist directives. How‐
17446 ever, if we toggle this to true, we will see the output described pre‐
17447 viously.
17448 Further reading
17450 For more information, refer to the docutils documentation and
17451 /extdev/index.
17452 Developing a “recipe” extension
17454 The objective of this tutorial is to illustrate roles, directives and
17455 domains. Once complete, we will be able to use this extension to
17456 describe a recipe and reference that recipe from elsewhere in our docu‐
17457 mentation.
17458 NOTE:
17460 This tutorial is based on a guide first published on opensource.com
17461 and is provided here with the original author’s permission.
17462 Overview
17464 We want the extension to add the following to Sphinx:
17465 · A recipe directive, containing some content describing the recipe
17467 steps, along with a :contains: option highlighting the main ingredi‐
17468 ents of the recipe.
17469 · A ref role, which provides a cross-reference to the recipe itself.
17471 · A recipe domain, which allows us to tie together the above role and
17473 domain, along with things like indices.
17474 For that, we will need to add the following elements to Sphinx:
17476 · A new directive called recipe
17478 · New indexes to allow us to reference ingredient and recipes
17480 · A new domain called recipe, which will contain the recipe directive
17482 and ref role
17483 Prerequisites
17485 We need the same setup as in the previous extensions. This time, we
17486 will be putting out extension in a file called recipe.py.
17487 Here is an example of the folder structure you might obtain:
17489 └── source
17491 ├── _ext
17492 │ └── recipe.py
17493 ├── conf.py
17494 └── index.rst
17495 Writing the extension
17497 Open recipe.py and paste the following code in it, all of which we will
17498 explain in detail shortly:
17499 from collections import defaultdict
17501 from docutils.parsers.rst import directives
17503 from sphinx import addnodes
17505 from sphinx.directives import ObjectDescription
17506 from sphinx.domains import Domain
17507 from sphinx.domains import Index
17508 from sphinx.roles import XRefRole
17509 from sphinx.util.nodes import make_refnode
17510 class RecipeDirective(ObjectDescription):
17513 """A custom directive that describes a recipe."""
17514 has_content = True
17516 required_arguments = 1
17517 option_spec = {
17518 'contains': directives.unchanged_required,
17519 }
17520 def handle_signature(self, sig, signode):
17522 signode += addnodes.desc_name(text=sig)
17523 return sig
17524 def add_target_and_index(self, name_cls, sig, signode):
17526 signode['ids'].append('recipe' + '-' + sig)
17527 if 'noindex' not in self.options:
17528 ingredients = [
17529 x.strip() for x in self.options.get('contains').split(',')]
17530 recipes = self.env.get_domain('recipe')
17532 recipes.add_recipe(sig, ingredients)
17533 class IngredientIndex(Index):
17536 """A custom index that creates an ingredient matrix."""
17537 name = 'ingredient'
17539 localname = 'Ingredient Index'
17540 shortname = 'Ingredient'
17541 def generate(self, docnames=None):
17543 content = defaultdict(list)
17544 recipes = {name: (dispname, typ, docname, anchor)
17546 for name, dispname, typ, docname, anchor, _
17547 in self.domain.get_objects()}
17548 recipe_ingredients = self.domain.data['recipe_ingredients']
17549 ingredient_recipes = defaultdict(list)
17550 # flip from recipe_ingredients to ingredient_recipes
17552 for recipe_name, ingredients in recipe_ingredients.items():
17553 for ingredient in ingredients:
17554 ingredient_recipes[ingredient].append(recipe_name)
17555 # convert the mapping of ingredient to recipes to produce the expected
17557 # output, shown below, using the ingredient name as a key to group
17558 #
17559 # name, subtype, docname, anchor, extra, qualifier, description
17560 for ingredient, recipe_names in ingredient_recipes.items():
17561 for recipe_name in recipe_names:
17562 dispname, typ, docname, anchor = recipes[recipe_name]
17563 content[ingredient].append(
17564 (dispname, 0, docname, anchor, docname, '', typ))
17565 # convert the dict to the sorted list of tuples expected
17567 content = sorted(content.items())
17568 return content, True
17570 class RecipeIndex(Index):
17573 """A custom index that creates an recipe matrix."""
17574 name = 'recipe'
17576 localname = 'Recipe Index'
17577 shortname = 'Recipe'
17578 def generate(self, docnames=None):
17580 content = defaultdict(list)
17581 # sort the list of recipes in alphabetical order
17583 recipes = self.domain.get_objects()
17584 recipes = sorted(recipes, key=lambda recipe: recipe[0])
17585 # generate the expected output, shown below, from the above using the
17587 # first letter of the recipe as a key to group thing
17588 #
17589 # name, subtype, docname, anchor, extra, qualifier, description
17590 for name, dispname, typ, docname, anchor, _ in recipes:
17591 content[dispname[0].lower()].append(
17592 (dispname, 0, docname, anchor, docname, '', typ))
17593 # convert the dict to the sorted list of tuples expected
17595 content = sorted(content.items())
17596 return content, True
17598 class RecipeDomain(Domain):
17601 name = 'recipe'
17603 label = 'Recipe Sample'
17604 roles = {
17605 'ref': XRefRole()
17606 }
17607 directives = {
17608 'recipe': RecipeDirective,
17609 }
17610 indices = {
17611 RecipeIndex,
17612 IngredientIndex
17613 }
17614 initial_data = {
17615 'recipes': [], # object list
17616 'recipe_ingredients': {}, # name -> object
17617 }
17618 def get_full_qualified_name(self, node):
17620 return '{}.{}'.format('recipe', node.arguments[0])
17621 def get_objects(self):
17623 for obj in self.data['recipes']:
17624 yield(obj)
17625 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
17627 contnode):
17628 match = [(docname, anchor)
17629 for name, sig, typ, docname, anchor, prio
17630 in self.get_objects() if sig == target]
17631 if len(match) > 0:
17633 todocname = match[0][0]
17634 targ = match[0][1]
17635 return make_refnode(builder, fromdocname, todocname, targ,
17637 contnode, targ)
17638 else:
17639 print('Awww, found nothing')
17640 return None
17641 def add_recipe(self, signature, ingredients):
17643 """Add a new recipe to the domain."""
17644 name = '{}.{}'.format('recipe', signature)
17645 anchor = 'recipe-{}'.format(signature)
17646 self.data['recipe_ingredients'][name] = ingredients
17648 # name, dispname, type, docname, anchor, priority
17649 self.data['recipes'].append(
17650 (name, signature, 'Recipe', self.env.docname, anchor, 0))
17651 def setup(app):
17654 app.add_domain(RecipeDomain)
17655 return {
17657 'version': '0.1',
17658 'parallel_read_safe': True,
17659 'parallel_write_safe': True,
17660 }
17661 Let’s look at each piece of this extension step-by-step to explain
17664 what’s going on.
17665 The directive class
17667 The first thing to examine is the RecipeDirective directive:
17669 required_arguments = 1
17671 option_spec = {
17672 'contains': directives.unchanged_required,
17673 }
17674 def handle_signature(self, sig, signode):
17676 signode += addnodes.desc_name(text=sig)
17677 return sig
17678 def add_target_and_index(self, name_cls, sig, signode):
17680 signode['ids'].append('recipe' + '-' + sig)
17681 if 'noindex' not in self.options:
17682 ingredients = [
17683 x.strip() for x in self.options.get('contains').split(',')]
17684 recipes = self.env.get_domain('recipe')
17686 recipes.add_recipe(sig, ingredients)
17687 class IngredientIndex(Index):
17690 """A custom index that creates an ingredient matrix."""
17691 Unlike helloworld and todo, this directive doesn’t derive from docu‐
17694 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
17695 it derives from sphinx.directives.ObjectDescription and defines han‐
17696 dle_signature and add_target_and_index methods. This is because Object‐
17697 Description is a special-purpose directive that’s intended for describ‐
17698 ing things like classes, functions, or, in our case, recipes. More
17699 specifically, handle_signature implements parsing the signature of the
17700 directive and passes on the object’s name and type to its superclass,
17701 while add_taget_and_index adds a target (to link to) and an entry to
17702 the index for this node.
17703 We also see that this directive defines has_content, required_arguments
17705 and option_spec. Unlike the TodoDirective directive added in the previ‐
17706 ous tutorial, this directive takes a single argument, the recipe name,
17707 and an option, contains, in addition to the nested reStructuredText in
17708 the body.
17709 The index classes
17711 Todo
17713 Add brief overview of indices
17714 localname = 'Ingredient Index'
17716 shortname = 'Ingredient'
17717 def generate(self, docnames=None):
17719 content = defaultdict(list)
17720 recipes = {name: (dispname, typ, docname, anchor)
17722 for name, dispname, typ, docname, anchor, _
17723 in self.domain.get_objects()}
17724 recipe_ingredients = self.domain.data['recipe_ingredients']
17725 ingredient_recipes = defaultdict(list)
17726 # flip from recipe_ingredients to ingredient_recipes
17728 for recipe_name, ingredients in recipe_ingredients.items():
17729 for ingredient in ingredients:
17730 ingredient_recipes[ingredient].append(recipe_name)
17731 # convert the mapping of ingredient to recipes to produce the expected
17733 # output, shown below, using the ingredient name as a key to group
17734 #
17735 # name, subtype, docname, anchor, extra, qualifier, description
17736 for ingredient, recipe_names in ingredient_recipes.items():
17737 for recipe_name in recipe_names:
17738 dispname, typ, docname, anchor = recipes[recipe_name]
17739 content[ingredient].append(
17740 (dispname, 0, docname, anchor, docname, '', typ))
17741 # convert the dict to the sorted list of tuples expected
17743 content = sorted(content.items())
17744 return content, True
17746 class RecipeIndex(Index):
17749 """A custom index that creates an recipe matrix."""
17750 name = 'recipe'
17752 localname = 'Recipe Index'
17753 shortname = 'Recipe'
17754 def generate(self, docnames=None):
17756 content = defaultdict(list)
17757 # sort the list of recipes in alphabetical order
17759 recipes = self.domain.get_objects()
17760 recipes = sorted(recipes, key=lambda recipe: recipe[0])
17761 # generate the expected output, shown below, from the above using the
17763 # first letter of the recipe as a key to group thing
17764 #
17765 # name, subtype, docname, anchor, extra, qualifier, description
17766 for name, dispname, typ, docname, anchor, _ in recipes:
17767 content[dispname[0].lower()].append(
17768 (dispname, 0, docname, anchor, docname, '', typ))
17769 # convert the dict to the sorted list of tuples expected
17771 content = sorted(content.items())
17772 return content, True
17774 class RecipeDomain(Domain):
17777 Both IngredientIndex and RecipeIndex are derived from Index. They
17781 implement custom logic to generate a tuple of values that define the
17782 index. Note that RecipeIndex is a simple index that has only one entry.
17783 Extending it to cover more object types is not yet part of the code.
17784 Both indices use the method Index.generate() to do their work. This
17786 method combines the information from our domain, sorts it, and returns
17787 it in a list structure that will be accepted by Sphinx. This might look
17788 complicated but all it really is is a list of tuples like ('tomato',
17789 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
17790 guide for more information on this API.
17791 The domain
17793 A Sphinx domain is a specialized container that ties together roles,
17795 directives, and indices, among other things. Let’s look at the domain
17796 we’re creating here.
17797 roles = {
17799 'ref': XRefRole()
17800 }
17801 directives = {
17802 'recipe': RecipeDirective,
17803 }
17804 indices = {
17805 RecipeIndex,
17806 IngredientIndex
17807 }
17808 initial_data = {
17809 'recipes': [], # object list
17810 'recipe_ingredients': {}, # name -> object
17811 }
17812 def get_full_qualified_name(self, node):
17814 return '{}.{}'.format('recipe', node.arguments[0])
17815 def get_objects(self):
17817 for obj in self.data['recipes']:
17818 yield(obj)
17819 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
17821 contnode):
17822 match = [(docname, anchor)
17823 for name, sig, typ, docname, anchor, prio
17824 in self.get_objects() if sig == target]
17825 if len(match) > 0:
17827 todocname = match[0][0]
17828 targ = match[0][1]
17829 return make_refnode(builder, fromdocname, todocname, targ,
17831 contnode, targ)
17832 else:
17833 print('Awww, found nothing')
17834 return None
17835 def add_recipe(self, signature, ingredients):
17837 """Add a new recipe to the domain."""
17838 name = '{}.{}'.format('recipe', signature)
17839 anchor = 'recipe-{}'.format(signature)
17840 self.data['recipe_ingredients'][name] = ingredients
17842 # name, dispname, type, docname, anchor, priority
17843 self.data['recipes'].append(
17844 (name, signature, 'Recipe', self.env.docname, anchor, 0))
17845 def setup(app):
17848 app.add_domain(RecipeDomain)
17849 There are some interesting things to note about this recipe domain and
17852 domains in general. Firstly, we actually register our directives, roles
17853 and indices here, via the directives, roles and indices attributes,
17854 rather than via calls later on in setup. We can also note that we
17855 aren’t actually defining a custom role and are instead reusing the
17856 sphinx.roles.XRefRole role and defining the
17857 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
17858 ments, typ and target, which refer to the cross-reference type and its
17859 target name. We’ll use target to resolve our destination from our
17860 domain’s recipes because we currently have only one type of node.
17861 Moving on, we can see that we’ve defined initial_data. The values
17863 defined in initial_data will be copied to env.domaindata[domain_name]
17864 as the initial data of the domain, and domain instances can access it
17865 via self.data. We see that we have defined two items in initial_data:
17866 recipes and recipe2ingredient. These contain a list of all objects
17867 defined (i.e. all recipes) and a hash that maps a canonical ingredient
17868 name to the list of objects. The way we name objects is common across
17869 our extension and is defined in the get_full_qualified_name method. For
17870 each object created, the canonical name is recipe.<recipename>, where
17871 <recipename> is the name the documentation writer gives the object (a
17872 recipe). This enables the extension to use different object types that
17873 share the same name. Having a canonical name and central place for our
17874 objects is a huge advantage. Both our indices and our cross-referencing
17875 code use this feature.
17876 The setup function
17878 As always, the setup function is a requirement and is used to hook the
17880 various parts of our extension into Sphinx. Let’s look at the setup
17881 function for this extension.
17882 'version': '0.1',
17884 'parallel_read_safe': True,
17885 'parallel_write_safe': True,
17886 }
17887 This looks a little different to what we’re used to seeing. There are
17890 no calls to add_directive() or even add_role(). Instead, we have a sin‐
17891 gle call to add_domain() followed by some initialization of the stan‐
17892 dard domain. This is because we had already registered our directives,
17893 roles and indexes as part of the directive itself.
17894 Using the extension
17896 You can now use the extension throughout your project. For example:
17897 index.rst
17899 Joe's Recipes
17901 =============
17902 Below are a collection of my favourite recipes. I highly recommend the
17904 :recipe:ref:`TomatoSoup` recipe in particular!
17905 .. toctree::
17907 tomato-soup
17909 tomato-soup.rst
17911 The recipe contains `tomato` and `cilantro`.
17913 .. recipe:recipe:: TomatoSoup
17915 :contains: tomato cilantro salt pepper
17916 This recipe is a tasty tomato soup, combine all ingredients
17918 and cook.
17919 The important things to note are the use of the :recipe:ref: role to
17921 cross-reference the recipe actually defined elsewhere (using the
17922 :recipe:recipe: directive.
17923 Further reading
17925 For more information, refer to the docutils documentation and
17926 /extdev/index.
17927
17929 This is a list of Frequently Asked Questions about Sphinx. Feel free
17930 to suggest new entries!
17931 How do I…
17933 … create PDF files without LaTeX?
17934 rinohtype provides a PDF builder that can be used as a drop-in
17935 replacement for the LaTeX builder.
17936 … get section numbers?
17938 They are automatic in LaTeX output; for HTML, give a :numbered:
17939 option to the toctree directive where you want to start number‐
17940 ing.
17941 … customize the look of the built HTML files?
17943 Use themes, see /usage/theming.
17944 … add global substitutions or includes?
17946 Add them in the rst_prolog or rst_epilog config value.
17947 … display the whole TOC tree in the sidebar?
17949 Use the toctree callable in a custom layout template, probably
17950 in the sidebartoc block.
17951 … write my own extension?
17953 See the /development/tutorials/index.
17954 … convert from my existing docs using MoinMoin markup?
17956 The easiest way is to convert to xhtml, then convert xhtml to
17957 reST. You’ll still need to mark up classes and such, but the
17958 headings and code examples come through cleanly.
17959 For many more extensions and other contributed stuff, see the
17961 sphinx-contrib repository.
17962 Using Sphinx with…
17964 Read the Docs
17965 https://readthedocs.org is a documentation hosting service based
17966 around Sphinx. They will host sphinx documentation, along with
17967 supporting a number of other features including version support,
17968 PDF generation, and more. The Getting Started guide is a good
17969 place to start.
17970 Epydoc There’s a third-party extension providing an api role which
17972 refers to Epydoc’s API docs for a given identifier.
17973 Doxygen
17975 Michael Jones is developing a reST/Sphinx bridge to doxygen
17976 called breathe.
17977 SCons Glenn Hutchings has written a SCons build script to build Sphinx
17979 documentation; it is hosted here:
17980 https://bitbucket.org/zondo/sphinx-scons
17981 PyPI Jannis Leidel wrote a setuptools command that automatically
17983 uploads Sphinx documentation to the PyPI package documentation
17984 area at https://pythonhosted.org/.
17985 GitHub Pages
17987 Please add sphinx.ext.githubpages to your project. It allows
17988 you to publish your document in GitHub Pages. It generates
17989 helper files for GitHub Pages on building HTML document automat‐
17990 ically.
17991 MediaWiki
17993 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
17994 project by Kevin Dunn.
17995 Google Analytics
17997 You can use a custom layout.html template, like this:
17998 {% extends "!layout.html" %}
18000 {%- block extrahead %}
18002 {{ super() }}
18003 <script type="text/javascript">
18004 var _gaq = _gaq || [];
18005 _gaq.push(['_setAccount', 'XXX account number XXX']);
18006 _gaq.push(['_trackPageview']);
18007 </script>
18008 {% endblock %}
18009 {% block footer %}
18011 {{ super() }}
18012 <div class="footer">This page uses <a href="https://analytics.google.com/">
18013 Google Analytics</a> to collect statistics. You can disable it by blocking
18014 the JavaScript coming from www.google-analytics.com.
18015 <script type="text/javascript">
18016 (function() {
18017 var ga = document.createElement('script');
18018 ga.src = ('https:' == document.location.protocol ?
18019 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
18020 ga.setAttribute('async', 'true');
18021 document.documentElement.firstChild.appendChild(ga);
18022 })();
18023 </script>
18024 </div>
18025 {% endblock %}
18026 Google Search
18028 To replace Sphinx’s built-in search function with Google Search,
18029 proceed as follows:
18030 1. Go to https://cse.google.com/cse/all to create the Google
18032 Search code snippet.
18033 2. Copy the code snippet and paste it into _templates/search‐
18035 box.html in your Sphinx project:
18036 <div>
18038 <h3>{{ _('Quick search') }}</h3>
18039 <script>
18040 (function() {
18041 var cx = '......';
18042 var gcse = document.createElement('script');
18043 gcse.type = 'text/javascript';
18044 gcse.async = true;
18045 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
18046 var s = document.getElementsByTagName('script')[0];
18047 s.parentNode.insertBefore(gcse, s);
18048 })();
18049 </script>
18050 <gcse:search></gcse:search>
18051 </div>
18052 3. Add searchbox.html to the html_sidebars configuration value.
18054 Epub info
18056 The following list gives some hints for the creation of epub files:
18057 · Split the text into several files. The longer the individual HTML
18059 files are, the longer it takes the ebook reader to render them. In
18060 extreme cases, the rendering can take up to one minute.
18061 · Try to minimize the markup. This also pays in rendering time.
18063 · For some readers you can use embedded or external fonts using the CSS
18065 @font-face directive. This is extremely useful for code listings
18066 which are often cut at the right margin. The default Courier font
18067 (or variant) is quite wide and you can only display up to 60 charac‐
18068 ters on a line. If you replace it with a narrower font, you can get
18069 more characters on a line. You may even use FontForge and create
18070 narrow variants of some free font. In my case I get up to 70 charac‐
18071 ters on a line.
18072 You may have to experiment a little until you get reasonable results.
18074 · Test the created epubs. You can use several alternatives. The ones I
18076 am aware of are Epubcheck, Calibre, FBreader (although it does not
18077 render the CSS), and Bookworm. For Bookworm, you can download the
18078 source from https://code.google.com/archive/p/threepress and run your
18079 own local server.
18080 · Large floating divs are not displayed properly. If they cover more
18082 than one page, the div is only shown on the first page. In that case
18083 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
18084 tory to your local _static/ directory and remove the float settings.
18085 · Files that are inserted outside of the toctree directive must be man‐
18087 ually included. This sometimes applies to appendixes, e.g. the glos‐
18088 sary or the indices. You can add them with the epub_post_files
18089 option.
18090 · The handling of the epub cover page differs from the reStructuredText
18092 procedure which automatically resolves image paths and puts the
18093 images into the _images directory. For the epub cover page put the
18094 image in the html_static_path directory and reference it with its
18095 full path in the epub_cover config option.
18096 · kindlegen command can convert from epub3 resulting file to .mobi file
18098 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
18099 lowing command:
18100 $ make epub
18102 $ kindlegen _build/epub/yourdoc.epub
18103 The kindlegen command doesn’t accept documents that have section
18105 titles surrounding toctree directive:
18106 Section Title
18108 =============
18109 .. toctree::
18111 subdocument
18113 Section After Toc Tree
18115 ======================
18116 kindlegen assumes all documents order in line, but the resulting doc‐
18118 ument has complicated order for kindlegen:
18119 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
18121 If you get the following error, fix your document structure:
18123 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
18125 Error(prcgen):E24001: The table of content could not be built.
18126 Texinfo info
18128 There are two main programs for reading Info files, info and GNU Emacs.
18129 The info program has less features but is available in most Unix envi‐
18130 ronments and can be quickly accessed from the terminal. Emacs provides
18131 better font and color display and supports extensive customization (of
18132 course).
18133 Displaying Links
18135 One noticeable problem you may encounter with the generated Info files
18136 is how references are displayed. If you read the source of an Info
18137 file, a reference to this section would look like:
18138 * note Displaying Links: target-id
18140 In the stand-alone reader, info, references are displayed just as they
18142 appear in the source. Emacs, on the other-hand, will by default
18143 replace *note: with see and hide the target-id. For example:
18144 Displaying Links
18145 The exact behavior of how Emacs displays references is dependent on the
18147 variable Info-hide-note-references. If set to the value of hide, Emacs
18148 will hide both the *note: part and the target-id. This is generally
18149 the best way to view Sphinx-based documents since they often make fre‐
18150 quent use of links and do not take this limitation into account. How‐
18151 ever, changing this variable affects how all Info documents are dis‐
18152 played and most do take this behavior into account.
18153 If you want Emacs to display Info files produced by Sphinx using the
18155 value hide for Info-hide-note-references and the default value for all
18156 other Info files, try adding the following Emacs Lisp code to your
18157 start-up file, ~/.emacs.d/init.el.
18158 (defadvice info-insert-file-contents (after
18160 sphinx-info-insert-file-contents
18161 activate)
18162 "Hack to make `Info-hide-note-references' buffer-local and
18163 automatically set to `hide' iff it can be determined that this file
18164 was created from a Texinfo file generated by Docutils or Sphinx."
18165 (set (make-local-variable 'Info-hide-note-references)
18166 (default-value 'Info-hide-note-references))
18167 (save-excursion
18168 (save-restriction
18169 (widen) (goto-char (point-min))
18170 (when (re-search-forward
18171 "^Generated by \\(Sphinx\\|Docutils\\)"
18172 (save-excursion (search-forward "\x1f" nil t)) t)
18173 (set (make-local-variable 'Info-hide-note-references)
18174 'hide)))))
18175 Notes
18177 The following notes may be helpful if you want to create Texinfo files:
18178 · Each section corresponds to a different node in the Info file.
18180 · Colons (:) cannot be properly escaped in menu entries and xrefs.
18182 They will be replaced with semicolons (;).
18183 · Links to external Info files can be created using the somewhat offi‐
18185 cial URI scheme info. For example:
18186 info:Texinfo#makeinfo_options
18188 · Inline markup
18190 The standard formatting for *strong* and _emphasis_ can result in
18192 ambiguous output when used to markup parameter names and other val‐
18193 ues. Since this is a fairly common practice, the default formatting
18194 has been changed so that emphasis and strong are now displayed like
18195 `literal's.
18196 The standard formatting can be re-enabled by adding the following to
18198 your conf.py:
18199 texinfo_elements = {'preamble': """
18201 @definfoenclose strong,*,*
18202 @definfoenclose emph,_,_
18203 """}
18204
18206 builder
18207 A class (inheriting from Builder) that takes parsed documents
18208 and performs an action on them. Normally, builders translate
18209 the documents to an output format, but it is also possible to
18210 use the builder builders that e.g. check for broken links in the
18211 documentation, or build coverage information.
18212 See /usage/builders/index for an overview over Sphinx’s built-in
18214 builders.
18215 configuration directory
18217 The directory containing conf.py. By default, this is the same
18218 as the source directory, but can be set differently with the -c
18219 command-line option.
18220 directive
18222 A reStructuredText markup element that allows marking a block of
18223 content with special meaning. Directives are supplied not only
18224 by docutils, but Sphinx and custom extensions can add their own.
18225 The basic directive syntax looks like this:
18226 .. directivename:: argument ...
18228 :option: value
18229 Content of the directive.
18231 See rst-directives for more information.
18233 document name
18235 Since reST source files can have different extensions (some peo‐
18236 ple like .txt, some like .rst – the extension can be configured
18237 with source_suffix) and different OSes have different path sepa‐
18238 rators, Sphinx abstracts them: document names are always rela‐
18239 tive to the source directory, the extension is stripped, and
18240 path separators are converted to slashes. All values, parame‐
18241 ters and such referring to “documents” expect such document
18242 names.
18243 Examples for document names are index, library/zipfile, or ref‐
18245 erence/datamodel/types. Note that there is no leading or trail‐
18246 ing slash.
18247 domain A domain is a collection of markup (reStructuredText directives
18249 and roles) to describe and link to objects belonging together,
18250 e.g. elements of a programming language. Directive and role
18251 names in a domain have names like domain:name, e.g. py:function.
18252 Having domains means that there are no naming problems when one
18254 set of documentation wants to refer to e.g. C++ and Python
18255 classes. It also means that extensions that support the docu‐
18256 mentation of whole new languages are much easier to write.
18257 For more information, refer to /usage/restructuredtext/domains.
18259 environment
18261 A structure where information about all documents under the root
18262 is saved, and used for cross-referencing. The environment is
18263 pickled after the parsing stage, so that successive runs only
18264 need to read and parse new and changed documents.
18265 extension
18267 A custom role, directive or other aspect of Sphinx that allows
18268 users to modify any aspect of the build process within Sphinx.
18269 For more information, refer to /usage/extensions/index.
18271 master document
18273 The document that contains the root toctree directive.
18274 object The basic building block of Sphinx documentation. Every “object
18276 directive” (e.g. function or object) creates such a block; and
18277 most objects can be cross-referenced to.
18278 RemoveInSphinxXXXWarning
18280 The feature which is warned will be removed in Sphinx-XXX ver‐
18281 sion. It usually caused from Sphinx extensions which is using
18282 deprecated. See also when-deprecation-warnings-are-displayed.
18283 role A reStructuredText markup element that allows marking a piece of
18285 text. Like directives, roles are extensible. The basic syntax
18286 looks like this: :rolename:`content`. See rst-inline-markup for
18287 details.
18288 source directory
18290 The directory which, including its subdirectories, contains all
18291 source files for one Sphinx project.
18292 reStructuredText
18294 An easy-to-read, what-you-see-is-what-you-get plaintext markup
18295 syntax and parser system.
18296
18298 Abstract
18299 This document describes the development process of Sphinx, a documenta‐
18300 tion system used by developers to document systems used by other devel‐
18301 opers to develop other systems that may also be documented using
18302 Sphinx.
18303 · Bug Reports and Feature Requests
18305 · Contributing to Sphinx
18307 · Getting Started
18309 · Core Developers
18311 · Locale updates
18313 · Coding Guide
18315 · Debugging Tips
18317 · Branch Model
18319 · Deprecating a feature
18321 · Deprecation policy
18323 · Unit Testing
18325 The Sphinx source code is managed using Git and is hosted on GitHub.
18327 git clone git://github.com/sphinx-doc/sphinx
18328 Community
18330 sphinx-users <sphinx-users@googlegroups.com>
18332 Mailing list for user support.
18333 sphinx-dev <sphinx-dev@googlegroups.com>
18335 Mailing list for development related discussions.
18336 #sphinx-doc on irc.freenode.net
18338 IRC channel for development questions and user support.
18339 Bug Reports and Feature Requests
18341 If you have encountered a problem with Sphinx or have an idea for a new
18342 feature, please submit it to the issue tracker on GitHub or discuss it
18343 on the sphinx-dev mailing list.
18344 For bug reports, please include the output produced during the build
18346 process and also the log file Sphinx creates after it encounters an
18347 unhandled exception. The location of this file should be shown towards
18348 the end of the error message.
18349 Including or providing a link to the source files involved may help us
18351 fix the issue. If possible, try to create a minimal project that pro‐
18352 duces the error and post that instead.
18353 Contributing to Sphinx
18355 The recommended way for new contributors to submit code to Sphinx is to
18356 fork the repository on GitHub and then submit a pull request after com‐
18357 mitting the changes. The pull request will then need to be approved by
18358 one of the core developers before it is merged into the main reposi‐
18359 tory.
18360 1. Check for open issues or open a fresh issue to start a discussion
18362 around a feature idea or a bug.
18363 2. If you feel uncomfortable or uncertain about an issue or your
18365 changes, feel free to email the sphinx-dev mailing list.
18366 3. Fork the repository on GitHub to start making your changes to the
18368 master branch for next MAJOR version, or X.Y branch for next MINOR
18369 version (see Branch Model).
18370 4. Write a test which shows that the bug was fixed or that the feature
18372 works as expected.
18373 5. Send a pull request and bug the maintainer until it gets merged and
18375 published. Make sure to add yourself to AUTHORS and the change to
18376 CHANGES.
18377 Getting Started
18379 These are the basic steps needed to start developing on Sphinx.
18380 1. Create an account on GitHub.
18382 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
18384 GitHub interface.
18385 3. Clone the forked repository to your machine.
18387 git clone https://github.com/USERNAME/sphinx
18389 cd sphinx
18390 4. Checkout the appropriate branch.
18392 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
18394 ).
18395 For changes that preserves backwards-compatibility of API and fea‐
18397 tures, they should be included in the next MINOR release, use the
18398 X.Y branch.
18399 git checkout X.Y
18401 For incompatible or other substantial changes that should wait
18403 until the next MAJOR release, use the master branch.
18404 For urgent release, a new PATCH branch must be branched from the
18406 newest release tag (see Branch Model for detail).
18407 5. Setup a virtual environment.
18409 This is not necessary for unit testing, thanks to tox, but it is
18411 necessary if you wish to run sphinx-build locally or run unit tests
18412 without the help of tox.
18413 virtualenv ~/.venv
18415 . ~/.venv/bin/activate
18416 pip install -e .
18417 6. Create a new working branch. Choose any name you like.
18419 git checkout -b feature-xyz
18421 7. Hack, hack, hack.
18423 For tips on working with the code, see the Coding Guide.
18425 8. Test, test, test.
18427 Testing is best done through tox, which provides a number of tar‐
18429 gets and allows testing against multiple different Python environ‐
18430 ments:
18431 · To list all possible targets:
18433 tox -av
18435 · To run unit tests for a specific Python version, such as 3.6:
18437 tox -e py36
18439 · To run unit tests for a specific Python version and turn on dep‐
18441 recation warnings on so they’re shown in the test output:
18442 PYTHONWARNINGS=all tox -e py36
18444 · To run code style and type checks:
18446 tox -e mypy
18448 tox -e flake8
18449 · Arguments to pytest can be passed via tox, e.g. in order to run a
18451 particular test:
18452 tox -e py36 tests/test_module.py::test_new_feature
18454 · To build the documentation:
18456 tox -e docs
18458 · To build the documentation in multiple formats:
18460 tox -e docs -- -b html,latexpdf
18462 · To run JavaScript tests with Karma, execute the following com‐
18464 mands (requires Node.js):
18465 npm install
18467 npm run test
18468 You can also test by installing dependencies in your local environ‐
18470 ment.
18471 pip install .[test]
18473 New unit tests should be included in the tests directory where nec‐
18475 essary:
18476 · For bug fixes, first add a test that fails without your changes
18478 and passes after they are applied.
18479 · Tests that need a sphinx-build run should be integrated in one of
18481 the existing test modules if possible. New tests that to
18482 @with_app and then build_all for a few assertions are not good
18483 since the test suite should not take more than a minute to run.
18484 9. Please add a bullet point to CHANGES if the fix or feature is not
18486 trivial (small doc updates, typo fixes). Then commit:
18487 git commit -m '#42: Add useful new feature that does this.'
18489 GitHub recognizes certain phrases that can be used to automatically
18491 update the issue tracker.
18492 For example:
18494 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
18496 would close issue #42.
18498 10. Push changes in the branch to your forked repository on GitHub.
18500 git push origin feature-xyz
18502 11. Submit a pull request from your branch to the respective branch
18504 (master or X.Y).
18505 12. Wait for a core developer to review your changes.
18507 Core Developers
18509 The core developers of Sphinx have write access to the main repository.
18510 They can commit changes, accept/reject pull requests, and manage items
18511 on the issue tracker.
18512 You do not need to be a core developer or have write access to be
18514 involved in the development of Sphinx. You can submit patches or cre‐
18515 ate pull requests from forked repositories and have a core developer
18516 add the changes for you.
18517 The following are some general guidelines for core developers:
18519 · Questionable or extensive changes should be submitted as a pull
18521 request instead of being committed directly to the main repository.
18522 The pull request should be reviewed by another core developer before
18523 it is merged.
18524 · Trivial changes can be committed directly but be sure to keep the
18526 repository in a good working state and that all tests pass before
18527 pushing your changes.
18528 · When committing code written by someone else, please attribute the
18530 original author in the commit message and any relevant CHANGES entry.
18531 Locale updates
18533 The parts of messages in Sphinx that go into builds are translated into
18534 several locales. The translations are kept as gettext .po files trans‐
18535 lated from the master template sphinx/locale/sphinx.pot.
18536 Sphinx uses Babel to extract messages and maintain the catalog files.
18538 It is integrated in setup.py:
18539 · Use python setup.py extract_messages to update the .pot template.
18541 · Use python setup.py update_catalog to update all existing language
18543 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
18544 the template file.
18545 · Use python setup.py compile_catalog to compile the .po files to
18547 binary .mo files and .js files.
18548 When an updated .po file is submitted, run compile_catalog to commit
18550 both the source and the compiled catalogs.
18551 When a new locale is submitted, add a new directory with the ISO 639-1
18553 language identifier and put sphinx.po in there. Don’t forget to update
18554 the possible values for language in doc/usage/configuration.rst.
18555 The Sphinx core messages can also be translated on Transifex. There
18557 exists a client tool named tx in the Python package “transifex_client”,
18558 which can be used to pull translations in .po format from Transifex.
18559 To do this, go to sphinx/locale and then run tx pull -f -l LANG where
18560 LANG is an existing language identifier. It is good practice to run
18561 python setup.py update_catalog afterwards to make sure the .po file has
18562 the canonical Babel formatting.
18563 Coding Guide
18565 · Try to use the same code style as used in the rest of the project.
18566 See the Pocoo Styleguide for more information.
18567 · For non-trivial changes, please update the CHANGES file. If your
18569 changes alter existing behavior, please document this.
18570 · New features should be documented. Include examples and use cases
18572 where appropriate. If possible, include a sample that is displayed
18573 in the generated output.
18574 · When adding a new configuration variable, be sure to document it and
18576 update sphinx/cmd/quickstart.py if it’s important enough.
18577 · Add appropriate unit tests.
18579 Debugging Tips
18581 · Delete the build cache before building documents if you make changes
18582 in the code by running the command make clean or using the
18583 sphinx-build -E option.
18584 · Use the sphinx-build -P option to run pdb on exceptions.
18586 · Use node.pformat() and node.asdom().toxml() to generate a printable
18588 representation of the document structure.
18589 · Set the configuration variable keep_warnings to True so warnings will
18591 be displayed in the generated output.
18592 · Set the configuration variable nitpicky to True so that Sphinx will
18594 complain about references without a known target.
18595 · Set the debugging options in the Docutils configuration file.
18597 · JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
18599 are generated by this modified snowballcode generator. Generated JSX
18600 files are in this repository. You can get the resulting JavaScript
18601 files using the following command:
18602 npm install
18604 node_modules/.bin/grunt build # -> dest/*.global.js
18605 Branch Model
18607 Sphinx project uses following branches for developing that conforms to
18608 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
18609 master Development for MAJOR version. All changes including incompati‐
18611 ble behaviors and public API updates are allowed.
18612 X.Y Where X.Y is the MAJOR.MINOR release. Used to maintain current
18614 MINOR release. All changes are allowed if the change preserves
18615 backwards-compatibility of API and features.
18616 Only the most recent MAJOR.MINOR branch is currently retained.
18618 When a new MAJOR version is released, the old MAJOR.MINOR branch
18619 will be deleted and replaced by an equivalent tag.
18620 X.Y.Z Where X.Y.Z is the MAJOR.MINOR.PATCH release. Only back‐
18622 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
18623 version is used for urgent bug fix.
18624 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
18626 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
18627 urgent release is needed. When new PATCH version is released,
18628 the branch will be deleted and replaced by an equivalent tag
18629 (ex. v2.3.1).
18630 Deprecating a feature
18632 There are a couple reasons that code in Sphinx might be deprecated:
18633 · If a feature has been improved or modified in a backwards-incompati‐
18635 ble way, the old feature or behavior will be deprecated.
18636 · Sometimes Sphinx will include a backport of a Python library that’s
18638 not included in a version of Python that Sphinx currently supports.
18639 When Sphinx no longer needs to support the older version of Python
18640 that doesn’t include the library, the library will be deprecated in
18641 Sphinx.
18642 As the Deprecation policy describes, the first release of Sphinx that
18644 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
18645 (where XX is the Sphinx version where the feature will be removed) when
18646 the deprecated feature is invoked. Assuming we have good test coverage,
18647 these warnings are converted to errors when running the test suite with
18648 warnings enabled:
18649 pytest -Wall
18651 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
18653 silence any warnings generated when running the tests.
18654 Deprecation policy
18656 MAJOR and MINOR releases may deprecate certain features from previous
18657 releases. If a feature is deprecated in a release A.x, it will continue
18658 to work in all A.x.x versions (for all versions of x). It will continue
18659 to work in all B.x.x versions but raise deprecation warnings. Depre‐
18660 cated features will be removed at the C.0.0. It means the deprecated
18661 feature will work during 2 MAJOR releases at least.
18662 So, for example, if we decided to start the deprecation of a function
18664 in Sphinx 2.x:
18665 · Sphinx 2.x will contain a backwards-compatible replica of the func‐
18667 tion which will raise a RemovedInSphinx40Warning.
18668 · Sphinx 3.x will still contain the backwards-compatible replica.
18670 · Sphinx 4.0 will remove the feature outright.
18672 The warnings are displayed by default. You can turn off display of
18674 these warnings with:
18675 · PYTHONWARNINGS= make html (Linux/Mac)
18677 · export PYTHONWARNINGS= and do make html (Linux/Mac)
18679 · set PYTHONWARNINGS= and do make html (Windows)
18681 Unit Testing
18683 Sphinx has been tested with pytest runner. Sphinx developers write unit
18684 tests using pytest notation. Utility functions and pytest fixtures for
18685 testing are provided in sphinx.testing. If you are a developer of
18686 Sphinx extensions, you can write unit tests with using pytest. At this
18687 time, sphinx.testing will help your test implementation.
18688 How to use pytest fixtures that are provided by sphinx.testing? You
18690 can require 'sphinx.testing.fixtures' in your test modules or con‐
18691 ftest.py files like this:
18692 pytest_plugins = 'sphinx.testing.fixtures'
18694 If you want to know more detailed usage, please refer to tests/con‐
18696 ftest.py and other test_*.py files under tests directory.
18697 NOTE:
18699 Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
18700 New in version 1.6: sphinx.testing as a experimental.
18702 New in version 1.8: Sphinx also runs JavaScript tests.
18705
18708 Release 2.2.2 (released Dec 03, 2019)
18709 Incompatible changes
18710 · #6803: For security reason of python, parallel mode is disabled on
18711 macOS and Python3.8+
18712 Bugs fixed
18714 · #6776: LaTeX: 2019-10-01 LaTeX release breaks sphinxcyrillic.sty
18715 · #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation
18717 messages has been broken
18718 · #6803: parallel build causes AttributeError on macOS and Python3.8
18720 Release 2.2.1 (released Oct 26, 2019)
18722 Bugs fixed
18723 · #6641: LaTeX: Undefined control sequence \sphinxmaketitle
18724 · #6710: LaTeX not well configured for Greek language as main language
18726 · #6759: validation of html static paths and extra paths no longer
18728 throws an error if the paths are in different directories
18729 Release 2.2.0 (released Aug 19, 2019)
18731 Incompatible changes
18732 · apidoc: template files are renamed to .rst_t
18733 · html: Field lists will be styled by grid layout
18735 Deprecated
18737 · sphinx.domains.math.MathDomain.add_equation()
18738 · sphinx.domains.math.MathDomain.get_next_equation_number()
18740 · The info and warn arguments of sphinx.ext.autosummary.generate.gener‐
18742 ate_autosummary_docs()
18743 · sphinx.ext.autosummary.generate._simple_info()
18745 · sphinx.ext.autosummary.generate._simple_warn()
18747 · sphinx.ext.todo.merge_info()
18749 · sphinx.ext.todo.process_todo_nodes()
18751 · sphinx.ext.todo.process_todos()
18753 · sphinx.ext.todo.purge_todos()
18755 Features added
18757 · #5124: graphviz: :graphviz_dot: option is renamed to :layout:
18758 · #1464: html: emit a warning if html_static_path and html_extra_path
18760 directories are inside output directory
18761 · #6514: html: Add a label to search input for accessability purposes
18763 · #5602: apidoc: Add --templatedir option
18765 · #6475: Add override argument to app.add_autodocumenter()
18767 · #6310: imgmath: let imgmath_use_preview work also with the SVG format
18769 for images rendering inline math
18770 · #6533: LaTeX: refactor visit_enumerated_list() to use \sphinxsetlist‐
18772 labels
18773 · #6628: quickstart: Use https://docs.python.org/3/ for default setting
18775 of intersphinx_mapping
18776 · #6419: sphinx-build: give reasons why rebuilded
18778 Bugs fixed
18780 · py domain: duplicated warning does not point the location of source
18781 code
18782 · #6499: html: Sphinx never updates a copy of html_logo even if origi‐
18784 nal file has changed
18785 · #1125: html theme: scrollbar is hard to see on classic theme and mac‐
18787 OS
18788 · #5502: linkcheck: Consider HTTP 503 response as not an error
18790 · #6439: Make generated download links reproducible
18792 · #6486: UnboundLocalError is raised if broken extension installed
18794 · #6567: autodoc: autodoc_inherit_docstrings does not effect to
18796 __init__() and __new__()
18797 · #6574: autodoc: autodoc_member_order does not refer order of imports
18799 when 'bysource' order
18800 · #6574: autodoc: missing type annotation for variadic and keyword
18802 parameters
18803 · #6589: autodoc: Formatting issues with autodoc_typehints=’none’
18805 · #6605: autodoc: crashed when target code contains custom method-like
18807 objects
18808 · #6498: autosummary: crashed with wrong autosummary_generate setting
18810 · #6507: autosummary: crashes without no autosummary_generate setting
18812 · #6511: LaTeX: autonumbered list can not be customized in LaTeX since
18814 Sphinx 1.8.0 (refs: #6533)
18815 · #6531: Failed to load last environment object when extension added
18817 · #736: Invalid sort in pair index
18819 · #6527: last_updated wrongly assumes timezone as UTC
18821 · #5592: std domain: option directive registers an index entry for each
18823 comma separated option
18824 · #6549: sphinx-build: Escaped characters in error messages
18826 · #6545: doctest comments not getting trimmed since Sphinx 1.8.0
18828 · #6561: glossary: Wrong hyperlinks are generated for non alphanumeric
18830 terms
18831 · #6620: i18n: classifiers of definition list are not translated with
18833 docutils-0.15
18834 · #6474: DocFieldTransformer raises AttributeError when given directive
18836 is not a subclass of ObjectDescription
18837 Release 2.1.2 (released Jun 19, 2019)
18839 Bugs fixed
18840 · #6497: custom lexers fails highlighting when syntax error
18841 · #6478, #6488: info field lists are incorrectly recognized
18843 Release 2.1.1 (released Jun 10, 2019)
18845 Incompatible changes
18846 · #6447: autodoc: Stop to generate document for undocumented module
18847 variables
18848 Bugs fixed
18850 · #6442: LaTeX: admonitions of note type can get separated from immedi‐
18851 ately preceding section title by pagebreak
18852 · #6448: autodoc: crashed when autodocumenting classes with __slots__ =
18854 None
18855 · #6451: autodoc: generates docs for “optional import”ed modules as
18857 variables
18858 · #6452: autosummary: crashed when generating document of properties
18860 · #6455: napoleon: docstrings for properties are not processed
18862 · #6436: napoleon: “Unknown target name” error if variable name ends
18864 with underscore
18865 · #6440: apidoc: missing blank lines between modules
18867 Release 2.1.0 (released Jun 02, 2019)
18869 Incompatible changes
18870 · Ignore filenames without file extension given to Builder.build_spe‐
18871 cific() API directly
18872 · #6230: The anchor of term in glossary directive is changed if it is
18874 consisted by non-ASCII characters
18875 · #4550: html: Centering tables by default using CSS
18877 · #6239: latex: xelatex and xeCJK are used for Chinese documents by
18879 default
18880 · Sphinx.add_lexer() now takes a Lexer class instead of instance. An
18882 instance of lexers are still supported until Sphinx-3.x.
18883 Deprecated
18885 · sphinx.builders.latex.LaTeXBuilder.apply_transforms()
18886 · sphinx.builders._epub_base.EpubBuilder.esc()
18888 · sphinx.directives.Acks
18890 · sphinx.directives.Author
18892 · sphinx.directives.Centered
18894 · sphinx.directives.Class
18896 · sphinx.directives.CodeBlock
18898 · sphinx.directives.Figure
18900 · sphinx.directives.HList
18902 · sphinx.directives.Highlight
18904 · sphinx.directives.Include
18906 · sphinx.directives.Index
18908 · sphinx.directives.LiteralInclude
18910 · sphinx.directives.Meta
18912 · sphinx.directives.Only
18914 · sphinx.directives.SeeAlso
18916 · sphinx.directives.TabularColumns
18918 · sphinx.directives.TocTree
18920 · sphinx.directives.VersionChange
18922 · sphinx.domains.python.PyClassmember
18924 · sphinx.domains.python.PyModulelevel
18926 · sphinx.domains.std.StandardDomain._resolve_citation_xref()
18928 · sphinx.domains.std.StandardDomain.note_citations()
18930 · sphinx.domains.std.StandardDomain.note_citation_refs()
18932 · sphinx.domains.std.StandardDomain.note_labels()
18934 · sphinx.environment.NoUri
18936 · sphinx.ext.apidoc.format_directive()
18938 · sphinx.ext.apidoc.format_heading()
18940 · sphinx.ext.apidoc.makename()
18942 · sphinx.ext.autodoc.importer.MockFinder
18944 · sphinx.ext.autodoc.importer.MockLoader
18946 · sphinx.ext.autodoc.importer.mock()
18948 · sphinx.ext.autosummary.autolink_role()
18950 · sphinx.ext.imgmath.DOC_BODY
18952 · sphinx.ext.imgmath.DOC_BODY_PREVIEW
18954 · sphinx.ext.imgmath.DOC_HEAD
18956 · sphinx.transforms.CitationReferences
18958 · sphinx.transforms.SmartQuotesSkipper
18960 · sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
18962 · sphinx.util.node.find_source_node()
18964 · sphinx.util.i18n.find_catalog()
18966 · sphinx.util.i18n.find_catalog_files()
18968 · sphinx.util.i18n.find_catalog_source_files()
18970 For more details, see deprecation APIs list.
18972 Features added
18974 · Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
18975 form
18976 · Add helper methods
18978 · PythonDomain.note_module()
18980 · PythonDomain.note_object()
18982 · SphinxDirective.set_source_info()
18984 · #6180: Support --keep-going with BuildDoc setup command
18986 · math directive now supports :class: option
18988 · todo: todo directive now supports :name: option
18990 · Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
18992 file variables (refs: #6232, #6303)
18993 · #6287: autodoc: Unable to document bound instance methods exported as
18995 module functions
18996 · #6289: autodoc: autodoc_default_options now supports imported-members
18998 option
18999 · #4777: autodoc: Support coroutine
19001 · #744: autodoc: Support abstractmethod
19003 · #6325: autodoc: Support attributes in __slots__. For dict-style
19005 __slots__, autodoc considers values as a docstring of the attribute
19006 · #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
19008 nature
19009 · #1063: autodoc: automodule directive now handles undocumented module
19011 level variables
19012 · #6212 autosummary: Add autosummary_imported_members to display
19014 imported members on autosummary
19015 · #6271: make clean is catastrophically broken if building into ‘.’
19017 · #6363: Support %O% environment variable in make.bat
19019 · #4777: py domain: Add :async: option to py:function directive
19021 · py domain: Add new options to py:method directive
19023 · :abstractmethod:
19025 · :async:
19027 · :classmethod:
19029 · :property:
19031 · :staticmethod:
19033 · rst domain: Add directive:option directive to describe the option for
19035 directive
19036 · #6306: html: Add a label to search form for accessability purposes
19038 · #4390: html: Consistent and semantic CSS for signatures
19040 · #6358: The rawsource property of production nodes now contains the
19042 full production rule
19043 · #6373: autosectionlabel: Allow suppression of warnings
19045 · coverage: Support a new coverage_ignore_pyobjects option
19047 · #6239: latex: Support to build Chinese documents
19049 Bugs fixed
19051 · #6230: Inappropriate node_id has been generated by glossary directive
19052 if term is consisted by non-ASCII characters
19053 · #6213: ifconfig: contents after headings are not shown
19055 · commented term in glossary directive is wrongly recognized
19057 · #6299: rst domain: rst:directive directive generates waste space
19059 · #6379: py domain: Module index (py-modindex.html) has duplicate
19061 titles
19062 · #6331: man: invalid output when doctest follows rubric
19064 · #6351: “Hyperlink target is not referenced” message is shown even if
19066 referenced
19067 · #6165: autodoc: tab_width setting of docutils has been ignored
19069 · #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
19071 · #6311: autosummary: autosummary table gets confused by complex type
19073 hints
19074 · #6350: autosummary: confused by an argument having some kind of
19076 default value
19077 · Generated Makefiles lack a final EOL (refs: #6232)
19079 · #6375: extlinks: Cannot escape angle brackets in link caption
19081 · #6378: linkcheck: Send commonly used User-Agent
19083 · #6387: html search: failed to search document with haiku and scrolls
19085 themes
19086 · #6408: html search: Fix the ranking of search results
19088 · #6406: Wrong year is returned for SOURCE_DATE_EPOCH
19090 · #6402: image directive crashes by unknown image format
19092 · #6286: C++, allow 8 and 9 in hexadecimal integer literals.
19094 · #6305: Fix the string in quickstart for ‘path’ argument of parser
19096 · LaTeX: Figures in admonitions produced errors (refs: #6364)
19098 Release 2.0.1 (released Apr 08, 2019)
19100 Bugs fixed
19101 · LaTeX: some system labels are not translated
19102 · RemovedInSphinx30Warning is marked as pending
19104 · deprecation warnings are not emitted
19106 · sphinx.application.CONFIG_FILENAME
19108 · sphinx.builders.htmlhelp
19110 · viewcode_import
19112 · #6208: C++, properly parse full xrefs that happen to have a short
19114 xref as prefix
19115 · #6220, #6225: napoleon: AttributeError is raised for raised section
19117 having references
19118 · #6245: circular import error on importing SerializingHTMLBuilder
19120 · #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
19122 · #6244: html: Search function is broken with 3rd party themes
19124 · #6263: html: HTML5Translator crashed with invalid field node
19126 · #6262: html theme: The style of field lists has changed in bizstyle
19128 theme
19129 Release 2.0.0 (released Mar 29, 2019)
19131 Dependencies
19132 2.0.0b1
19133 · LaTeX builder now depends on TeX Live 2015 or above.
19135 · LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
19137 Greek letters in text (not in math mark-up) via the text font and
19138 will not escape them to math mark-up. See the discussion of the
19139 'fontenc' key of latex_elements; such (optional) support for Greek
19140 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
19141 default font set-up is not modified) cm-super(-minimal) as additional
19142 Sphinx LaTeX requirements.
19143 · LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex'
19145 requires (by default) the FreeFont fonts, which in Ubuntu xenial are
19146 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
19147 package texlive-gnu-freefont.
19148 · requests 2.5.0 or above
19150 · The six package is no longer a dependency
19152 · The sphinxcontrib-websupport package is no longer a dependency
19154 · Some packages are separated to sub packages:
19156 · sphinxcontrib.applehelp
19158 · sphinxcontrib.devhelp
19160 · sphinxcontrib.htmlhelp
19162 · sphinxcontrib.jsmath
19164 · sphinxcontrib.serializinghtml
19166 · sphinxcontrib.qthelp
19168 Incompatible changes
19170 2.0.0b1
19171 · Drop python 2.7 and 3.4 support
19173 · Drop docutils 0.11 support
19175 · Drop features and APIs deprecated in 1.7.x
19177 · The default setting for master_doc is changed to 'index' which has
19179 been longly used as default of sphinx-quickstart.
19180 · LaTeX: Move message resources to sphinxmessage.sty
19182 · LaTeX: Stop using \captions<lang> macro for some labels
19184 · LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
19186 as default choice (refs: #5645)
19187 · LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
19189 FreeMono character width) like 'pdflatex' already did (due to Courier
19190 character width). You may need to adjust this via latex_elements
19191 'fvset' key, in case of usage of some other OpenType fonts (refs:
19192 #5768)
19193 · LaTeX: Greek letters in text are not escaped to math mode mark-up,
19195 and they will use the text font not the math font. The LGR font
19196 encoding must be added to the 'fontenc' key of latex_elements for
19197 this to work (only if it is needed by the document, of course).
19198 · LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
19200 chap, now it is Bjarne to match case of no language specified.
19201 (refs: #5772)
19202 · #5770: doctest: Follow highlight_language on highlighting doctest
19204 block. As a result, they are highlighted as python3 by default.
19205 · The order of argument for HTMLTranslator, HTML5Translator and Manual‐
19207 PageTranslator are changed
19208 · LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
19210 merly done during loading of 'manual' docclass get executed later, at
19211 time of \sphinxtableofcontents. This means that custom user defini‐
19212 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
19213 contentshook to insert custom user definitions. See latex-macros.
19214 · quickstart: Simplify generated conf.py
19216 · #4148: quickstart: some questions are removed. They are still able
19218 to specify via command line options
19219 · websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
19221 support
19222 · C++, the visibility of base classes is now always rendered as present
19224 in the input. That is, private is now shown, where it was ellided
19225 before.
19226 · LaTeX: graphics inclusion of oversized images rescales to not exceed
19228 the text width and height, even if width and/or height option were
19229 used. (refs: #5956)
19230 · epub: epub_title defaults to the project option
19232 · #4550: All tables and figures without align option are displayed to
19234 center
19235 · #4587: html: Output HTML5 by default
19237 2.0.0b2
19239 · texinfo: image files are copied into name-figure directory
19241 Deprecated
19243 2.0.0b1
19244 · Support for evaluating Python 2 syntax is deprecated. This includes
19246 configuration files which should be converted to Python 3.
19247 · The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
19249 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
19250 EpubBuilder.build_epub()
19251 · The arguments of Epub3Builder.build_navigation_doc()
19253 · The config variables
19255 · html_experimental_html5_writer
19257 · The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
19259 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
19260 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
19261 are deprecated.
19262 · The importer argument of sphinx.ext.autodoc.importer._MockModule
19264 · The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
19266 words()
19267 · The suffix argument of env.doc2path() is deprecated.
19269 · The string style base argument of env.doc2path() is deprecated.
19271 · The fallback to allow omitting the filename argument from an overrid‐
19273 den IndexBuilder.feed() method is deprecated.
19274 · sphinx.addnodes.abbreviation
19276 · sphinx.application.Sphinx._setting_up_extension
19278 · sphinx.builders.epub3.Epub3Builder.validate_config_value()
19280 · sphinx.builders.html.SingleFileHTMLBuilder
19282 · sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
19284 · sphinx.cmd.quickstart.term_decode()
19286 · sphinx.cmd.quickstart.TERM_ENCODING
19288 · sphinx.config.check_unicode()
19290 · sphinx.config.string_classes
19292 · sphinx.domains.cpp.DefinitionError.description
19294 · sphinx.domains.cpp.NoOldIdError.description
19296 · sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
19298 · sphinx.ext.autodoc.importer._MockImporter
19300 · sphinx.ext.autosummary.Autosummary.warn()
19302 · sphinx.ext.autosummary.Autosummary.genopt
19304 · sphinx.ext.autosummary.Autosummary.warnings
19306 · sphinx.ext.autosummary.Autosummary.result
19308 · sphinx.ext.doctest.doctest_encode()
19310 · sphinx.io.SphinxBaseFileInput
19312 · sphinx.io.SphinxFileInput.supported
19314 · sphinx.io.SphinxRSTFileInput
19316 · sphinx.registry.SphinxComponentRegistry.add_source_input()
19318 · sphinx.roles.abbr_role()
19320 · sphinx.roles.emph_literal_role()
19322 · sphinx.roles.menusel_role()
19324 · sphinx.roles.index_role()
19326 · sphinx.roles.indexmarkup_role()
19328 · sphinx.testing.util.remove_unicode_literal()
19330 · sphinx.util.attrdict
19332 · sphinx.util.force_decode()
19334 · sphinx.util.get_matching_docs()
19336 · sphinx.util.inspect.Parameter
19338 · sphinx.util.jsonimpl
19340 · sphinx.util.osutil.EEXIST
19342 · sphinx.util.osutil.EINVAL
19344 · sphinx.util.osutil.ENOENT
19346 · sphinx.util.osutil.EPIPE
19348 · sphinx.util.osutil.walk()
19350 · sphinx.util.PeekableIterator
19352 · sphinx.util.pycompat.NoneType
19354 · sphinx.util.pycompat.TextIOWrapper
19356 · sphinx.util.pycompat.UnicodeMixin
19358 · sphinx.util.pycompat.htmlescape
19360 · sphinx.util.pycompat.indent
19362 · sphinx.util.pycompat.sys_encoding
19364 · sphinx.util.pycompat.terminal_safe()
19366 · sphinx.util.pycompat.u
19368 · sphinx.writers.latex.ExtBabel
19370 · sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
19372 · sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
19374 · sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
19376 · sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
19378 · sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
19380 · sphinx.writers.text.TextTranslator._make_depart_admonition()
19382 · template variables for LaTeX template
19384 · logo
19386 · numfig_format
19388 · pageautorefname
19390 · translatablestrings
19392 For more details, see deprecation APIs list.
19394 Features added
19396 2.0.0b1
19397 · #1618: The search results preview of generated HTML documentation is
19399 reader-friendlier: instead of showing the snippets as raw reStruc‐
19400 turedText markup, Sphinx now renders the corresponding HTML. This
19401 means the Sphinx extension Sphinx: pretty search results is no longer
19402 necessary. Note that changes to the search function of your custom
19403 or 3rd-party HTML template might overwrite this improvement.
19404 · #4182: autodoc: Support suppress_warnings
19406 · #5533: autodoc: autodoc_default_options supports member-order
19408 · #5394: autodoc: Display readable names in type annotations for mocked
19410 objects
19411 · #5459: autodoc: autodoc_default_options accepts True as a value
19413 · #1148: autodoc: Add autodecorator directive for decorators
19415 · #5635: autosummary: Add autosummary_mock_imports to mock external
19417 libraries on importing targets
19418 · #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
19420 · #5559: text: Support complex tables (colspan and rowspan)
19422 · LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
19424 Unicode letters in non-Cyrillic document even with 'pdflatex' as
19425 latex_engine (refs: #5645)
19426 · #5660: The versionadded, versionchanged and deprecated directives are
19428 now generated with their own specific CSS classes (added, changed and
19429 deprecated, respectively) in addition to the generic versionmodified
19430 class.
19431 · #5841: apidoc: Add –extensions option to sphinx-apidoc
19433 · #4981: C++, added an alias directive for inserting lists of declara‐
19435 tions, that references existing declarations (e.g., for making a syn‐
19436 opsis).
19437 · C++: add cpp:struct to complement cpp:class.
19439 · #1341 the HTML search considers words that contain a search term of
19441 length three or longer a match.
19442 · #4611: epub: Show warning for duplicated ToC entries
19444 · #1851: Allow to omit an argument for code-block directive. If omit‐
19446 ted, it follows highlight or highlight_language
19447 · #4587: html: Add html4_writer to use old HTML4 writer
19449 · #6016: HTML search: A placeholder for the search summary prevents
19451 search result links from changing their position when the search ter‐
19452 minates. This makes navigating search results easier.
19453 · #5196: linkcheck also checks remote images exist
19455 · #5924: githubpages: create CNAME file for custom domains when
19457 html_baseurl set
19458 · #4261: autosectionlabel: restrict the labeled sections by new config
19460 value; autosectionlabel_maxdepth
19461 Bugs fixed
19463 2.0.0b1
19464 · #1682: LaTeX: writer should not translate Greek unicode, but use
19466 textgreek package
19467 · #5247: LaTeX: PDF does not build with default font config for Russian
19469 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
19470 · #5248: LaTeX: Greek letters in section titles disappear from PDF
19472 bookmarks
19473 · #5249: LaTeX: Unicode Greek letters in math directive break PDF build
19475 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
19476 latex_engine setting)
19477 · #5772: LaTeX: should the Bjarne style of fncychap be used for English
19479 also if passed as language option?
19480 · #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
19482 enough as \textgreater{}\textgreater{} applies TeX-ligature
19483 · LaTeX: project name is not escaped if latex_documents omitted
19485 · LaTeX: authors are not shown if latex_documents omitted
19487 · HTML: Invalid HTML5 file is generated for a glossary having multiple
19489 terms for one description (refs: #4611)
19490 · QtHelp: OS dependent path separator is used in .qhp file
19492 · HTML search: search always returns nothing when multiple search terms
19494 are used and one term is shorter than three characters
19495 2.0.0b2
19497 · #6096: html: Anchor links are not added to figures
19499 · #3620: html: Defer searchindex.js rather than loading it via ajax
19501 · #6113: html: Table cells and list items have large margins
19503 · #5508: linenothreshold option for highlight directive was ignored
19505 · texinfo: make install-info causes syntax error
19507 · texinfo: make install-info fails on macOS
19509 · #3079: texinfo: image files are not copied on make install-info
19511 · #5391: A cross reference in heading is rendered as literal
19513 · #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
19515 · #6147: classes attribute of citation_reference node is lost
19517 · AssertionError is raised when custom citation_reference node having
19519 classes attribute refers missing citation (refs: #6147)
19520 · #2155: Support code directive
19522 · C++, fix parsing of braced initializers.
19524 · #6172: AttributeError is raised for old styled index nodes
19526 · #4872: inheritance_diagram: correctly describe behavior of parts
19528 option in docs, allow negative values.
19529 · #6178: i18n: Captions missing in translations for hidden TOCs
19531 2.0.0 final
19533 · #6196: py domain: unexpected prefix is generated
19535 Testing
19537 2.0.0b1
19538 · Stop to use SPHINX_TEST_TEMPDIR envvar
19540 2.0.0b2
19542 · Add a helper function: sphinx.testing.restructuredtext.parse()
19544 Release 1.8.5 (released Mar 10, 2019)
19546 Bugs fixed
19547 · LaTeX: Remove extraneous space after author names on PDF title page
19548 (refs: #6004)
19549 · #6026: LaTeX: A cross reference to definition list does not work
19551 · #6046: LaTeX: TypeError is raised when invalid latex_elements given
19553 · #6067: LaTeX: images having a target are concatenated to next line
19555 · #6067: LaTeX: images having a target are not aligned even if speci‐
19557 fied
19558 · #6149: LaTeX: :index: role in titles causes Use of \@icentercr
19560 doesn't match its definition error on latexpdf build
19561 · #6019: imgconverter: Including multipage PDF fails
19563 · #6047: autodoc: autofunction emits a warning for method objects
19565 · #6028: graphviz: Ensure the graphviz filenames are reproducible
19567 · #6068: doctest: skipif option may remove the code block from documen‐
19569 tation
19570 · #6136: :name: option for math directive causes a crash
19572 · #6139: intersphinx: ValueError on failure reporting
19574 · #6135: changes: Fix UnboundLocalError when any module found
19576 · #3859: manpage: code-block captions are not displayed correctly
19578 Release 1.8.4 (released Feb 03, 2019)
19580 Bugs fixed
19581 · #3707: latex: no bold checkmark (✔) available.
19582 · #5605: with the documentation language set to Chinese, English words
19584 could not be searched.
19585 · #5889: LaTeX: user numfig_format is stripped of spaces and may cause
19587 build failure
19588 · C++, fix hyperlinks for declarations involving east cv-qualifiers.
19590 · #5755: C++, fix duplicate declaration error on function templates
19592 with constraints in the return type.
19593 · C++, parse unary right fold expressions and binary fold expressions.
19595 · pycode could not handle egg files on windows
19597 · #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
19599 · #5936: LaTeX: PDF build broken by inclusion of image taller than page
19601 height in an admonition
19602 · #5231: “make html” does not read and build “po” files in “locale” dir
19604 · #5954: :scale: image option may break PDF build if image in an admo‐
19606 nition
19607 · #5966: mathjax has not been loaded on incremental build
19609 · #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
19611 of parskip.sty
19612 · #5948: LaTeX: duplicated labels are generated for sections
19614 · #5958: versionadded directive causes crash with Python 3.5.0
19616 · #5995: autodoc: autodoc_mock_imports conflict with metaclass on
19618 Python 3.7
19619 · #5871: texinfo: a section title . is not allowed
19621 Release 1.8.3 (released Dec 26, 2018)
19623 Features added
19624 · LaTeX: it is possible to insert custom material to appear on back of
19625 title page, see discussion of 'maketitle' key of latex_elements
19626 ('manual' docclass only)
19627 Bugs fixed
19629 · #5725: mathjax: Use CDN URL for “latest” version by default
19630 · #5460: html search does not work with some 3rd party themes
19632 · #5520: LaTeX, caption package incompatibility since Sphinx 1.6
19634 · #5614: autodoc: incremental build is broken when builtin modules are
19636 imported
19637 · #5627: qthelp: index.html missing in QtHelp
19639 · #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
19641 acter
19642 · #5754: DOC: Fix some mistakes in /latex
19644 · #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
19646 1.6.6 (refs: #1238)
19647 · #5636: C++, fix parsing of floating point literals.
19649 · #5496 (again): C++, fix assertion in partial builds with duplicates.
19651 · #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
19653 · #1956: Default conf.py is not PEP8-compliant
19655 · #5849: LaTeX: document class \maketitle is overwritten with no possi‐
19657 bility to use original meaning in place of Sphinx custom one
19658 · #5834: apidoc: wrong help for --tocfile
19660 · #5800: todo: crashed if todo is defined in TextElement
19662 · #5846: htmlhelp: convert hex escaping to decimal escaping in
19664 .hhc/.hhk files
19665 · htmlhelp: broken .hhk file generated when title contains a double
19667 quote
19668 Release 1.8.2 (released Nov 11, 2018)
19670 Incompatible changes
19671 · #5497: Do not include MathJax.js and jsmath.js unless it is really
19672 needed
19673 Features added
19675 · #5471: Show appropriate deprecation warnings
19676 Bugs fixed
19678 · #5490: latex: enumerated list causes a crash with recommonmark
19679 · #5492: sphinx-build fails to build docs w/ Python < 3.5.2
19681 · #3704: latex: wrong \label positioning for figures with a legend
19683 · #5496: C++, fix assertion when a symbol is declared more than twice.
19685 · #5493: gettext: crashed with broken template
19687 · #5495: csv-table directive with file option in included file is bro‐
19689 ken (refs: #4821)
19690 · #5498: autodoc: unable to find type hints for a functools.partial
19692 · #5480: autodoc: unable to find type hints for unresolvable Forward
19694 references
19695 · #5419: incompatible math_block node has been generated
19697 · #5548: Fix ensuredir() in case of pre-existing file
19699 · #5549: graphviz Correctly deal with non-existing static dir
19701 · #3002: i18n: multiple footnote_references referring same footnote
19703 cause duplicated node_ids
19704 · #5563: latex: footnote_references generated by extension causes a
19706 LaTeX builder crash
19707 · #5561: make all-pdf fails with old xindy version
19709 · #5557: quickstart: –no-batchfile isn’t honored
19711 · #3080: texinfo: multiline rubrics are broken
19713 · #3080: texinfo: multiline citations are broken
19715 Release 1.8.1 (released Sep 22, 2018)
19717 Incompatible changes
19718 · LaTeX \pagestyle commands have been moved to the LaTeX template. No
19719 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
19720 tained them, had been customized in conf.py. (refs: #5455)
19721 Bugs fixed
19723 · #5418: Incorrect default path for sphinx-build -d/doctrees files
19724 · #5421: autodoc emits deprecation warning for autodoc_default_flags
19726 · #5422: lambda object causes PicklingError on storing environment
19728 · #5417: Sphinx fails to build with syntax error in Python 2.7.5
19730 · #4911: add latexpdf to make.bat for non make-mode
19732 · #5436: Autodoc does not work with enum subclasses with proper‐
19734 ties/methods
19735 · #5437: autodoc: crashed on modules importing eggs
19737 · #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
19739 · #5431: autodoc: autofunction emits a warning for callable objects
19741 · #5457: Fix TypeError in error message when override is prohibited
19743 · #5453: PDF builds of ‘howto’ documents have no page numbers
19745 · #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
19747 · #5454: latex: Index has disappeared from PDF for Japanese documents
19749 · #5432: py domain: :type: field can’t process :term: references
19751 · #5426: py domain: TypeError has been raised for class attribute
19753 Release 1.8.0 (released Sep 13, 2018)
19755 Dependencies
19756 1.8.0b1
19757 · LaTeX: latex_use_xindy, if True (default for xelatex/lualatex),
19759 instructs make latexpdf to use xindy for general index. Make sure
19760 your LaTeX distribution includes it. (refs: #5134)
19761 · LaTeX: latexmk is required for make latexpdf on Windows
19763 Incompatible changes
19765 1.8.0b2
19766 · #5282: html theme: refer pygments_style settings of HTML themes pref‐
19768 erentially
19769 · The URL of download files are changed
19771 · #5127: quickstart: Makefile and make.bat are not overwritten if
19773 exists
19774 1.8.0b1
19776 · #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
19778 of the document being built instead of in the root directory of the
19779 documentation.
19780 · #4460: extensions which stores any data to environment should return
19782 the version of its env data structure as metadata. In detail, please
19783 see ext-metadata.
19784 · Sphinx expects source parser modules to have supported file formats
19786 as Parser.supported attribute
19787 · The default value of epub_author and epub_publisher are changed from
19789 'unknown' to the value of author. This is same as a conf.py file
19790 sphinx-build generates.
19791 · The gettext_compact attribute is removed from document.settings
19793 object. Please use config.gettext_compact instead.
19794 · The processing order on reading phase is changed. smart_quotes,
19796 sphinx domains, doctree-read event and versioning doctrees are
19797 invoked earlier than so far. For more details, please read a
19798 description of Sphinx.add_transform()
19799 · #4827: All substitution_definition nodes are removed from doctree on
19801 reading phase
19802 · docutils.conf in $HOME or /etc directories are ignored. Only docu‐
19804 tils.conf from confdir is obeyed.
19805 · #789: :samp: role supports to escape curly braces with backslash
19807 · #4811: The files under html_static_path are excluded from source
19809 files.
19810 · latex: Use \sphinxcite for citation references instead \hyperref
19812 · The config value viewcode_import is renamed to viewcode_fol‐
19814 low_imported_members (refs: #4035)
19815 · #1857: latex: latex_show_pagerefs does not add pagerefs for citations
19817 · #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
19819 tion title
19820 · #4983: html: The anchor for productionlist tokens has been changed
19822 · Modifying a template variable script_files in templates is allowed
19824 now. Please use app.add_js_file() instead.
19825 · #5072: Save environment object also with only new documents
19827 · #5035: qthelp builder allows dashes in qthelp_namespace
19829 · LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
19831 replacement of makeindex (refs: #5134). After upgrading Sphinx,
19832 please clean latex build repertory of existing project before new
19833 build.
19834 · #5163: html: hlist items are now aligned to top
19836 · highlightlang directive is processed on resolving phase
19838 · #4000: LaTeX: template changed. Following elements moved to it:
19840 · \begin{document}
19842 · shorthandoff variable
19844 · maketitle variable
19846 · tableofcontents variable
19848 Deprecated
19850 1.8.0b2
19851 · sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
19853 · sphinx.io.SphinxI18nReader.line is deprecated
19855 · sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
19857 text_compact argument has been deprecated
19858 · #5403: sphinx.util.images.guess_mimetype() has changed; the content
19860 argument has been deprecated
19861 1.8.0b1
19863 · source_parsers is deprecated
19865 · autodoc_default_flags is deprecated
19867 · quickstart: --epub option becomes default, so it is deprecated
19869 · Drop function based directive support. For now, Sphinx only supports
19871 class based directives (see Directive)
19872 · sphinx.util.docutils.directive_helper() is deprecated
19874 · sphinx.cmdline is deprecated
19876 · sphinx.make_mode is deprecated
19878 · sphinx.locale.l_() is deprecated
19880 · #2157: helper function warn() for HTML themes is deprecated
19882 · app.override_domain() is deprecated
19884 · app.add_stylesheet() is deprecated
19886 · app.add_javascript() is deprecated
19888 · app.import_object() is deprecated
19890 · app.add_source_parser() has changed; the suffix argument has been
19892 deprecated
19893 · sphinx.versioning.prepare() is deprecated
19895 · Config.__init__() has changed; the dirname, filename and tags argu‐
19897 ment has been deprecated
19898 · Config.check_types() is deprecated
19900 · Config.check_unicode() is deprecated
19902 · sphinx.application.CONFIG_FILENAME is deprecated
19904 · highlightlang directive is deprecated
19906 · BuildEnvironment.load() is deprecated
19908 · BuildEnvironment.loads() is deprecated
19910 · BuildEnvironment.frompickle() is deprecated
19912 · env.read_doc() is deprecated
19914 · env.update() is deprecated
19916 · env._read_serial() is deprecated
19918 · env._read_parallel() is deprecated
19920 · env.write_doctree() is deprecated
19922 · env._nitpick_ignore is deprecated
19924 · env.versionchanges is deprecated
19926 · env.dump() is deprecated
19928 · env.dumps() is deprecated
19930 · env.topickle() is deprecated
19932 · env.note_versionchange() is deprecated
19934 · sphinx.writers.latex.Table.caption_footnotetexts is deprecated
19936 · sphinx.writers.latex.Table.header_footnotetexts is deprecated
19938 · sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
19940 · sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
19942 deprecated
19943 · sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
19945 · sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
19947 · sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
19949 cated
19950 · sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
19952 cated
19953 · sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
19955 cated
19956 · sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
19958 cated
19959 · sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
19961 cated
19962 · sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
19964 · sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
19966 · sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
19968 · sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
19970 · sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
19972 · sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
19974 · sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
19976 cated
19977 · sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
19979 · sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
19981 · sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
19983 · sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
19985 recated
19986 · sphinx.ext.mathbase extension is deprecated
19988 · sphinx.ext.mathbase.math node is deprecated
19990 · sphinx.ext.mathbase.displaymath node is deprecated
19992 · sphinx.ext.mathbase.eqref node is deprecated
19994 · sphinx.ext.mathbase.is_in_section_title() is deprecated
19996 · sphinx.ext.mathbase.MathDomain is deprecated
19998 · sphinx.ext.mathbase.MathDirective is deprecated
20000 · sphinx.ext.mathbase.math_role is deprecated
20002 · sphinx.ext.mathbase.setup_math() is deprecated
20004 · sphinx.directives.other.VersionChanges is deprecated
20006 · sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
20008 · sphinx.ext.mathbase.get_node_equation_number() is deprecated
20010 · sphinx.ext.mathbase.wrap_displaymath() is deprecated
20012 · The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
20014 is deprecated
20015 For more details, see deprecation APIs list
20017 Features added
20019 1.8.0b2
20020 · #5388: Ensure frozen object descriptions are reproducible
20022 · #5362: apidoc: Add --tocfile option to change the filename of ToC
20024 1.8.0b1
20026 · Add config-inited event
20028 · Add sphinx.config.Any to represent the config value accepts any type
20030 of value
20031 · source_suffix allows a mapping fileext to file types
20033 · Add author as a configuration value
20035 · #2852: imgconverter: Support to convert GIF to PNG
20037 · sphinx-build command supports i18n console output
20039 · Add app.add_message_catalog() and sphinx.locale.get_translations() to
20041 support translation for 3rd party extensions
20042 · helper function warning() for HTML themes is added
20044 · Add Domain.enumerable_nodes to manage own enumerable nodes for
20046 domains (experimental)
20047 · Add a new keyword argument override to Application APIs
20049 · LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
20051 default sets fanvyvrb to use normal, not small, fontsize in
20052 code-blocks (refs: #4793)
20053 · Add html_css_files and epub_css_files for adding CSS files from con‐
20055 figuration
20056 · Add html_js_files for adding JS files from configuration
20058 · #4834: Ensure set object descriptions are reproducible.
20060 · #4828: Allow to override numfig_format partially. Full definition is
20062 not needed.
20063 · Improve warning messages during including (refs: #4818)
20065 · LaTeX: separate customizability of guilabel and menuselection (refs:
20067 #4830)
20068 · Add Config.read() classmethod to create a new config object from con‐
20070 figuration file
20071 · #4866: Wrap graphviz diagrams in <div> tag
20073 · viewcode: Add viewcode-find-source and viewcode-follow-imported to
20075 load source code without loading
20076 · #4785: napoleon: Add strings to translation file for localisation
20078 · #4927: Display a warning when invalid values are passed to
20080 linenothreshold option of highlight directive
20081 · C++:
20083 · Add a cpp:texpr role as a sibling to cpp:expr.
20085 · Add support for unions.
20087 · #3593, #2683: add support for anonymous entities using names star‐
20089 ing with @.
20090 · #5147: add support for (most) character literals.
20092 · Cross-referencing entities inside primary templates is supported,
20094 and now properly documented.
20095 · #1552: add new cross-referencing format for cpp:any and cpp:func
20097 roles, for referencing specific function overloads.
20098 · #3606: MathJax should be loaded with async attribute
20100 · html: Output canonical_url metadata if html_baseurl set (refs: #4193)
20102 · #5029: autosummary: expose inherited_members to template
20104 · #3784: mathjax: Add mathjax_options to give options to script tag for
20106 mathjax
20107 · #4362: latex: Don’t overwrite .tex file if document not changed
20109 · #1431: latex: Add alphanumeric enumerated list support
20111 · Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
20113 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
20114 · #4976: SphinxLoggerAdapter.info() now supports location parameter
20116 · #5122: setuptools: support nitpicky option
20118 · #2820: autoclass directive supports nested class
20120 · Add app.add_html_math_renderer() to register a math renderer for HTML
20122 · Apply trim_doctest_flags to all builders (cf. text, manpages)
20124 · #5140: linkcheck: Add better Accept header to HTTP client
20126 · #4614: sphinx-build: Add --keep-going option to show all warnings
20128 · Add math:numref role to refer equations (Same as eq)
20130 · quickstart: epub builder is enabled by default
20132 · #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
20134 builder
20135 · #5273: doctest: Skip doctest conditionally
20137 · #5306: autodoc: emit a warning for invalid typehints
20139 · #4075, #5215: autodoc: Add autodoc_default_options which accepts
20141 option values as dict
20142 Bugs fixed
20144 1.8.0b2
20145 · html: search box overrides to other elements if scrolled
20147 · i18n: warnings for translation catalogs have wrong line numbers
20149 (refs: #5321)
20150 · #5325: latex: cross references has been broken by multiply labeled
20152 objects
20153 · C++, fixes for symbol addition and lookup. Lookup should no longer
20155 break in partial builds. See also #5337.
20156 · #5348: download reference to remote file is not displayed
20158 · #5282: html theme: pygments_style of theme was overridden by conf.py
20160 by default
20161 · #4379: toctree shows confusing warning when document is excluded
20163 · #2401: autodoc: :members: causes :special-members: not to be shown
20165 · autodoc: ImportError is replaced by AttributeError for deeper module
20167 · #2720, #4034: Incorrect links with :download:, duplicate names, and
20169 parallel builds
20170 · #5290: autodoc: failed to analyze source code in egg package
20172 · #5399: Sphinx crashes if unknown po file exists
20174 1.8.0b1
20176 · i18n: message catalogs were reset on each initialization
20178 · #4850: latex: footnote inside footnote was not rendered
20180 · #4945: i18n: fix lang_COUNTRY not fallback correctly for
20182 IndexBuilder. Thanks to Shengjing Zhu.
20183 · #4983: productionlist directive generates invalid IDs for the tokens
20185 · #5132: lualatex: PDF build fails if indexed word starts with Unicode
20187 character
20188 · #5133: latex: index headings “Symbols” and “Numbers” not internation‐
20190 alized
20191 · #5114: sphinx-build: Handle errors on scanning documents
20193 · epub: spine has been broken when “self” is listed on toctree (refs:
20195 #4611)
20196 · #344: autosummary does not understand docstring of module level
20198 attributes
20199 · #5191: C++, prevent nested declarations in functions to avoid lookup
20201 problems.
20202 · #5126: C++, add missing isPack method for certain template parameter
20204 types.
20205 · #5187: C++, parse attributes on declarators as well.
20207 · C++, parse delete expressions and basic new expressions as well.
20209 · #5002: graphviz: SVGs do not adapt to the column width
20211 Features removed
20213 1.8.0b1
20214 · sphinx.ext.pngmath extension
20216 Documentation
20218 1.8.0b1
20219 · #5083: Fix wrong make.bat option for internationalization.
20221 · #5115: napoleon: add admonitions added by #4613 to the docs.
20223 Release 1.7.9 (released Sep 05, 2018)
20225 Features added
20226 · #5359: Make generated texinfo files reproducible by sorting the
20227 anchors
20228 Bugs fixed
20230 · #5361: crashed on incremental build if document uses include direc‐
20231 tive
20232 Release 1.7.8 (released Aug 29, 2018)
20234 Incompatible changes
20235 · The type of env.included has been changed to dict of set
20236 Bugs fixed
20238 · #5320: intersphinx: crashed if invalid url given
20239 · #5326: manpage: crashed when invalid docname is specified as
20241 man_pages
20242 · #5322: autodoc: Any typehint causes formatting error
20244 · #5327: “document isn’t included in any toctree” warning on rebuild
20246 with generated files
20247 · #5335: quickstart: escape sequence has been displayed with MacPorts’
20249 python
20250 Release 1.7.7 (released Aug 19, 2018)
20252 Bugs fixed
20253 · #5198: document not in toctree warning when including files only for
20254 parallel builds
20255 · LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
20257 in latex console output (refs: #5236)
20258 · LaTeX: suppress “remreset Warning: The remreset package is obsolete”
20260 in latex console output with recent LaTeX (refs: #5237)
20261 · #5234: PDF output: usage of PAPER environment variable is broken
20263 since Sphinx 1.5
20264 · LaTeX: fix the latex_engine documentation regarding Latin Modern font
20266 with XeLaTeX/LuaLateX (refs: #5251)
20267 · #5280: autodoc: Fix wrong type annotations for complex typing
20269 · autodoc: Optional types are wrongly rendered
20271 · #5291: autodoc crashed by ForwardRef types
20273 · #5211: autodoc: No docs generated for functools.partial functions
20275 · #5306: autodoc: getargspec() raises NameError for invalid typehints
20277 · #5298: imgmath: math_number_all causes equations to have two numbers
20279 in html
20280 · #5294: sphinx-quickstart blank prompts in PowerShell
20282 Release 1.7.6 (released Jul 17, 2018)
20284 Bugs fixed
20285 · #5037: LaTeX \sphinxupquote{} breaks in Russian
20286 · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
20288 · #5016: crashed when recommonmark.AutoStrictify is enabled
20290 · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
20292 · #5009: latex: a label for table is vanished if table does not have a
20294 caption
20295 · #5048: crashed with numbered toctree
20297 · #2410: C, render empty argument lists for macros.
20299 · C++, fix lookup of full template specializations with no template
20301 arguments.
20302 · #4667: C++, fix assertion on missing references in global scope when
20304 using intersphinx. Thanks to Alan M. Carroll.
20305 · #5019: autodoc: crashed by Form Feed Character
20307 · #5032: autodoc: loses the first staticmethod parameter for old styled
20309 classes
20310 · #5036: quickstart: Typing Ctrl-U clears the whole of line
20312 · #5066: html: “relations” sidebar is not shown by default
20314 · #5091: latex: curly braces in index entries are not handled correctly
20316 · #5070: epub: Wrong internal href fragment links
20318 · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
20320 · #4272: PDF builds of French projects have issues with XeTeX
20322 · #5076: napoleon raises RuntimeError with python 3.7
20324 · #5125: sphinx-build: Interface of sphinx:main() has changed
20326 · sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
20328 given argument
20329 · #5146: autosummary: warning is emitted when the first line of doc‐
20331 string ends with literal notation
20332 · autosummary: warnings of autosummary indicates wrong location (refs:
20334 #5146)
20335 · #5143: autodoc: crashed on inspecting dict like object which does not
20337 support sorting
20338 · #5139: autodoc: Enum argument missing if it shares value with another
20340 · #4946: py domain: rtype field could not handle “None” as a type
20342 · #5176: LaTeX: indexing of terms containing @, !, or " fails
20344 · #5161: html: crashes if copying static files are failed
20346 · #5167: autodoc: Fix formatting type annotations for tuples with more
20348 than two arguments
20349 · #3329: i18n: crashed by auto-symbol footnote references
20351 · #5158: autosummary: module summary has been broken when it starts
20353 with heading
20354 Release 1.7.5 (released May 29, 2018)
20356 Bugs fixed
20357 · #4924: html search: Upper characters problem in any other languages
20358 · #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
20360 tains a module starting with underscore
20361 · #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
20363 for contents, topic, admonition, table and section.
20364 · #4913: i18n: literal blocks in bullet list are not translated
20366 · #4962: C++, raised TypeError on duplicate declaration.
20368 · #4825: C++, properly parse expr roles and give better error messages
20370 when (escaped) line breaks are present.
20371 · C++, properly use desc_addname nodes for prefixes of names.
20373 · C++, parse pack expansions in function calls.
20375 · #4915, #4916: links on search page are broken when using dirhtml
20377 builder
20378 · #4969: autodoc: constructor method should not have return annotation
20380 · latex: deeply nested enumerated list which is beginning with non-1
20382 causes LaTeX engine crashed
20383 · #4978: latex: shorthandoff is not set up for Brazil locale
20385 · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
20387 · #4946: py domain: type field could not handle “None” as a type
20389 · #4979: latex: Incorrect escaping of curly braces in index entries
20391 · #4956: autodoc: Failed to extract document from a subclass of the
20393 class on mocked module
20394 · #4973: latex: glossary directive adds whitespace to each item
20396 · #4980: latex: Explicit labels on code blocks are duplicated
20398 · #4919: node.asdom() crashes if toctree has :numbered: option
20400 · #4914: autodoc: Parsing error when using dataclasses without default
20402 values
20403 · #4931: autodoc: crashed when handler for autodoc-skip-member raises
20405 an error
20406 · #4931: autodoc: crashed when subclass of mocked class are processed
20408 by napoleon module
20409 · #5007: sphinx-build crashes when error log contains a “%” character
20411 Release 1.7.4 (released Apr 25, 2018)
20413 Bugs fixed
20414 · #4885, #4887: domains: Crashed with duplicated objects
20415 · #4889: latex: sphinx.writers.latex causes recursive import
20417 Release 1.7.3 (released Apr 23, 2018)
20419 Bugs fixed
20420 · #4769: autodoc loses the first staticmethod parameter
20421 · #4790: autosummary: too wide two column tables in PDF builds
20423 · #4795: Latex customization via _templates/longtable.tex_t is broken
20425 · #4789: imgconverter: confused by convert.exe of Windows
20427 · #4783: On windows, Sphinx crashed when drives of srcdir and outdir
20429 are different
20430 · #4812: autodoc ignores type annotated variables
20432 · #4817: wrong URLs on warning messages
20434 · #4784: latex: latex_show_urls assigns incorrect footnote numbers if
20436 hyperlinks exists inside substitutions
20437 · #4837: latex with class memoir Error: Font command \sf is not sup‐
20439 ported
20440 · #4803: latex: too slow in proportion to number of auto numbered foot‐
20442 notes
20443 · #4838: htmlhelp: The entries in .hhp file is not ordered
20445 · toctree directive tries to glob for URL having query_string
20447 · #4871: html search: Upper characters problem in German
20449 · #4717: latex: Compilation for German docs failed with LuaLaTeX and
20451 XeLaTeX
20452 · #4459: duplicated labels detector does not work well in parallel
20454 build
20455 · #4878: Crashed with extension which returns invalid metadata
20457 Release 1.7.2 (released Mar 21, 2018)
20459 Incompatible changes
20460 · #4520: apidoc: folders with an empty __init__.py are no longer
20461 excluded from TOC
20462 Bugs fixed
20464 · #4669: sphinx.build_main and sphinx.make_main throw NameError
20465 · #4685: autosummary emits meaningless warnings
20467 · autodoc: crashed when invalid options given
20469 · pydomain: always strip parenthesis if empty (refs: #1042)
20471 · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
20473 · #4701: viewcode: Misplaced <div> in viewcode html output
20475 · #4444: Don’t require numfig to use :numref: on sections
20477 · #4727: Option clash for package textcomp
20479 · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
20481 · #4716: Generation PDF file with TexLive on Windows, file not found
20483 error
20484 · #4574: vertical space before equation in latex
20486 · #4720: message when an image is mismatched for builder is not clear
20488 · #4655, #4684: Incomplete localization strings in Polish and Chinese
20490 · #2286: Sphinx crashes when error is happens in rendering HTML pages
20492 · #4688: Error to download remote images having long URL
20494 · #4754: sphinx/pycode/__init__.py raises AttributeError
20496 · #1435: qthelp builder should htmlescape keywords
20498 · epub: Fix docTitle elements of toc.ncx is not escaped
20500 · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
20502 · #4767: html: search highlighting breaks mathjax equations
20504 Release 1.7.1 (released Feb 23, 2018)
20506 Deprecated
20507 · #4623: sphinx.build_main() is deprecated.
20508 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
20510 has been changed (Since 1.7.0)
20511 · #4664: sphinx.ext.intersphinx.debug() is deprecated.
20513 For more details, see deprecation APIs list
20515 Bugs fixed
20517 · #4608: epub: Invalid meta tag is generated
20518 · #4260: autodoc: keyword only argument separator is not disappeared if
20520 it is appeared at top of the argument list
20521 · #4622: epub: epub_scheme does not effect to content.opf
20523 · #4627: graphviz: Fit graphviz images to page
20525 · #4617: quickstart: PROJECT_DIR argument is required
20527 · #4623: sphinx.build_main no longer exists in 1.7.0
20529 · #4615: The argument of sphinx.build has been changed in 1.7.0
20531 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
20533 has been changed
20534 · #4630: Have order on msgids in sphinx.pot deterministic
20536 · #4563: autosummary: Incorrect end of line punctuation detection
20538 · #4577: Enumerated sublists with explicit start with wrong number
20540 · #4641: A external link in TOC cannot contain “?” with :glob: option
20542 · C++, add missing parsing of explicit casts and typeid in expression
20544 parsing.
20545 · C++, add missing parsing of this in expression parsing.
20547 · #4655: Fix incomplete localization strings in Polish
20549 · #4653: Fix error reporting for parameterless ImportErrors
20551 · #4664: Reading objects.inv fails again
20553 · #4662: any refs with term targets crash when an ambiguity is encoun‐
20555 tered
20556 Release 1.7.0 (released Feb 12, 2018)
20558 Dependencies
20559 1.7.0b1
20560 · Add packaging package
20562 Incompatible changes
20564 1.7.0b1
20565 · #3668: The arguments has changed of main functions for each command
20567 · #3893: Unknown html_theme_options throw warnings instead of errors
20569 · #3927: Python parameter/variable types should match classes, not all
20571 objects
20572 · #3962: sphinx-apidoc now recognizes given directory as an implicit
20574 namespace package when --implicit-namespaces option given, not subdi‐
20575 rectories of given directory.
20576 · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
20578 · #4226: apidoc: Generate new style makefile (make-mode)
20580 · #4274: sphinx-build returns 2 as an exit code on argument error
20582 · #4389: output directory will be created after loading extensions
20584 · autodoc does not generate warnings messages to the generated document
20586 even if keep_warnings is True. They are only emitted to stderr.
20587 · shebang line is removed from generated conf.py
20589 · #2557: autodoc: autodoc_mock_imports only mocks specified modules
20591 with their descendants. It does not mock their ancestors. If you
20592 want to mock them, please specify the name of ancestors explicitly.
20593 · #3620: html theme: move DOCUMENTATION_OPTIONS to independent
20595 JavaScript file (refs: #4295)
20596 · #4246: Limit width of text body for all themes. Configurable via
20598 theme options body_min_width and body_max_width.
20599 · #4771: apidoc: The exclude_patterns arguments are ignored if they are
20601 placed just after command line options
20602 1.7.0b2
20604 · #4467: html theme: Rename csss block to css
20606 Deprecated
20608 1.7.0b1
20609 · using a string value for html_sidebars is deprecated and only list
20611 values will be accepted at 2.0.
20612 · format_annotation() and formatargspec() is deprecated. Please use
20614 sphinx.util.inspect.Signature instead.
20615 · sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
20617 tils. switch_source_input() and now deprecated. It will be removed
20618 in Sphinx-2.0.
20619 · sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
20621 now deprecated. Please use app.add_autodocumenter() instead.
20622 · AutoDirective._special_attrgetters is now deprecated. Please use
20624 app.add_autodoc_attrgetter() instead.
20625 Features added
20627 1.7.0b1
20628 · C++, handle decltype(auto).
20630 · #2406: C++, add proper parsing of expressions, including linking of
20632 identifiers.
20633 · C++, add a cpp:expr role for inserting inline C++ expressions or
20635 types.
20636 · C++, support explicit member instantiations with shorthand template
20638 prefix
20639 · C++, make function parameters linkable, like template params.
20641 · #3638: Allow to change a label of reference to equation using
20643 math_eqref_format
20644 · Now suppress_warnings accepts following configurations:
20646 · ref.python (ref: #3866)
20648 · #3872: Add latex key to configure literal blocks caption position in
20650 PDF output (refs #3792, #1723)
20651 · In case of missing docstring try to retrieve doc from base classes
20653 (ref: #3140)
20654 · #4023: Clarify error message when any role has more than one target.
20656 · #3973: epub: allow to override build date
20658 · #3972: epub: Sort manifest entries by filename
20660 · #4052: viewcode: Sort before highlighting module code
20662 · #1448: qthelp: Add new config value; qthelp_namespace
20664 · #4140: html themes: Make body tag inheritable
20666 · #4168: improve zh search with jieba
20668 · HTML themes can set up default sidebars through theme.conf
20670 · #3160: html: Use <kdb> to represent :kbd: role
20672 · #4212: autosummary: catch all exceptions when importing modules
20674 · #4166: Add math_numfig for equation numbering by section (refs:
20676 #3991, #4080). Thanks to Oliver Jahn.
20677 · #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
20679 code-blocks
20680 · #947: autodoc now supports ignore-module-all to ignore a module’s
20682 __all__
20683 · #4332: Let LaTeX obey math_numfig for equation numbering
20685 · #4093: sphinx-build creates empty directories for unknown tar‐
20687 gets/builders
20688 · Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
20690 sion to limit the scope of inheritance graphs.
20691 · #4183: doctest: :pyversion: option also follows PEP-440 specification
20693 · #4235: html: Add manpages_url to make manpage roles to hyperlinks
20695 · #3570: autodoc: Do not display ‘typing.’ module for type hints
20697 · #4354: sphinx-build now emits finish message. Builders can modify it
20699 through Builder.epilog attribute
20700 · #4245: html themes: Add language to javascript vars list
20702 · #4079: html: Add notranslate class to each code-blocks, literals and
20704 maths to let Google Translate know they are not translatable
20705 · #4137: doctest: doctest block is always highlighted as python console
20707 (pycon)
20708 · #4137: doctest: testcode block is always highlighted as python
20710 · #3998: text: Assign section numbers by default. You can control it
20712 using text_add_secnumbers and text_secnumber_suffix
20713 1.7.0b2
20715 · #4271: sphinx-build supports an option called -j auto to adjust num‐
20717 bers of processes automatically.
20718 · Napoleon: added option to specify custom section tags.
20720 Features removed
20722 1.7.0b1
20723 · Configuration variables
20725 · html_use_smartypants
20727 · latex_keep_old_macro_names
20729 · latex_elements[‘footer’]
20731 · utility methods of sphinx.application.Sphinx class
20733 · buildername (property)
20735 · _display_chunk()
20737 · old_status_iterator()
20739 · status_iterator()
20741 · _directive_helper()
20743 · utility methods of sphinx.environment.BuildEnvironment class
20745 · currmodule (property)
20747 · currclass (property)
20749 · epub2 builder
20751 · prefix and colorfunc parameter for warn()
20753 · sphinx.util.compat module
20755 · sphinx.util.nodes.process_only_nodes()
20757 · LaTeX environment notice, use sphinxadmonition instead
20759 · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
20761 · C++, support of function concepts. Thanks to mickk-on-cpp.
20763 · Not used and previously not documented LaTeX macros \shortversion and
20765 \setshortversion
20766 Bugs fixed
20768 1.7.0b1
20769 · #3882: Update the order of files for HTMLHelp and QTHelp
20771 · #3962: sphinx-apidoc does not recognize implicit namespace packages
20773 correctly
20774 · #4094: C++, allow empty template argument lists.
20776 · C++, also hyperlink types in the name of declarations with qualified
20778 names.
20779 · C++, do not add index entries for declarations inside concepts.
20781 · C++, support the template disambiguator for dependent names.
20783 · #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
20785 from the one of figures and tables
20786 · #4330: PDF ‘howto’ documents have an incoherent default LaTeX
20788 tocdepth counter setting
20789 · #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
20791 Thanks to Joel Nothman.
20792 · #4081: Warnings and errors colored the same when building
20794 · latex: Do not display ‘Release’ label if release is not set
20796 1.7.0b2
20798 · #4415: autodoc classifies inherited classmethods as regular methods
20800 · #4415: autodoc classifies inherited staticmethods as regular methods
20802 · #4472: DOCUMENTATION_OPTIONS is not defined
20804 · #4491: autodoc: prefer _MockImporter over other importers in
20806 sys.meta_path
20807 · #4490: autodoc: type annotation is broken with python 3.7.0a4+
20809 · utils package is no longer installed
20811 · #3952: apidoc: module header is too escaped
20813 · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
20815 · #4493: recommonmark raises AttributeError if AutoStructify enabled
20817 · #4209: intersphinx: In link title, “v” should be optional if target
20819 has no version
20820 · #4230: slowdown in writing pages with sphinx 1.6
20822 · #4522: epub: document is not rebuilt even if config changed
20824 1.7.0b3
20826 · #4019: inheritance_diagram AttributeError stopping make process
20828 · #4531: autosummary: methods are not treated as attributes
20830 · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
20832 · #4539: autodoc emits warnings for partialmethods
20834 · #4223: doctest: failing tests reported in wrong file, at wrong line
20836 · i18n: message catalogs are not compiled if specific filenames are
20838 given for sphinx-build as arguments (refs: #4560)
20839 · #4027: sphinx.ext.autosectionlabel now expects labels to be the same
20841 as they are in the raw source; no smart quotes, nothig fancy.
20842 · #4581: apidoc: Excluded modules still included
20844 Testing
20846 1.7.0b1
20847 · Add support for docutils 0.14
20849 · Add tests for the sphinx.ext.inheritance_diagram extension.
20851 Release 1.6.7 (released Feb 04, 2018)
20853 Bugs fixed
20854 · #1922: html search: Upper characters problem in French
20855 · #4412: Updated jQuery version from 3.1.0 to 3.2.1
20857 · #4438: math: math with labels with whitespace cause html error
20859 · #2437: make full reference for classes, aliased with “alias of”
20861 · #4434: pure numbers as link targets produce warning
20863 · #4477: Build fails after building specific files
20865 · #4449: apidoc: include “empty” packages that contain modules
20867 · #3917: citation labels are transformed to ellipsis
20869 · #4501: graphviz: epub3 validation error caused if graph is not click‐
20871 able
20872 · #4514: graphviz: workaround for wrong map ID which graphviz generates
20874 · #4525: autosectionlabel does not support parallel build
20876 · #3953: Do not raise warning when there is a working intersphinx
20878 inventory
20879 · #4487: math: ValueError is raised on parallel build. Thanks to
20881 jschueller.
20882 · #2372: autosummary: invalid signatures are shown for type annotated
20884 functions
20885 · #3942: html: table is not aligned to center even if :align: center
20887 Release 1.6.6 (released Jan 08, 2018)
20889 Features added
20890 · #4181: autodoc: Sort dictionary keys when possible
20891 · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
20893 · Easier customizability of LaTeX macros involved in rendering of
20895 code-blocks
20896 · Show traceback if conf.py raises an exception (refs: #4369)
20898 · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
20900 · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
20902 Bugs fixed
20904 · #4334: sphinx-apidoc: Don’t generate references to non-existing files
20905 in TOC
20906 · #4206: latex: reST label between paragraphs loses paragraph break
20908 · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
20910 · #4221: napoleon depends on autodoc, but users need to load it manu‐
20912 ally
20913 · #2298: automodule fails to document a class attribute
20915 · #4099: C++: properly link class reference to class from inside con‐
20917 structor
20918 · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
20920 · #4249: PDF output: Pygments error highlighting increases line spacing
20922 in code blocks
20923 · #1238: Support :emphasize-lines: in PDF output
20925 · #4279: Sphinx crashes with pickling error when run with multiple pro‐
20927 cesses and remote image
20928 · #1421: Respect the quiet flag in sphinx-quickstart
20930 · #4281: Race conditions when creating output directory
20932 · #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
20934 generates \chapter commands
20935 · #4214: Two todolist directives break sphinx-1.6.5
20937 · Fix links to external option docs with intersphinx (refs: #3769)
20939 · #4091: Private members not documented without :undoc-members:
20941 Release 1.6.5 (released Oct 23, 2017)
20943 Features added
20944 · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
20945 · #4112: Don’t override the smart_quotes setting if it was already set
20947 · #4125: Display reference texts of original and translated passages on
20949 i18n warning message
20950 · #4147: Include the exception when logging PO/MO file read/write
20952 Bugs fixed
20954 · #4085: Failed PDF build from image in parsed-literal using :align:
20955 option
20956 · #4100: Remove debug print from autodoc extension
20958 · #3987: Changing theme from alabaster causes HTML build to fail
20960 · #4096: C++, don’t crash when using the wrong role type. Thanks to
20962 mitya57.
20963 · #4070, #4111: crashes when the warning message contains format
20965 strings (again)
20966 · #4108: Search word highlighting breaks SVG images
20968 · #3692: Unable to build HTML if writing .buildinfo failed
20970 · #4152: HTML writer crashes if a field list is placed on top of the
20972 document
20973 · #4063: Sphinx crashes when labeling directive .. todolist::
20975 · #4134: [doc] docutils.conf is not documented explicitly
20977 · #4169: Chinese language doesn’t trigger Chinese search automatically
20979 · #1020: ext.todo todolist not linking to the page in pdflatex
20981 · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
20983 · #3739: :module: option is ignored at content of pyobjects
20985 · #4149: Documentation: Help choosing latex_engine
20987 · #4090: [doc] latex_additional_files with extra LaTeX macros should
20989 not use .tex extension
20990 · Failed to convert reST parser error to warning (refs: #4132)
20992 Release 1.6.4 (released Sep 26, 2017)
20994 Features added
20995 · #3926: Add autodoc_warningiserror to suppress the behavior of -W
20996 option during importing target modules on autodoc
20997 Bugs fixed
20999 · #3924: docname lost after dynamically parsing RST in extension
21000 · #3946: Typo in sphinx.sty (this was a bug with no effect in default
21002 context)
21003 ·
21005 pep and :rfc: does not supports default-role directive (refs:
21007 #3960)
21008 · #3960: default_role = ‘guilabel’ not functioning
21010 · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
21012 dows.
21013 · #4026: nature: Fix macOS Safari scrollbar color
21015 · #3877: Fix for C++ multiline signatures.
21017 · #4006: Fix crash on parallel build
21019 · #3969: private instance attributes causes AttributeError
21021 · #4041: C++, remove extra name linking in function pointers.
21023 · #4038: C, add missing documentation of member role.
21025 · #4044: An empty multicolumn cell causes extra row height in PDF out‐
21027 put
21028 · #4049: Fix typo in output of sphinx-build -h
21030 · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
21032 · Avoid indent after index entries in latex (refs: #4066)
21034 · #4070: crashes when the warning message contains format strings
21036 · #4067: Return non-zero exit status when make subprocess fails
21038 · #4055: graphviz: the :align: option does not work for SVG output
21040 · #4055: graphviz: the :align: center option does not work for latex
21042 output
21043 · #4051: warn() function for HTML theme outputs ‘None’ string
21045 Release 1.6.3 (released Jul 02, 2017)
21047 Features added
21048 · latex: hint that code-block continues on next page (refs: #3764,
21049 #3792)
21050 Bugs fixed
21052 · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
21053 · #3829: sphinx-quickstart template is incomplete regarding use of
21055 alabaster
21056 · #3772: ‘str object’ has no attribute ‘filename’
21058 · Emit wrong warnings if citation label includes hyphens (refs: #3565)
21060 · #3858: Some warnings are not colored when using –color option
21062 · #3775: Remove unwanted whitespace in default template
21064 · #3835: sphinx.ext.imgmath fails to convert SVG images if project
21066 directory name contains spaces
21067 · #3850: Fix color handling in make mode’s help command
21069 · #3865: use of self.env.warn in sphinx extension fails
21071 · #3824: production lists apply smart quotes transform since Sphinx
21073 1.6.1
21074 · latex: fix \sphinxbfcode swallows initial space of argument
21076 · #3878: Quotes in auto-documented class attributes should be straight
21078 quotes in PDF output
21079 · #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
21081 tical whitespace
21082 · #3885: duplicated footnotes raises IndexError
21084 · #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
21086 pat.Directive
21087 · #3874: Bogus warnings for “citation not referenced” for cross-file
21089 citations
21090 · #3860: Don’t download images when builders not supported images
21092 · #3860: Remote image URIs without filename break builders not sup‐
21094 ported remote images
21095 · #3833: command line messages are translated unintentionally with lan‐
21097 guage setting.
21098 · #3840: make checking epub_uid strict
21100 · #3851, #3706: Fix about box drawing characters for PDF output
21102 · #3900: autosummary could not find methods
21104 · #3902: Emit error if latex_documents contains non-unicode string in
21106 py2
21107 Release 1.6.2 (released May 28, 2017)
21109 Incompatible changes
21110 · #3789: Do not require typing module for python>=3.5
21111 Bugs fixed
21113 · #3754: HTML builder crashes if HTML theme appends own stylesheets
21114 · #3756: epub: Entity ‘mdash’ not defined
21116 · #3758: Sphinx crashed if logs are emitted in conf.py
21118 · #3755: incorrectly warns about dedent with literalinclude
21120 · #3742: RTD PDF builds of Sphinx own docs are missing an index entry
21122 in the bookmarks and table of contents. This is
21123 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
21124 extra LaTeX code in Sphinx’s own conf.py
21125 · #3770: Build fails when a “code-block” has the option emphasize-lines
21127 and the number indicated is higher than the number of lines
21128 · #3774: Incremental HTML building broken when using citations
21130 · #3763: got epubcheck validations error if epub_cover is set
21132 · #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
21134 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
21135 · #3796: env.resolve_references() crashes when non-document node given
21137 · #3803: Sphinx crashes with invalid PO files
21139 · #3791: PDF “continued on next page” for long tables isn’t interna‐
21141 tionalized
21142 · #3788: smartquotes emits warnings for unsupported languages
21144 · #3807: latex Makefile for make latexpdf is only for unixen
21146 · #3781: double hyphens in option directive are compiled as endashes
21148 · #3817: latex builder raises AttributeError
21150 Release 1.6.1 (released May 16, 2017)
21152 Dependencies
21153 1.6b1
21154 · (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
21156 ages (Feb. 2014) and earlier tex installations may not be fully com‐
21157 pliant, particularly regarding Unicode engines xelatex and lualatex
21158 · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
21160 X (refs: #3082)
21161 Incompatible changes
21163 1.6b1
21164 · #1061, #2336, #3235: Now generation of autosummary doesn’t contain
21166 imported members by default. Thanks to Luc Saffre.
21167 · LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
21169 graphics has the custom code to fit image to available width if over‐
21170 sized.
21171 · The subclasses of sphinx.domains.Index should override generate()
21173 method. The default implementation raises NotImplementedError
21174 · LaTeX positioned long tables horizontally centered, and short ones
21176 flushed left (no text flow around table.) The position now defaults
21177 to center in both cases, and it will obey Docutils 0.13 :align:
21178 option (refs #3415, #3377)
21179 · option directive also allows all punctuations for the option name
21181 (refs: #3366)
21182 · #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
21184 tive (refs #3412)
21185 · literalinclude directive does not allow the combination of :diff:
21187 option and other options (refs: #3416)
21188 · LuaLaTeX engine uses fontspec like XeLaTeX. It is advised
21190 latex_engine = 'lualatex' be used only on up-to-date TeX installs
21191 (refs #3070, #3466)
21192 · latex_keep_old_macro_names default value has been changed from True
21194 to False. This means that some LaTeX macros for styling are by
21195 default defined only with \sphinx.. prefixed names. (refs: #3429)
21196 · Footer “Continued on next page” of LaTeX longtable’s now not framed
21198 (refs: #3497)
21199 · #3529: The arguments of BuildEnvironment.__init__ is changed
21201 · #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
21203 only)
21204 · #3558: Emit warnings if footnotes and citations are not referenced.
21206 The warnings can be suppressed by suppress_warnings.
21207 · latex made available (non documented) colour macros from a file dis‐
21209 tributed with pdftex engine for Plain TeX. This is removed in order
21210 to provide better support for multiple TeX engines. Only interface
21211 from color or xcolor packages should be used by extensions of Sphinx
21212 latex writer. (refs #3550)
21213 · Builder.env is not filled at instantiation
21215 · #3594: LaTeX: single raw directive has been considered as block level
21217 element
21218 · #3639: If html_experimental_html5_writer is available, epub builder
21220 use it by default.
21221 · Sphinx.add_source_parser() raises an error if duplicated
21223 1.6b2
21225 · #3345: Replace the custom smartypants code with Docutils’
21227 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at
21228 Docutils.
21229 1.6b3
21231 · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
21233 · LaTeX package multirow is not used and not loaded by Sphinx anymore
21235 · Add line numbers to citation data in std domain
21237 1.6 final
21239 · LaTeX package threeparttable is not used and not loaded by Sphinx
21241 anymore (refs #3686, #3532, #3377)
21242 Features removed
21244 · Configuration variables
21245 · epub3_contributor
21247 · epub3_description
21249 · epub3_page_progression_direction
21251 · html_translator_class
21253 · html_use_modindex
21255 · latex_font_size
21257 · latex_paper_size
21259 · latex_preamble
21261 · latex_use_modindex
21263 · latex_use_parts
21265 · termsep node
21267 · defindex.html template
21269 · LDML format support in today, today_fmt and html_last_updated_fmt
21271 · :inline: option for the directives of sphinx.ext.graphviz extension
21273 · sphinx.ext.pngmath extension
21275 · sphinx.util.compat.make_admonition()
21277 Features added
21279 1.6b1
21280 · #3136: Add :name: option to the directives in sphinx.ext.graphviz
21282 · #2336: Add imported_members option to sphinx-autogen command to docu‐
21284 ment imported members.
21285 · C++, add :tparam-line-spec: option to templated declarations. When
21287 specified, each template parameter will be rendered on a separate
21288 line.
21289 · #3359: Allow sphinx.js in a user locale dir to override sphinx.js
21291 from Sphinx
21292 · #3303: Add :pyversion: option to the doctest directive.
21294 · #3378: (latex) support for :widths: option of table directives (refs:
21296 #3379, #3381)
21297 · #3402: Allow to suppress “download file not readable” warnings using
21299 suppress_warnings.
21300 · #3377: latex: Add support for Docutils 0.13 :align: option for tables
21302 (but does not implement text flow around table).
21303 · latex: footnotes from inside tables are hyperlinked (except from cap‐
21305 tions or headers) (refs: #3422)
21306 · Emit warning if over dedent has detected on literalinclude directive
21308 (refs: #3416)
21309 · Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
21311 and polyglossia). (refs: #3070, #3466)
21312 · Make 'extraclassoptions' key of latex_elements public (refs #3480)
21314 · #3463: Add warning messages for required EPUB3 metadata. Add default
21316 value to epub_description to avoid warning like other settings.
21317 · #3476: setuptools: Support multiple builders
21319 · latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
21321 quotes… as do normal cells (refs: #3435)
21322 · HTML builder uses experimental HTML5 writer if html_experimen‐
21324 tal_html5_writer is True and docutils 0.13 or later is installed.
21325 · LaTeX macros to customize space before and after tables in PDF output
21327 (refs #3504)
21328 · #3348: Show decorators in literalinclude and viewcode directives
21330 · #3108: Show warning if :start-at: and other literalinclude options
21332 does not match to the text
21333 · #3609: Allow to suppress “duplicate citation” warnings using sup‐
21335 press_warnings
21336 · #2803: Discovery of builders by entry point
21338 · #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
21340 stylesheets
21341 · #3589: Support remote images on non-HTML builders
21343 · #3589: Support images in Data URI on non-HTML builders
21345 · #2961: improve autodoc_mock_imports. Now the config value only
21347 requires to declare the top-level modules that should be mocked.
21348 Thanks to Robin Jarry.
21349 · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
21351 ture calculation. Thanks to Nathaniel J. Smith.
21352 · #3641: Epub theme supports HTML structures that are generated by
21354 HTML5 writer.
21355 · #3644 autodoc uses inspect instead of checking types. Thanks to
21357 Jeroen Demeyer.
21358 · Add a new extension; sphinx.ext.imgconverter. It converts images in
21360 the document to appropriate format for builders
21361 · latex: Use templates to render tables (refs #3389, 2a37b0e)
21363 1.6b2
21365 · LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass
21367 options to latexmk when executing make latexpdf (refs #3695, #3720)
21368 · Add a new event env-check-consistency to check consistency to exten‐
21370 sions
21371 · Add Domain.check_consistency() to check consistency
21373 Bugs fixed
21375 1.6b1
21376 · literalinclude directive expands tabs after dedent-ing (refs: #3416)
21378 · #1574: Paragraphs in table cell doesn’t work in Latex output
21380 · #3288: Table with merged headers not wrapping text
21382 · #3491: Inconsistent vertical space around table and longtable in PDF
21384 · #3506: Depart functions for all admonitions in HTML writer now prop‐
21386 erly pass node to depart_admonition.
21387 · #2693: Sphinx latex style file wrongly inhibits colours for section
21389 headings for latex+dvi(ps,pdf,pdfmx)
21390 · C++, properly look up any references.
21392 · #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
21394 with gzip
21395 · #3551: PDF information dictionary is lacking author and title data
21397 · #3351: intersphinx does not refers context like py:module, py:class
21399 and so on.
21400 · Fail to load template file if the parent template is archived
21402 1.6b2
21404 · #3661: sphinx-build crashes on parallel build
21406 · #3669: gettext builder fails with “ValueError: substring not found”
21408 · #3660: Sphinx always depends on sphinxcontrib-websupport and its
21410 dependencies
21411 · #3472: smart quotes getting wrong in latex (at least with list of
21413 strings via autoattribute) (refs: #3345, #3666)
21414 1.6b3
21416 · #3588: No compact (p tag) html output in the i18n document build even
21418 when html_compact_lists is True.
21419 · The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using
21421 latexmk) aborted earlier in case of LaTeX errors than was the case
21422 with 1.5 series, due to hard-coded usage of --halt-on-error option
21423 (refs #3695)
21424 · #3683: sphinx.websupport module is not provided by default
21426 · #3683: Failed to build document if builder.css_file.insert() is
21428 called
21429 · #3714: viewcode extension not taking highlight_code='none' in account
21431 · #3698: Moving :doc: to std domain broke backwards compatibility
21433 · #3633: misdetect unreferenced citations
21435 1.6 final
21437 · LaTeX tables do not allow multiple paragraphs in a header cell
21439 · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
21441 · #3532: Figure or literal block captions in cells of short tables
21443 cause havoc in PDF output
21444 · Fix: in PDF captions of tables are rendered differently whether table
21446 is of longtable class or not (refs #3686)
21447 · #3725: Todo looks different from note in LaTeX output
21449 · #3479: stub-columns have no effect in LaTeX output
21451 · #3738: Nonsensical code in theming.py
21453 · #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
21455 options -pdfxe and -pdflua
21456 Deprecated
21458 1.6b1
21459 · sphinx.util.compat.Directive class is now deprecated. Please use
21461 instead docutils.parsers.rst.Directive
21462 · sphinx.util.compat.docutils_version is now deprecated
21464 · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
21466 deprecated. Please use sphinx.util.logging (logging-api) instead.
21467 · #3318: notice is now deprecated as LaTeX environment name and will be
21469 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
21470 instead (as Sphinx does since 1.5.)
21471 · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
21473 recated. Please use sphinx.util:status_iterator() instead.
21474 · Sphinx._directive_helper() is deprecated. Please use
21476 sphinx.util.docutils.directive_helper() instead.
21477 · BuildEnvironment.set_warnfunc() is now deprecated
21479 · Following methods of BuildEnvironment is now deprecated.
21481 · BuildEnvironment.note_toctree()
21483 · BuildEnvironment.get_toc_for()
21485 · BuildEnvironment.get_toctree_for()
21487 · BuildEnvironment.create_index()
21489 Please use sphinx.environment.adapters modules instead.
21491 · latex package footnote is not loaded anymore by its bundled replace‐
21493 ment footnotehyper-sphinx. The redefined macros keep the same names
21494 as in the original package.
21495 · #3429: deprecate config setting latex_keep_old_macro_names. It will
21497 be removed at 1.7, and already its default value has changed from
21498 True to False.
21499 · #3221: epub2 builder is deprecated
21501 · #3254: sphinx.websupport is now separated into independent package;
21503 sphinxcontrib-websupport. sphinx.websupport will be removed in
21504 Sphinx-2.0.
21505 · #3628: sphinx_themes entry_point is deprecated. Please use
21507 sphinx.html_themes instead.
21508 1.6b2
21510 · #3662: builder.css_files is deprecated. Please use add_stylesheet()
21512 API instead.
21513 1.6 final
21515 · LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
21517 1.7. Please move customization into new macro \sphinxstyletheadfam‐
21518 ily.
21519 Testing
21521 1.6 final
21522 · #3458: Add sphinx.testing (experimental)
21524 Release 1.6 (unreleased)
21526 · not released (because of package script error)
21527 Release 1.5.6 (released May 15, 2017)
21529 Bugs fixed
21530 · #3614: Sphinx crashes with requests-2.5.0
21531 · #3618: autodoc crashes with tupled arguments
21533 · #3664: No space after the bullet in items of a latex list produced by
21535 Sphinx
21536 · #3657: EPUB builder crashes if a document starting with genindex
21538 exists
21539 · #3588: No compact (p tag) html output in the i18n document build even
21541 when html_compact_lists is True.
21542 · #3685: AttributeError when using 3rd party domains
21544 · #3702: LaTeX writer styles figure legends with a hard-coded \small
21546 · #3708: LaTeX writer allows irc scheme
21548 · #3717: Stop enforcing that favicon’s must be .ico
21550 · #3731, #3732: Protect isenumclass predicate against non-class argu‐
21552 ments
21553 · #3320: Warning about reference target not being found for container
21555 types
21556 · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
21558 Release 1.5.5 (released Apr 03, 2017)
21560 Bugs fixed
21561 · #3597: python domain raises UnboundLocalError if invalid name given
21562 · #3599: Move to new MathJax CDN
21564 Release 1.5.4 (released Apr 02, 2017)
21566 Features added
21567 · #3470: Make genindex support all kinds of letters, not only Latin
21568 ones
21569 Bugs fixed
21571 · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
21572 to failed PDF build
21573 · EPUB file has duplicated nav.xhtml link in content.opf except first
21575 time build
21576 · #3488: objects.inv has broken when release or version contain return
21578 code
21579 · #2073, #3443, #3490: gettext builder that writes pot files unless the
21581 content are same without creation date. Thanks to Yoshiki Shibukawa.
21582 · #3487: intersphinx: failed to refer options
21584 · #3496: latex longtable’s last column may be much wider than its con‐
21586 tents
21587 · #3507: wrong quotes in latex output for productionlist directive
21589 · #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
21591 links rendered as code
21592 · #2665, #2607: Link names in C++ docfields, and make it possible for
21594 other domains.
21595 · #3542: C++, fix parsing error of non-type template argument with tem‐
21597 plate.
21598 · #3065, #3520: python domain fails to recognize nested class
21600 · #3575: Problems with pdflatex in a Turkish document built with sphinx
21602 has reappeared (refs #2997, #2397)
21603 · #3577: Fix intersphinx debug tool
21605 · A LaTeX command such as \\large inserted in the title items of
21607 latex_documents causes failed PDF build (refs #3551, #3567)
21608 Release 1.5.3 (released Feb 26, 2017)
21610 Features added
21611 · Support requests-2.0.0 (experimental) (refs: #3367)
21612 · (latex) PDF page margin dimensions may be customized (refs: #3387)
21614 · literalinclude directive allows combination of :pyobject: and :lines:
21616 options (refs: #3416)
21617 · #3400: make-mode doesn’t use subprocess on building docs
21619 Bugs fixed
21621 · #3370: the caption of code-block is not picked up for translation
21622 · LaTeX: release is not escaped (refs: #3362)
21624 · #3364: sphinx-quickstart prompts overflow on Console with 80 chars
21626 width
21627 · since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
21629 (refs: #3383)
21630 · #3392: 'releasename' in latex_elements is not working
21632 · #3356: Page layout for Japanese 'manual' docclass has a shorter text
21634 area
21635 · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
21637 wrong PDF page dimensions
21638 · #3399: quickstart: conf.py was not overwritten by template
21640 · #3366: option directive does not allow punctuations
21642 · #3410: return code in release breaks html search
21644 · #3427: autodoc: memory addresses are not stripped on Windows
21646 · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
21648 · #3349: Result of IndexBuilder.load() is broken
21650 · #3450:   is appeared in EPUB docs
21652 · #3418: Search button is misaligned in nature and pyramid theme
21654 · #3421: Could not translate a caption of tables
21656 · #3552: linkcheck raises UnboundLocalError
21658 Release 1.5.2 (released Jan 22, 2017)
21660 Incompatible changes
21661 · Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
21662 #3310)
21663 Features added
21665 · #3241: emit latex warning if buggy titlesec (ref #3210)
21666 · #3194: Refer the $MAKE environment variable to determine make command
21668 · Emit warning for nested numbered toctrees (refs: #3142)
21670 · #978: intersphinx_mapping also allows a list as a parameter
21672 · #3340: (LaTeX) long lines in parsed-literal are wrapped like in
21674 code-block, inline math and footnotes are fully functional.
21675 Bugs fixed
21677 · #3246: xapian search adapter crashes
21678 · #3253: In Py2 environment, building another locale with a non-cap‐
21680 tioned toctree produces None captions
21681 · #185: References to section title including raw node has broken
21683 · #3255: In Py3.4 environment, autodoc doesn’t support documentation
21685 for attributes of Enum class correctly.
21686 · #3261: latex_use_parts makes sphinx crash
21688 · The warning type misc.highlighting_failure does not work
21690 · #3294: add_latex_package() make crashes non-LaTeX builders
21692 · The caption of table are rendered as invalid HTML (refs: #3287)
21694 · #3268: Sphinx crashes with requests package from Debian jessie
21696 · #3284: Sphinx crashes on parallel build with an extension which
21698 raises unserializable exception
21699 · #3315: Bibliography crashes on latex build with docclass ‘memoir’
21701 · #3328: Could not refer rubric implicitly
21703 · #3329: emit warnings if po file is invalid and can’t read it. Also
21705 writing mo
21706 · #3337: Ugly rendering of definition list term’s classifier
21708 · #3335: gettext does not extract field_name of a field in a field_list
21710 · #2952: C++, fix refs to operator() functions.
21712 · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
21714 eral LaTeX output (ref #3342)
21715 · LaTeX writer: leave " character inside parsed-literal as is (ref
21717 #3341)
21718 · #3234: intersphinx failed for encoded inventories
21720 · #3158: too much space after captions in PDF output
21722 · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
21724 if with hyphen
21725 · LaTeX crash if the filename of an image inserted in parsed-literal
21727 via a substitution contains an hyphen (ref #3340)
21728 · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
21730 #3340)
21731 · Inline math in parsed-literal is not rendered well by LaTeX (ref
21733 #3340)
21734 · #3308: Parsed-literals don’t wrap very long lines with pdf builder
21736 (ref #3340)
21737 · #3295: Could not import extension sphinx.builders.linkcheck
21739 · #3285: autosummary: asterisks are escaped twice
21741 · LaTeX, pass dvipdfm option to geometry package for Japanese documents
21743 (ref #3363)
21744 · Fix parselinenos() could not parse left half open range (cf. “-4”)
21746 Release 1.5.1 (released Dec 13, 2016)
21748 Features added
21749 · #3214: Allow to suppress “unknown mimetype” warnings from epub
21750 builder using suppress_warnings.
21751 Bugs fixed
21753 · #3195: Can not build in parallel
21754 · #3198: AttributeError is raised when toctree has ‘self’
21756 · #3211: Remove untranslated sphinx locale catalogs (it was covered by
21758 untranslated it_IT)
21759 · #3212: HTML Builders crashes with docutils-0.13
21761 · #3207: more latex problems with references inside parsed-literal
21763 directive (\DUrole)
21764 · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
21766 · #3220: KeyError when having a duplicate citation
21768 · #3200: LaTeX: xref inside desc_name not allowed
21770 · #3228: build_sphinx command crashes when missing dependency
21772 · #2469: Ignore updates of catalog files for gettext builder. Thanks to
21774 Hiroshi Ohkubo.
21775 · #3183: Randomized jump box order in generated index page.
21777 Release 1.5 (released Dec 5, 2016)
21779 Incompatible changes
21780 1.5a1
21781 · latex, package fancybox is not any longer a dependency of sphinx.sty
21783 · Use 'locales' as a default value of locale_dirs
21785 · latex, package ifthen is not any longer a dependency of sphinx.sty
21787 · latex, style file does not modify fancyvrb’s Verbatim (also available
21789 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
21790 per.
21791 · latex, package newfloat is not used (and not included) anymore (ref
21793 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
21794 · latex, literal blocks in tables do not use OriginalVerbatim but
21796 sphinxVerbatimintable which handles captions and wraps lines (ref
21797 #2704).
21798 · latex, replace pt by TeX equivalent bp if found in width or height
21800 attribute of an image.
21801 · latex, if width or height attribute of an image is given with no
21803 unit, use px rather than ignore it.
21804 · latex: Separate stylesheets of pygments to independent .sty file
21806 · #2454: The filename of sourcelink is now changed. The value of
21808 html_sourcelink_suffix will be appended to the original filename
21809 (like index.rst.txt).
21810 · sphinx.util.copy_static_entry() is now deprecated. Use
21812 sphinx.util.fileutil.copy_asset() instead.
21813 · sphinx.util.osutil.filecopy() skips copying if the file has not been
21815 changed (ref: #2510, #2753)
21816 · Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
21818 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
21819 #2773)
21820 · QtHelpBuilder doesn’t generate search page (ref: #2352)
21822 · QtHelpBuilder uses nonav theme instead of default one to improve
21824 readability.
21825 · latex: To provide good default settings to Japanese documents, Sphinx
21827 uses jreport and jsbook as docclass if language is ja.
21828 · sphinx-quickstart now allows a project version is empty
21830 · Fix :download: role on epub/qthelp builder. They ignore the role
21832 because they don’t support it.
21833 · sphinx.ext.viewcode doesn’t work on epub building by default. view‐
21835 code_enable_epub option
21836 · sphinx.ext.viewcode disabled on singlehtml builder.
21838 · Use make-mode of sphinx-quickstart by default. To disable this, use
21840 -M option
21841 · Fix genindex.html, Sphinx’s document template, link address to itself
21843 to satisfy xhtml standard.
21844 · Use epub3 builder by default. And the old epub builder is renamed to
21846 epub2.
21847 · Fix epub and epub3 builders that contained links to genindex even if
21849 epub_use_index = False.
21850 · html_translator_class is now deprecated. Use Sphinx.set_translator()
21852 API instead.
21853 · Drop python 2.6 and 3.3 support
21855 · Drop epub3 builder’s epub3_page_progression_direction option (use
21857 epub3_writing_mode).
21858 · #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
21860 body']
21861 1.5a2
21863 · #2983: Rename epub3_description and epub3_contributor to
21865 epub_description and epub_contributor.
21866 · Remove themes/basic/defindex.html; no longer used
21868 · Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
21870 chap
21871 · #2435: Slim down quickstarted conf.py
21873 · The sphinx.sty latex package does not load itself “hyperref”, as this
21875 is done later in the preamble of the latex output via 'hyperref' key.
21876 · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
21878 lary. The non-modified package is used.
21879 · #3057: By default, footnote marks in latex PDF output are not pre‐
21881 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
21882 tomization if needed.
21883 · LaTeX target requires that option hyperfootnotes of package hyperref
21885 be left unchanged to its default (i.e. true) (refs: #3022)
21886 1.5 final
21888 · #2986: themes/basic/defindex.html is now deprecated
21890 · Emit warnings that will be deprecated in Sphinx 1.6 by default.
21892 Users can change the behavior by setting the environment variable
21893 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
21894 · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
21896 Deprecated
21898 These features are removed in Sphinx-1.6:
21899 · LDML format support in i18n feature
21901 · sphinx.addnodes.termsep
21903 · Some functions and classes in sphinx.util.pycompat: zip_longest,
21905 product, all, any, next, open, class_types, base_exception, relpath,
21906 StringIO, BytesIO. Please use the standard library version instead;
21907 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
21909 played, please refer when-deprecation-warnings-are-displayed.
21910 Features added
21912 1.5a1
21913 · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
21915 · Add :caption: option for sphinx.ext.inheritance_diagram.
21917 · #2471: Add config variable for default doctest flags.
21919 · Convert linkcheck builder to requests for better encoding handling
21921 · #2463, #2516: Add keywords of “meta” directive to search index
21923 · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
21925 · #2575: Now sphinx.ext.graphviz allows :align: option
21927 · Show warnings if unknown key is specified to latex_elements
21929 · Show warnings if no domains match with primary_domain (ref: #2001)
21931 · C++, show warnings when the kind of role is misleading for the kind
21933 of target it refers to (e.g., using the class role for a function).
21934 · latex, writer abstracts more of text styling into customizable
21936 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
21937 rather than \emph (which may be in use elsewhere or in an added LaTeX
21938 package). See list at end of sphinx.sty (ref: #2686)
21939 · latex, public names for environments and parameters used by note,
21941 warning, and other admonition types, allowing full customizability
21942 from the 'preamble' key or an input file (ref: feature request #2674,
21943 #2685)
21944 · latex, better computes column widths of some tables (as a result,
21946 there will be slight changes as tables now correctly fill the line
21947 width; ref: #2708)
21948 · latex, sphinxVerbatim environment is more easily customizable (ref:
21950 #2704). In addition to already existing VerbatimColor and Verbatim‐
21951 BorderColor:
21952 · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
21954 · booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
21956 slines.
21957 · latex, captions for literal blocks inside tables are handled, and
21959 long code lines wrapped to fit table cell (ref: #2704)
21960 · #2597: Show warning messages as darkred
21962 · latex, allow image dimensions using px unit (default is 96px=1in)
21964 · Show warnings if invalid dimension units found
21966 · #2650: Add --pdb option to setup.py command
21968 · latex, make the use of \small for code listings customizable (ref
21970 #2721)
21971 · #2663: Add --warning-is-error option to setup.py command
21973 · Show warnings if deprecated latex options are used
21975 · Add sphinx.config.ENUM to check the config values is in candidates
21977 · math: Add hyperlink marker to each equations in HTML output
21979 · Add new theme nonav that doesn’t include any navigation links. This
21981 is for any help generator like qthelp.
21982 · #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings
21984 enabled. Also, it emits an additional event named todo-defined to
21985 handle the TODO entries in 3rd party extensions.
21986 · Python domain signature parser now uses the xref mixin for ‘excep‐
21988 tions’, allowing exception classes to be autolinked.
21989 · #2513: Add latex_engine to switch the LaTeX engine by conf.py
21991 · #2682: C++, basic support for attributes (C++11 style and GNU style).
21993 The new configuration variables ‘cpp_id_attributes’ and
21994 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
21995 · #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
21997 removing prefixes from the index text of C++ objects.
21998 · C++, added concept directive. Thanks to mickk-on-cpp.
22000 · C++, added support for template introduction syntax. Thanks to
22002 mickk-on-cpp.
22003 · #2725: latex builder: allow to use user-defined template file (exper‐
22005 imental)
22006 · apidoc now avoids invalidating cached files by not writing to files
22008 whose content doesn’t change. This can lead to significant perfor‐
22009 mance wins if apidoc is run frequently.
22010 · #2851: sphinx.ext.math emits missing-reference event if equation not
22012 found
22013 · #1210: eqref role now supports cross reference
22015 · #2892: Added -a (--append-syspath) option to sphinx-apidoc
22017 · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
22019 · #646: option directive support ‘.’ character as a part of options
22021 · Add document about kindlegen and fix document structure for it.
22023 · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
22025 · #2926: EPUB3 builder supports vertical mode (epub3_writing_mode
22027 option)
22028 · #2695: build_sphinx subcommand for setuptools handles exceptions as
22030 same as sphinx-build does
22031 · #326: numref role can also refer sections
22033 · #2916: numref role can also refer caption as an its linktext
22035 1.5a2
22037 · #3008: linkcheck builder ignores self-signed certificate URL
22039 · #3020: new 'geometry' key to latex_elements whose default uses LaTeX
22041 style file geometry.sty to set page layout
22042 · #2843: Add :start-at: and :end-at: options to literalinclude direc‐
22044 tive
22045 · #2527: Add :reversed: option to toctree directive
22047 · Add -t and -d option to sphinx-quickstart to support templating gen‐
22049 erated sphinx project.
22050 · #3028: Add {path} and {basename} to the format of figure_lan‐
22052 guage_filename
22053 · new 'hyperref' key in the latex_elements dictionary (ref #3030)
22055 · #3022: Allow code-blocks in footnotes for LaTeX PDF output
22057 1.5b1
22059 · #2513: A better default settings for XeLaTeX
22061 · #3096: 'maxlistdepth' key to work around LaTeX list limitations
22063 · #3060: autodoc supports documentation for attributes of Enum class.
22065 Now autodoc render just the value of Enum attributes instead of Enum
22066 attribute representation.
22067 · Add --extensions to sphinx-quickstart to support enable arbitrary
22069 extensions from command line (ref: #2904)
22070 · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
22072 · #3071: Autodoc: Allow mocked module decorators to pass-through func‐
22074 tions unchanged
22075 · #2495: linkcheck: Allow skipping anchor checking using
22077 linkcheck_anchors_ignore
22078 · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
22080 · #3116: allow word wrap in PDF output for inline literals (ref #3110)
22082 · #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
22084 Nick Coghlan.
22085 · #3121: add inlineliteralwraps option to control if inline literal
22087 word-wraps in latex
22088 1.5 final
22090 · #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
22092 servers in linkcheck and intersphinx
22093 · #2215: make.bat generated by sphinx-quickstart can be called from
22095 another dir. Thanks to Timotheus Kampik.
22096 · #3185: Add new warning type misc.highlighting_failure
22098 Bugs fixed
22100 1.5a1
22101 · #2707: (latex) the column width is badly computed for tabular
22103 · #2799: Sphinx installs roles and directives automatically on import‐
22105 ing sphinx module. Now Sphinx installs them on running application.
22106 · sphinx.ext.autodoc crashes if target code imports * from mock modules
22108 by autodoc_mock_imports.
22109 · #1953: Sphinx.add_node does not add handlers the translator installed
22111 by html_translator_class
22112 · #1797: text builder inserts blank line on top
22114 · #2894: quickstart main() doesn’t use argv argument
22116 · #2874: gettext builder could not extract all text under the only
22118 directives
22119 · #2485: autosummary crashes with multiple source_suffix values
22121 · #1734: Could not translate the caption of toctree directive
22123 · Could not translate the content of meta directive (ref: #1734)
22125 · #2550: external links are opened in help viewer
22127 · #2687: Running Sphinx multiple times produces ‘already registered’
22129 warnings
22130 1.5a2
22132 · #2810: Problems with pdflatex in an Italian document
22134 · Use latex_elements.papersize to specify papersize of LaTeX in Make‐
22136 file
22137 · #2988: linkcheck: retry with GET request if denied HEAD request
22139 · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
22141 itly” error if linkcheck_anchors enabled
22142 · #3004: Invalid link types “top” and “up” are used
22144 · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
22146 · #3000: option directive generates invalid HTML anchors
22148 · #2984: Invalid HTML has been generated if html_split_index enabled
22150 · #2986: themes/basic/defindex.html should be changed for html5
22152 friendly
22153 · #2987: Invalid HTML has been generated if multiple IDs are assigned
22155 to a list
22156 · #2891: HTML search does not provide all the results
22158 · #1986: Title in PDF Output
22160 · #147: Problem with latex chapter style
22162 · #3018: LaTeX problem with page layout dimensions and chapter titles
22164 · Fix an issue with \pysigline in LaTeX style file (ref #3023)
22166 · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
22168 · #3031: incompatibility with LaTeX package tocloft
22170 · #3003: literal blocks in footnotes are not supported by Latex
22172 · #3047: spacing before footnote in pdf output is not coherent and
22174 allows breaks
22175 · #3045: HTML search index creator should ignore “raw” content if now
22177 html
22178 · #3039: English stemmer returns wrong word if the word is capitalized
22180 · Fix make-mode Makefile template (ref #3056, #2936)
22182 1.5b1
22184 · #2432: Fix unwanted * between varargs and keyword only args. Thanks
22186 to Alex Grönholm.
22187 · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
22189 panese documents since PR#3030)
22190 · Better rendering of multiline signatures in html.
22192 · #777: LaTeX output “too deeply nested” (ref #3096)
22194 · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
22196 #3059)
22197 · #3019: LaTeX fails on description of C function with arguments (ref
22199 #3083)
22200 · fix latex inline literals where < > - gobbled a space
22202 1.5 final
22204 · #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
22206 tains one \addto\captions...
22207 · #3123: user 'babel' key setting is not obeyed anymore
22209 · #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
22211 Opera
22212 · #3085: keep current directory after breaking build documentation.
22214 Thanks to Timotheus Kampik.
22215 · #3181: pLaTeX crashes with a section contains endash
22217 · #3180: latex: add stretch/shrink between successive singleline or
22219 multipleline cpp signatures (ref #3072)
22220 · #3128: globing images does not support .svgz file
22222 · #3015: fix a broken test on Windows.
22224 · #1843: Fix documentation of descriptor classes that have a custom
22226 metaclass. Thanks to Erik Bray.
22227 · #3190: util.split_docinfo fails to parse multi-line field bodies
22229 · #3024, #3037: In Python3, application.Sphinx._log crushed when the
22231 log message cannot be encoded into console encoding.
22232 Testing
22234 · To simplify, sphinx uses external mock package even if unittest.mock
22235 exists.
22236 Release 1.4.9 (released Nov 23, 2016)
22238 Bugs fixed
22239 · #2936: Fix doc/Makefile that can’t build man because doc/man exists
22240 · #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
22242 directives results in warning / error
22243 · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
22245 · #3074: add_source_parser() crashes in debug mode
22247 · #3135: sphinx.ext.autodoc crashes with plain Callable
22249 · #3150: Fix query word splitter in JavaScript. It behaves as same as
22251 Python’s regular expression.
22252 · #3093: gettext build broken on substituted images.
22254 · #3093: gettext build broken on image node under note directive.
22256 · imgmath: crashes on showing error messages if image generation failed
22258 · #3117: LaTeX writer crashes if admonition is placed before first sec‐
22260 tion title
22261 · #3164: Change search order of sphinx.ext.inheritance_diagram
22263 Release 1.4.8 (released Oct 1, 2016)
22265 Bugs fixed
22266 · #2996: The wheel package of Sphinx got crash with ImportError
22267 Release 1.4.7 (released Oct 1, 2016)
22269 Bugs fixed
22270 · #2890: Quickstart should return an error consistently on all error
22271 conditions
22272 · #2870: flatten genindex columns’ heights.
22274 · #2856: Search on generated HTML site doesn’t find some symbols
22276 · #2882: Fall back to a GET request on 403 status in linkcheck
22278 · #2902: jsdump.loads fails to load search index if keywords starts
22280 with underscore
22281 · #2900: Fix epub content.opf: add auto generated orphan files to
22283 spine.
22284 · #2899: Fix hasdoc() function in Jinja2 template. It will detect
22286 genindex, search also.
22287 · #2901: Fix epub result: skip creating links from image tags to origi‐
22289 nal image files.
22290 · #2917: inline code is hyphenated on HTML
22292 · #1462: autosummary warns for namedtuple with attribute with trailing
22294 underscore
22295 · Could not reference equations if :nowrap: option specified
22297 · #2873: code-block overflow in latex (due to commas)
22299 · #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
22301 relative paths are used in intersphinx_mapping
22302 · #2931: code-block directive with same :caption: causes warning of
22304 duplicate target. Now code-block and literalinclude does not define
22305 hyperlink target using its caption automatically.
22306 · #2962: latex: missing label of longtable
22308 · #2968: autodoc: show-inheritance option breaks docstrings
22310 Release 1.4.6 (released Aug 20, 2016)
22312 Incompatible changes
22313 · #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
22314 six-1.5 or later
22315 Bugs fixed
22317 · applehelp: Sphinx crashes if hiutil or codesign commands not found
22318 · Fix make clean abort issue when build dir contains regular files like
22320 DS_Store.
22321 · Reduce epubcheck warnings/errors:
22323 · Fix DOCTYPE to html5
22325 · Change extension from .html to .xhtml.
22327 · Disable search page on epub results
22329 · #2778: Fix autodoc crashes if obj.__dict__ is a property method and
22331 raises exception
22332 · Fix duplicated toc in epub3 output.
22334 · #2775: Fix failing linkcheck with servers not supporting identity
22336 encoding
22337 · #2833: Fix formatting instance annotations in ext.autodoc.
22339 · #1911: -D option of sphinx-build does not override the extensions
22341 variable
22342 · #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the
22344 inventory is given
22345 · parsing errors for caption of code-blocks are displayed in document
22347 (ref: #2845)
22348 · #2846: singlehtml builder does not include figure numbers
22350 · #2816: Fix data from builds cluttering the Domain.initial_data class
22352 attributes
22353 Release 1.4.5 (released Jul 13, 2016)
22355 Incompatible changes
22356 · latex, inclusion of non-inline images from image directive resulted
22357 in non-coherent whitespaces depending on original image width; new
22358 behaviour by necessity differs from earlier one in some cases. (ref:
22359 #2672)
22360 · latex, use of \includegraphics to refer to Sphinx custom variant is
22362 deprecated; in future it will revert to original LaTeX macro, custom
22363 one already has alternative name \sphinxincludegraphics.
22364 Features added
22366 · new config option latex_keep_old_macro_names, defaults to True. If
22367 False, lets macros (for text styling) be defined only with
22368 \sphinx-prefixed names
22369 · latex writer allows user customization of “shadowed” boxes (topics),
22371 via three length variables.
22372 · woff-format web font files now supported by the epub builder.
22374 Bugs fixed
22376 · jsdump fix for python 3: fixes the HTML search on python > 3
22377 · #2676: (latex) Error with verbatim text in captions since Sphinx
22379 1.4.4
22380 · #2629: memoir class crashes LaTeX. Fixed by
22382 latex_keep_old_macro_names=False (ref 2675)
22383 · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
22385 · #2679: float package needed for 'figure_align': 'H' latex option
22387 · #2671: image directive may lead to inconsistent spacing in pdf
22389 · #2705: toctree generates empty bullet_list if :titlesonly: specified
22391 · #2479: sphinx.ext.viewcode uses python2 highlighter by default
22393 · #2700: HtmlHelp builder has hard coded index.html
22395 · latex, since 1.4.4 inline literal text is followed by spurious space
22397 · #2722: C++, fix id generation for var/member declarations to include
22399 namespaces.
22400 · latex, images (from image directive) in lists or quoted blocks did
22402 not obey indentation (fixed together with #2671)
22403 · #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
22405 warnings
22406 · #2731: sphinx.ext.autodoc does not access propertymethods which
22408 raises any exceptions
22409 · #2666: C++, properly look up nested names involving constructors.
22411 · #2579: Could not refer a label including both spaces and colons via
22413 sphinx.ext.intersphinx
22414 · #2718: Sphinx crashes if the document file is not readable
22416 · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
22418 · #2723: extra spaces in latex pdf output from multirow cell
22420 · #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
22422 page
22423 · #2667: latex crashes if resized images appeared in section title
22425 · #2763: (html) Provide default value for required alt attribute for
22427 image tags of SVG source, required to validate and now consistent w/
22428 other formats.
22429 Release 1.4.4 (released Jun 12, 2016)
22431 Bugs fixed
22432 · #2630: latex: sphinx.sty notice environment formatting problem
22433 · #2632: Warning directives fail in quote environment latex build
22435 · #2633: Sphinx crashes with old styled indices
22437 · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
22439 · #2622: Latex produces empty pages after title and table of contents
22441 · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
22443 · Let LaTeX use straight quotes also in inline code (ref #2627)
22445 · #2351: latex crashes if enumerated lists are placed on footnotes
22447 · #2646: latex crashes if math contains twice empty lines
22449 · #2480: sphinx.ext.autodoc: memory addresses were shown
22451 · latex: allow code-blocks appearing inside lists and quotes at maximal
22453 nesting depth (ref #777, #2624, #2651)
22454 · #2635: Latex code directives produce inconsistent frames based on
22456 viewing resolution
22457 · #2639: Sphinx now bundles iftex.sty
22459 · Failed to build PDF with framed.sty 0.95
22461 · Sphinx now bundles needspace.sty
22463 Release 1.4.3 (released Jun 5, 2016)
22465 Bugs fixed
22466 · #2530: got “Counter too large” error on building PDF if large num‐
22467 bered footnotes existed in admonitions
22468 · width option of figure directive does not work if align option speci‐
22470 fied at same time (ref: #2595)
22471 · #2590: The inputenc package breaks compiling under lualatex and xela‐
22473 tex
22474 · #2540: date on latex front page use different font
22476 · Suppress “document isn’t included in any toctree” warning if the doc‐
22478 ument is included (ref: #2603)
22479 · #2614: Some tables in PDF output will end up shifted if user sets non
22481 zero parindent in preamble
22482 · #2602: URL redirection breaks the hyperlinks generated by
22484 sphinx.ext.intersphinx
22485 · #2613: Show warnings if merged extensions are loaded
22487 · #2619: make sure amstext LaTeX package always loaded (ref: d657225,
22489 488ee52, 9d82cad and #2615)
22490 · #2593: latex crashes if any figures in the table
22492 Release 1.4.2 (released May 29, 2016)
22494 Features added
22495 · Now suppress_warnings accepts following configurations (ref: #2451,
22496 #2466):
22497 · app.add_node
22499 · app.add_directive
22501 · app.add_role
22503 · app.add_generic_role
22505 · app.add_source_parser
22507 · image.data_uri
22509 · image.nonlocal_uri
22511 · #2453: LaTeX writer allows page breaks in topic contents; and their
22513 horizontal extent now fits in the line width (with shadow in margin).
22514 Also warning-type admonitions allow page breaks and their vertical
22515 spacing has been made more coherent with the one for hint-type
22516 notices (ref #2446).
22517 · #2459: the framing of literal code-blocks in LaTeX output (and not
22519 only the code lines themselves) obey the indentation in lists or
22520 quoted blocks.
22521 · #2343: the long source lines in code-blocks are wrapped (without mod‐
22523 ifying the line numbering) in LaTeX output (ref #1534, #2304).
22524 Bugs fixed
22526 · #2370: the equations are slightly misaligned in LaTeX writer
22527 · #1817, #2077: suppress pep8 warnings on conf.py generated by
22529 sphinx-quickstart
22530 · #2407: building docs crash if document includes large data image URIs
22532 · #2436: Sphinx does not check version by needs_sphinx if loading
22534 extensions failed
22535 · #2397: Setup shorthandoff for Turkish documents
22537 · #2447: VerbatimBorderColor wrongly used also for captions of PDF
22539 · #2456: C++, fix crash related to document merging (e.g., singlehtml
22541 and Latex builders).
22542 · #2446: latex(pdf) sets local tables of contents (or more generally
22544 topic nodes) in unbreakable boxes, causes overflow at bottom
22545 · #2476: Omit MathJax markers if :nowrap: is given
22547 · #2465: latex builder fails in case no caption option is provided to
22549 toctree directive
22550 · Sphinx crashes if self referenced toctree found
22552 · #2481: spelling mistake for mecab search splitter. Thanks to Naoki
22554 Sato.
22555 · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
22557 · intersphinx fails if mapping URL contains any port
22559 · #2088: intersphinx crashes if the mapping URL requires basic auth
22561 · #2304: auto line breaks in latexpdf codeblocks
22563 · #1534: Word wrap long lines in Latex verbatim blocks
22565 · #2460: too much white space on top of captioned literal blocks in PDF
22567 output
22568 · Show error reason when multiple math extensions are loaded (ref:
22570 #2499)
22571 · #2483: any figure number was not assigned if figure title contains
22573 only non text objects
22574 · #2501: Unicode subscript numbers are normalized in LaTeX
22576 · #2492: Figure directive with :figwidth: generates incorrect
22578 Latex-code
22579 · The caption of figure is always put on center even if :align: was
22581 specified
22582 · #2526: LaTeX writer crashes if the section having only images
22584 · #2522: Sphinx touches mo files under installed directory that caused
22586 permission error.
22587 · #2536: C++, fix crash when an immediately nested scope has the same
22589 name as the current scope.
22590 · #2555: Fix crash on any-references with unicode.
22592 · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
22594 · #2521: generated Makefile causes BSD make crashed if sphinx-build not
22596 found
22597 · #2470: typing backport package causes autodoc errors with python 2.7
22599 · sphinx.ext.intersphinx crashes if non-string value is used for key of
22601 intersphinx_mapping
22602 · #2518: intersphinx_mapping disallows non alphanumeric keys
22604 · #2558: unpack error on devhelp builder
22606 · #2561: Info builder crashes when a footnote contains a link
22608 · #2565: The descriptions of objects generated by sphinx.ext.autosum‐
22610 mary overflow lines at LaTeX writer
22611 · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
22613 · #2445: rst_prolog and rst_epilog affect to non reST sources
22615 · #2576: sphinx.ext.imgmath crashes if subprocess raises error
22617 · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
22619 · #2556: Xapian search does not work with Python 3
22621 · #2581: The search doesn’t work if language=”es” (Spanish)
22623 · #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
22625 writer
22626 · #2383: The generated footnote by latex_show_urls overflows lines
22628 · #2497, #2552: The label of search button does not fit for the button
22630 itself
22631 Release 1.4.1 (released Apr 12, 2016)
22633 Incompatible changes
22634 · The default format of today_fmt and html_last_updated_fmt is back to
22635 strftime format again. Locale Date Markup Language is also supported
22636 for backward compatibility until Sphinx-1.5.
22637 Translations
22639 · Added Welsh translation, thanks to Geraint Palmer.
22640 · Added Greek translation, thanks to Stelios Vitalis.
22642 · Added Esperanto translation, thanks to Dinu Gherman.
22644 · Added Hindi translation, thanks to Purnank H. Ghumalia.
22646 · Added Romanian translation, thanks to Razvan Stefanescu.
22648 Bugs fixed
22650 · C++, added support for extern and thread_local.
22651 · C++, type declarations are now using the prefixes typedef, using, and
22653 type, depending on the style of declaration.
22654 · #2413: C++, fix crash on duplicate declarations
22656 · #2394: Sphinx crashes when html_last_updated_fmt is invalid
22658 · #2408: dummy builder not available in Makefile and make.bat
22660 · #2412: hyperlink targets are broken in LaTeX builder
22662 · figure directive crashes if non paragraph item is given as caption
22664 · #2418: time formats no longer allowed in today_fmt
22666 · #2395: Sphinx crashes if unicode character in image filename
22668 · #2396: “too many values to unpack” in genindex-single
22670 · #2405: numref link in PDF jumps to the wrong location
22672 · #2414: missing number in PDF hyperlinks to code listings
22674 · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
22676 Release 1.4 (released Mar 28, 2016)
22678 Incompatible changes
22679 · Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
22680 Stemmer to accelerate stemming.
22681 · sphinx_rtd_theme has become optional. Please install it manually.
22683 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
22684 · #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
22686 It enables to take title of roles as an argument of custom macros.
22687 · #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns
22689 default values in conf.py that will be provided on sphinx-quickstart.
22690 · #2027, #2208: The html_title accepts string values only. And The None
22692 value cannot be accepted.
22693 · sphinx.ext.graphviz: show graph image in inline by default
22695 · #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
22697 node instead of sphinx.addnodes.literal_emphasis node.
22698 · #2022: html_extra_path also copies dotfiles in the extra directory,
22700 and refers to exclude_patterns to exclude extra files and directo‐
22701 ries.
22702 · #2300: enhance autoclass:: to use the docstring of __new__ if
22704 __init__ method’s is missing of empty
22705 · #2251: Previously, under glossary directives, multiple terms for one
22707 definition are converted into single term node and the each terms in
22708 the term node are separated by termsep node. In new implementation,
22709 each terms are converted into individual term nodes and termsep node
22710 is removed. By this change, output layout of every builders are
22711 changed a bit.
22712 · The default highlight language is now Python 3. This means that
22714 source code is highlighted as Python 3 (which is mostly a superset of
22715 Python 2), and no parsing is attempted to distinguish valid code. To
22716 get the old behavior back, add highlight_language = "python" to
22717 conf.py.
22718 · Locale Date Markup Language like "MMMM dd, YYYY" is default format
22720 for today_fmt and html_last_updated_fmt. However strftime format
22721 like "%B %d, %Y" is also supported for backward compatibility until
22722 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
22723 · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
22725 ing instead.
22726 · #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
22728 writer.
22729 · #1498: manpage writer: don’t make whole of item in definition list
22731 bold if it includes strong node.
22732 · #582: Remove hint message from quick search box for html output.
22734 · #2378: Sphinx now bundles newfloat.sty
22736 Features added
22738 · #2092: add todo directive support in napoleon package.
22739 · #1962: when adding directives, roles or nodes from an extension, warn
22741 if such an element is already present (built-in or added by another
22742 extension).
22743 · #1909: Add “doc” references to Intersphinx inventories.
22745 · C++ type alias support (e.g., .. type:: T = int).
22747 · C++ template support for classes, functions, type aliases, and vari‐
22749 ables (#1729, #1314).
22750 · C++, added new scope management directives namespace-push and names‐
22752 pace-pop.
22753 · #1970: Keyboard shortcuts to navigate Next and Previous topics
22755 · Intersphinx: Added support for fetching Intersphinx inventories with
22757 URLs using HTTP basic auth.
22758 · C++, added support for template parameter in function info field
22760 lists.
22761 · C++, added support for pointers to member (function).
22763 · #2113: Allow :class: option to code-block directive.
22765 · #2192: Imgmath (pngmath with svg support).
22767 · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
22769 · #1906: Use xcolor over color for fcolorbox where available for LaTeX
22771 output.
22772 · #2216: Texinputs makefile improvements.
22774 · #2170: Support for Chinese language search index.
22776 · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
22778 · #1030: Make page reference names for latex_show_pagerefs translatable
22780 · #2162: Add Sphinx.add_source_parser() to add source_suffix and
22782 source_parsers from extension
22783 · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
22785 · #656: Add graphviz_dot option to graphviz directives to switch the
22787 dot command
22788 · #1939: Added the dummy builder: syntax check without output.
22790 · #2230: Add math_number_all option to number all displayed math in
22792 math extensions
22793 · #2235: needs_sphinx supports micro version comparison
22795 · #2282: Add “language” attribute to html tag in the “basic” theme
22797 · #1779: Add EPUB 3 builder
22799 · #1751: Add todo_link_only to avoid file path and line indication on
22801 todolist. Thanks to Francesco Montesano.
22802 · #2199: Use imagesize package to obtain size of images.
22804 · #1099: Add configurable retries to the linkcheck builder. Thanks to
22806 Alex Gaynor. Also don’t check anchors starting with !.
22807 · #2300: enhance autoclass:: to use the docstring of __new__ if
22809 __init__ method’s is missing of empty
22810 · #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
22812 numfig feature
22813 · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
22815 erence sections using its title. Thanks to Tadhg O’Higgins.
22816 · #1854: Allow to choose Janome for Japanese splitter.
22818 · #1853: support custom text splitter on html search with lan‐
22820 guage='ja'.
22821 · #2320: classifier of glossary terms can be used for index entries
22823 grouping key The classifier also be used for translation. See also
22824 glossary-directive.
22825 · #2308: Define \tablecontinued macro to redefine the style of contin‐
22827 ued label for longtables.
22828 · Select an image by similarity if multiple images are globbed by ..
22830 image:: filename.*
22831 · #1921: Support figure substitutions by language and figure_lan‐
22833 guage_filename
22834 · #2245: Add latex_elements["passoptionstopackages"] option to call
22836 PassOptionsToPackages in early stage of preambles.
22837 · #2340: Math extension: support alignment of multiple equations for
22839 MathJax.
22840 · #2338: Define \titleref macro to redefine the style of title-refer‐
22842 ence roles.
22843 · Define \menuselection and \accelerator macros to redefine the style
22845 of menuselection roles.
22846 · Define \crossref macro to redefine the style of references
22848 · #2301: Texts in the classic html theme should be hyphenated.
22850 · #2355: Define \termref macro to redefine the style of term roles.
22852 · Add suppress_warnings to suppress arbitrary warning message (experi‐
22854 mental)
22855 · #2229: Fix no warning is given for unknown options
22857 · #2327: Add latex_toplevel_sectioning to switch the top level section‐
22859 ing of LaTeX document.
22860 Bugs fixed
22862 · #1913: C++, fix assert bug for enumerators in next-to-global and
22863 global scope.
22864 · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
22866 · C++, add missing support for ‘friend’ functions.
22868 · C++, add missing support for virtual base classes (thanks to Rapptz).
22870 · C++, add support for final classes.
22872 · C++, fix parsing of types prefixed with ‘enum’.
22874 · #2023: Dutch search support uses Danish stemming info.
22876 · C++, add support for user-defined literals.
22878 · #1804: Now html output wraps overflowed long-line-text in the side‐
22880 bar. Thanks to Hassen ben tanfous.
22881 · #2183: Fix porterstemmer causes make json to fail.
22883 · #1899: Ensure list is sent to OptParse.
22885 · #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
22887 package option).
22888 · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
22890 · Fix broken LaTeX code is generated if unknown language is given
22892 · #1944: Fix rst_prolog breaks file-wide metadata
22894 · #2074: make gettext should use canonical relative paths for .pot.
22896 Thanks to anatoly techtonik.
22897 · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
22899 · #2251: Line breaks in .rst files are transferred to .pot files in a
22901 wrong way.
22902 · #794: Fix date formatting in latex output is not localized
22904 · Remove image/gif from supported_image_types of LaTeX writer (#2272)
22906 · Fix ValueError is raised if LANGUAGE is empty string
22908 · Fix unpack warning is shown when the directives generated from
22910 Sphinx.add_crossref_type is used
22911 · The default highlight language is now default. This means that
22913 source code is highlighted as Python 3 (which is mostly a superset of
22914 Python 2) if possible. To get the old behavior back, add high‐
22915 light_language = "python" to conf.py.
22916 · #2329: Refresh environment forcedly if source directory has changed.
22918 · #2331: Fix code-blocks are filled by block in dvi; remove xcdraw
22920 option from xcolor package
22921 · Fix the confval type checker emits warnings if unicode is given to
22923 confvals which expects string value
22924 · #2360: Fix numref in LaTeX output is broken
22926 · #2361: Fix additional paragraphs inside the “compound” directive are
22928 indented
22929 · #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
22931 sion.
22932 · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
22934 · #2368: Ignore emacs lock files like .#foo.rst by default.
22936 · #2262: literal_block and its caption has been separated by pagebreak
22938 in LaTeX output.
22939 · #2319: Fix table counter is overridden by code-block’s in LaTeX.
22941 Thanks to jfbu.
22942 · Fix unpack warning if combined with 3rd party domain extensions.
22944 · #1153: Fix figures in sidebar causes latex build error.
22946 · #2358: Fix user-preamble could not override the tocdepth definition.
22948 · #2358: Reduce tocdepth if part or chapter is used for top_section‐
22950 level
22951 · #2351: Fix footnote spacing
22953 · #2363: Fix toctree() in templates generates broken links in Single‐
22955 HTMLBuilder.
22956 · #2366: Fix empty hyperref is generated on toctree in HTML builder.
22958 Documentation
22960 · #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
22961 mecke.
22962 Release 1.3.6 (released Feb 29, 2016)
22964 Features added
22965 · #1873, #1876, #2278: Add page_source_suffix html context variable.
22966 This should be introduced with source_parsers feature. Thanks for
22967 Eric Holscher.
22968 Bugs fixed
22970 · #2265: Fix babel is used in spite of disabling it on latex_elements
22971 · #2295: Avoid mutating dictionary errors while enumerating members in
22973 autodoc with Python 3
22974 · #2291: Fix pdflatex “Counter too large” error from footnotes inside
22976 tables of contents
22977 · #2292: Fix some footnotes disappear from LaTeX output
22979 · #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
22981 feature should support parsers that specified source_parsers.
22982 · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
22984 of math fonts
22985 · #2324: Print a hint how to increase the recursion limit when it is
22987 hit.
22988 · #1565, #2229: Revert new warning; the new warning will be triggered
22990 from version 1.4 on.
22991 · #2329: Refresh environment forcedly if source directory has changed.
22993 · #2019: Fix the domain objects in search result are not escaped
22995 Release 1.3.5 (released Jan 24, 2016)
22997 Bugs fixed
22998 · Fix line numbers was not shown on warnings in LaTeX and texinfo
22999 builders
23000 · Fix filenames were not shown on warnings of citations
23002 · Fix line numbers was not shown on warnings in LaTeX and texinfo
23004 builders
23005 · Fix line numbers was not shown on warnings of indices
23007 · #2026: Fix LaTeX builder raises error if parsed-literal includes
23009 links
23010 · #2243: Ignore strange docstring types for classes, do not crash
23012 · #2247: Fix #2205 breaks make html for definition list with classi‐
23014 fiers that contains regular-expression like string
23015 · #1565: Sphinx will now emit a warning that highlighting was skipped
23017 if the syntax is incorrect for code-block, literalinclude and so on.
23018 · #2211: Fix paragraphs in table cell doesn’t work in Latex output
23020 · #2253: :pyobject: option of literalinclude directive can’t detect
23022 indented body block when the block starts with blank or comment
23023 lines.
23024 · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
23026 · Fix warning message for :numref: if target is in orphaned doc (ref:
23028 #2244)
23029 Release 1.3.4 (released Jan 12, 2016)
23031 Bugs fixed
23032 · #2134: Fix figure caption with reference causes latex build error
23033 · #2094: Fix rubric with reference not working in Latex
23035 · #2147: Fix literalinclude code in latex does not break in pages
23037 · #1833: Fix email addresses is showed again if latex_show_urls is not
23039 None
23040 · #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
23042 svg
23043 · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
23045 · #1237: Fix footnotes not working in definition list in LaTeX
23047 · #2168: Fix raw directive does not work for text writer
23049 · #2171: Fix cannot linkcheck url with unicode
23051 · #2182: LaTeX: support image file names with more than 1 dots
23053 · #2189: Fix previous sibling link for first file in subdirectory uses
23055 last file, not intended previous from root toctree
23056 · #2003: Fix decode error under python2 (only) when make linkcheck is
23058 run
23059 · #2186: Fix LaTeX output of mathbb in math
23061 · #1480, #2188: LaTeX: Support math in section titles
23063 · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
23065 Bug
23066 · #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
23068 non-ascii characters
23069 · #2193: Fix shutil.SameFileError if source directory and destination
23071 directory are same
23072 · #2178: Fix unparsable C++ cross-reference when referencing a function
23074 with :cpp:any:
23075 · #2206: Fix Sphinx latex doc build failed due to a footnotes
23077 · #2201: Fix wrong table caption for tables with over 30 rows
23079 · #2213: Set <blockquote> in the classic theme to fit with <p>
23081 · #1815: Fix linkcheck does not raise an exception if warniserror set
23083 to true and link is broken
23084 · #2197: Fix slightly cryptic error message for missing index.rst file
23086 · #1894: Unlisted phony targets in quickstart Makefile
23088 · #2125: Fix unifies behavior of collapsed fields (GroupedField and
23090 TypedField)
23091 · #1408: Check latex_logo validity before copying
23093 · #771: Fix latex output doesn’t set tocdepth
23095 · #1820: On Windows, console coloring is broken with colorama version
23097 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
23098 · #2072: Fix footnotes in chapter-titles do not appear in PDF output
23100 · #1580: Fix paragraphs in longtable don’t work in Latex output
23102 · #1366: Fix centered image not centered in latex
23104 · #1860: Fix man page using :samp: with braces - font doesn’t reset
23106 · #1610: Sphinx crashes in Japanese indexing in some systems
23108 · Fix Sphinx crashes if mecab initialization failed
23110 · #2160: Fix broken TOC of PDFs if section includes an image
23112 · #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
23114 Thanks to jfbu.
23115 · #2198,#2205: make gettext generate broken msgid for definition lists.
23117 · #2062: Escape characters in doctests are treated incorrectly with
23119 Python 2.
23120 · #2225: Fix if the option does not begin with dash, linking is not
23122 performed
23123 · #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
23125 mathjax)
23126 · #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
23128 extensions doesn’t support resolve_any_xref and resolve_xref returns
23129 problematic node instead of None. sphinxcontrib-httpdomain is one of
23130 them.
23131 · #2229: Fix no warning is given for unknown options
23133 Release 1.3.3 (released Dec 2, 2015)
23135 Bugs fixed
23136 · #2177: Fix parallel hangs
23137 · #2012: Fix exception occurred if numfig_format is invalid
23139 · #2142: Provide non-minified JS code in sphinx/search/non-mini‐
23141 fied-js/*.js for source distribution on PyPI.
23142 · #2148: Error while building devhelp target with non-ASCII document.
23144 Release 1.3.2 (released Nov 29, 2015)
23146 Features added
23147 · #1935: Make “numfig_format” overridable in latex_elements.
23148 Bugs fixed
23150 · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
23151 dows environment.
23152 · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
23154 patibility
23155 · #1788: graphviz extension raises exception when caption option is
23157 present.
23158 · #1789: :pyobject: option of literalinclude directive includes follow‐
23160 ing lines after class definitions
23161 · #1790: literalinclude strips empty lines at the head and tail
23163 · #1802: load plugin themes automatically when theme.conf use it as
23165 ‘inherit’. Thanks to Takayuki Hirai.
23166 · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
23168 find base theme.
23169 · #1834: compatibility for docutils-0.13: handle_io_errors keyword
23171 argument for docutils.io.FileInput cause TypeError.
23172 · #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
23174 error. Now ‘.’ is converted to absolute path automatically.
23175 · Fix a crash when setting up extensions which do not support metadata.
23177 · #1784: Provide non-minified JS code in sphinx/search/non-mini‐
23179 fied-js/*.js
23180 · #1822, #1892: Fix regression for #1061. autosummary can’t generate
23182 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
23183 · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
23185 Takayuki Hirai.
23186 · #1780, #1866: “make text” shows “class” keyword twice. Thanks to
23188 Takayuki Hirai.
23189 · #1871: Fix for LaTeX output of tables with one column and multirows.
23191 · Work around the lack of the HTMLParserError exception in Python 3.5.
23193 · #1949: Use safe_getattr in the coverage builder to avoid aborting
23195 with descriptors that have custom behavior.
23196 · #1915: Do not generate smart quotes in doc field type annotations.
23198 · #1796: On py3, automated .mo building caused UnicodeDecodeError.
23200 · #1923: Use babel features only if the babel latex element is
23202 nonempty.
23203 · #1942: Fix a KeyError in websupport.
23205 · #1903: Fix strange id generation for glossary terms.
23207 · make text will crush if a definition list item has more than 1 clas‐
23209 sifiers as: term : classifier1 : classifier2.
23210 · #1855: make gettext generates broken po file for definition lists
23212 with classifier.
23213 · #1869: Fix problems when dealing with files containing non-ASCII
23215 characters. Thanks to Marvin Schmidt.
23216 · #1798: Fix building LaTeX with references in titles.
23218 · #1725: On py2 environment, doctest with using non-ASCII characters
23220 causes 'ascii' codec can't decode byte exception.
23221 · #1540: Fix RuntimeError with circular referenced toctree
23223 · #1983: i18n translation feature breaks references which uses section
23225 name.
23226 · #1990: Use caption of toctree to title of tableofcontents in LaTeX
23228 · #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
23230 LaTeX builder
23231 · #1994: More supporting non-standard parser (like recommonmark parser)
23233 for Translation and WebSupport feature. Now node.rawsource is fall
23234 backed to node.astext() during docutils transforming.
23235 · #1989: “make blahblah” on Windows indicate help messages for
23237 sphinx-build every time. It was caused by wrong make.bat that gener‐
23238 ated by Sphinx-1.3.0/1.3.1.
23239 · On Py2 environment, conf.py that is generated by sphinx-quickstart
23241 should have u prefixed config value for ‘version’ and ‘release’.
23242 · #2102: On Windows + Py3, using |today| and non-ASCII date format will
23244 raise UnicodeEncodeError.
23245 · #1974: UnboundLocalError: local variable ‘domain’ referenced before
23247 assignment when using any role and sphinx.ext.intersphinx in same
23248 time.
23249 · #2121: multiple words search doesn’t find pages when words across on
23251 the page title and the page content.
23252 · #1884, #1885: plug-in html themes cannot inherit another plug-in
23254 theme. Thanks to Suzumizaki.
23255 · #1818: sphinx.ext.todo directive generates broken html class
23257 attribute as ‘admonition-‘ when language is specified with non-ASCII
23258 linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive
23259 can use :class: option.
23260 · #2140: Fix footnotes in table has broken in LaTeX
23262 · #2127: MecabBinder for html searching feature doesn’t work with
23264 Python 3. Thanks to Tomoko Uchida.
23265 Release 1.3.1 (released Mar 17, 2015)
23267 Bugs fixed
23268 · #1769: allows generating quickstart files/dirs for destination dir
23269 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
23270 rou.
23271 · #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
23273 option argument.
23274 · #1766: the message “least Python 2.6 to run” is at best misleading.
23276 · #1772: cross reference in docstrings like :param .write: breaks
23278 building.
23279 · #1770, #1774: literalinclude with empty file occurs exception. Thanks
23281 to Takayuki Hirai.
23282 · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
23284 · #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
23286 sion.
23287 · #1771: automated .mo building doesn’t work properly.
23289 · #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
23291 Jens Hedegaard Nielsen.
23292 · #1781: Setting html_domain_indices to a list raises a type check
23294 warnings.
23295 Release 1.3 (released Mar 10, 2015)
23297 Incompatible changes
23298 · Roles ref, term and menusel now don’t generate emphasis nodes any‐
23299 more. If you want to keep italic style, adapt your stylesheet.
23300 · Role numref uses %s as special character to indicate position of fig‐
23302 ure numbers instead # symbol.
23303 Features added
23305 · Add convenience directives and roles to the C++ domain: directive
23306 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
23307 ber, and role any for cross-reference to any C++ declaraction. #1577,
23308 #1744
23309 · The source_suffix config value can now be a list of multiple suf‐
23311 fixes.
23312 · Add the ability to specify source parsers by source suffix with the
23314 source_parsers config value.
23315 · #1675: A new builder, AppleHelpBuilder, has been added that builds
23317 Apple Help Books.
23318 Bugs fixed
23320 · 1.3b3 change breaks a previous gettext output that contains dupli‐
23321 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
23322 · #1745: latex builder cause maximum recursion depth exceeded when a
23324 footnote has a footnote mark itself.
23325 · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
23327 · #1658, #1750: No link created (and warning given) if option does not
23329 begin with -, / or +. Thanks to Takayuki Hirai.
23330 · #1753: C++, added missing support for more complex declarations.
23332 · #1700: Add :caption: option for toctree.
23334 · #1742: :name: option is provided for toctree, code-block and literal‐
23336 include directives.
23337 · #1756: Incorrect section titles in search that was introduced from
23339 1.3b3.
23340 · #1746: C++, fixed name lookup procedure, and added missing lookups in
23342 declarations.
23343 · #1765: C++, fix old id generation to use fully qualified names.
23345 Documentation
23347 · #1651: Add vartype field description for python domain.
23348 Release 1.3b3 (released Feb 24, 2015)
23350 Incompatible changes
23351 · Dependency requirement updates: docutils 0.11, Pygments 2.0
23352 · The gettext_enables config value has been renamed to gettext_addi‐
23354 tional_targets.
23355 · #1735: Use https://docs.python.org/ instead of http protocol. It was
23357 used for sphinx.ext.intersphinx and some documentation.
23358 Features added
23360 · #1346: Add new default theme;
23361 · Add ‘alabaster’ theme.
23363 · Add ‘sphinx_rtd_theme’ theme.
23365 · The ‘default’ html theme has been renamed to ‘classic’. ‘default’
23367 is still available, however it will emit notice a recommendation
23368 that using new ‘alabaster’ theme.
23369 · Added highlight_options configuration value.
23371 · The language config value is now available in the HTML templates.
23373 · The env-updated event can now return a value, which is interpreted as
23375 an iterable of additional docnames that need to be rewritten.
23376 · #772: Support for scoped and unscoped enums in C++. Enumerators in
23378 unscoped enums are injected into the parent scope in addition to the
23379 enum scope.
23380 · Add todo_include_todos config option to quickstart conf file, handled
23382 as described in documentation.
23383 · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
23385 nav-item-0, 1, 2…).
23386 · New option sphinx-quickstart --use-make-mode for generating Makefile
23388 that use sphinx-build make-mode.
23389 · #1235: i18n: several node can be translated if it is set to get‐
23391 text_additional_targets in conf.py. Supported nodes are:
23392 · ‘literal-block’
23394 · ‘doctest-block’
23396 · ‘raw’
23398 · ‘image’
23400 · #1227: Add html_scaled_image_link config option to conf.py, to con‐
23402 trol scaled image link.
23403 Bugs fixed
23405 · LaTeX writer now generates correct markup for cells spanning multiple
23406 rows.
23407 · #1674: Do not crash if a module’s __all__ is not a list of strings.
23409 · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
23411 · On windows, make-mode didn’t work on Win32 platform if sphinx was
23413 invoked as python sphinx-build.py.
23414 · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
23416 · #1690: toctrees with glob option now can also contain entries for
23418 single documents with explicit title.
23419 · #1591: html search results for C++ elements now has correct interpage
23421 links.
23422 · bizstyle theme: nested long title pages make long breadcrumb that
23424 breaks page layout.
23425 · bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
23427 browser (iPhone5s safari).
23428 · #1722: restore toctree() template function behavior that was changed
23430 at 1.3b1.
23431 · #1732: i18n: localized table caption raises exception.
23433 · #1718: :numref: does not work with capital letters in the label
23435 · #1630: resolve CSS conflicts, div.container css target for literal
23437 block wrapper now renamed to div.literal-block-wrapper.
23438 · sphinx.util.pycompat has been restored in its backwards-compatibil‐
23440 ity; slated for removal in Sphinx 1.4.
23441 · #1719: LaTeX writer does not respect numref_format option in captions
23443 Release 1.3b2 (released Dec 5, 2014)
23445 Incompatible changes
23446 · update bundled ez_setup.py for setuptools-7.0 that requires Python
23447 2.6 or later.
23448 Features added
23450 · #1597: Added possibility to return a new template name from
23451 html-page-context.
23452 · PR#314, #1150: Configuration values are now checked for their type.
23454 A warning is raised if the configured and the default value do not
23455 have the same type and do not share a common non-trivial base class.
23456 Bugs fixed
23458 · PR#311: sphinx-quickstart does not work on python 3.4.
23459 · Fix autodoc_docstring_signature not working with signatures in class
23461 docstrings.
23462 · Rebuilding cause crash unexpectedly when source files were added.
23464 · #1607: Fix a crash when building latexpdf with “howto” class
23466 · #1251: Fix again. Sections which depth are lower than :tocdepth:
23468 should not be shown on localtoc sidebar.
23469 · make-mode didn’t work on Win32 platform if sphinx was installed by
23471 wheel package.
23472 Release 1.3b1 (released Oct 10, 2014)
23474 Incompatible changes
23475 · Dropped support for Python 2.5, 3.1 and 3.2.
23476 · Dropped support for docutils versions up to 0.9.
23478 · Removed the sphinx.ext.oldcmarkup extension.
23480 · The deprecated config values exclude_trees, exclude_dirnames and
23482 unused_docs have been removed.
23483 · A new node, sphinx.addnodes.literal_strong, has been added, for text
23485 that should appear literally (i.e. no smart quotes) in strong font.
23486 Custom writers will have to be adapted to handle this node.
23487 · PR#269, #1476: replace <tt> tag by <code>. User customized
23489 stylesheets should be updated If the css contain some styles for tt>
23490 tag. Thanks to Takeshi Komiya.
23491 · #1543: templates_path is automatically added to exclude_patterns to
23493 avoid reading autosummary rst templates in the templates directory.
23494 · Custom domains should implement the new Domain.resolve_any_xref
23496 method to make the any role work properly.
23497 · gettext builder: gettext doesn’t emit uuid information to generated
23499 pot files by default. Please set True to gettext_uuid to emit uuid
23500 information. Additionally, if the python-levenshtein 3rd-party pack‐
23501 age is installed, it will improve the calculation time.
23502 · gettext builder: disable extracting/apply ‘index’ node by default.
23504 Please set ‘index’ to gettext_enables to enable extracting index
23505 entries.
23506 · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
23508 Features added
23510 · Add support for Python 3.4.
23511 · Add support for docutils 0.12
23513 · Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
23515 string support.
23516 · Added support for parallel reading (parsing) of source files with the
23518 sphinx-build -j option. Third-party extensions will need to be
23519 checked for compatibility and may need to be adapted if they store
23520 information in the build environment object. See env-merge-info.
23521 · Added the any role that can be used to find a cross-reference of any
23523 type in any domain. Custom domains should implement the new
23524 Domain.resolve_any_xref method to make this work properly.
23525 · Exception logs now contain the last 10 messages emitted by Sphinx.
23527 · Added support for extension versions (a string returned by setup(),
23529 these can be shown in the traceback log files). Version requirements
23530 for extensions can be specified in projects using the new
23531 needs_extensions config value.
23532 · Changing the default role within a document with the default-role
23534 directive is now supported.
23535 · PR#214: Added stemming support for 14 languages, so that the built-in
23537 document search can now handle these. Thanks to Shibukawa Yoshiki.
23538 · PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
23540 tables and code-blocks. This feature is configured with numfig, num‐
23541 fig_secnum_depth and numfig_format. Also numref role is available.
23542 Thanks to Takeshi Komiya.
23543 · PR#202: Allow “.” and “~” prefixed references in :param: doc fields
23545 for Python.
23546 · PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
23548 nal modules that need not be present when autodocumenting.
23549 · #925: Allow list-typed config values to be provided on the command
23551 line, like -D key=val1,val2.
23552 · #668: Allow line numbering of code-block and literalinclude direc‐
23554 tives to start at an arbitrary line number, with a new lineno-start
23555 option.
23556 · PR#172, PR#266: The code-block and literalinclude directives now can
23558 have a caption option that shows a filename before the code in the
23559 output. Thanks to Nasimul Haque, Takeshi Komiya.
23560 · Prompt for the document language in sphinx-quickstart.
23562 · PR#217: Added config values to suppress UUID and location information
23564 in generated gettext catalogs.
23565 · PR#236, #1456: apidoc: Add a -M option to put module documentation
23567 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
23568 · #1434: Provide non-minified JS files for jquery.js and underscore.js
23570 to clarify the source of the minified files.
23571 · PR#252, #1291: Windows color console support. Thanks to meu31.
23573 · PR#255: When generating latex references, also insert latex tar‐
23575 get/anchor for the ids defined on the node. Thanks to Olivier
23576 Heurtier.
23577 · PR#229: Allow registration of other translators. Thanks to Russell
23579 Sim.
23580 · Add app.set_translator() API to register or override a Docutils
23582 translator class like html_translator_class.
23583 · PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
23585 Richard Wall and WAKAYAMA shirou.
23586 · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
23588 · Automatically compile *.mo files from *.po files when get‐
23590 text_auto_build is True (default) and *.po is newer than *.mo file.
23591 · #623: sphinx.ext.viewcode supports imported function/class aliases.
23593 · PR#275: sphinx.ext.intersphinx supports multiple target for the
23595 inventory. Thanks to Brigitta Sipocz.
23596 · PR#261: Added the env-before-read-docs event that can be connected to
23598 modify the order of documents before they are read by the environ‐
23599 ment.
23600 · #1284: Program options documented with option can now start with +.
23602 · PR#291: The caption of code-block is recognized as a title of ref
23604 target. Thanks to Takeshi Komiya.
23605 · PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
23607 · #1344: add gettext_enables to enable extracting ‘index’ to gettext
23609 catalog output / applying translation catalog to generated documenta‐
23610 tion.
23611 · PR#301, #1583: Allow the line numbering of the directive literalin‐
23613 clude to match that of the included file, using a new lineno-match
23614 option. Thanks to Jeppe Pihl.
23615 · PR#299: add various options to sphinx-quickstart. Quiet mode option
23617 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
23618 · #1623: Return types specified with :rtype: are now turned into links
23620 if possible.
23621 Bugs fixed
23623 · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
23624 · #1568: Fix a crash when a “centered” directive contains a reference.
23626 · Now sphinx.ext.autodoc works with python-2.5 again.
23628 · #1563: add_search_language() raises AssertionError for correct type
23630 of argument. Thanks to rikoman.
23631 · #1174: Fix smart quotes being applied inside roles like program or
23633 makevar.
23634 · PR#235: comment db schema of websupport lacked a length of the
23636 node_id field. Thanks to solos.
23637 · #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
23639 “variadic templates” declarations. Thanks to Victor Zverovich.
23640 · #1459,PR#244: Fix default mathjax js path point to http:// that cause
23642 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
23643 · PR#157: autodoc remove spurious signatures from @property decorated
23645 attributes. Thanks to David Ham.
23646 · PR#159: Add coverage targets to quickstart generated Makefile and
23648 make.bat. Thanks to Matthias Troffaes.
23649 · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
23651 data, sub section number that is larger depth than :tocdepth: is
23652 shrunk.
23653 · PR#260: Encode underscore in citation labels for latex export. Thanks
23655 to Lennart Fricke.
23656 · PR#264: Fix could not resolve xref for figure node with :name:
23658 option. Thanks to Takeshi Komiya.
23659 · PR#265: Fix could not capture caption of graphviz node by xref.
23661 Thanks to Takeshi Komiya.
23662 · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
23664 Andersen.
23665 · Hyperlinks to all found nested names and template arguments
23667 (#1103).
23668 · Support for function types everywhere, e.g., in std::func‐
23670 tion<bool(int, int)> (#1013).
23671 · Support for virtual functions.
23673 · Changed interpretation of function arguments to following standard
23675 prototype declarations, i.e., void f(arg) means that arg is the
23676 type of the argument, instead of it being the name.
23677 · Updated tests.
23679 · Updated documentation with elaborate description of what declara‐
23681 tions are supported and how the namespace declarations influence
23682 declaration and cross-reference lookup.
23683 · Index names may be different now. Elements are indexed by their
23685 fully qualified name. It should be rather easy to change this be‐
23686 haviour and potentially index by namespaces/classes as well.
23687 · PR#258, #939: Add dedent option for code-block and literalinclude.
23689 Thanks to Zafar Siddiqui.
23690 · PR#268: Fix numbering section does not work at singlehtml mode. It
23692 still ad-hoc fix because there is a issue that section IDs are con‐
23693 flicted. Thanks to Takeshi Komiya.
23694 · PR#273, #1536: Fix RuntimeError with numbered circular toctree.
23696 Thanks to Takeshi Komiya.
23697 · PR#274: Set its URL as a default title value if URL appears in toc‐
23699 tree. Thanks to Takeshi Komiya.
23700 · PR#276, #1381: rfc and pep roles support custom link text. Thanks to
23702 Takeshi Komiya.
23703 · PR#277, #1513: highlights for function pointers in argument list of
23705 c:function. Thanks to Takeshi Komiya.
23706 · PR#278: Fix section entries were shown twice if toctree has been put
23708 under only directive. Thanks to Takeshi Komiya.
23709 · #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
23711 py3).
23712 · PR#294: On LaTeX builder, wrap float environment on writing lit‐
23714 eral_block to avoid separation of caption and body. Thanks to Takeshi
23715 Komiya.
23716 · PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
23718 directory. Thanks to Peter Suter.
23719 · PR#297, #1571: Add imgpath property to all builders. It make easier
23721 to develop builder extensions. Thanks to Takeshi Komiya.
23722 · #1584: Point to master doc in HTML “top” link.
23724 · #1585: Autosummary of modules broken in Sphinx-1.2.3.
23726 · #1610: Sphinx cause AttributeError when MeCab search option is
23728 enabled and python-mecab is not installed.
23729 · #1674: Do not crash if a module’s __all__ is not a list of strings.
23731 · #1673: Fix crashes with nitpick_ignore and :doc: references.
23733 · #1686: ifconfig directive doesn’t care about default config values.
23735 · #1642: Fix only one search result appearing in Chrome.
23737 Documentation
23739 · Add clarification about the syntax of tags. (doc/markup/misc.rst)
23740 Release 1.2.3 (released Sep 1, 2014)
23742 Features added
23743 · #1518: sphinx-apidoc command now has a --version option to show ver‐
23744 sion information and exit
23745 · New locales: Hebrew, European Portuguese, Vietnamese.
23747 Bugs fixed
23749 · #636: Keep straight single quotes in literal blocks in the LaTeX
23750 build.
23751 · #1419: Generated i18n sphinx.js files are missing message catalog
23753 entries from ‘.js_t’ and ‘.html’. The issue was introduced from
23754 Sphinx-1.1
23755 · #1363: Fix i18n: missing python domain’s cross-references with cur‐
23757 rentmodule directive or currentclass directive.
23758 · #1444: autosummary does not create the description from attributes
23760 docstring.
23761 · #1457: In python3 environment, make linkcheck cause “Can’t convert
23763 ‘bytes’ object to str implicitly” error when link target url has a
23764 hash part. Thanks to Jorge_C.
23765 · #1467: Exception on Python3 if nonexistent method is specified by
23767 automethod
23768 · #1441: autosummary can’t handle nested classes correctly.
23770 · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
23772 user-friendly error message.
23773 · #1502: In autodoc, fix display of parameter defaults containing back‐
23775 slashes.
23776 · #1226: autodoc, autosummary: importing setup.py by automodule will
23778 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
23779 mExit exception and emits warnings without unexpected termination.
23780 · #1503: py:function directive generate incorrectly signature when
23782 specifying a default parameter with an empty list []. Thanks to Geert
23783 Jansen.
23784 · #1508: Non-ASCII filename raise exception on make singlehtml, latex,
23786 man, texinfo and changes.
23787 · #1531: On Python3 environment, docutils.conf with ‘source_link=true’
23789 in the general section cause type error.
23790 · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
23792 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
23793 · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
23795 Thanks to Takeshi Komiya.
23796 · #1477: gettext does not extract nodes.line in a table or list.
23798 · #1544: make text generates wrong table when it has empty table cells.
23800 · #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
23802 lem has been appeared from Sphinx-1.2.1 by #949.
23803 · #508: Sphinx every time exit with zero when is invoked from setup.py
23805 command. ex. python setup.py build_sphinx -b doctest return zero
23806 even if doctest failed.
23807 Release 1.2.2 (released Mar 2, 2014)
23809 Bugs fixed
23810 · PR#211: When checking for existence of the html_logo file, check the
23811 full relative path and not the basename.
23812 · PR#212: Fix traceback with autodoc and __init__ methods without doc‐
23814 string.
23815 · PR#213: Fix a missing import in the setup command.
23817 · #1357: Option names documented by option are now again allowed to not
23819 start with a dash or slash, and referencing them will work correctly.
23820 · #1358: Fix handling of image paths outside of the source directory
23822 when using the “wildcard” style reference.
23823 · #1374: Fix for autosummary generating overly-long summaries if first
23825 line doesn’t end with a period.
23826 · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
23828 · #1391: Actually prevent using “pngmath” and “mathjax” extensions at
23830 the same time in sphinx-quickstart.
23831 · #1386: Fix bug preventing more than one theme being added by the
23833 entry point mechanism.
23834 · #1370: Ignore “toctree” nodes in text writer, instead of raising.
23836 · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
23838 present.
23839 · #1367: Fix a change of PR#96 that break sphinx.util.doc‐
23841 fields.Field.make_field interface/behavior for item argument usage.
23842 Documentation
23844 · Extended the documentation about building extensions.
23845 Release 1.2.1 (released Jan 19, 2014)
23847 Bugs fixed
23848 · #1335: Fix autosummary template overloading with exclamation prefix
23849 like {% extends "!autosummary/class.rst" %} cause infinite recursive
23850 function call. This was caused by PR#181.
23851 · #1337: Fix autodoc with autoclass_content="both" uses useless
23853 object.__init__ docstring when class does not have __init__. This
23854 was caused by a change for #1138.
23855 · #1340: Can’t search alphabetical words on the HTML quick search gen‐
23857 erated with language=’ja’.
23858 · #1319: Do not crash if the html_logo file does not exist.
23860 · #603: Do not use the HTML-ized title for building the search index
23862 (that resulted in “literal” being found on every page with a literal
23863 in the title).
23864 · #751: Allow production lists longer than a page in LaTeX by using
23866 longtable.
23867 · #764: Always look for stopwords lowercased in JS search.
23869 · #814: autodoc: Guard against strange type objects that don’t have
23871 __bases__.
23872 · #932: autodoc: Do not crash if __doc__ is not a string.
23874 · #933: Do not crash if an option value is malformed (contains spaces
23876 but no option name).
23877 · #908: On Python 3, handle error messages from LaTeX correctly in the
23879 pngmath extension.
23880 · #943: In autosummary, recognize “first sentences” to pull from the
23882 docstring if they contain uppercase letters.
23883 · #923: Take the entire LaTeX document into account when caching png‐
23885 math-generated images. This rebuilds them correctly when png‐
23886 math_latex_preamble changes.
23887 · #901: Emit a warning when using docutils’ new “math” markup without a
23889 Sphinx math extension active.
23890 · #845: In code blocks, when the selected lexer fails, display line
23892 numbers nevertheless if configured.
23893 · #929: Support parsed-literal blocks in LaTeX output correctly.
23895 · #949: Update the tabulary.sty packed with Sphinx.
23897 · #1050: Add anonymous labels into objects.inv to be referenced via
23899 intersphinx.
23900 · #1095: Fix print-media stylesheet being included always in the
23902 “scrolls” theme.
23903 · #1085: Fix current classname not getting set if class description has
23905 :noindex: set.
23906 · #1181: Report option errors in autodoc directives more gracefully.
23908 · #1155: Fix autodocumenting C-defined methods as attributes in Python
23910 3.
23911 · #1233: Allow finding both Python classes and exceptions with the
23913 “class” and “exc” roles in intersphinx.
23914 · #1198: Allow “image” for the “figwidth” option of the figure direc‐
23916 tive as documented by docutils.
23917 · #1152: Fix pycode parsing errors of Python 3 code by including two
23919 grammar versions for Python 2 and 3, and loading the appropriate ver‐
23920 sion for the running Python version.
23921 · #1017: Be helpful and tell the user when the argument to option does
23923 not match the required format.
23924 · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
23926 the store environment for changes to have effect.
23927 · #1072: In the JS search, fix issues searching for upper-cased words
23929 by lowercasing words before stemming.
23930 · #1299: Make behavior of the math directive more consistent and avoid
23932 producing empty environments in LaTeX output.
23933 · #1308: Strip HTML tags from the content of “raw” nodes before feeding
23935 it to the search indexer.
23936 · #1249: Fix duplicate LaTeX page numbering for manual documents.
23938 · #1292: In the linkchecker, retry HEAD requests when denied by HTTP
23940 405. Also make the redirect code apparent and tweak the output a bit
23941 to be more obvious.
23942 · #1285: Avoid name clashes between C domain objects and section
23944 titles.
23945 · #848: Always take the newest code in incremental rebuilds with the
23947 sphinx.ext.viewcode extension.
23948 · #979, #1266: Fix exclude handling in sphinx-apidoc.
23950 · #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
23952 menting classes that can’t be pickled.
23953 · #1316: Remove hard-coded font-face resources from epub theme.
23955 · #1329: Fix traceback with empty translation msgstr in .po files.
23957 · #1300: Fix references not working in translated documents in some
23959 instances.
23960 · #1283: Fix a bug in the detection of changed files that would try to
23962 access doctrees of deleted documents.
23963 · #1330: Fix exclude_patterns behavior with subdirectories in the
23965 html_static_path.
23966 · #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
23968 valid HTML.
23969 · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
23971 Documentation
23973 · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
23974 Release 1.2 (released Dec 10, 2013)
23976 Features added
23977 · Added sphinx.version_info tuple for programmatic checking of the
23978 Sphinx version.
23979 Incompatible changes
23981 · Removed the sphinx.ext.refcounting extension – it is very specific to
23982 CPython and has no place in the main distribution.
23983 Bugs fixed
23985 · Restore versionmodified CSS class for versionadded/changed and depre‐
23986 cated directives.
23987 · PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
23989 ments always (This change keeps the current “theme changes cause a
23990 rebuild” feature).
23991 · #1296: Fix invalid charset in HTML help generated HTML files for
23993 default locale.
23994 · PR#190: Fix gettext does not extract figure caption and rubric title
23996 inside other blocks. Thanks to Michael Schlenker.
23997 · PR#176: Make sure setup_command test can always import Sphinx. Thanks
23999 to Dmitry Shachnev.
24000 · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
24002 · #1269: Fix ResourceWarnings with Python 3.2 or later.
24004 · #1138: Fix: When autodoc_docstring_signature = True and auto‐
24006 class_content = 'init' or 'both', __init__ line should be removed
24007 from class documentation.
24008 Release 1.2 beta3 (released Oct 3, 2013)
24010 Features added
24011 · The Sphinx error log files will now include a list of the loaded
24012 extensions for help in debugging.
24013 Incompatible changes
24015 · PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
24016 manual’ and ‘sphinxhowto’. Now you can use your custom document class
24017 without ‘sphinx’ prefix. Thanks to Erik B.
24018 Bugs fixed
24020 · #1265: Fix i18n: crash when translating a section name that is
24021 pointed to from a named target.
24022 · A wrong condition broke the search feature on first page that is usu‐
24024 ally index.rst. This issue was introduced in 1.2b1.
24025 · #703: When Sphinx can’t decode filenames with non-ASCII characters,
24027 Sphinx now catches UnicodeError and will continue if possible instead
24028 of raising the exception.
24029 Release 1.2 beta2 (released Sep 17, 2013)
24031 Features added
24032 · apidoc now ignores “_private” modules by default, and has an option
24033 -P to include them.
24034 · apidoc now has an option to not generate headings for packages and
24036 modules, for the case that the module docstring already includes a
24037 reST heading.
24038 · PR#161: apidoc can now write each module to a standalone page instead
24040 of combining all modules in a package on one page.
24041 · Builders: rebuild i18n target document when catalog updated.
24043 · Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
24045 HTML writer. The latex, manpage and texinfo writers also support
24046 their respective ‘writers’ sections.
24047 · The new html_extra_path config value allows to specify directories
24049 with files that should be copied directly to the HTML output direc‐
24050 tory.
24051 · Autodoc directives for module data and attributes now support an
24053 annotation option, so that the default display of the data/attribute
24054 value can be overridden.
24055 · PR#136: Autodoc directives now support an imported-members option to
24057 include members imported from different modules.
24058 · New locales: Macedonian, Sinhala, Indonesian.
24060 · Theme package collection by using setuptools plugin mechanism.
24062 Incompatible changes
24064 · PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
24065 ation-Date that was generated by gettext builder. Thanks to masklinn
24066 and Jakub Wilk.
24067 Bugs fixed
24069 · PR#132: Updated jQuery version to 1.8.3.
24070 · PR#141, #982: Avoid crash when writing PNG file using Python 3.
24072 Thanks to Marcin Wojdyr.
24073 · PR#145: In parallel builds, sphinx drops second document file to
24075 write. Thanks to tychoish.
24076 · PR#151: Some styling updates to tables in LaTeX.
24078 · PR#153: The “extensions” config value can now be overridden.
24080 · PR#155: Added support for some C++11 function qualifiers.
24082 · Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
24084 utf-8 encoded strings.
24085 · #828: use inspect.getfullargspec() to be able to document functions
24087 with keyword-only arguments on Python 3.
24088 · #1090: Fix i18n: multiple cross references (term, ref, doc) in the
24090 same line return the same link.
24091 · #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
24093 exception.
24094 · #1159: fix wrong generation of objects inventory for Python modules,
24096 and add a workaround in intersphinx to fix handling of affected
24097 inventories.
24098 · #1160: Citation target missing caused an AssertionError.
24100 · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
24102 · #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
24104 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
24105 der Dupuy.
24106 · #1185: Don’t crash when a Python module has a wrong or no encoding
24108 declared, and non-ASCII characters are included.
24109 · #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
24111 sion” includes non-ASCII characters.
24112 · #1189: “Title underline is too short” WARNING is given when using
24114 fullwidth characters to “Project name” on quickstart.
24115 · #1190: Output TeX/texinfo/man filename has no basename (only exten‐
24117 sion) when using non-ASCII characters in the “Project name” on quick‐
24118 start.
24119 · #1192: Fix escaping problem for hyperlinks in the manpage writer.
24121 · #1193: Fix i18n: multiple link references in the same line return the
24123 same link.
24124 · #1176: Fix i18n: footnote reference number missing for auto numbered
24126 named footnote and auto symbol footnote.
24127 · PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to
24129 tychoish.
24130 · #1204: Fix wrong generation of links to local intersphinx targets.
24132 · #1206: Fix i18n: gettext did not translate admonition directive’s
24134 title.
24135 · #1232: Sphinx generated broken ePub files on Windows.
24137 · #1259: Guard the debug output call when emitting events; to prevent
24139 the repr() implementation of arbitrary objects causing build fail‐
24140 ures.
24141 · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
24143 · #1234: Ignoring the string consists only of white-space characters.
24145 Release 1.2 beta1 (released Mar 31, 2013)
24147 Incompatible changes
24148 · Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
24149 eref_role() which were deprecated since version 1.0.
24150 · PR#122: the files given in latex_additional_files now override TeX
24152 files included by Sphinx, such as sphinx.sty.
24153 · PR#124: the node generated by versionadded, versionchanged and depre‐
24155 cated directives now includes all added markup (such as “New in ver‐
24156 sion X”) as child nodes, and no additional text must be generated by
24157 writers.
24158 · PR#99: the seealso directive now generates admonition nodes instead
24160 of the custom seealso node.
24161 Features added
24163 · Markup
24164 · The toctree directive and the toctree() template function now have
24166 an includehidden option that includes hidden toctree entries (bugs
24167 #790 and #1047). A bug in the maxdepth option for the toctree()
24168 template function has been fixed (bug #1046).
24169 · PR#99: Strip down seealso directives to normal admonitions. This
24171 removes their unusual CSS classes (admonition-see-also), inconsis‐
24172 tent LaTeX admonition title (“See Also” instead of “See also”), and
24173 spurious indentation in the text builder.
24174 · HTML builder
24176 · #783: Create a link to full size image if it is scaled with width
24178 or height.
24179 · #1067: Improve the ordering of the JavaScript search results:
24181 matches in titles come before matches in full text, and object
24182 results are better categorized. Also implement a pluggable search
24183 scorer.
24184 · #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
24186 options now work together.
24187 · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
24189 · Texinfo builder
24191 · An “Index” node is no longer added when there are no entries.
24193 · “deffn” categories are no longer capitalized if they contain capi‐
24195 tal letters.
24196 · desc_annotation nodes are now rendered.
24198 · strong and emphasis nodes are now formatted like literals. The rea‐
24200 son for this is because the standard Texinfo markup (*strong* and
24201 _emphasis_) resulted in confusing output due to the common usage of
24202 using these constructs for documenting parameter names.
24203 · Field lists formatting has been tweaked to better display “Info
24205 field lists”.
24206 · system_message and problematic nodes are now formatted in a similar
24208 fashion as done by the text builder.
24209 · “en-dash” and “em-dash” conversion of hyphens is no longer per‐
24211 formed in option directive signatures.
24212 · @ref is now used instead of @pxref for cross-references which pre‐
24214 vents the word “see” from being added before the link (does not
24215 affect the Info output).
24216 · The @finalout command has been added for better TeX output.
24218 · transition nodes are now formatted using underscores (“_”) instead
24220 of asterisks (“*”).
24221 · The default value for the paragraphindent has been changed from 2
24223 to 0 meaning that paragraphs are no longer indented by default.
24224 · #1110: A new configuration value texinfo_no_detailmenu has been
24226 added for controlling whether a @detailmenu is added in the “Top”
24227 node’s menu.
24228 · Detailed menus are no longer created except for the “Top” node.
24230 · Fixed an issue where duplicate domain indices would result in
24232 invalid output.
24233 · LaTeX builder:
24235 · PR#115: Add 'transition' item in latex_elements for customizing how
24237 transitions are displayed. Thanks to Jeff Klukas.
24238 · PR#114: The LaTeX writer now includes the “cmap” package by
24240 default. The 'cmappkg' item in latex_elements can be used to con‐
24241 trol this. Thanks to Dmitry Shachnev.
24242 · The 'fontpkg' item in latex_elements now defaults to '' when the
24244 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
24245 · The latex_documents, texinfo_documents, and man_pages configuration
24247 values will be set to default values based on the master_doc if not
24248 explicitly set in conf.py. Previously, if these values were not
24249 set, no output would be generated by their respective builders.
24250 · Internationalization:
24252 · Add i18n capabilities for custom templates. For example: The
24254 Sphinx reference documentation in doc directory provides a
24255 sphinx.pot file with message strings from doc/_templates/*.html
24256 when using make gettext.
24257 · PR#61,#703: Add support for non-ASCII filename handling.
24259 · Other builders:
24261 · Added the Docutils-native XML and pseudo-XML builders. See XML‐
24263 Builder and PseudoXMLBuilder.
24264 · PR#45: The linkcheck builder now checks #anchors for existence.
24266 · PR#123, #1106: Add epub_use_index configuration value. If pro‐
24268 vided, it will be used instead of html_use_index for epub builder.
24269 · PR#126: Add epub_tocscope configuration value. The setting controls
24271 the generation of the epub toc. The user can now also include hid‐
24272 den toc entries.
24273 · PR#112: Add epub_show_urls configuration value.
24275 · Extensions:
24277 · PR#52: special_members flag to autodoc now behaves like members.
24279 · PR#47: Added sphinx.ext.linkcode extension.
24281 · PR#25: In inheritance diagrams, the first line of the class doc‐
24283 string is now the tooltip for the class.
24284 · Command-line interfaces:
24286 · PR#75: Added --follow-links option to sphinx-apidoc.
24288 · #869: sphinx-build now has the option -T for printing the full
24290 traceback after an unhandled exception.
24291 · sphinx-build now supports the standard --help and --version
24293 options.
24294 · sphinx-build now provides more specific error messages when called
24296 with invalid options or arguments.
24297 · sphinx-build now has a verbose option -v which can be repeated for
24299 greater effect. A single occurrence provides a slightly more ver‐
24300 bose output than normal. Two or more occurrences of this option
24301 provides more detailed output which may be useful for debugging.
24302 · Locales:
24304 · PR#74: Fix some Russian translation.
24306 · PR#54: Added Norwegian bokmaal translation.
24308 · PR#35: Added Slovak translation.
24310 · PR#28: Added Hungarian translation.
24312 · #1113: Add Hebrew locale.
24314 · #1097: Add Basque locale.
24316 · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
24318 · #1012: Update Estonian translation.
24320 · Optimizations:
24322 · Speed up building the search index by caching the results of the
24324 word stemming routines. Saves about 20 seconds when building the
24325 Python documentation.
24326 · PR#108: Add experimental support for parallel building with a new
24328 sphinx-build -j option.
24329 Documentation
24331 · PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
24332 outlines the basic development process of the Sphinx project.
24333 · Added a detailed “Installing Sphinx” document (doc/install.rst).
24335 Bugs fixed
24337 · PR#124: Fix paragraphs in versionmodified are ignored when it has no
24338 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
24339 versionmodified is not translatable. Thanks to Nozomu Kaneko.
24340 · PR#111: Respect add_autodoc_attrgetter() even when inherited-members
24342 is set. Thanks to A. Jesse Jiryu Davis.
24343 · PR#97: Fix footnote handling in translated documents.
24345 · Fix text writer not handling visit_legend for figure directive con‐
24347 tents.
24348 · Fix text builder not respecting wide/fullwidth characters: title
24350 underline width, table layout width and text wrap width.
24351 · Fix leading space in LaTeX table header cells.
24353 · #1132: Fix LaTeX table output for multi-row cells in the first col‐
24355 umn.
24356 · #1128: Fix Unicode errors when trying to format time strings with a
24358 non-standard locale.
24359 · #1127: Fix traceback when autodoc tries to tokenize a non-Python
24361 file.
24362 · #1126: Fix double-hyphen to en-dash conversion in wrong places such
24364 as command-line option names in LaTeX.
24365 · #1123: Allow whitespaces in filenames given to literalinclude.
24367 · #1120: Added improvements about i18n for themes “basic”, “haiku” and
24369 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
24370 · #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
24372 G.
24373 · #1117: Handle .pyx files in sphinx-apidoc.
24375 · #1112: Avoid duplicate download files when referenced from documents
24377 in different ways (absolute/relative).
24378 · #1111: Fix failure to find uppercase words in search when
24380 html_search_language is ‘ja’. Thanks to Tomo Saito.
24381 · #1108: The text writer now correctly numbers enumerated lists with
24383 non-default start values (based on patch by Ewan Edwards).
24384 · #1102: Support multi-context “with” statements in autodoc.
24386 · #1090: Fix gettext not extracting glossary terms.
24388 · #1074: Add environment version info to the generated search index to
24390 avoid compatibility issues with old builds.
24391 · #1070: Avoid un-pickling issues when running Python 3 and the saved
24393 environment was created under Python 2.
24394 · #1069: Fixed error caused when autodoc would try to format signatures
24396 of “partial” functions without keyword arguments (patch by Artur Gas‐
24397 par).
24398 · #1062: sphinx.ext.autodoc use __init__ method signature for class
24400 signature.
24401 · #1055: Fix web support with relative path to source directory.
24403 · #1043: Fix sphinx-quickstart asking again for yes/no questions
24405 because input() returns values with an extra ‘r’ on Python 3.2.0 +
24406 Windows. Thanks to Régis Décamps.
24407 · #1041: Fix failure of the cpp domain parser to parse a const type
24409 with a modifier.
24410 · #1038: Fix failure of the cpp domain parser to parse C+11 “static
24412 constexpr” declarations. Thanks to Jakub Wilk.
24413 · #1029: Fix intersphinx_mapping values not being stable if the mapping
24415 has plural key/value set with Python 3.3.
24416 · #1028: Fix line block output in the text builder.
24418 · #1024: Improve Makefile/make.bat error message if Sphinx is not
24420 found. Thanks to Anatoly Techtonik.
24421 · #1018: Fix “container” directive handling in the text builder.
24423 · #1015: Stop overriding jQuery contains() in the JavaScript.
24425 · #1010: Make pngmath images transparent by default; IE7+ should handle
24427 it.
24428 · #1008: Fix test failures with Python 3.3.
24430 · #995: Fix table-of-contents and page numbering for the LaTeX “howto”
24432 class.
24433 · #976: Fix gettext does not extract index entries.
24435 · PR#72: #975: Fix gettext not extracting definition terms before docu‐
24437 tils 0.10.
24438 · #961: Fix LaTeX output for triple quotes in code snippets.
24440 · #958: Do not preserve environment.pickle after a failed build.
24442 · #955: Fix i18n transformation.
24444 · #940: Fix gettext does not extract figure caption.
24446 · #920: Fix PIL packaging issue that allowed to import Image without
24448 PIL namespace. Thanks to Marc Schlaich.
24449 · #723: Fix the search function on local files in WebKit based
24451 browsers.
24452 · #440: Fix coarse timestamp resolution in some filesystem generating a
24454 wrong list of outdated files.
24455 Release 1.1.3 (Mar 10, 2012)
24457 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
24458 characters correctly.
24459 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
24461 · PR#34: Restore Python 2.4 compatibility.
24463 · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
24465 the document class.
24466 · #695: When the highlight language “python” is specified explicitly,
24468 do not try to parse the code to recognize non-Python snippets.
24469 · #859: Fix exception under certain circumstances when not finding
24471 appropriate objects to link to.
24472 · #860: Do not crash when encountering invalid doctest examples, just
24474 emit a warning.
24475 · #864: Fix crash with some settings of modindex_common_prefix.
24477 · #862: Fix handling of -D and -A options on Python 3.
24479 · #851: Recognize and warn about circular toctrees, instead of running
24481 into recursion errors.
24482 · #853: Restore compatibility with docutils trunk.
24484 · #852: Fix HtmlHelp index entry links again.
24486 · #854: Fix inheritance_diagram raising attribute errors on builtins.
24488 · #832: Fix crashes when putting comments or lone terms in a glossary.
24490 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
24492 supported languages.
24493 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
24495 sion.
24496 · #831: Provide --project flag in setup_command as advertised.
24498 · #875: Fix reading config files under Python 3.
24500 · #876: Fix quickstart test under Python 3.
24502 · #870: Fix spurious KeyErrors when removing documents.
24504 · #892: Fix single-HTML builder misbehaving with the master document in
24506 a subdirectory.
24507 · #873: Fix assertion errors with empty only directives.
24509 · #816: Fix encoding issues in the Qt help builder.
24511 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
24513 · #809: Include custom fixers in the source distribution.
24514 Release 1.1.1 (Nov 1, 2011)
24516 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
24517 · #792: Include “sphinx-apidoc” in the source distribution.
24519 · #797: Don’t crash on a misformatted glossary.
24521 · #801: Make intersphinx work properly without SSL support.
24523 · #805: Make the Sphinx.add_index_to_domain method work correctly.
24525 · #780: Fix Python 2.5 compatibility.
24527 Release 1.1 (Oct 9, 2011)
24529 Incompatible changes
24530 · The py:module directive doesn’t output its platform option value any‐
24531 more. (It was the only thing that the directive did output, and
24532 therefore quite inconsistent.)
24533 · Removed support for old dependency versions; requirements are now:
24535 · Pygments >= 1.2
24537 · Docutils >= 0.7
24539 · Jinja2 >= 2.3
24541 Features added
24543 · Added Python 3.x support.
24544 · New builders and subsystems:
24546 · Added a Texinfo builder.
24548 · Added i18n support for content, a gettext builder and related util‐
24550 ities.
24551 · Added the websupport library and builder.
24553 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
24555 source files containing autodoc directives to document modules and
24556 packages.
24557 · #273: Add an API for adding full-text search support for languages
24559 other than English. Add support for Japanese.
24560 · Markup:
24562 · #138: Added an index role, to make inline index entries.
24564 · #454: Added more index markup capabilities: marking see/seealso
24566 entries, and main entries for a given key.
24567 · #460: Allowed limiting the depth of section numbers for HTML using
24569 the toctree’s numbered option.
24570 · #586: Implemented improved glossary markup which allows multiple
24572 terms per definition.
24573 · #478: Added py:decorator directive to describe decorators.
24575 · C++ domain now supports array definitions.
24577 · C++ domain now supports doc fields (:param x: inside directives).
24579 · Section headings in only directives are now correctly handled.
24581 · Added emphasize-lines option to source code directives.
24583 · #678: C++ domain now supports superclasses.
24585 · HTML builder:
24587 · Added pyramid theme.
24589 · #559: html_add_permalinks is now a string giving the text to dis‐
24591 play in permalinks.
24592 · #259: HTML table rows now have even/odd CSS classes to enable
24594 “Zebra styling”.
24595 · #554: Add theme option sidebarwidth to the basic theme.
24597 · Other builders:
24599 · #516: Added new value of the latex_show_urls option to show the
24601 URLs in footnotes.
24602 · #209: Added text_newlines and text_sectionchars config values.
24604 · Added man_show_urls config value.
24606 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
24608 requests and allow configuring the timeout. New config values:
24609 linkcheck_timeout and linkcheck_workers.
24610 · #521: Added linkcheck_ignore config value.
24612 · #28: Support row/colspans in tables in the LaTeX builder.
24614 · Configuration and extensibility:
24616 · #537: Added nitpick_ignore.
24618 · #306: Added env-get-outdated event.
24620 · Application.add_stylesheet() now accepts full URIs.
24622 · Autodoc:
24624 · #564: Add autodoc_docstring_signature. When enabled (the default),
24626 autodoc retrieves the signature from the first line of the doc‐
24627 string, if it is found there.
24628 · #176: Provide private-members option for autodoc directives.
24630 · #520: Provide special-members option for autodoc directives.
24632 · #431: Doc comments for attributes can now be given on the same line
24634 as the assignment.
24635 · #437: autodoc now shows values of class data attributes.
24637 · autodoc now supports documenting the signatures of functools.par‐
24639 tial objects.
24640 · Other extensions:
24642 · Added the sphinx.ext.mathjax extension.
24644 · #443: Allow referencing external graphviz files.
24646 · Added inline option to graphviz directives, and fixed the default
24648 (block-style) in LaTeX output.
24649 · #590: Added caption option to graphviz directives.
24651 · #553: Added testcleanup blocks in the doctest extension.
24653 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
24655 · #367: Added automatic exclusion of hidden members in inheritance
24657 diagrams, and an option to selectively enable it.
24658 · Added pngmath_add_tooltips.
24660 · The math extension displaymath directives now support name in addi‐
24662 tion to label for giving the equation label, for compatibility with
24663 Docutils.
24664 · New locales:
24666 · #221: Added Swedish locale.
24668 · #526: Added Iranian locale.
24670 · #694: Added Latvian locale.
24672 · Added Nepali locale.
24674 · #714: Added Korean locale.
24676 · #766: Added Estonian locale.
24678 · Bugs fixed:
24680 · #778: Fix “hide search matches” link on pages linked by search.
24682 · Fix the source positions referenced by the “viewcode” extension.
24684 Release 1.0.8 (Sep 23, 2011)
24686 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
24687 · Fix the abbr role when the abbreviation has newlines in it.
24689 · #727: Fix the links to search results with custom object types.
24691 · #648: Fix line numbers reported in warnings about undefined refer‐
24693 ences.
24694 · #696, #666: Fix C++ array definitions and template arguments that are
24696 not type names.
24697 · #633: Allow footnotes in section headers in LaTeX output.
24699 · #616: Allow keywords to be linked via intersphinx.
24701 · #613: Allow Unicode characters in production list token names.
24703 · #720: Add dummy visitors for graphviz nodes for text and man.
24705 · #704: Fix image file duplication bug.
24707 · #677: Fix parsing of multiple signatures in C++ domain.
24709 · #637: Ignore Emacs lock files when looking for source files.
24711 · #544: Allow .pyw extension for importable modules in autodoc.
24713 · #700: Use $(MAKE) in quickstart-generated Makefiles.
24715 · #734: Make sidebar search box width consistent in browsers.
24717 · #644: Fix spacing of centered figures in HTML output.
24719 · #767: Safely encode SphinxError messages when printing them to
24721 sys.stderr.
24722 · #611: Fix LaTeX output error with a document with no sections but a
24724 link target.
24725 · Correctly treat built-in method descriptors as methods in autodoc.
24727 · #706: Stop monkeypatching the Python textwrap module.
24729 · #657: viewcode now works correctly with source files that have
24731 non-ASCII encoding.
24732 · #669: Respect the noindex flag option in py:module directives.
24734 · #675: Fix IndexErrors when including nonexisting lines with literal‐
24736 include.
24737 · #676: Respect custom function/method parameter separator strings.
24739 · #682: Fix JS incompatibility with jQuery >= 1.5.
24741 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
24743 · #647: Do not apply SmartyPants in parsed-literal blocks.
24745 · C++ domain now supports array definitions.
24747 Release 1.0.7 (Jan 15, 2011)
24749 · #347: Fix wrong generation of directives of static methods in auto‐
24750 summary.
24751 · #599: Import PIL as from PIL import Image.
24753 · #558: Fix longtables with captions in LaTeX output.
24755 · Make token references work as hyperlinks again in LaTeX output.
24757 · #572: Show warnings by default when reference labels cannot be found.
24759 · #536: Include line number when complaining about missing reference
24761 targets in nitpicky mode.
24762 · #590: Fix inline display of graphviz diagrams in LaTeX output.
24764 · #589: Build using app.build() in setup command.
24766 · Fix a bug in the inheritance diagram exception that caused base
24768 classes to be skipped if one of them is a builtin.
24769 · Fix general index links for C++ domain objects.
24771 · #332: Make admonition boundaries in LaTeX output visible.
24773 · #573: Fix KeyErrors occurring on rebuild after removing a file.
24775 · Fix a traceback when removing files with globbed toctrees.
24777 · If an autodoc object cannot be imported, always re-read the document
24779 containing the directive on next build.
24780 · If an autodoc object cannot be imported, show the full traceback of
24782 the import error.
24783 · Fix a bug where the removal of download files and images wasn’t
24785 noticed.
24786 · #571: Implement ~ cross-reference prefix for the C domain.
24788 · Fix regression of LaTeX output with the fix of #556.
24790 · #568: Fix lookup of class attribute documentation on descriptors so
24792 that comment documentation now works.
24793 · Fix traceback with only directives preceded by targets.
24795 · Fix tracebacks occurring for duplicate C++ domain objects.
24797 · Fix JavaScript domain links to objects with $ in their name.
24799 Release 1.0.6 (Jan 04, 2011)
24801 · #581: Fix traceback in Python domain for empty cross-reference tar‐
24802 gets.
24803 · #283: Fix literal block display issues on Chrome browsers.
24805 · #383, #148: Support sorting a limited range of accented characters in
24807 the general index and the glossary.
24808 · #570: Try decoding -D and -A command-line arguments with the locale’s
24810 preferred encoding.
24811 · #528: Observe locale_dirs when looking for the JS translations file.
24813 · #574: Add special code for better support of Japanese documents in
24815 the LaTeX builder.
24816 · Regression of #77: If there is only one parameter given with :param:
24818 markup, the bullet list is now suppressed again.
24819 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
24821 tions.
24822 · #567: Emit the autodoc-process-docstring event even for objects with‐
24824 out a docstring so that it can add content.
24825 · #565: In the LaTeX builder, not only literal blocks require different
24827 table handling, but also quite a few other list-like block elements.
24828 · #515: Fix tracebacks in the viewcode extension for Python objects
24830 that do not have a valid signature.
24831 · Fix strange reports of line numbers for warnings generated from
24833 autodoc-included docstrings, due to different behavior depending on
24834 docutils version.
24835 · Several fixes to the C++ domain.
24837 Release 1.0.5 (Nov 12, 2010)
24839 · #557: Add CSS styles required by docutils 0.7 for aligned images and
24840 figures.
24841 · In the Makefile generated by LaTeX output, do not delete pdf files on
24843 clean; they might be required images.
24844 · #535: Fix LaTeX output generated for line blocks.
24846 · #544: Allow .pyw as a source file extension.
24848 Release 1.0.4 (Sep 17, 2010)
24850 · #524: Open intersphinx inventories in binary mode on Windows, since
24851 version 2 contains zlib-compressed data.
24852 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
24854 JSMath extension.
24855 · #512: Fix traceback when intersphinx_mapping is empty.
24857 Release 1.0.3 (Aug 23, 2010)
24859 · #495: Fix internal vs. external link distinction for links coming
24860 from a docutils table-of-contents.
24861 · #494: Fix the maxdepth option for the toctree() template callable
24863 when used with collapse=True.
24864 · #507: Fix crash parsing Python argument lists containing brackets in
24866 string literals.
24867 · #501: Fix regression when building LaTeX docs with figures that don’t
24869 have captions.
24870 · #510: Fix inheritance diagrams for classes that are not picklable.
24872 · #497: Introduce separate background color for the sidebar collapse
24874 button, making it easier to see.
24875 · #502, #503, #496: Fix small layout bugs in several builtin themes.
24877 Release 1.0.2 (Aug 14, 2010)
24879 · #490: Fix cross-references to objects of types added by the
24880 add_object_type() API function.
24881 · Fix handling of doc field types for different directive types.
24883 · Allow breaking long signatures, continuing with backlash-escaped new‐
24885 lines.
24886 · Fix unwanted styling of C domain references (because of a namespace
24888 clash with Pygments styles).
24889 · Allow references to PEPs and RFCs with explicit anchors.
24891 · #471: Fix LaTeX references to figures.
24893 · #482: When doing a non-exact search, match only the given type of
24895 object.
24896 · #481: Apply non-exact search for Python reference targets with .name
24898 for modules too.
24899 · #484: Fix crash when duplicating a parameter in an info field list.
24901 · #487: Fix setting the default role to one provided by the oldcmarkup
24903 extension.
24904 · #488: Fix crash when json-py is installed, which provides a json mod‐
24906 ule but is incompatible to simplejson.
24907 · #480: Fix handling of target naming in intersphinx.
24909 · #486: Fix removal of ! for all cross-reference roles.
24911 Release 1.0.1 (Jul 27, 2010)
24913 · #470: Fix generated target names for reST domain objects; they are
24914 not in the same namespace.
24915 · #266: Add Bengali language.
24917 · #473: Fix a bug in parsing JavaScript object names.
24919 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
24921 · Fix display names for objects linked to by intersphinx with explicit
24923 targets.
24924 · Fix building with the JSON builder.
24926 · Fix hyperrefs in object descriptions for LaTeX.
24928 Release 1.0 (Jul 23, 2010)
24930 Incompatible changes
24931 · Support for domains has been added. A domain is a collection of
24932 directives and roles that all describe objects belonging together,
24933 e.g. elements of a programming language. A few builtin domains are
24934 provided:
24935 · Python
24937 · C
24939 · C++
24941 · JavaScript
24943 · reStructuredText
24945 · The old markup for defining and linking to C directives is now depre‐
24947 cated. It will not work anymore in future versions without activat‐
24948 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
24949 default.
24950 · Removed support for old dependency versions; requirements are now:
24952 · docutils >= 0.5
24954 · Jinja2 >= 2.2
24956 · Removed deprecated elements:
24958 · exclude_dirs config value
24960 · sphinx.builder module
24962 Features added
24964 · General:
24965 · Added a “nitpicky” mode that emits warnings for all missing refer‐
24967 ences. It is activated by the sphinx-build -n command-line switch
24968 or the nitpicky config value.
24969 · Added latexpdf target in quickstart Makefile.
24971 · Markup:
24973 · The menuselection and guilabel roles now support ampersand acceler‐
24975 ators.
24976 · New more compact doc field syntax is now recognized: :param type
24978 name: description.
24979 · Added tab-width option to literalinclude directive.
24981 · Added titlesonly option to toctree directive.
24983 · Added the prepend and append options to the literalinclude direc‐
24985 tive.
24986 · #284: All docinfo metadata is now put into the document metadata,
24988 not just the author.
24989 · The ref role can now also reference tables by caption.
24991 · The include directive now supports absolute paths, which are inter‐
24993 preted as relative to the source directory.
24994 · In the Python domain, references like :func:`.name` now look for
24996 matching names with any prefix if no direct match is found.
24997 · Configuration:
24999 · Added rst_prolog config value.
25001 · Added html_secnumber_suffix config value to control section number‐
25003 ing format.
25004 · Added html_compact_lists config value to control docutils’ compact
25006 lists feature.
25007 · The html_sidebars config value can now contain patterns as keys,
25009 and the values can be lists that explicitly select which sidebar
25010 templates should be rendered. That means that the builtin sidebar
25011 contents can be included only selectively.
25012 · html_static_path can now contain single file entries.
25014 · The new universal config value exclude_patterns makes the old
25016 unused_docs, exclude_trees and exclude_dirnames obsolete.
25017 · Added html_output_encoding config value.
25019 · Added the latex_docclass config value and made the “twoside” docu‐
25021 mentclass option overridable by “oneside”.
25022 · Added the trim_doctest_flags config value, which is true by
25024 default.
25025 · Added html_show_copyright config value.
25027 · Added latex_show_pagerefs and latex_show_urls config values.
25029 · The behavior of html_file_suffix changed slightly: the empty string
25031 now means “no suffix” instead of “default suffix”, use None for
25032 “default suffix”.
25033 · New builders:
25035 · Added a builder for the Epub format.
25037 · Added a builder for manual pages.
25039 · Added a single-file HTML builder.
25041 · HTML output:
25043 · Inline roles now get a CSS class with their name, allowing styles
25045 to customize their appearance. Domain-specific roles get two
25046 classes, domain and domain-rolename.
25047 · References now get the class internal if they are internal to the
25049 whole project, as opposed to internal to the current page.
25050 · External references can be styled differently with the new exter‐
25052 nalrefs theme option for the default theme.
25053 · In the default theme, the sidebar can experimentally now be made
25055 collapsible using the new collapsiblesidebar theme option.
25056 · #129: Toctrees are now wrapped in a div tag with class toc‐
25058 tree-wrapper in HTML output.
25059 · The toctree callable in templates now has a maxdepth keyword argu‐
25061 ment to control the depth of the generated tree.
25062 · The toctree callable in templates now accepts a titles_only keyword
25064 argument.
25065 · Added htmltitle block in layout template.
25067 · In the JavaScript search, allow searching for object names includ‐
25069 ing the module name, like sys.argv.
25070 · Added new theme haiku, inspired by the Haiku OS user guide.
25072 · Added new theme nature.
25074 · Added new theme agogo, created by Andi Albrecht.
25076 · Added new theme scrolls, created by Armin Ronacher.
25078 · #193: Added a visitedlinkcolor theme option to the default theme.
25080 · #322: Improved responsiveness of the search page by loading the
25082 search index asynchronously.
25083 · Extension API:
25085 · Added html-collect-pages.
25087 · Added needs_sphinx config value and require_sphinx() application
25089 API method.
25090 · #200: Added add_stylesheet() application API method.
25092 · Extensions:
25094 · Added the viewcode extension.
25096 · Added the extlinks extension.
25098 · Added support for source ordering of members in autodoc, with
25100 autodoc_member_order = 'bysource'.
25101 · Added autodoc_default_flags config value, which can be used to
25103 select default flags for all autodoc directives.
25104 · Added a way for intersphinx to refer to named labels in other
25106 projects, and to specify the project you want to link to.
25107 · #280: Autodoc can now document instance attributes assigned in
25109 __init__ methods.
25110 · Many improvements and fixes to the autosummary extension, thanks to
25112 Pauli Virtanen.
25113 · #309: The graphviz extension can now output SVG instead of PNG
25115 images, controlled by the graphviz_output_format config value.
25116 · Added alt option to graphviz extension directives.
25118 · Added exclude argument to autodoc.between().
25120 · Translations:
25122 · Added Croatian translation, thanks to Bojan Mihelač.
25124 · Added Turkish translation, thanks to Firat Ozgul.
25126 · Added Catalan translation, thanks to Pau Fernández.
25128 · Added simplified Chinese translation.
25130 · Added Danish translation, thanks to Hjorth Larsen.
25132 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
25134 · Bugs fixed:
25136 · #445: Fix links to result pages when using the search function of
25138 HTML built with the dirhtml builder.
25139 · #444: In templates, properly re-escape values treated with the
25141 “striptags” Jinja filter.
25142 Previous versions
25144 The changelog for versions before 1.0 can be found in the file
25145 CHANGES.old in the source distribution or at GitHub.
25146
25148 This is an (incomplete) alphabetic list of projects that use Sphinx or
25149 are experimenting with using it for their documentation. If you like
25150 to be included, please mail to the Google group.
25151 I’ve grouped the list into sections to make it easier to find interest‐
25153 ing examples.
25154 Documentation using the alabaster theme
25156 · Alabaster
25157 · Blinker
25159 · Calibre
25161 · Click (customized)
25163 · coala (customized)
25165 · CodePy
25167 · Eve (Python REST API framework)
25169 · Fabric
25171 · Fityk
25173 · Flask
25175 · Flask-OpenID
25177 · Invoke
25179 · Jinja
25181 · Lino (customized)
25183 · marbl
25185 · MDAnalysis (customized)
25187 · MeshPy
25189 · Molecule
25191 · PyCUDA
25193 · PyOpenCL
25195 · PyLangAcq
25197 · pytest (customized)
25199 · python-apt
25201 · PyVisfile
25203 · Requests
25205 · searx
25207 · Spyder (customized)
25209 · Tablib
25211 · urllib3 (customized)
25213 · Werkzeug (customized)
25215 Documentation using the classic theme
25217 · Advanced Generic Widgets (customized)
25218 · Apache CouchDB (customized)
25220 · APSW
25222 · Arb
25224 · Bazaar (customized)
25226 · Beautiful Soup
25228 · Blender
25230 · Bugzilla
25232 · Buildbot
25234 · CMake (customized)
25236 · Chaco (customized)
25238 · CORE
25240 · CORE Python modules
25242 · Cormoran
25244 · DEAP (customized)
25246 · Director
25248 · EZ-Draw (customized)
25250 · F2py
25252 · Generic Mapping Tools (GMT) (customized)
25254 · Genomedata
25256 · GetFEM++ (customized)
25258 · Glasgow Haskell Compiler (customized)
25260 · Grok (customized)
25262 · GROMACS
25264 · GSL Shell
25266 · Hands-on Python Tutorial
25268 · Kaa (customized)
25270 · Leo
25272 · LEPL (customized)
25274 · Mayavi (customized)
25276 · MediaGoblin (customized)
25278 · mpmath
25280 · OpenCV (customized)
25282 · OpenEXR
25284 · OpenGDA
25286 · Peach^3 (customized)
25288 · Plone (customized)
25290 · PyEMD
25292 · Pyevolve
25294 · Pygame (customized)
25296 · PyMQI
25298 · PyQt4 (customized)
25300 · PyQt5 (customized)
25302 · Python 2
25304 · Python 3 (customized)
25306 · Python Packaging Authority (customized)
25308 · Ring programming language (customized)
25310 · SageMath (customized)
25312 · Segway
25314 · simuPOP (customized)
25316 · Sprox (customized)
25318 · SymPy
25320 · TurboGears (customized)
25322 · tvtk
25324 · Varnish (customized, alabaster for index)
25326 · Waf
25328 · wxPython Phoenix (customized)
25330 · Yum
25332 · z3c
25334 · zc.async (customized)
25336 · Zope (customized)
25338 Documentation using the sphinxdoc theme
25340 · ABRT
25341 · cartopy
25343 · Jython
25345 · Matplotlib
25347 · MDAnalysis Tutorial
25349 · NetworkX
25351 · PyCantonese
25353 · Pyre
25355 · pySPACE
25357 · Pysparse
25359 · PyTango
25361 · Python Wild Magic (customized)
25363 · Reteisi (customized)
25365 · Sqlkit (customized)
25367 · Turbulenz
25369 Documentation using the nature theme
25371 · Alembic
25372 · Cython
25374 · easybuild
25376 · jsFiddle
25378 · libLAS (customized)
25380 · Lmod
25382 · MapServer (customized)
25384 · Pandas
25386 · pyglet (customized)
25388 · Setuptools
25390 · Spring Python
25392 · StatsModels (customized)
25394 · Sylli
25396 Documentation using another builtin theme
25398 · Breathe (haiku)
25399 · MPipe (sphinx13)
25401 · NLTK (agogo)
25403 · Programmieren mit PyGTK und Glade (German) (agogo, customized)
25405 · PyPubSub (bizstyle)
25407 · Pylons (pyramid)
25409 · Pyramid web framework (pyramid)
25411 · Sphinx (sphinx13) :-)
25413 · Valence (haiku, customized)
25415 Documentation using sphinx_rtd_theme
25417 · Annotator
25418 · Ansible (customized)
25420 · Arcade
25422 · aria2
25424 · ASE
25426 · Autofac
25428 · BigchainDB
25430 · Blocks
25432 · bootstrap-datepicker
25434 · Certbot
25436 · Chainer (customized)
25438 · CherryPy
25440 · cloud-init
25442 · CodeIgniter
25444 · Conda
25446 · Corda
25448 · Dask
25450 · Databricks (customized)
25452 · Dataiku DSS
25454 · DNF
25456 · edX
25458 · Electrum
25460 · Elemental
25462 · ESWP3
25464 · Ethereum Homestead
25466 · Faker
25468 · Fidimag
25470 · Flake8
25472 · Flatpak
25474 · FluidDyn
25476 · Fluidsim
25478 · GeoNode
25480 · Glances
25482 · Godot
25484 · Graylog
25486 · GPAW (customized)
25488 · HDF5 for Python (h5py)
25490 · Hyperledger Fabric
25492 · Hyperledger Sawtooth
25494 · IdentityServer
25496 · Idris
25498 · javasphinx
25500 · Julia
25502 · Jupyter Notebook
25504 · Lasagne
25506 · latexindent.pl
25508 · Linguistica
25510 · Linux kernel
25512 · MathJax
25514 · MDTraj (customized)
25516 · MICrobial Community Analysis (micca)
25518 · MicroPython
25520 · Minds (customized)
25522 · Mink
25524 · Mockery
25526 · mod_wsgi
25528 · MoinMoin
25530 · Mopidy
25532 · MyHDL
25534 · Nextflow
25536 · NICOS (customized)
25538 · Pelican
25540 · picamera
25542 · Pillow
25544 · pip
25546 · Paver
25548 · peewee
25550 · Phinx
25552 · phpMyAdmin
25554 · PROS (customized)
25556 · Pushkin
25558 · Pweave
25560 · PyPy
25562 · python-sqlparse
25564 · PyVISA
25566 · Read The Docs
25568 · Free your information from their silos (French) (customized)
25570 · Releases Sphinx extension
25572 · Qtile
25574 · Quex
25576 · QuTiP
25578 · Satchmo
25580 · Scapy
25582 · SimGrid
25584 · SimPy
25586 · six
25588 · SlamData
25590 · Solidity
25592 · Sonos Controller (SoCo)
25594 · Sphinx AutoAPI
25596 · sphinx-argparse
25598 · Sphinx-Gallery (customized)
25600 · SpotBugs
25602 · StarUML
25604 · Sublime Text Unofficial Documentation
25606 · SunPy
25608 · Sylius
25610 · Syncthing
25612 · Tango Controls (customized)
25614 · Topshelf
25616 · Theano
25618 · ThreatConnect
25620 · Tuleap
25622 · TYPO3 (customized)
25624 · Veyon
25626 · uWSGI
25628 · virtualenv
25630 · Wagtail
25632 · Web Application Attack and Audit Framework (w3af)
25634 · Weblate
25636 · x265
25638 · ZeroNet
25640 · Zulip
25642 Documentation using sphinx_bootstrap_theme
25644 · Bootstrap Theme
25645 · C/C++ Software Development with Eclipse
25647 · Dataverse
25649 · e-cidadania
25651 · Hangfire
25653 · Hedge
25655 · ObsPy
25657 · Open Dylan
25659 · Pootle
25661 · PyUblas
25663 · seaborn
25665 Documentation using a custom theme or integrated in a website
25667 · Apache Cassandra
25668 · Astropy
25670 · Bokeh
25672 · Boto 3
25674 · CakePHP
25676 · CasperJS
25678 · Ceph
25680 · Chef
25682 · CKAN
25684 · Confluent Platform
25686 · Django
25688 · Doctrine
25690 · Enterprise Toolkit for Acrobat products
25692 · Gameduino
25694 · gensim
25696 · GeoServer
25698 · gevent
25700 · GHC - Glasgow Haskell Compiler
25702 · Guzzle
25704 · H2O.ai
25706 · Heka
25708 · Istihza (Turkish Python documentation project)
25710 · Kombu
25712 · Lasso
25714 · Mako
25716 · MirrorBrain
25718 · MongoDB
25720 · Music21
25722 · MyHDL
25724 · nose
25726 · ns-3
25728 · NumPy
25730 · ObjectListView
25732 · OpenERP
25734 · OpenCV
25736 · OpenLayers
25738 · OpenTURNS
25740 · Open vSwitch
25742 · PlatformIO
25744 · PyEphem
25746 · Pygments
25748 · Plone User Manual (German)
25750 · PSI4
25752 · PyMOTW
25754 · python-aspectlib (sphinx_py3doc_enhanced_theme)
25756 · QGIS
25758 · qooxdoo
25760 · Roundup
25762 · SaltStack
25764 · scikit-learn
25766 · SciPy
25768 · Scrapy
25770 · Seaborn
25772 · Selenium
25774 · Self
25776 · Substance D
25778 · Sulu
25780 · SQLAlchemy
25782 · tinyTiM
25784 · Twisted
25786 · Ubuntu Packaging Guide
25788 · WebFaction
25790 · WTForms
25792 Homepages and other non-documentation sites
25794 · Arizona State University PHY494/PHY598/CHM598 Simulation approaches
25795 to Bio-and Nanophysics (classic)
25796 · Benoit Boissinot (classic, customized)
25798 · Computer Networks, Parallelization, and Simulation Laboratory
25800 (CNPSLab) (sphinx_rtd_theme)
25801 · Deep Learning Tutorials (sphinxdoc)
25803 · Eric Holscher (alabaster)
25805 · Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
25807 · Loyola University Chicago COMP 339-439 Distributed Systems course
25809 (sphinx_bootstrap_theme)
25810 · Pylearn2 (sphinxdoc, customized)
25812 · PyXLL (sphinx_bootstrap_theme, customized)
25814 · SciPy Cookbook (sphinx_rtd_theme)
25816 · The Wine Cellar Book (sphinxdoc)
25818 · Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
25820 (standard)
25821 · UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
25823 · Željko Svedružić’s Biomolecular Structure and Function Laboratory
25825 (BioSFLab) (sphinx_bootstrap_theme)
25826 Books produced using Sphinx
25828 · “The Art of Community” (Japanese translation)
25829 · “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
25831 · “Expert Python Programming”
25833 · “Expert Python Programming” (Japanese translation)
25835 · “Expert Python Programming 2nd Edition” (Japanese translation)
25837 · “The Hitchhiker’s Guide to Python”
25839 · “LassoGuide”
25841 · “Learning Sphinx” (in Japanese)
25843 · “Learning System Programming with Go (Japanese)”
25845 · “Mercurial: the definitive guide (Second edition)”
25847 · “Mithril – The fastest clientside MVC (Japanese)”
25849 · “Pioneers and Prominent Men of Utah”
25851 · “Pomodoro Technique Illustrated” (Japanese translation)
25853 · “Professional Software Development”
25855 · “Python Professional Programming” (in Japanese)
25857 · “Python Professional Programming 2nd Edition” (in Japanese)
25859 · “Python Professional Programming 3rd Edition” (in Japanese)
25861 · “Real World HTTP – Learning The Internet and Web Technology via its
25863 history and code (Japanese)”
25864 · “Redmine Primer 5th Edition (in Japanese)”
25866 · “The repoze.bfg Web Application Framework”
25868 · “The Self-Taught Programmer” (Japanese translation)
25870 · “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
25872 panese)
25873 · “Software-Dokumentation mit Sphinx”
25875 · “Theoretical Physics Reference”
25877 · “The Varnish Book”
25879 Theses produced using Sphinx
25881 · “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
25882 the Use of CouchDB”
25883 · “Content Conditioning and Distribution for Dynamic Virtual Worlds”
25885 · “The Sphinx Thesis Resource”
25887 Projects integrating Sphinx functionality
25889 · Read the Docs, a software-as-a-service documentation hosting plat‐
25890 form, uses Sphinx to automatically build documentation updates that
25891 are pushed to GitHub.
25892 · Spyder, the Scientific Python Development Environment, uses Sphinx in
25894 its help pane to render rich documentation for functions, classes and
25895 methods automatically or on-demand.
25896
25898 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
25899 Substantial parts of the templates were written by Armin Ronacher <‐
25901 armin.ronacher@active-4.com>.
25902 Other co-maintainers:
25904 · Takayuki Shimizukawa <shimizukawa@gmail.com>
25906 · Daniel Neuhäuser <@DasIch>
25908 · Jon Waltman <@jonwaltman>
25910 · Rob Ruana <@RobRuana>
25912 · Robert Lehmann <@lehmannro>
25914 · Roland Meister <@rolmei>
25916 · Takeshi Komiya <@tk0miya>
25918 · Jean-François Burnol <@jfbu>
25920 · Yoshiki Shibukawa <@shibu_jp>
25922 · Timotheus Kampik - <@TimKam>
25924 Other contributors, listed alphabetically, are:
25926 · Alastair Houghton – Apple Help builder
25928 · Alexander Todorov – inheritance_diagram tests and improvements
25930 · Andi Albrecht – agogo theme
25932 · Jakob Lykke Andersen – Rewritten C++ domain
25934 · Henrique Bastos – SVG support for graphviz extension
25936 · Daniel Bültmann – todo extension
25938 · Marco Buttu – doctest extension (pyversion option)
25940 · Nathan Damon – bugfix in validation of static paths in html builders
25942 · Etienne Desautels – apidoc module
25944 · Michael Droettboom – inheritance_diagram extension
25946 · Charles Duffy – original graphviz extension
25948 · Kevin Dunn – MathJax extension
25950 · Josip Dzolonga – coverage builder
25952 · Buck Evan – dummy builder
25954 · Matthew Fernandez – todo extension fix
25956 · Hernan Grecco – search improvements
25958 · Horst Gutmann – internationalization support
25960 · Martin Hans – autodoc improvements
25962 · Zac Hatfield-Dodds – doctest reporting improvements
25964 · Doug Hellmann – graphviz improvements
25966 · Tim Hoffmann – theme improvements
25968 · Antti Kaihola – doctest extension (skipif option)
25970 · Dave Kuhlman – original LaTeX writer
25972 · Blaise Laflamme – pyramid theme
25974 · Chris Lamb – reproducibility fixes
25976 · Thomas Lamb – linkcheck builder
25978 · Łukasz Langa – partial support for autodoc
25980 · Martin Larralde – additional napoleon admonitions
25982 · Ian Lee – quickstart improvements
25984 · Robert Lehmann – gettext builder (GSOC project)
25986 · Dan MacKinlay – metadata fixes
25988 · Martin Mahner – nature theme
25990 · Will Maier – directory HTML builder
25992 · Jacob Mason – websupport library (GSOC project)
25994 · Glenn Matthews – python domain signature improvements
25996 · Kurt McKee – documentation updates
25998 · Roland Meister – epub builder
26000 · Ezio Melotti – collapsible sidebar JavaScript
26002 · Bruce Mitchener – Minor epub improvement
26004 · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
26006 · Julien Palard – Colspan and rowspan in text builder
26008 · Christopher Perkins – autosummary integration
26010 · Benjamin Peterson – unittests
26012 · T. Powers – HTML output improvements
26014 · Jeppe Pihl – literalinclude improvements
26016 · Rob Ruana – napoleon extension
26018 · Stefan Seefeld – toctree improvements
26020 · Gregory Szorc – performance improvements
26022 · Taku Shimizu – epub3 builder
26024 · Antonio Valentino – qthelp builder, docstring inheritance
26026 · Filip Vavera – napoleon todo directive
26028 · Pauli Virtanen – autodoc improvements, autosummary extension
26030 · Eric N. Vander Weele – autodoc improvements
26032 · Stefan van der Walt – autosummary extension
26034 · Thomas Waldmann – apidoc module fixes
26036 · John Waltman – Texinfo builder
26038 · Barry Warsaw – setup command improvements
26040 · Sebastian Wiesner – image handling, distutils support
26042 · Michael Wilson – Intersphinx HTTP basic auth support
26044 · Matthew Woodcraft – text output improvements
26046 · Joel Wurtz – cellspanning support in LaTeX
26048 · Hong Xu – svg support in imgmath extension and various bug fixes
26050 · Stephen Finucane – setup command improvements and documentation
26052 · Daniel Pizetta – inheritance diagram improvements
26054 · KINEBUCHI Tomohiko – typing Sphinx as well as docutils
26056 · Adrián Chaves (Gallaecio) – coverage builder improvements
26058 Many thanks for all contributions!
26060 There are also a few modules or functions incorporated from other
26062 authors and projects:
26063 · sphinx.util.jsdump uses the basestring encoding from simplejson,
26065 written by Bob Ippolito, released under the MIT license
26066 · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
26068 Domain
26069 · modindex
26071 · glossary
26073
26075 Georg Brandl
26076
26078 2007-2020, Georg Brandl and the Sphinx team
260792.2.2 Jan 30, 2020 SPHINX-ALL(1)