1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 · Overview
10 · Linux
12 · macOS
14 · Windows
16 · Installation from PyPI
18 · Installation from source
20 Overview
22 Sphinx is written in Python and supports both Python 2.7 and Python
23 3.3+. We recommend the latter.
24 Linux
26 Debian/Ubuntu
27 Install either python3-sphinx (Python 3) or python-sphinx (Python 2)
28 using apt-get:
29 $ apt-get install python3-sphinx
31 If it not already present, this will install Python for you.
33 RHEL, CentOS
35 Install python-sphinx using yum:
36 $ yum install python-sphinx
38 If it not already present, this will install Python for you.
40 Other distributions
42 Most Linux distributions have Sphinx in their package repositories.
43 Usually the package is called python3-sphinx, python-sphinx or sphinx.
44 Be aware that there are at least two other packages with sphinx in
45 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
46 search database (Sphinx search).
47 macOS
49 Sphinx can be installed using Homebrew, MacPorts, or as part of a
50 Python distribution such as Anaconda.
51 Homebrew
53 $ brew install sphinx-doc
54 For more information, refer to the package overview.
56 MacPorts
58 Install either python36-sphinx (Python 3) or python27-sphinx (Python 2)
59 using port:
60 $ sudo port install py36-sphinx
62 To set up the executable paths, use the port select command:
64 $ sudo port select --set python python36
66 $ sudo port select --set sphinx py36-sphinx
67 For more information, refer to the package overview.
69 Anaconda
71 $ conda install sphinx
72 Windows
74 Todo
75 Could we start packaging this?
76 Most Windows users do not have Python installed by default, so we begin
78 with the installation of Python itself. If you are unsure, open the
79 Command Prompt (⊞Win-r and type cmd). Once the command prompt is open,
80 type python --version and press Enter. If Python is available, you
81 will see the version of Python printed to the screen. If you do not
82 have Python installed, refer to the Hitchhikers Guide to Python’s
83 Python on Windows installation guides. You can install either Python 3
84 or Python 2.7. Python 3 is recommended.
85 Once Python is installed, you can install Sphinx using pip. Refer to
87 the pip installation instructions below for more information.
88 Installation from PyPI
90 Sphinx packages are published on the Python Package Index. The pre‐
91 ferred tool for installing packages from PyPI is pip. This tool is
92 provided with all modern versions of Python.
93 On Linux or MacOS, you should open your terminal and run the following
95 command.
96 $ pip install -U sphinx
98 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
100 run the same command.
101 C:\> pip install -U sphinx
103 After installation, type sphinx-build --version on the command prompt.
105 If everything worked fine, you will see the version number for the
106 Sphinx package you just installed.
107 Installation from PyPI also allows you to install the latest develop‐
109 ment release. You will not generally need (or want) to do this, but it
110 can be useful if you see a possible bug in the latest stable release.
111 To do this, use the --pre flag.
112 $ pip install -U --pre sphinx
114 Installation from source
116 You can install Sphinx directly from a clone of the Git repository.
117 This can be done either by cloning the repo and installing from the
118 local clone, on simply installing directly via git.
119 $ git clone https://github.com/sphinx-doc/sphinx
121 $ cd sphinx
122 $ pip install .
123 $ pip install git+https://github.com/sphinx-doc/sphinx
125 You can also download a snapshot of the Git repo in either tar.gz or
127 zip format. Once downloaded and extracted, these can be installed with
128 pip as above.
129
131 Once Sphinx is installed, you can proceed with setting up your first
132 Sphinx project. To ease the process of getting started, Sphinx provides
133 a tool, sphinx-quickstart, which will generate a documentation source
134 directory and populate it with some defaults. We’re going to use the
135 sphinx-quickstart tool here, though it’s use by no means necessary.
136 Setting up the documentation sources
138 The root directory of a Sphinx collection of reStructuredText document
139 sources is called the source directory. This directory also contains
140 the Sphinx configuration file conf.py, where you can configure all
141 aspects of how Sphinx reads your sources and builds your documentation.
142 [1]
143 Sphinx comes with a script called sphinx-quickstart that sets up a
145 source directory and creates a default conf.py with the most useful
146 configuration values from a few questions it asks you. To use this,
147 run:
148 $ sphinx-quickstart
150 Answer each question asked. Be sure to say yes to the autodoc exten‐
152 sion, as we will use this later.
153 There is also an automatic “API documentation” generator called
155 sphinx-apidoc; see /man/sphinx-apidoc for details.
156 Defining document structure
158 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
159 tory with conf.py and a master document, index.rst (if you accepted the
160 defaults). The main function of the master document is to serve as a
161 welcome page, and to contain the root of the “table of contents tree”
162 (or toctree). This is one of the main things that Sphinx adds to
163 reStructuredText, a way to connect multiple files to a single hierarchy
164 of documents.
165 reStructuredText directives
167 toctree is a reStructuredText directive, a very versatile piece of
168 markup. Directives can have arguments, options and content.
169 Arguments are given directly after the double colon following the
171 directive’s name. Each directive decides whether it can have argu‐
172 ments, and how many.
173 Options are given after the arguments, in form of a “field list”. The
175 maxdepth is such an option for the toctree directive.
176 Content follows the options or arguments after a blank line. Each
178 directive decides whether to allow content, and what to do with it.
179 A common gotcha with directives is that the first line of the content
181 must be indented to the same level as the options are.
182 The toctree directive initially is empty, and looks like so:
184 .. toctree::
186 :maxdepth: 2
187 You add documents listing them in the content of the directive:
189 .. toctree::
191 :maxdepth: 2
192 usage/installation
194 usage/quickstart
195 ...
196 This is exactly how the toctree for this documentation looks. The doc‐
198 uments to include are given as document names, which in short means
199 that you leave off the file name extension and use forward slashes (/)
200 as directory separators.
201 [image: more info] [image]
203 Read more about the toctree directive.
204 You can now create the files you listed in the toctree and add content,
206 and their section titles will be inserted (up to the maxdepth level) at
207 the place where the toctree directive is placed. Also, Sphinx now
208 knows about the order and hierarchy of your documents. (They may con‐
209 tain toctree directives themselves, which means you can create deeply
210 nested hierarchies if necessary.)
211 Adding content
213 In Sphinx source files, you can use most features of standard reStruc‐
214 turedText. There are also several features added by Sphinx. For exam‐
215 ple, you can add cross-file references in a portable way (which works
216 for all output types) using the ref role.
217 For an example, if you are viewing the HTML version you can look at the
219 source for this document – use the “Show Source” link in the sidebar.
220 Todo
222 Update the below link when we add new guides on these.
223 [image: more info] [image]
225 See /usage/restructuredtext/index for a more in-depth introduction to
226 reStructuredText, including markup added by Sphinx.
227 Running the build
229 Now that you have added some files and content, let’s make a first
230 build of the docs. A build is started with the sphinx-build program:
231 $ sphinx-build -b html sourcedir builddir
233 where sourcedir is the source directory, and builddir is the directory
235 in which you want to place the built documentation. The -b option
236 selects a builder; in this example Sphinx will build HTML files.
237 [image: more info] [image]
239 Refer to the sphinx-build man page for all options that sphinx-build
240 supports.
241 However, sphinx-quickstart script creates a Makefile and a make.bat
243 which make life even easier for you. These can be executed by running
244 make with the name of the builder. For example.
245 $ make html
247 This will build HTML docs in the build directory you chose. Execute
249 make without an argument to see which targets are available.
250 How do I generate PDF documents?
252 make latexpdf runs the LaTeX builder and readily invokes the
254 pdfTeX toolchain for you.
255 Todo
257 Move this whole section into a guide on rST or directives
258 Documenting objects
260 One of Sphinx’s main objectives is easy documentation of objects (in a
261 very general sense) in any domain. A domain is a collection of object
262 types that belong together, complete with markup to create and refer‐
263 ence descriptions of these objects.
264 The most prominent domain is the Python domain. For example, to docu‐
266 ment Python’s built-in function enumerate(), you would add this to one
267 of your source files.
268 .. py:function:: enumerate(sequence[, start=0])
270 Return an iterator that yields tuples of an index and an item of the
272 *sequence*. (And so on.)
273 This is rendered like this:
275 enumerate(sequence[, start=0])
277 Return an iterator that yields tuples of an index and an item of
278 the sequence. (And so on.)
279 The argument of the directive is the signature of the object you
281 describe, the content is the documentation for it. Multiple signatures
282 can be given, each in its own line.
283 The Python domain also happens to be the default domain, so you don’t
285 need to prefix the markup with the domain name.
286 .. function:: enumerate(sequence[, start=0])
288 ...
290 does the same job if you keep the default setting for the default
292 domain.
293 There are several more directives for documenting other types of Python
295 objects, for example py:class or py:method. There is also a cross-ref‐
296 erencing role for each of these object types. This markup will create
297 a link to the documentation of enumerate().
298 The :py:func:`enumerate` function can be used for ...
300 And here is the proof: A link to enumerate().
302 Again, the py: can be left out if the Python domain is the default one.
304 It doesn’t matter which file contains the actual documentation for enu‐
305 merate(); Sphinx will find it and create a link to it.
306 Each domain will have special rules for how the signatures can look
308 like, and make the formatted output look pretty, or add specific fea‐
309 tures like links to parameter types, e.g. in the C/C++ domains.
310 [image: more info] [image]
312 See /usage/restructuredtext/domains for all the available domains and
313 their directives/roles.
314 Basic configuration
316 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
317 cesses your documents. In that file, which is executed as a Python
318 source file, you assign configuration values. For advanced users:
319 since it is executed by Sphinx, you can do non-trivial tasks in it,
320 like extending sys.path or importing a module to find out the version
321 you are documenting.
322 The config values that you probably want to change are already put into
324 the conf.py by sphinx-quickstart and initially commented out (with
325 standard Python syntax: a # comments the rest of the line). To change
326 the default value, remove the hash sign and modify the value. To cus‐
327 tomize a config value that is not automatically added by sphinx-quick‐
328 start, just add an additional assignment.
329 Keep in mind that the file uses Python syntax for strings, numbers,
331 lists and so on. The file is saved in UTF-8 by default, as indicated
332 by the encoding declaration in the first line. If you use non-ASCII
333 characters in any string value, you need to use Python Unicode strings
334 (like project = u'Exposé').
335 [image: more info] [image]
337 See /usage/configuration for documentation of all available config
338 values.
339 Todo
341 Move this entire doc to a different section
342 Autodoc
344 When documenting Python code, it is common to put a lot of documenta‐
345 tion in the source files, in documentation strings. Sphinx supports
346 the inclusion of docstrings from your modules with an extension (an
347 extension is a Python module that provides additional features for
348 Sphinx projects) called autodoc.
349 In order to use autodoc, you need to activate it in conf.py by putting
351 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
352 sions config value. Then, you have a few additional directives at your
353 disposal.
354 For example, to document the function io.open(), reading its signature
356 and docstring from the source file, you’d write this:
357 .. autofunction:: io.open
359 You can also document whole classes or even modules automatically,
361 using member options for the auto directives, like
362 .. automodule:: io
364 :members:
365 autodoc needs to import your modules in order to extract the doc‐
367 strings. Therefore, you must add the appropriate path to sys.path in
368 your conf.py.
369 WARNING:
371 autodoc imports the modules to be documented. If any modules have
372 side effects on import, these will be executed by autodoc when
373 sphinx-build is run.
374 If you document scripts (as opposed to library modules), make sure
376 their main routine is protected by a if __name__ == '__main__' con‐
377 dition.
378 [image: more info] [image]
380 See sphinx.ext.autodoc for the complete description of the features of
381 autodoc.
382 Todo
384 Move this doc to another section
385 Intersphinx
387 Many Sphinx documents including the Python documentation are published
388 on the internet. When you want to make links to such documents from
389 your documentation, you can do it with sphinx.ext.intersphinx.
390 In order to use intersphinx, you need to activate it in conf.py by
392 putting the string 'sphinx.ext.intersphinx' into the extensions list
393 and set up the intersphinx_mapping config value.
394 For example, to link to io.open() in the Python library manual, you
396 need to setup your intersphinx_mapping like:
397 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
399 And now, you can write a cross-reference like :py:func:`io.open`. Any
401 cross-reference that has no matching target in the current documenta‐
402 tion set, will be looked up in the documentation sets configured in
403 intersphinx_mapping (this needs access to the URL in order to download
404 the list of valid targets). Intersphinx also works for some other
405 domain’s roles including :ref:, however it doesn’t work for :doc: as
406 that is non-domain role.
407 [image: more info] [image]
409 See sphinx.ext.intersphinx for the complete description of the fea‐
410 tures of intersphinx.
411 More topics to be covered
413 · Other extensions:
414 · Static files
416 · Selecting a theme
418 · /setuptools
420 · Templating
422 · Using extensions
424 · Writing extensions
426
428 [1] This is the usual layout. However, conf.py can also live in
429 another directory, the configuration directory. Refer to the
430 sphinx-build man page for more information.
431
433 reStructuredText (reST) is the default plaintext markup language used
434 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
435 Text syntax, while Sphinx extends this to support additional function‐
436 ality.
437 The below guides go through the most important aspects of reST. For the
439 authoritative reStructuredText reference, refer to the docutils docu‐
440 mentation.
441 reStructuredText Primer
443 reStructuredText is the default plaintext markup language used by
444 Sphinx. This section is a brief introduction to reStructuredText
445 (reST) concepts and syntax, intended to provide authors with enough
446 information to author documents productively. Since reST was designed
447 to be a simple, unobtrusive markup language, this will not take too
448 long.
449 SEE ALSO:
451 The authoritative reStructuredText User Documentation. The “ref”
452 links in this document link to the description of the individual
453 constructs in the reST reference.
454 Paragraphs
456 The paragraph (ref) is the most basic block in a reST document. Para‐
457 graphs are simply chunks of text separated by one or more blank lines.
458 As in Python, indentation is significant in reST, so all lines of the
459 same paragraph must be left-aligned to the same level of indentation.
460 Inline markup
462 The standard reST inline markup is quite simple: use
463 · one asterisk: *text* for emphasis (italics),
465 · two asterisks: **text** for strong emphasis (boldface), and
467 · backquotes: ``text`` for code samples.
469 If asterisks or backquotes appear in running text and could be confused
471 with inline markup delimiters, they have to be escaped with a back‐
472 slash.
473 Be aware of some restrictions of this markup:
475 · it may not be nested,
477 · content may not start or end with whitespace: * text* is wrong,
479 · it must be separated from surrounding text by non-word characters.
481 Use a backslash escaped space to work around that: thisis\ *one*\
482 word.
483 These restrictions may be lifted in future versions of the docutils.
485 It is also possible to replace or expand upon some of this inline
487 markup with roles. Refer to Roles for more information.
488 Lists and Quote-like blocks
490 List markup (ref) is natural: just place an asterisk at the start of a
491 paragraph and indent properly. The same goes for numbered lists; they
492 can also be autonumbered using a # sign:
493 * This is a bulleted list.
495 * It has two items, the second
496 item uses two lines.
497 1. This is a numbered list.
499 2. It has two items too.
500 #. This is a numbered list.
502 #. It has two items too.
503 Nested lists are possible, but be aware that they must be separated
505 from the parent list items by blank lines:
506 * this is
508 * a list
509 * with a nested list
511 * and some subitems
512 * and here the parent list continues
514 Definition lists (ref) are created as follows:
516 term (up to a line of text)
518 Definition of the term, which must be indented
519 and can even consist of multiple paragraphs
521 next term
523 Description.
524 Note that the term cannot have more than one line of text.
526 Quoted paragraphs (ref) are created by just indenting them more than
528 the surrounding paragraphs.
529 Line blocks (ref) are a way of preserving line breaks:
531 | These lines are
533 | broken exactly like in
534 | the source file.
535 There are also several more special blocks available:
537 · field lists (ref, with caveats noted in Field Lists)
539 · option lists (ref)
541 · quoted literal blocks (ref)
543 · doctest blocks (ref)
545 Literal blocks
547 Literal code blocks (ref) are introduced by ending a paragraph with the
548 special marker ::. The literal block must be indented (and, like all
549 paragraphs, separated from the surrounding ones by blank lines):
550 This is a normal text paragraph. The next paragraph is a code sample::
552 It is not processed in any way, except
554 that the indentation is removed.
555 It can span multiple lines.
557 This is a normal text paragraph again.
559 The handling of the :: marker is smart:
561 · If it occurs as a paragraph of its own, that paragraph is completely
563 left out of the document.
564 · If it is preceded by whitespace, the marker is removed.
566 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
568 gle colon.
569 That way, the second sentence in the above example’s first paragraph
571 would be rendered as “The next paragraph is a code sample:”.
572 Code highlighting can be enabled for these literal blocks on a docu‐
574 ment-wide basis using the highlight directive and on a project-wide
575 basis using the highlight_language configuration option. The code-block
576 directive can be used to set highlighting on a block-by-block basis.
577 These directives are discussed later.
578 Doctest blocks
580 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
581 into docstrings. They do not require the literal blocks syntax. The
582 doctest block must end with a blank line and should not end with with
583 an unused prompt:
584 >>> 1 + 1
586 2
587 Tables
589 For grid tables (ref), you have to “paint” the cell grid yourself.
590 They look like this:
591 +------------------------+------------+----------+----------+
593 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
594 | (header rows optional) | | | |
595 +========================+============+==========+==========+
596 | body row 1, column 1 | column 2 | column 3 | column 4 |
597 +------------------------+------------+----------+----------+
598 | body row 2 | ... | ... | |
599 +------------------------+------------+----------+----------+
600 Simple tables (ref) are easier to write, but limited: they must contain
602 more than one row, and the first column cells cannot contain multiple
603 lines. They look like this:
604 ===== ===== =======
606 A B A and B
607 ===== ===== =======
608 False False False
609 True False False
610 False True False
611 True True True
612 ===== ===== =======
613 Two more syntaxes are supported: CSV tables and List tables. They use
615 an explicit markup block. Refer to table-directives for more informa‐
616 tion.
617 Hyperlinks
619 External links
620 Use `Link text <https://domain.invalid/>`_ for inline web links. If
621 the link text should be the web address, you don’t need special markup
622 at all, the parser finds links and mail addresses in ordinary text.
623 IMPORTANT:
625 There must be a space between the link text and the opening < for
626 the URL.
627 You can also separate the link and the target definition (ref), like
629 this:
630 This is a paragraph that contains `a link`_.
632 .. _a link: https://domain.invalid/
634 Internal links
636 Internal linking is done via a special reST role provided by Sphinx,
637 see the section on specific markup, ref-role.
638 Sections
640 Section headers (ref) are created by underlining (and optionally over‐
641 lining) the section title with a punctuation character, at least as
642 long as the text:
643 =================
645 This is a heading
646 =================
647 Normally, there are no heading levels assigned to certain characters as
649 the structure is determined from the succession of headings. However,
650 this convention is used in Python’s Style Guide for documenting which
651 you may follow:
652 · # with overline, for parts
654 · * with overline, for chapters
656 · =, for sections
658 · -, for subsections
660 · ^, for subsubsections
662 · ", for paragraphs
664 Of course, you are free to use your own marker characters (see the reST
666 documentation), and use a deeper nesting level, but keep in mind that
667 most target formats (HTML, LaTeX) have a limited supported nesting
668 depth.
669 Field Lists
671 Field lists (ref) are sequences of fields marked up like this:
672 :fieldname: Field content
674 They are commonly used in Python documentation:
676 def my_function(my_arg, my_other_arg):
678 """A function just for me.
679 :param my_arg: The first of my arguments.
681 :param my_other_arg: The second of my arguments.
682 :returns: A message (just for me, of course).
684 """
685 Sphinx extends standard docutils behavior and intercepts field lists
687 specified at the beginning of documents. Refer to field-lists for more
688 information.
689 Roles
691 A role or “custom interpreted text role” (ref) is an inline piece of
692 explicit markup. It signifies that that the enclosed text should be
693 interpreted in a specific way. Sphinx uses this to provide semantic
694 markup and cross-referencing of identifiers, as described in the appro‐
695 priate section. The general syntax is :rolename:`content`.
696 Docutils supports the following roles:
698 · emphasis – equivalent of *emphasis*
700 · strong – equivalent of **strong**
702 · literal – equivalent of ``literal``
704 · subscript – subscript text
706 · superscript – superscript text
708 · title-reference – for titles of books, periodicals, and other materi‐
710 als
711 Refer to roles for roles added by Sphinx.
713 Explicit Markup
715 “Explicit markup” (ref) is used in reST for most constructs that need
716 special handling, such as footnotes, specially-highlighted paragraphs,
717 comments, and generic directives.
718 An explicit markup block begins with a line starting with .. followed
720 by whitespace and is terminated by the next paragraph at the same level
721 of indentation. (There needs to be a blank line between explicit
722 markup and normal paragraphs. This may all sound a bit complicated,
723 but it is intuitive enough when you write it.)
724 Directives
726 A directive (ref) is a generic block of explicit markup. Along with
727 roles, it is one of the extension mechanisms of reST, and Sphinx makes
728 heavy use of it.
729 Docutils supports the following directives:
731 · Admonitions: attention, caution, danger, error, hint, important,
733 note, tip, warning and the generic admonition. (Most themes style
734 only “note” and “warning” specially.)
735 · Images:
737 · image (see also Images below)
739 · figure (an image with caption and optional legend)
741 · Additional body elements:
743 · contents (a local, i.e. for the current file only, table of con‐
745 tents)
746 · container (a container with a custom class, useful to generate an
748 outer <div> in HTML)
749 · rubric (a heading without relation to the document sectioning)
751 · topic, sidebar (special highlighted body elements)
753 · parsed-literal (literal block that supports inline markup)
755 · epigraph (a block quote with optional attribution line)
757 · highlights, pull-quote (block quotes with their own class
759 attribute)
760 · compound (a compound paragraph)
762 · Special tables:
764 · table (a table with title)
766 · csv-table (a table generated from comma-separated values)
768 · list-table (a table generated from a list of lists)
770 · Special directives:
772 · raw (include raw target-format markup)
774 · include (include reStructuredText from another file) – in Sphinx,
776 when given an absolute include file path, this directive takes it
777 as relative to the source directory
778 · class (assign a class attribute to the next element) [1]
780 · HTML specifics:
782 · meta (generation of HTML <meta> tags)
784 · title (override document title)
786 · Influencing markup:
788 · default-role (set a new default role)
790 · role (create a new role)
792 Since these are only per-file, better use Sphinx’s facilities for
794 setting the default_role.
795 WARNING:
797 Do not use the directives sectnum, header and footer.
798 Directives added by Sphinx are described in directives.
800 Basically, a directive consists of a name, arguments, options and con‐
802 tent. (Keep this terminology in mind, it is used in the next chapter
803 describing custom directives.) Looking at this example,
804 .. function:: foo(x)
806 foo(y, z)
807 :module: some.module.name
808 Return a line of text input from the user.
810 function is the directive name. It is given two arguments here, the
812 remainder of the first line and the second line, as well as one option
813 module (as you can see, options are given in the lines immediately fol‐
814 lowing the arguments and indicated by the colons). Options must be
815 indented to the same level as the directive content.
816 The directive content follows after a blank line and is indented rela‐
818 tive to the directive start.
819 Images
821 reST supports an image directive (ref), used like so:
822 .. image:: gnu.png
824 (options)
825 When used within Sphinx, the file name given (here gnu.png) must either
827 be relative to the source file, or absolute which means that they are
828 relative to the top source directory. For example, the file
829 sketch/spam.rst could refer to the image images/spam.png as
830 ../images/spam.png or /images/spam.png.
831 Sphinx will automatically copy image files over to a subdirectory of
833 the output directory on building (e.g. the _static directory for HTML
834 output.)
835 Interpretation of image size options (width and height) is as follows:
837 if the size has no unit or the unit is pixels, the given size will only
838 be respected for output channels that support pixels. Other units (like
839 pt for points) will be used for HTML and LaTeX output (the latter
840 replaces pt by bp as this is the TeX unit such that 72bp=1in).
841 Sphinx extends the standard docutils behavior by allowing an asterisk
843 for the extension:
844 .. image:: gnu.*
846 Sphinx then searches for all images matching the provided pattern and
848 determines their type. Each builder then chooses the best image out of
849 these candidates. For instance, if the file name gnu.* was given and
850 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
851 builder would choose the former, while the HTML builder would prefer
852 the latter. Supported image types and choosing priority are defined at
853 /usage/builders/index.
854 Note that image file names should not contain spaces.
856 Changed in version 0.4: Added the support for file names ending in an
858 asterisk.
859 Changed in version 0.6: Image paths can now be absolute.
862 Changed in version 1.5: latex target supports pixels (default is
865 96px=1in).
866 Footnotes
869 For footnotes (ref), use [#name]_ to mark the footnote location, and
870 add the footnote body at the bottom of the document after a “Footnotes”
871 rubric heading, like so:
872 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
874 .. rubric:: Footnotes
876 .. [#f1] Text of the first footnote.
878 .. [#f2] Text of the second footnote.
879 You can also explicitly number the footnotes ([1]_) or use auto-num‐
881 bered footnotes without names ([#]_).
882 Citations
884 Standard reST citations (ref) are supported, with the additional fea‐
885 ture that they are “global”, i.e. all citations can be referenced from
886 all files. Use them like so:
887 Lorem ipsum [Ref]_ dolor sit amet.
889 .. [Ref] Book or article reference, URL or whatever.
891 Citation usage is similar to footnote usage, but with a label that is
893 not numeric or begins with #.
894 Substitutions
896 reST supports “substitutions” (ref), which are pieces of text and/or
897 markup referred to in the text by |name|. They are defined like foot‐
898 notes with explicit markup blocks, like this:
899 .. |name| replace:: replacement *text*
901 or this:
903 .. |caution| image:: warning.png
905 :alt: Warning!
906 See the reST reference for substitutions for details.
908 If you want to use some substitutions for all documents, put them into
910 rst_prolog or rst_epilog or put them into a separate file and include
911 it into all documents you want to use them in, using the include direc‐
912 tive. (Be sure to give the include file a file name extension differ‐
913 ing from that of other source files, to avoid Sphinx finding it as a
914 standalone document.)
915 Sphinx defines some default substitutions, see default-substitutions.
917 Comments
919 Every explicit markup block which isn’t a valid markup construct (like
920 the footnotes above) is regarded as a comment (ref). For example:
921 .. This is a comment.
923 You can indent text after a comment start to form multiline comments:
925 ..
927 This whole indented block
928 is a comment.
929 Still in the comment.
931 Source encoding
933 Since the easiest way to include special characters like em dashes or
934 copyright signs in reST is to directly write them as Unicode charac‐
935 ters, one has to specify an encoding. Sphinx assumes source files to
936 be encoded in UTF-8 by default; you can change this with the
937 source_encoding config value.
938 Gotchas
940 There are some problems one commonly runs into while authoring reST
941 documents:
942 · Separation of inline markup: As said above, inline markup spans must
944 be separated from the surrounding text by non-word characters, you
945 have to use a backslash-escaped space to get around that. See the
946 reference for the details.
947 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
949 sible.
950
952 [1] When the default domain contains a class directive, this directive
953 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
954 Roles
956 Sphinx uses interpreted text roles to insert semantic markup into docu‐
957 ments. They are written as :rolename:`content`.
958 NOTE:
960 The default role (`content`) has no special meaning by default. You
961 are free to use it for anything you like, e.g. variable names; use
962 the default_role config value to set it to a known role – the any
963 role to find anything or the py:obj role to find Python objects are
964 very useful for this.
965 See /usage/restructuredtext/domains for roles added by domains.
967 Cross-referencing syntax
969 Cross-references are generated by many semantic interpreted text roles.
970 Basically, you only need to write :role:`target`, and a link will be
971 created to the item named target of the type indicated by role. The
972 link’s text will be the same as target.
973 There are some additional facilities, however, that make cross-refer‐
975 encing roles more versatile:
976 · You may supply an explicit title and reference target, like in reST
978 direct hyperlinks: :role:`title <target>` will refer to target, but
979 the link text will be title.
980 · If you prefix the content with !, no reference/hyperlink will be cre‐
982 ated.
983 · If you prefix the content with ~, the link text will only be the last
985 component of the target. For example, :py:meth:`~Queue.Queue.get`
986 will refer to Queue.Queue.get but only display get as the link text.
987 This does not work with all cross-reference roles, but is domain spe‐
988 cific.
989 In HTML output, the link’s title attribute (that is e.g. shown as a
991 tool-tip on mouse-hover) will always be the full target name.
992 Cross-referencing anything
994 :any: New in version 1.3.
995 This convenience role tries to do its best to find a valid tar‐
998 get for its reference text.
999 · First, it tries standard cross-reference targets that would be
1001 referenced by doc, ref or option.
1002 Custom objects added to the standard domain by extensions (see
1004 Sphinx.add_object_type()) are also searched.
1005 · Then, it looks for objects (targets) in all loaded domains.
1007 It is up to the domains how specific a match must be. For
1008 example, in the Python domain a reference of :any:`Builder`
1009 would match the sphinx.builders.Builder class.
1010 If none or multiple targets are found, a warning will be emit‐
1012 ted. In the case of multiple targets, you can change “any” to a
1013 specific role.
1014 This role is a good candidate for setting default_role. If you
1016 do, you can write cross-references without a lot of markup over‐
1017 head. For example, in this Python function documentation
1018 .. function:: install()
1020 This function installs a `handler` for every signal known by the
1022 `signal` module. See the section `about-signals` for more information.
1023 there could be references to a glossary term (usually
1025 :term:`handler`), a Python module (usually :py:mod:`signal` or
1026 :mod:`signal`) and a section (usually :ref:`about-signals`).
1027 The any role also works together with the intersphinx extension:
1029 when no local cross-reference is found, all object types of
1030 intersphinx inventories are also searched.
1031 Cross-referencing objects
1033 These roles are described with their respective domains:
1034 · Python
1036 · C
1038 · C++
1040 · JavaScript
1042 · ReST
1044 Cross-referencing arbitrary locations
1046 :ref: To support cross-referencing to arbitrary locations in any docu‐
1047 ment, the standard reST labels are used. For this to work label
1048 names must be unique throughout the entire documentation. There
1049 are two ways in which you can refer to labels:
1050 · If you place a label directly before a section title, you can
1052 reference to it with :ref:`label-name`. For example:
1053 .. _my-reference-label:
1055 Section to cross-reference
1057 --------------------------
1058 This is the text of the section.
1060 It refers to the section itself, see :ref:`my-reference-label`.
1062 The :ref: role would then generate a link to the section, with
1064 the link title being “Section to cross-reference”. This works
1065 just as well when section and reference are in different
1066 source files.
1067 Automatic labels also work with figures. For example:
1069 .. _my-figure:
1071 .. figure:: whatever
1073 Figure caption
1075 In this case, a reference :ref:`my-figure` would insert a
1077 reference to the figure with link text “Figure caption”.
1078 The same works for tables that are given an explicit caption
1080 using the table directive.
1081 · Labels that aren’t placed before a section title can still be
1083 referenced, but you must give the link an explicit title,
1084 using this syntax: :ref:`Link title <label-name>`.
1085 NOTE:
1087 Reference labels must start with an underscore. When refer‐
1088 encing a label, the underscore must be omitted (see examples
1089 above).
1090 Using ref is advised over standard reStructuredText links to
1092 sections (like `Section title`_) because it works across files,
1093 when section headings are changed, will raise warnings if incor‐
1094 rect, and works for all builders that support cross-references.
1095 Cross-referencing documents
1097 New in version 0.6.
1098 There is also a way to directly link to documents:
1101 :doc: Link to the specified document; the document name can be speci‐
1103 fied in absolute or relative fashion. For example, if the ref‐
1104 erence :doc:`parrot` occurs in the document sketches/index, then
1105 the link refers to sketches/parrot. If the reference is
1106 :doc:`/people` or :doc:`../people`, the link refers to people.
1107 If no explicit link text is given (like usual: :doc:`Monty
1109 Python members </people>`), the link caption will be the title
1110 of the given document.
1111 Referencing downloadable files
1113 New in version 0.6.
1114 :download:
1117 This role lets you link to files within your source tree that
1118 are not reST documents that can be viewed, but files that can be
1119 downloaded.
1120 When you use this role, the referenced file is automatically
1122 marked for inclusion in the output when building (obviously, for
1123 HTML output only). All downloadable files are put into the
1124 _downloads subdirectory of the output directory; duplicate file‐
1125 names are handled.
1126 An example:
1128 See :download:`this example script <../example.py>`.
1130 The given filename is usually relative to the directory the cur‐
1132 rent source file is contained in, but if it absolute (starting
1133 with /), it is taken as relative to the top source directory.
1134 The example.py file will be copied to the output directory, and
1136 a suitable link generated to it.
1137 Not to show unavailable download links, you should wrap whole
1139 paragraphs that have this role:
1140 .. only:: builder_html
1142 See :download:`this example script <../example.py>`.
1144 Cross-referencing figures by figure number
1146 New in version 1.3.
1147 Changed in version 1.5: numref role can also refer sections. And num‐
1150 ref allows {name} for the link text.
1151 :numref:
1154 Link to the specified figures, tables, code-blocks and sections;
1155 the standard reST labels are used. When you use this role, it
1156 will insert a reference to the figure with link text by its fig‐
1157 ure number like “Fig. 1.1”.
1158 If an explicit link text is given (as usual: :numref:`Image of
1160 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1161 title of the reference. As placeholders, %s and {number} get
1162 replaced by the figure number and {name} by the figure caption.
1163 If no explicit link text is given, the numfig_format setting is
1164 used as fall-back default.
1165 If numfig is False, figures are not numbered, so this role
1167 inserts not a reference but the label or the link text.
1168 Cross-referencing other items of interest
1170 The following roles do possibly create a cross-reference, but do not
1171 refer to objects:
1172 :envvar:
1174 An environment variable. Index entries are generated. Also
1175 generates a link to the matching envvar directive, if it exists.
1176 :token:
1178 The name of a grammar token (used to create links between pro‐
1179 ductionlist directives).
1180 :keyword:
1182 The name of a keyword in Python. This creates a link to a ref‐
1183 erence label with that name, if it exists.
1184 :option:
1186 A command-line option to an executable program. This generates
1187 a link to a option directive, if it exists.
1188 The following role creates a cross-reference to a term in a glossary:
1190 :term: Reference to a term in a glossary. A glossary is created using
1192 the glossary directive containing a definition list with terms
1193 and definitions. It does not have to be in the same file as the
1194 term markup, for example the Python docs have one global glos‐
1195 sary in the glossary.rst file.
1196 If you use a term that’s not explained in a glossary, you’ll get
1198 a warning during build.
1199 Math
1201 :math: Role for inline math. Use like this:
1202 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1204 :eq: Same as math:numref.
1206 Other semantic markup
1208 The following roles don’t do anything special except formatting the
1209 text in a different style:
1210 :abbr: An abbreviation. If the role content contains a parenthesized
1212 explanation, it will be treated specially: it will be shown in a
1213 tool-tip in HTML, and output only once in LaTeX.
1214 Example: :abbr:`LIFO (last-in, first-out)`.
1216 New in version 0.6.
1218 :command:
1221 The name of an OS-level command, such as rm.
1222 :dfn: Mark the defining instance of a term in the text. (No index
1224 entries are generated.)
1225 :file: The name of a file or directory. Within the contents, you can
1227 use curly braces to indicate a “variable” part, for example:
1228 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1230 In the built documentation, the x will be displayed differently
1232 to indicate that it is to be replaced by the Python minor ver‐
1233 sion.
1234 :guilabel:
1236 Labels presented as part of an interactive user interface should
1237 be marked using guilabel. This includes labels from text-based
1238 interfaces such as those created using curses or other
1239 text-based libraries. Any label used in the interface should be
1240 marked with this role, including button labels, window titles,
1241 field names, menu and menu selection names, and even values in
1242 selection lists.
1243 Changed in version 1.0: An accelerator key for the GUI label can
1245 be included using an ampersand; this will be stripped and dis‐
1246 played underlined in the output (example: :guilabel:`&Cancel`).
1247 To include a literal ampersand, double it.
1248 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1251 may depend on platform- or application-specific conventions.
1252 When there are no relevant conventions, the names of modifier
1253 keys should be spelled out, to improve accessibility for new
1254 users and non-native speakers. For example, an xemacs key
1255 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1256 ence to a specific application or platform, the same sequence
1257 should be marked as :kbd:`Control-x Control-f`.
1258 :mailheader:
1260 The name of an RFC 822-style mail header. This markup does not
1261 imply that the header is being used in an email message, but can
1262 be used to refer to any header of the same “style.” This is
1263 also used for headers defined by the various MIME specifica‐
1264 tions. The header name should be entered in the same way it
1265 would normally be found in practice, with the camel-casing con‐
1266 ventions being preferred where there is more than one common
1267 usage. For example: :mailheader:`Content-Type`.
1268 :makevar:
1270 The name of a make variable.
1271 :manpage:
1273 A reference to a Unix manual page including the section, e.g.
1274 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1275 dering the manpage if manpages_url is defined.
1276 :menuselection:
1278 Menu selections should be marked using the menuselection role.
1279 This is used to mark a complete sequence of menu selections,
1280 including selecting submenus and choosing a specific operation,
1281 or any subsequence of such a sequence. The names of individual
1282 selections should be separated by -->.
1283 For example, to mark the selection “Start > Programs”, use this
1285 markup:
1286 :menuselection:`Start --> Programs`
1288 When including a selection that includes some trailing indica‐
1290 tor, such as the ellipsis some operating systems use to indicate
1291 that the command opens a dialog, the indicator should be omitted
1292 from the selection name.
1293 menuselection also supports ampersand accelerators just like
1295 guilabel.
1296 :mimetype:
1298 The name of a MIME type, or a component of a MIME type (the
1299 major or minor portion, taken alone).
1300 :newsgroup:
1302 The name of a Usenet newsgroup.
1303 Todo
1305 Is this not part of the standard domain?
1306 :program:
1308 The name of an executable program. This may differ from the
1309 file name for the executable for some platforms. In particular,
1310 the .exe (or other) extension should be omitted for Windows pro‐
1311 grams.
1312 :regexp:
1314 A regular expression. Quotes should not be included.
1315 :samp: A piece of literal text, such as code. Within the contents, you
1317 can use curly braces to indicate a “variable” part, as in file.
1318 For example, in :samp:`print 1+{variable}`, the part variable
1319 would be emphasized.
1320 If you don’t need the “variable part” indication, use the stan‐
1322 dard ``code`` instead.
1323 Changed in version 1.8: Allowed to escape curly braces with
1325 backslash
1326 There is also an index role to generate index entries.
1329 The following roles generate external links:
1331 :pep: A reference to a Python Enhancement Proposal. This generates
1333 appropriate index entries. The text “PEP number” is generated;
1334 in the HTML output, this text is a hyperlink to an online copy
1335 of the specified PEP. You can link to a specific section by
1336 saying :pep:`number#anchor`.
1337 :rfc: A reference to an Internet Request for Comments. This generates
1339 appropriate index entries. The text “RFC number” is generated;
1340 in the HTML output, this text is a hyperlink to an online copy
1341 of the specified RFC. You can link to a specific section by
1342 saying :rfc:`number#anchor`.
1343 Note that there are no special roles for including hyperlinks as you
1345 can use the standard reST markup for that purpose.
1346 Substitutions
1348 The documentation system provides three substitutions that are defined
1349 by default. They are set in the build configuration file.
1350 |release|
1352 Replaced by the project release the documentation refers to.
1353 This is meant to be the full version string including
1354 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1355 release.
1356 |version|
1358 Replaced by the project version the documentation refers to.
1359 This is meant to consist only of the major and minor version
1360 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1361 |today|
1363 Replaced by either today’s date (the date on which the document
1364 is read), or the date set in the build configuration file. Nor‐
1365 mally has the format April 14, 2007. Set by today_fmt and
1366 today.
1367 Directives
1369 As previously discussed, a directive is a generic block of explicit
1370 markup. While Docutils provides a number of directives, Sphinx provides
1371 many more and uses directives as one of the primary extension mecha‐
1372 nisms.
1373 See /usage/restructuredtext/domains for roles added by domains.
1375 SEE ALSO:
1377 Refer to the reStructuredText Primer for an overview of the direc‐
1378 tives provided by Docutils.
1379 Table of contents
1381 Since reST does not have facilities to interconnect several documents,
1382 or split documents into multiple output files, Sphinx uses a custom
1383 directive to add relations between the single files the documentation
1384 is made of, as well as tables of contents. The toctree directive is
1385 the central element.
1386 NOTE:
1388 Simple “inclusion” of one file in another can be done with the
1389 include directive.
1390 NOTE:
1392 For local tables of contents, use the standard reST contents direc‐
1393 tive.
1394 .. toctree::
1396 This directive inserts a “TOC tree” at the current location,
1397 using the individual TOCs (including “sub-TOC trees”) of the
1398 documents given in the directive body. Relative document names
1399 (not beginning with a slash) are relative to the document the
1400 directive occurs in, absolute names are relative to the source
1401 directory. A numeric maxdepth option may be given to indicate
1402 the depth of the tree; by default, all levels are included. [1]
1403 Consider this example (taken from the Python docs’ library ref‐
1405 erence index):
1406 .. toctree::
1408 :maxdepth: 2
1409 intro
1411 strings
1412 datatypes
1413 numeric
1414 (many more documents listed here)
1415 This accomplishes two things:
1417 · Tables of contents from all those documents are inserted, with
1419 a maximum depth of two, that means one nested heading. toc‐
1420 tree directives in those documents are also taken into
1421 account.
1422 · Sphinx knows the relative order of the documents intro,
1424 strings and so forth, and it knows that they are children of
1425 the shown document, the library index. From this information
1426 it generates “next chapter”, “previous chapter” and “parent
1427 chapter” links.
1428 Entries
1430 Document titles in the toctree will be automatically read from
1432 the title of the referenced document. If that isn’t what you
1433 want, you can specify an explicit title and target using a simi‐
1434 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1435 syntax). This looks like:
1436 .. toctree::
1438 intro
1440 All about strings <strings>
1441 datatypes
1442 The second line above will link to the strings document, but
1444 will use the title “All about strings” instead of the title of
1445 the strings document.
1446 You can also add external links, by giving an HTTP URL instead
1448 of a document name.
1449 Section numbering
1451 If you want to have section numbers even in HTML output, give
1453 the toplevel toctree a numbered option. For example:
1454 .. toctree::
1456 :numbered:
1457 foo
1459 bar
1460 Numbering then starts at the heading of foo. Sub-toctrees are
1462 automatically numbered (don’t give the numbered flag to those).
1463 Numbering up to a specific depth is also possible, by giving the
1465 depth as a numeric argument to numbered.
1466 Additional options
1468 You can use caption option to provide a toctree caption and you
1470 can use name option to provide implicit target name that can be
1471 referenced by using ref:
1472 .. toctree::
1474 :caption: Table of Contents
1475 :name: mastertoc
1476 foo
1478 If you want only the titles of documents in the tree to show up,
1480 not other headings of the same level, you can use the titlesonly
1481 option:
1482 .. toctree::
1484 :titlesonly:
1485 foo
1487 bar
1488 You can use “globbing” in toctree directives, by giving the glob
1490 flag option. All entries are then matched against the list of
1491 available documents, and matches are inserted into the list
1492 alphabetically. Example:
1493 .. toctree::
1495 :glob:
1496 intro*
1498 recipe/*
1499 *
1500 This includes first all documents whose names start with intro,
1502 then all documents in the recipe folder, then all remaining doc‐
1503 uments (except the one containing the directive, of course.) [2]
1504 The special entry name self stands for the document containing
1506 the toctree directive. This is useful if you want to generate a
1507 “sitemap” from the toctree.
1508 You can use the reversed flag option to reverse the order of the
1510 entries in the list. This can be useful when using the glob flag
1511 option to reverse the ordering of the files. Example:
1512 .. toctree::
1514 :glob:
1515 :reversed:
1516 recipe/*
1518 You can also give a “hidden” option to the directive, like this:
1520 .. toctree::
1522 :hidden:
1523 doc_1
1525 doc_2
1526 This will still notify Sphinx of the document hierarchy, but not
1528 insert links into the document at the location of the directive
1529 – this makes sense if you intend to insert these links yourself,
1530 in a different style, or in the HTML sidebar.
1531 In cases where you want to have only one top-level toctree and
1533 hide all other lower level toctrees you can add the “includehid‐
1534 den” option to the top-level toctree entry:
1535 .. toctree::
1537 :includehidden:
1538 doc_1
1540 doc_2
1541 All other toctree entries can then be eliminated by the “hidden”
1543 option.
1544 In the end, all documents in the source directory (or subdirec‐
1546 tories) must occur in some toctree directive; Sphinx will emit a
1547 warning if it finds a file that is not included, because that
1548 means that this file will not be reachable through standard nav‐
1549 igation.
1550 Use exclude_patterns to explicitly exclude documents or directo‐
1552 ries from building completely. Use the “orphan” metadata to let
1553 a document be built, but notify Sphinx that it is not reachable
1554 via a toctree.
1555 The “master document” (selected by master_doc) is the “root” of
1557 the TOC tree hierarchy. It can be used as the documentation’s
1558 main page, or as a “full table of contents” if you don’t give a
1559 maxdepth option.
1560 Changed in version 0.3: Added “globbing” option.
1562 Changed in version 0.6: Added “numbered” and “hidden” options as
1565 well as external links and support for “self” references.
1566 Changed in version 1.0: Added “titlesonly” option.
1569 Changed in version 1.1: Added numeric argument to “numbered”.
1572 Changed in version 1.2: Added “includehidden” option.
1575 Changed in version 1.3: Added “caption” and “name” option.
1578 Special names
1581 Sphinx reserves some document names for its own use; you should not try
1582 to create documents with these names – it will cause problems.
1583 The special document names (and pages generated for them) are:
1585 · genindex, modindex, search
1587 These are used for the general index, the Python module index, and
1589 the search page, respectively.
1590 The general index is populated with entries from modules, all
1592 index-generating object descriptions, and from index directives.
1593 The Python module index contains one entry per py:module directive.
1595 The search page contains a form that uses the generated JSON search
1597 index and JavaScript to full-text search the generated documents for
1598 search words; it should work on every major browser that supports
1599 modern JavaScript.
1600 · every name beginning with _
1602 Though only few such names are currently used by Sphinx, you should
1604 not create documents or document-containing directories with such
1605 names. (Using _ as a prefix for a custom template directory is
1606 fine.)
1607 WARNING:
1609 Be careful with unusual characters in filenames. Some formats may
1610 interpret these characters in unexpected ways:
1611 · Do not use the colon : for HTML based formats. Links to other
1613 parts may not work.
1614 · Do not use the plus + for the ePub format. Some resources may not
1616 be found.
1617 Paragraph-level markup
1619 These directives create short paragraphs and can be used inside infor‐
1620 mation units as well as normal text.
1621 .. note::
1623 An especially important bit of information about an API that a
1624 user should be aware of when using whatever bit of API the note
1625 pertains to. The content of the directive should be written in
1626 complete sentences and include all appropriate punctuation.
1627 Example:
1629 .. note::
1631 This function is not suitable for sending spam e-mails.
1633 .. warning::
1635 An important bit of information about an API that a user should
1636 be very aware of when using whatever bit of API the warning per‐
1637 tains to. The content of the directive should be written in
1638 complete sentences and include all appropriate punctuation. This
1639 differs from note in that it is recommended over note for infor‐
1640 mation regarding security.
1641 .. versionadded:: version
1643 This directive documents the version of the project which added
1644 the described feature to the library or C API. When this applies
1645 to an entire module, it should be placed at the top of the mod‐
1646 ule section before any prose.
1647 The first argument must be given and is the version in question;
1649 you can add a second argument consisting of a brief explanation
1650 of the change.
1651 Example:
1653 .. versionadded:: 2.5
1655 The *spam* parameter.
1656 Note that there must be no blank line between the directive head
1658 and the explanation; this is to make these blocks visually con‐
1659 tinuous in the markup.
1660 .. versionchanged:: version
1662 Similar to versionadded, but describes when and what changed in
1663 the named feature in some way (new parameters, changed side
1664 effects, etc.).
1665 .. deprecated:: version
1667 Similar to versionchanged, but describes when the feature was
1668 deprecated. An explanation can also be given, for example to
1669 inform the reader what should be used instead. Example:
1670 .. deprecated:: 3.1
1672 Use :func:`spam` instead.
1673 .. seealso::
1675 Many sections include a list of references to module documenta‐
1676 tion or external documents. These lists are created using the
1677 seealso directive.
1678 The seealso directive is typically placed in a section just
1680 before any subsections. For the HTML output, it is shown boxed
1681 off from the main flow of the text.
1682 The content of the seealso directive should be a reST definition
1684 list. Example:
1685 .. seealso::
1687 Module :py:mod:`zipfile`
1689 Documentation of the :py:mod:`zipfile` standard module.
1690 `GNU tar manual, Basic Tar Format <http://link>`_
1692 Documentation for tar archive files, including GNU tar extensions.
1693 There’s also a “short form” allowed that looks like this:
1695 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1697 New in version 0.5: The short form.
1699 .. rubric:: title
1702 This directive creates a paragraph heading that is not used to
1703 create a table of contents node.
1704 NOTE:
1706 If the title of the rubric is “Footnotes” (or the selected
1707 language’s equivalent), this rubric is ignored by the LaTeX
1708 writer, since it is assumed to only contain footnote defini‐
1709 tions and therefore would create an empty heading.
1710 .. centered::
1712 This directive creates a centered boldfaced line of text. Use
1713 it as follows:
1714 .. centered:: LICENSE AGREEMENT
1716 Deprecated since version 1.1: This presentation-only directive
1718 is a legacy from older versions. Use a rst-class directive
1719 instead and add an appropriate style.
1720 .. hlist::
1723 This directive must contain a bullet list. It will transform it
1724 into a more compact list by either distributing more than one
1725 item horizontally, or reducing spacing between items, depending
1726 on the builder.
1727 For builders that support the horizontal distribution, there is
1729 a columns option that specifies the number of columns; it
1730 defaults to 2. Example:
1731 .. hlist::
1733 :columns: 3
1734 * A list of
1736 * short items
1737 * that should be
1738 * displayed
1739 * horizontally
1740 New in version 0.6.
1742 Showing code examples
1745 There are multiple ways to show syntax-highlighted literal code blocks
1746 in Sphinx: using reST doctest blocks; using reST literal blocks,
1747 optionally in combination with the highlight directive; using the
1748 code-block directive; and using the literalinclude directive. Doctest
1749 blocks can only be used to show interactive Python sessions, while the
1750 remaining three can be used for other languages. Of these three, lit‐
1751 eral blocks are useful when an entire document, or at least large sec‐
1752 tions of it, use code blocks with the same syntax and which should be
1753 styled in the same manner. On the other hand, the code-block directive
1754 makes more sense when you want more fine-tuned control over the styling
1755 of each block or when you have a document containing code blocks using
1756 multiple varied syntaxes. Finally, the literalinclude directive is use‐
1757 ful for including entire code files in your documentation.
1758 In all cases, Syntax highlighting is provided by Pygments. When using
1760 literal blocks, this is configured using any highlight directives in
1761 the source file. When a highlight directive is encountered, it is used
1762 until the next highlight directive is encountered. If there is no high‐
1763 light directive in the file, the global highlighting language is used.
1764 This defaults to python but can be configured using the highlight_lan‐
1765 guage config value. The following values are supported:
1766 · none (no highlighting)
1768 · default (similar to python3 but with a fallback to none without warn‐
1770 ing highlighting fails; the default when highlight_language isn’t
1771 set)
1772 · guess (let Pygments guess the lexer based on contents, only works
1774 with certain well-recognizable languages)
1775 · python
1777 · rest
1779 · c
1781 · … and any other lexer alias that Pygments supports
1783 If highlighting with the selected language fails (i.e. Pygments emits
1785 an “Error” token), the block is not highlighted in any way.
1786 IMPORTANT:
1788 The list of lexer aliases supported is tied to the Pygment version.
1789 If you want to ensure consistent highlighting, you should fix your
1790 version of Pygments.
1791 .. highlight:: language
1793 Example:
1794 .. highlight:: c
1796 This language is used until the next highlight directive is
1798 encountered. As discussed previously, language can be any lexer
1799 alias supported by Pygments.
1800 Additional options
1802 Pygments can generate line numbers for code blocks. To enable
1804 this, use the linenothreshold option.
1805 .. highlight:: python
1807 :linenothreshold: 5
1808 This will produce line numbers for all code blocks longer than
1810 five lines.
1811 .. code-block:: language
1813 Example:
1814 .. code-block:: ruby
1816 Some Ruby code.
1818 The directive’s alias name sourcecode works as well. As with
1820 highlight’s language option, language can be any lexer alias
1821 supported by Pygments.
1822 Additional options
1824 Pygments can generate line numbers for code blocks. To enable
1826 this for, use the linenos flag option.
1827 .. code-block:: ruby
1829 :linenos:
1830 Some more Ruby code.
1832 The first line number can be selected with the lineno-start
1834 option. If present, linenos flag is automatically activated:
1835 .. code-block:: ruby
1837 :lineno-start: 10
1838 Some more Ruby code, with line numbering starting at 10.
1840 Additionally, an emphasize-lines option can be given to have
1842 Pygments emphasize particular lines:
1843 .. code-block:: python
1845 :emphasize-lines: 3,5
1846 def some_function():
1848 interesting = False
1849 print 'This line is highlighted.'
1850 print 'This one is not...'
1851 print '...but this one is.'
1852 A caption option can be given to show that name before the
1854 code block. A name option can be provided implicit target
1855 name that can be referenced by using ref. For example:
1856 .. code-block:: python
1858 :caption: this.py
1859 :name: this-py
1860 print 'Explicit is better than implicit.'
1862 A dedent option can be given to strip indentation characters
1864 from the code block. For example:
1865 .. code-block:: ruby
1867 :dedent: 4
1868 some ruby code
1870 Changed in version 1.1: The emphasize-lines option has been
1872 added.
1873 Changed in version 1.3: The lineno-start, caption, name and
1876 dedent options have been added.
1877 Changed in version 1.6.6: LaTeX supports the emphasize-lines
1880 option.
1881 .. literalinclude:: filename
1884 Longer displays of verbatim text may be included by storing the
1885 example text in an external file containing only plain text.
1886 The file may be included using the literalinclude directive. [3]
1887 For example, to include the Python source file example.py, use:
1888 .. literalinclude:: example.py
1890 The file name is usually relative to the current file’s path.
1892 However, if it is absolute (starting with /), it is relative to
1893 the top source directory.
1894 Additional options
1896 Like code-block, the directive supports the linenos flag option
1898 to switch on line numbers, the lineno-start option to select the
1899 first line number, the emphasize-lines option to emphasize par‐
1900 ticular lines, the name option to provide an implicit target
1901 name, the dedent option to strip indentation characters for the
1902 code block, and a language option to select a language different
1903 from the current file’s standard language. In addition, it sup‐
1904 ports the caption option; however, this can be provided with no
1905 argument to use the filename as the caption. Example with
1906 options:
1907 .. literalinclude:: example.rb
1909 :language: ruby
1910 :emphasize-lines: 12,15-18
1911 :linenos:
1912 Tabs in the input are expanded if you give a tab-width option
1914 with the desired tab width.
1915 Include files are assumed to be encoded in the source_encoding.
1917 If the file has a different encoding, you can specify it with
1918 the encoding option:
1919 .. literalinclude:: example.py
1921 :encoding: latin-1
1922 The directive also supports including only parts of the file.
1924 If it is a Python module, you can select a class, function or
1925 method to include using the pyobject option:
1926 .. literalinclude:: example.py
1928 :pyobject: Timer.start
1929 This would only include the code lines belonging to the start()
1931 method in the Timer class within the file.
1932 Alternately, you can specify exactly which lines to include by
1934 giving a lines option:
1935 .. literalinclude:: example.py
1937 :lines: 1,3,5-10,20-
1938 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
1940 line.
1941 Another way to control which part of the file is included is to
1943 use the start-after and end-before options (or only one of
1944 them). If start-after is given as a string option, only lines
1945 that follow the first line containing that string are included.
1946 If end-before is given as a string option, only lines that pre‐
1947 cede the first lines containing that string are included. The
1948 start-at and end-at options behave in a similar way, but the
1949 lines containing the matched string are included.
1950 With lines selected using start-after it is still possible to
1952 use lines, the first allowed line having by convention the line
1953 number 1.
1954 When lines have been selected in any of the ways described
1956 above, the line numbers in emphasize-lines refer to those
1957 selected lines, counted consecutively starting at 1.
1958 When specifying particular parts of a file to display, it can be
1960 useful to display the original line numbers. This can be done
1961 using the lineno-match option, which is however allowed only
1962 when the selection consists of contiguous lines.
1963 You can prepend and/or append a line to the included code, using
1965 the prepend and append option, respectively. This is useful
1966 e.g. for highlighting PHP code that doesn’t include the <?php/?>
1967 markers.
1968 If you want to show the diff of the code, you can specify the
1970 old file by giving a diff option:
1971 .. literalinclude:: example.py
1973 :diff: example.py.orig
1974 This shows the diff between example.py and example.py.orig with
1976 unified diff format.
1977 Changed in version 0.4.3: Added the encoding option.
1979 Changed in version 0.6: Added the pyobject, lines, start-after
1982 and end-before options, as well as support for absolute file‐
1983 names.
1984 Changed in version 1.0: Added the prepend, append, and tab-width
1987 options.
1988 Changed in version 1.3: Added the diff, lineno-match, caption,
1991 name, and dedent options.
1992 Changed in version 1.5: Added the start-at, and end-at options.
1995 Changed in version 1.6: With both start-after and lines in use,
1998 the first line as per start-after is considered to be with line
1999 number 1 for lines.
2000 Glossary
2003 .. glossary::
2004 This directive must contain a reST definition-list-like markup
2005 with terms and definitions. The definitions will then be refer‐
2006 enceable with the term role. Example:
2007 .. glossary::
2009 environment
2011 A structure where information about all documents under the root is
2012 saved, and used for cross-referencing. The environment is pickled
2013 after the parsing stage, so that successive runs only need to read
2014 and parse new and changed documents.
2015 source directory
2017 The directory which, including its subdirectories, contains all
2018 source files for one Sphinx project.
2019 In contrast to regular definition lists, multiple terms per
2021 entry are allowed, and inline markup is allowed in terms. You
2022 can link to all of the terms. For example:
2023 .. glossary::
2025 term 1
2027 term 2
2028 Definition of both terms.
2029 (When the glossary is sorted, the first term determines the sort
2031 order.)
2032 If you want to specify “grouping key” for general index entries,
2034 you can put a “key” as “term : key”. For example:
2035 .. glossary::
2037 term 1 : A
2039 term 2 : B
2040 Definition of both terms.
2041 Note that “key” is used for grouping key as is. The “key” isn’t
2043 normalized; key “A” and “a” become different groups. The whole
2044 characters in “key” is used instead of a first character; it is
2045 used for “Combining Character Sequence” and “Surrogate Pairs”
2046 grouping key.
2047 In i18n situation, you can specify “localized term : key” even
2049 if original text only have “term” part. In this case, translated
2050 “localized term” will be categorized in “key” group.
2051 New in version 0.6: You can now give the glossary directive a
2053 :sorted: flag that will automatically sort the entries alphabet‐
2054 ically.
2055 Changed in version 1.1: Now supports multiple terms and inline
2058 markup in terms.
2059 Changed in version 1.4: Index key for glossary term should be
2062 considered experimental.
2063 Meta-information markup
2066 .. sectionauthor:: name <email>
2067 Identifies the author of the current section. The argument
2068 should include the author’s name such that it can be used for
2069 presentation and email address. The domain name portion of the
2070 address should be lower case. Example:
2071 .. sectionauthor:: Guido van Rossum <guido@python.org>
2073 By default, this markup isn’t reflected in the output in any way
2075 (it helps keep track of contributions), but you can set the con‐
2076 figuration value show_authors to True to make them produce a
2077 paragraph in the output.
2078 .. codeauthor:: name <email>
2080 The codeauthor directive, which can appear multiple times, names
2081 the authors of the described code, just like sectionauthor names
2082 the author(s) of a piece of documentation. It too only produces
2083 output if the show_authors configuration value is True.
2084 Index-generating markup
2086 Sphinx automatically creates index entries from all object descriptions
2087 (like functions, classes or attributes) like discussed in
2088 /usage/restructuredtext/domains.
2089 However, there is also explicit markup available, to make the index
2091 more comprehensive and enable index entries in documents where informa‐
2092 tion is not mainly contained in information units, such as the language
2093 reference.
2094 .. index:: <entries>
2096 This directive contains one or more index entries. Each entry
2097 consists of a type and a value, separated by a colon.
2098 For example:
2100 .. index::
2102 single: execution; context
2103 module: __main__
2104 module: sys
2105 triple: module; search; path
2106 The execution context
2108 ---------------------
2109 ...
2111 This directive contains five entries, which will be converted to
2113 entries in the generated index which link to the exact location
2114 of the index statement (or, in case of offline media, the corre‐
2115 sponding page number).
2116 Since index directives generate cross-reference targets at their
2118 location in the source, it makes sense to put them before the
2119 thing they refer to – e.g. a heading, as in the example above.
2120 The possible entry types are:
2122 single Creates a single index entry. Can be made a subentry by
2124 separating the subentry text with a semicolon (this nota‐
2125 tion is also used below to describe what entries are cre‐
2126 ated).
2127 pair pair: loop; statement is a shortcut that creates two
2129 index entries, namely loop; statement and statement;
2130 loop.
2131 triple Likewise, triple: module; search; path is a shortcut that
2133 creates three index entries, which are module; search
2134 path, search; path, module and path; module search.
2135 see see: entry; other creates an index entry that refers from
2137 entry to other.
2138 seealso
2140 Like see, but inserts “see also” instead of “see”.
2141 module, keyword, operator, object, exception, statement, builtin
2143 These all create two index entries. For example, module:
2144 hashlib creates the entries module; hashlib and hashlib;
2145 module. (These are Python-specific and therefore depre‐
2146 cated.)
2147 You can mark up “main” index entries by prefixing them with an
2149 exclamation mark. The references to “main” entries are empha‐
2150 sized in the generated index. For example, if two pages contain
2151 .. index:: Python
2153 and one page contains
2155 .. index:: ! Python
2157 then the backlink to the latter page is emphasized among the
2159 three backlinks.
2160 For index directives containing only “single” entries, there is
2162 a shorthand notation:
2163 .. index:: BNF, grammar, syntax, notation
2165 This creates four index entries.
2167 Changed in version 1.1: Added see and seealso types, as well as
2169 marking main entries.
2170 :index:
2173 While the index directive is a block-level markup and links to
2174 the beginning of the next paragraph, there is also a correspond‐
2175 ing role that sets the link target directly where it is used.
2176 The content of the role can be a simple phrase, which is then
2178 kept in the text and used as an index entry. It can also be a
2179 combination of text and index entry, styled like with explicit
2180 targets of cross-references. In that case, the “target” part
2181 can be a full entry as described for the directive above. For
2182 example:
2183 This is a normal reST :index:`paragraph` that contains several
2185 :index:`index entries <pair: index; entry>`.
2186 New in version 1.1.
2188 Including content based on tags
2191 .. only:: <expression>
2192 Include the content of the directive only if the expression is
2193 true. The expression should consist of tags, like this:
2194 .. only:: html and draft
2196 Undefined tags are false, defined tags (via the -t command-line
2198 option or within conf.py, see here) are true. Boolean expres‐
2199 sions, also using parentheses (like html and (latex or draft))
2200 are supported.
2201 The format and the name of the current builder (html, latex or
2203 text) are always set as a tag [4]. To make the distinction
2204 between format and name explicit, they are also added with the
2205 prefix format_ and builder_, e.g. the epub builder defines the
2206 tags html, epub, format_html and builder_epub.
2207 These standard tags are set after the configuration file is
2209 read, so they are not available there.
2210 All tags must follow the standard Python identifier syntax as
2212 set out in the Identifiers and keywords documentation. That is,
2213 a tag expression may only consist of tags that conform to the
2214 syntax of Python variables. In ASCII, this consists of the
2215 uppercase and lowercase letters A through Z, the underscore _
2216 and, except for the first character, the digits 0 through 9.
2217 New in version 0.6.
2219 Changed in version 1.2: Added the name of the builder and the
2222 prefixes.
2223 WARNING:
2226 This directive is designed to control only content of docu‐
2227 ment. It could not control sections, labels and so on.
2228 Tables
2230 Use reStructuredText tables, i.e. either
2231 · grid table syntax (ref),
2233 · simple table syntax (ref),
2235 · csv-table syntax,
2237 · or list-table syntax.
2239 The table directive serves as optional wrapper of the grid and simple
2241 syntaxes.
2242 They work fine in HTML output, however there are some gotchas when
2244 using tables in LaTeX: the column width is hard to determine correctly
2245 automatically. For this reason, the following directive exists:
2246 .. tabularcolumns:: column spec
2248 This directive gives a “column spec” for the next table occur‐
2249 ring in the source file. The spec is the second argument to the
2250 LaTeX tabulary package’s environment (which Sphinx uses to
2251 translate tables). It can have values like
2252 |l|l|l|
2254 which means three left-adjusted, nonbreaking columns. For col‐
2256 umns with longer text that should automatically be broken, use
2257 either the standard p{width} construct, or tabulary’s automatic
2258 specifiers:
2259 ┌──┬────────────────────────────┐
2261 │L │ flush left column with │
2262 │ │ automatic width │
2263 ├──┼────────────────────────────┤
2264 │R │ flush right column with │
2265 │ │ automatic width │
2266 └──┴────────────────────────────┘
2267 │C │ centered column with auto‐ │
2269 │ │ matic width │
2270 ├──┼────────────────────────────┤
2271 │J │ justified column with │
2272 │ │ automatic width │
2273 └──┴────────────────────────────┘
2274 The automatic widths of the LRCJ columns are attributed by tabu‐
2276 lary in proportion to the observed shares in a first pass where
2277 the table cells are rendered at their natural “horizontal”
2278 widths.
2279 By default, Sphinx uses a table layout with J for every column.
2281 New in version 0.3.
2283 Changed in version 1.6: Merged cells may now contain multiple
2286 paragraphs and are much better handled, thanks to custom Sphinx
2287 LaTeX macros. This novel situation motivated the switch to J
2288 specifier and not L by default.
2289 HINT:
2292 Sphinx actually uses T specifier having done \newcolumn‐
2293 type{T}{J}. To revert to previous default, insert \newcolum‐
2294 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2295 A frequent issue with tabulary is that columns with little
2297 contents are “squeezed”. The minimal column width is a tabu‐
2298 lary parameter called \tymin. You may set it globally in the
2299 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2300 Else, use the tabularcolumns directive with an explicit
2302 p{40pt} (for example) for that column. You may use also l
2303 specifier but this makes the task of setting column widths
2304 more difficult if some merged cell intersects that column.
2305 WARNING:
2307 Tables with more than 30 rows are rendered using longtable,
2308 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2309 ifiers do not work for these tables.
2310 Tables that contain list-like elements such as object
2312 descriptions, blockquotes or any kind of lists cannot be set
2313 out of the box with tabulary. They are therefore set with the
2314 standard LaTeX tabular (or longtable) environment if you
2315 don’t give a tabularcolumns directive. If you do, the table
2316 will be set with tabulary but you must use the p{width} con‐
2317 struct (or Sphinx’s \X and \Y specifiers described below) for
2318 the columns containing these elements.
2319 Literal blocks do not work with tabulary at all, so tables
2321 containing a literal block are always set with tabular. The
2322 verbatim environment used for literal blocks only works in
2323 p{width} (and \X or \Y) columns, hence Sphinx generates such
2324 column specs for tables containing literal blocks.
2325 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2327 backslash in the specifier letter). It is like p{width} with the
2328 width set to a fraction a/b of the current line width. You can
2329 use it in the tabularcolumns (it is not a problem if some LaTeX
2330 macro is also called \X.)
2331 It is not needed for b to be the total number of columns, nor
2333 for the sum of the fractions of the \X specifiers to add up to
2334 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2335 the table will occupy 80% of the line width, the first of its
2336 three columns having the same width as the sum of the next two.
2337 This is used by the :widths: option of the table directive.
2339 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2341 a decimal argument, such has \Y{0.15}: this would have the same
2342 effect as \X{3}{20}.
2343 Changed in version 1.6: Merged cells from complex grid tables
2345 (either multi-row, multi-column, or both) now allow blockquotes,
2346 lists, literal blocks, … as do regular cells.
2347 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2349 Y{f} and tabulary’s columns.
2350 NOTE:
2353 tabularcolumns conflicts with :widths: option of table direc‐
2354 tives. If both are specified, :widths: option will be
2355 ignored.
2356 Math
2358 The input language for mathematics is LaTeX markup. This is the
2359 de-facto standard for plain-text math notation and has the added advan‐
2360 tage that no further translation is necessary when building LaTeX out‐
2361 put.
2362 Keep in mind that when you put math markup in Python docstrings read by
2364 autodoc, you either have to double all backslashes, or use Python raw
2365 strings (r"raw").
2366 .. math::
2368 Directive for displayed math (math that takes the whole line for
2369 itself).
2370 The directive supports multiple equations, which should be sepa‐
2372 rated by a blank line:
2373 .. math::
2375 (a + b)^2 = a^2 + 2ab + b^2
2377 (a - b)^2 = a^2 - 2ab + b^2
2379 In addition, each single equation is set within a split environ‐
2381 ment, which means that you can have multiple aligned lines in an
2382 equation, aligned at & and separated by \\:
2383 .. math::
2385 (a + b)^2 &= (a + b)(a + b) \\
2387 &= a^2 + 2ab + b^2
2388 For more details, look into the documentation of the AmSMath
2390 LaTeX package.
2391 When the math is only one line of text, it can also be given as
2393 a directive argument:
2394 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2396 Normally, equations are not numbered. If you want your equation
2398 to get a number, use the label option. When given, it selects
2399 an internal label for the equation, by which it can be
2400 cross-referenced, and causes an equation number to be issued.
2401 See eq for an example. The numbering style depends on the out‐
2402 put format.
2403 There is also an option nowrap that prevents any wrapping of the
2405 given math in a math environment. When you give this option,
2406 you must make sure yourself that the math is properly set up.
2407 For example:
2408 .. math::
2410 :nowrap:
2411 \begin{eqnarray}
2413 y & = & ax^2 + bx + c \\
2414 f(x) & = & x^2 + 2xy + y^2
2415 \end{eqnarray}
2416 Grammar production displays
2418 Special markup is available for displaying the productions of a formal
2419 grammar. The markup is simple and does not attempt to model all
2420 aspects of BNF (or any derived forms), but provides enough to allow
2421 context-free grammars to be displayed in a way that causes uses of a
2422 symbol to be rendered as hyperlinks to the definition of the symbol.
2423 There is this directive:
2424 .. productionlist:: [name]
2426 This directive is used to enclose a group of productions. Each
2427 production is given on a single line and consists of a name,
2428 separated by a colon from the following definition. If the def‐
2429 inition spans multiple lines, each continuation line must begin
2430 with a colon placed at the same column as in the first line.
2431 The argument to productionlist serves to distinguish different
2433 sets of production lists that belong to different grammars.
2434 Blank lines are not allowed within productionlist directive
2436 arguments.
2437 The definition can contain token names which are marked as
2439 interpreted text (e.g. sum ::= `integer` "+" `integer`) – this
2440 generates cross-references to the productions of these tokens.
2441 Outside of the production list, you can reference to token pro‐
2442 ductions using token.
2443 Note that no further reST parsing is done in the production, so
2445 that you don’t have to escape * or | characters.
2446 The following is an example taken from the Python Reference Manual:
2448 .. productionlist::
2450 try_stmt: try1_stmt | try2_stmt
2451 try1_stmt: "try" ":" `suite`
2452 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2453 : ["else" ":" `suite`]
2454 : ["finally" ":" `suite`]
2455 try2_stmt: "try" ":" `suite`
2456 : "finally" ":" `suite`
2457
2459 [1] The LaTeX writer only refers the maxdepth option of first toctree
2460 directive in the document.
2461 [2] A note on available globbing syntax: you can use the standard
2463 shell constructs *, ?, [...] and [!...] with the feature that
2464 these all don’t match slashes. A double star ** can be used to
2465 match any sequence of characters including slashes.
2466 [3] There is a standard .. include directive, but it raises errors if
2468 the file is not found. This one only emits a warning.
2469 [4] For most builders name and format are the same. At the moment only
2471 builders derived from the html builder distinguish between the
2472 builder format and the builder name.
2473 Note that the current builder tag is not available in conf.py, it
2475 is only available after the builder is initialized.
2476 Field Lists
2478 As previously discussed, field lists are sequences of fields marked up
2479 like this:
2480 :fieldname: Field content
2482 Sphinx provides custom behavior for bibliographic fields compared to
2484 docutils.
2485 File-wide metadata
2487 A field list near the top of a file is normally parsed by docutils as
2488 the docinfo which is generally used to record the author, date of pub‐
2489 lication and other metadata. However, in Sphinx, a field list preced‐
2490 ing any other markup is moved from the docinfo to the Sphinx environ‐
2491 ment as document metadata and is not displayed in the output; a field
2492 list appearing after the document title will be part of the docinfo as
2493 normal and will be displayed in the output.
2494 At the moment, these metadata fields are recognized:
2496 tocdepth
2498 The maximum depth for a table of contents of this file.
2499 :tocdepth: 2
2501 New in version 0.4.
2503 nocomments
2506 If set, the web application won’t display a comment form for a
2507 page generated from this source file.
2508 :nocomments:
2510 orphan If set, warnings about this file not being included in any toc‐
2512 tree will be suppressed.
2513 :orphan:
2515 New in version 1.0.
2517 Domains
2520 New in version 1.0.
2521 Originally, Sphinx was conceived for a single project, the documenta‐
2524 tion of the Python language. Shortly afterwards, it was made available
2525 for everyone as a documentation tool, but the documentation of Python
2526 modules remained deeply built in – the most fundamental directives,
2527 like function, were designed for Python objects. Since Sphinx has
2528 become somewhat popular, interest developed in using it for many dif‐
2529 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2530 markup (like in this documentation).
2531 While this was always possible, it is now much easier to easily support
2533 documentation of projects using different programming languages or even
2534 ones not supported by the main Sphinx distribution, by providing a
2535 domain for every such purpose.
2536 A domain is a collection of markup (reStructuredText directives and
2538 roles) to describe and link to objects belonging together, e.g. ele‐
2539 ments of a programming language. Directive and role names in a domain
2540 have names like domain:name, e.g. py:function. Domains can also pro‐
2541 vide custom indices (like the Python Module Index).
2542 Having domains means that there are no naming problems when one set of
2544 documentation wants to refer to e.g. C++ and Python classes. It also
2545 means that extensions that support the documentation of whole new lan‐
2546 guages are much easier to write.
2547 This section describes what the domains that are included with Sphinx
2549 provide. The domain API is documented as well, in the section
2550 domain-api.
2551 Basic Markup
2553 Most domains provide a number of object description directives, used to
2554 describe specific objects provided by modules. Each directive requires
2555 one or more signatures to provide basic information about what is being
2556 described, and the content should be the description. The basic ver‐
2557 sion makes entries in the general index; if no index entry is desired,
2558 you can give the directive option flag :noindex:. An example using a
2559 Python domain directive:
2560 .. py:function:: spam(eggs)
2562 ham(eggs)
2563 Spam or ham the foo.
2565 This describes the two Python functions spam and ham. (Note that when
2567 signatures become too long, you can break them if you add a backslash
2568 to lines that are continued in the next line. Example:
2569 .. py:function:: filterwarnings(action, message='', category=Warning, \
2571 module='', lineno=0, append=False)
2572 :noindex:
2573 (This example also shows how to use the :noindex: flag.)
2575 The domains also provide roles that link back to these object descrip‐
2577 tions. For example, to link to one of the functions described in the
2578 example above, you could say
2579 The function :py:func:`spam` does a similar thing.
2581 As you can see, both directive and role names contain the domain name
2583 and the directive name. Default Domain
2584 For documentation describing objects from solely one domain, authors
2586 will not have to state again its name at each directive, role, etc…
2587 after having specified a default. This can be done either via the con‐
2588 fig value primary_domain or via this directive:
2589 .. default-domain:: name
2591 Select a new default domain. While the primary_domain selects a
2592 global default, this only has an effect within the same file.
2593 If no other default is selected, the Python domain (named py) is the
2595 default one, mostly for compatibility with documentation written for
2596 older versions of Sphinx.
2597 Directives and roles that belong to the default domain can be mentioned
2599 without giving the domain name, i.e.
2600 .. function:: pyfunc()
2602 Describes a Python function.
2604 Reference to :func:`pyfunc`.
2606 Cross-referencing syntax
2608 For cross-reference roles provided by domains, the same facilities
2609 exist as for general cross-references. See xref-syntax.
2610 In short:
2612 · You may supply an explicit title and reference target: :role:`title
2614 <target>` will refer to target, but the link text will be title.
2615 · If you prefix the content with !, no reference/hyperlink will be cre‐
2617 ated.
2618 · If you prefix the content with ~, the link text will only be the last
2620 component of the target. For example, :py:meth:`~Queue.Queue.get`
2621 will refer to Queue.Queue.get but only display get as the link text.
2622 The Python Domain
2624 The Python domain (name py) provides the following directives for mod‐
2625 ule declarations:
2626 .. py:module:: name
2628 This directive marks the beginning of the description of a mod‐
2629 ule (or package submodule, in which case the name should be
2630 fully qualified, including the package name). It does not cre‐
2631 ate content (like e.g. py:class does).
2632 This directive will also cause an entry in the global module
2634 index.
2635 The platform option, if present, is a comma-separated list of
2637 the platforms on which the module is available (if it is avail‐
2638 able on all platforms, the option should be omitted). The keys
2639 are short identifiers; examples that are in use include “IRIX”,
2640 “Mac”, “Windows”, and “Unix”. It is important to use a key
2641 which has already been used when applicable.
2642 The synopsis option should consist of one sentence describing
2644 the module’s purpose – it is currently only used in the Global
2645 Module Index.
2646 The deprecated option can be given (with no value) to mark a
2648 module as deprecated; it will be designated as such in various
2649 locations then.
2650 .. py:currentmodule:: name
2652 This directive tells Sphinx that the classes, functions etc.
2653 documented from here are in the given module (like py:module),
2654 but it will not create index entries, an entry in the Global
2655 Module Index, or a link target for py:mod. This is helpful in
2656 situations where documentation for things in a module is spread
2657 over multiple files or sections – one location has the py:module
2658 directive, the others only py:currentmodule.
2659 The following directives are provided for module and class contents:
2661 .. py:function:: name(parameters)
2663 Describes a module-level function. The signature should include
2664 the parameters as given in the Python function definition, see
2665 Python Signatures. For example:
2666 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2668 For methods you should use py:method.
2670 The description normally includes information about the parame‐
2672 ters required and how they are used (especially whether mutable
2673 objects passed as parameters are modified), side effects, and
2674 possible exceptions.
2675 This information can (in any py directive) optionally be given
2677 in a structured form, see Info field lists.
2678 .. py:data:: name
2680 Describes global data in a module, including both variables and
2681 values used as “defined constants.” Class and object attributes
2682 are not documented using this environment.
2683 .. py:exception:: name
2685 Describes an exception class. The signature can, but need not
2686 include parentheses with constructor arguments.
2687 .. py:class:: name
2689 .. py:class:: name(parameters)
2691 Describes a class. The signature can optionally include paren‐
2692 theses with parameters which will be shown as the constructor
2693 arguments. See also Python Signatures.
2694 Methods and attributes belonging to the class should be placed
2696 in this directive’s body. If they are placed outside, the sup‐
2697 plied name should contain the class name so that cross-refer‐
2698 ences still work. Example:
2699 .. py:class:: Foo
2701 .. py:method:: quux()
2703 -- or --
2705 .. py:class:: Bar
2707 .. py:method:: Bar.quux()
2709 The first way is the preferred one.
2711 .. py:attribute:: name
2713 Describes an object data attribute. The description should
2714 include information about the type of the data to be expected
2715 and whether it may be changed directly.
2716 .. py:method:: name(parameters)
2718 Describes an object method. The parameters should not include
2719 the self parameter. The description should include similar
2720 information to that described for function. See also Python
2721 Signatures and Info field lists.
2722 .. py:staticmethod:: name(parameters)
2724 Like py:method, but indicates that the method is a static
2725 method.
2726 New in version 0.4.
2728 .. py:classmethod:: name(parameters)
2731 Like py:method, but indicates that the method is a class method.
2732 New in version 0.6.
2734 .. py:decorator:: name
2737 .. py:decorator:: name(parameters)
2739 Describes a decorator function. The signature should represent
2740 the usage as a decorator. For example, given the functions
2741 def removename(func):
2743 func.__name__ = ''
2744 return func
2745 def setnewname(name):
2747 def decorator(func):
2748 func.__name__ = name
2749 return func
2750 return decorator
2751 the descriptions should look like this:
2753 .. py:decorator:: removename
2755 Remove name of the decorated function.
2757 .. py:decorator:: setnewname(name)
2759 Set name of the decorated function to *name*.
2761 (as opposed to .. py:decorator:: removename(func).)
2763 There is no py:deco role to link to a decorator that is marked
2765 up with this directive; rather, use the py:func role.
2766 .. py:decoratormethod:: name
2768 .. py:decoratormethod:: name(signature)
2770 Same as py:decorator, but for decorators that are methods.
2771 Refer to a decorator method using the py:meth role.
2773 Python Signatures
2775 Signatures of functions, methods and class constructors can be given
2776 like they would be written in Python.
2777 Default values for optional arguments can be given (but if they contain
2779 commas, they will confuse the signature parser). Python 3-style argu‐
2780 ment annotations can also be given as well as return type annotations:
2781 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
2783 For functions with optional parameters that don’t have default values
2785 (typically functions implemented in C extension modules without keyword
2786 argument support), you can use brackets to specify the optional parts:
2787 compile(source[, filename[, symbol]])
2789 It is customary to put the opening bracket before the comma.
2791 Info field lists
2793 New in version 0.4.
2794 Inside Python object description directives, reST field lists with
2797 these fields are recognized and formatted nicely:
2798 · param, parameter, arg, argument, key, keyword: Description of a
2800 parameter.
2801 · type: Type of a parameter. Creates a link if possible.
2803 · raises, raise, except, exception: That (and when) a specific excep‐
2805 tion is raised.
2806 · var, ivar, cvar: Description of a variable.
2808 · vartype: Type of a variable. Creates a link if possible.
2810 · returns, return: Description of the return value.
2812 · rtype: Return type. Creates a link if possible.
2814 NOTE:
2816 In current release, all var, ivar and cvar are represented as “Vari‐
2817 able”. There is no difference at all.
2818 The field names must consist of one of these keywords and an argument
2820 (except for returns and rtype, which do not need an argument). This is
2821 best explained by an example:
2822 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
2824 Send a message to a recipient
2826 :param str sender: The person sending the message
2828 :param str recipient: The recipient of the message
2829 :param str message_body: The body of the message
2830 :param priority: The priority of the message, can be a number 1-5
2831 :type priority: integer or None
2832 :return: the message id
2833 :rtype: int
2834 :raises ValueError: if the message_body exceeds 160 characters
2835 :raises TypeError: if the message_body is not a basestring
2836 This will render like this:
2838 send_message(sender, recipient, message_body[, priority=1])
2840 Send a message to a recipient
2841 Parameters
2843 · sender (str) – The person sending the message
2845 · recipient (str) – The recipient of the message
2847 · message_body (str) – The body of the message
2849 · priority (integer or None) – The priority of the
2851 message, can be a number 1-5
2852 Returns
2854 the message id
2855 Return type
2857 int
2858 Raises
2860 · ValueError – if the message_body exceeds 160 charac‐
2862 ters
2863 · TypeError – if the message_body is not a basestring
2865 It is also possible to combine parameter type and description, if the
2867 type is a single word, like this:
2868 :param int priority: The priority of the message, can be a number 1-5
2870 New in version 1.5.
2872 Container types such as lists and dictionaries can be linked automati‐
2875 cally using the following syntax:
2876 :type priorities: list(int)
2878 :type priorities: list[int]
2879 :type mapping: dict(str, int)
2880 :type mapping: dict[str, int]
2881 :type point: tuple(float, float)
2882 :type point: tuple[float, float]
2883 Multiple types in a type field will be linked automatically if sepa‐
2885 rated by the word “or”:
2886 :type an_arg: int or None
2888 :vartype a_var: str or int
2889 :rtype: float or str
2890 Cross-referencing Python objects
2892 The following roles refer to objects in modules and are possibly hyper‐
2893 linked if a matching identifier is found:
2894 :py:mod:
2896 Reference a module; a dotted name may be used. This should also
2897 be used for package names.
2898 :py:func:
2900 Reference a Python function; dotted names may be used. The role
2901 text needs not include trailing parentheses to enhance readabil‐
2902 ity; they will be added automatically by Sphinx if the add_func‐
2903 tion_parentheses config value is True (the default).
2904 :py:data:
2906 Reference a module-level variable.
2907 :py:const:
2909 Reference a “defined” constant. This may be a Python variable
2910 that is not intended to be changed.
2911 :py:class:
2913 Reference a class; a dotted name may be used.
2914 :py:meth:
2916 Reference a method of an object. The role text can include the
2917 type name and the method name; if it occurs within the descrip‐
2918 tion of a type, the type name can be omitted. A dotted name may
2919 be used.
2920 :py:attr:
2922 Reference a data attribute of an object.
2923 :py:exc:
2925 Reference an exception. A dotted name may be used.
2926 :py:obj:
2928 Reference an object of unspecified type. Useful e.g. as the
2929 default_role.
2930 New in version 0.4.
2932 The name enclosed in this markup can include a module name and/or a
2935 class name. For example, :py:func:`filter` could refer to a function
2936 named filter in the current module, or the built-in function of that
2937 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
2938 function in the foo module.
2939 Normally, names in these roles are searched first without any further
2941 qualification, then with the current module name prepended, then with
2942 the current module and class name (if any) prepended. If you prefix
2943 the name with a dot, this order is reversed. For example, in the docu‐
2944 mentation of Python’s codecs module, :py:func:`open` always refers to
2945 the built-in function, while :py:func:`.open` refers to codecs.open().
2946 A similar heuristic is used to determine whether the name is an
2948 attribute of the currently documented class.
2949 Also, if the name is prefixed with a dot, and no exact match is found,
2951 the target is taken as a suffix and all object names with that suffix
2952 are searched. For example, :py:meth:`.TarFile.close` references the
2953 tarfile.TarFile.close() function, even if the current module is not
2954 tarfile. Since this can get ambiguous, if there is more than one pos‐
2955 sible match, you will get a warning from Sphinx.
2956 Note that you can combine the ~ and . prefixes:
2958 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
2959 method, but the visible link caption will only be close().
2960 The C Domain
2962 The C domain (name c) is suited for documentation of C API.
2963 .. c:function:: function prototype
2965 Describes a C function. The signature should be given as in C,
2966 e.g.:
2967 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
2969 This is also used to describe function-like preprocessor macros.
2971 The names of the arguments should be given so they may be used
2972 in the description.
2973 Note that you don’t have to backslash-escape asterisks in the
2975 signature, as it is not parsed by the reST inliner.
2976 .. c:member:: declaration
2978 Describes a C struct member. Example signature:
2979 .. c:member:: PyObject* PyTypeObject.tp_bases
2981 The text of the description should include the range of values
2983 allowed, how the value should be interpreted, and whether the
2984 value can be changed. References to structure members in text
2985 should use the member role.
2986 .. c:macro:: name
2988 Describes a “simple” C macro. Simple macros are macros which
2989 are used for code expansion, but which do not take arguments so
2990 cannot be described as functions. This is a simple C-language
2991 #define. Examples of its use in the Python documentation
2992 include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
2993 .. c:type:: name
2995 Describes a C type (whether defined by a typedef or struct). The
2996 signature should just be the type name.
2997 .. c:var:: declaration
2999 Describes a global C variable. The signature should include the
3000 type, such as:
3001 .. c:var:: PyObject* PyClass_Type
3003 Cross-referencing C constructs
3005 The following roles create cross-references to C-language constructs if
3006 they are defined in the documentation:
3007 :c:func:
3009 Reference a C-language function. Should include trailing paren‐
3010 theses.
3011 :c:member:
3013 Reference a C-language member of a struct.
3014 :c:macro:
3016 Reference a “simple” C macro, as defined above.
3017 :c:type:
3019 Reference a C-language type.
3020 :c:data:
3022 Reference a C-language variable.
3023 The C++ Domain
3025 The C++ domain (name cpp) supports documenting C++ projects.
3026 Directives
3028 The following directives are available. All declarations can start with
3029 a visibility statement (public, private or protected).
3030 .. cpp:class:: class specifier
3032 Describe a class/struct, possibly with specification of inheri‐
3033 tance, e.g.,:
3034 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3036 The class can be directly declared inside a nested scope, e.g.,:
3038 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3040 A class template can be declared:
3042 .. cpp:class:: template<typename T, std::size_t N> std::array
3044 or with a line break:
3046 .. cpp:class:: template<typename T, std::size_t N> \
3048 std::array
3049 Full and partial template specialisations can be declared:
3051 .. cpp:class:: template<> \
3053 std::array<bool, 256>
3054 .. cpp:class:: template<typename T> \
3056 std::array<T, 42>
3057 .. cpp:function:: (member) function prototype
3059 Describe a function or member function, e.g.,:
3060 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3062 A function with parameters and types.
3064 .. cpp:function:: bool myMethod(int, double)
3066 A function with unnamed parameters.
3068 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3070 An overload for the indexing operator.
3072 .. cpp:function:: operator bool() const
3074 A casting operator.
3076 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3078 A constexpr function.
3080 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3082 A copy constructor with default implementation.
3084 Function templates can also be described:
3086 .. cpp:function:: template<typename U> \
3088 void print(U &&u)
3089 and function template specialisations:
3091 .. cpp:function:: template<> \
3093 void print(int i)
3094 .. cpp:member:: (member) variable declaration
3096 .. cpp:var:: (member) variable declaration
3098 Describe a variable or member variable, e.g.,:
3099 .. cpp:member:: std::string MyClass::myMember
3101 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3103 .. cpp:member:: int a = 42
3105 Variable templates can also be described:
3107 .. cpp:member:: template<class T> \
3109 constexpr T pi = T(3.1415926535897932385)
3110 .. cpp:type:: typedef declaration
3112 .. cpp:type:: name
3114 .. cpp:type:: type alias declaration
3116 Describe a type as in a typedef declaration, a type alias decla‐
3117 ration, or simply the name of a type with unspecified type,
3118 e.g.,:
3119 .. cpp:type:: std::vector<int> MyList
3121 A typedef-like declaration of a type.
3123 .. cpp:type:: MyContainer::const_iterator
3125 Declaration of a type alias with unspecified type.
3127 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3129 Declaration of a type alias.
3131 A type alias can also be templated:
3133 .. cpp:type:: template<typename T> \
3135 MyContainer = std::vector<T>
3136 The example are rendered as follows.
3138 typedef std::vector<int> MyList
3140 A typedef-like declaration of a type.
3141 type MyContainer::const_iterator
3143 Declaration of a type alias with unspecified type.
3144 using MyType = std::unordered_map<int, std::string>
3146 Declaration of a type alias.
3147 template<typename T> using MyContainer = std::vector<T>
3149 .. cpp:enum:: unscoped enum declaration
3151 .. cpp:enum-struct:: scoped enum declaration
3153 .. cpp:enum-class:: scoped enum declaration
3155 Describe a (scoped) enum, possibly with the underlying type
3156 specified. Any enumerators declared inside an unscoped enum
3157 will be declared both in the enum scope and in the parent scope.
3158 Examples:
3159 .. cpp:enum:: MyEnum
3161 An unscoped enum.
3163 .. cpp:enum:: MySpecificEnum : long
3165 An unscoped enum with specified underlying type.
3167 .. cpp:enum-class:: MyScopedEnum
3169 A scoped enum.
3171 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3173 A scoped enum with non-default visibility, and with a specified underlying type.
3175 .. cpp:enumerator:: name
3177 .. cpp:enumerator:: name = constant
3179 Describe an enumerator, optionally with its value defined,
3180 e.g.,:
3181 .. cpp:enumerator:: MyEnum::myEnumerator
3183 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3185 .. cpp:union:: name
3187 Describe a union.
3188 .. cpp:concept:: template-parameter-list name
3190 WARNING:
3192 The support for concepts is experimental. It is based on the
3193 current draft standard and the Concepts Technical Specifica‐
3194 tion. The features may change as they evolve.
3195 Describe a concept. It must have exactly 1 template parameter
3197 list. The name may be a nested name. Example:
3198 .. cpp:concept:: template<typename It> std::Iterator
3200 Proxy to an element of a notional sequence that can be compared,
3202 indirected, or incremented.
3203 **Notation**
3205 .. cpp:var:: It r
3207 An lvalue.
3209 **Valid Expressions**
3211 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3213 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.
3214 This will render as follows:
3216 template<typename It> concept std::Iterator
3218 Proxy to an element of a notional sequence that can be
3219 compared, indirected, or incremented.
3220 Notation
3222 It r An lvalue.
3224 Valid Expressions
3226 · *r, when r is dereferenceable.
3228 · ++r, with return type It&, when r is incrementable.
3230 Options
3232 Some directives support options:
3233 · :noindex:, see Basic Markup.
3235 · :tparam-line-spec:, for templated declarations. If specified, each
3237 template parameter will be rendered on a separate line.
3238 Anonymous Entities
3240 C++ supports anonymous namespaces, classes, enums, and unions. For the
3241 sake of documentation they must be given some name that starts with @,
3242 e.g., @42 or @data. These names can also be used in cross-references
3243 and (type) expressions, though nested symbols will be found even when
3244 omitted. The @... name will always be rendered as [anonymous] (possi‐
3245 bly as a link).
3246 Example:
3248 .. cpp:class:: Data
3250 .. cpp:union:: @data
3252 .. cpp:var:: int a
3254 .. cpp:var:: double b
3256 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3258 This will be rendered as:
3260 class Data
3262 union [anonymous]
3264 int a
3266 double b
3268 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3270 Constrained Templates
3272 WARNING:
3273 The support for concepts is experimental. It is based on the current
3274 draft standard and the Concepts Technical Specification. The fea‐
3275 tures may change as they evolve.
3276 NOTE:
3278 Sphinx does not currently support requires clauses.
3279 Placeholders
3281 Declarations may use the name of a concept to introduce constrained
3282 template parameters, or the keyword auto to introduce unconstrained
3283 template parameters:
3284 .. cpp:function:: void f(auto &&arg)
3286 A function template with a single unconstrained template parameter.
3288 .. cpp:function:: void f(std::Iterator it)
3290 A function template with a single template parameter, constrained by the
3292 Iterator concept.
3293 Template Introductions
3295 Simple constrained function or class templates can be declared with a
3296 template introduction instead of a template parameter list:
3297 .. cpp:function:: std::Iterator{It} void advance(It &it)
3299 A function template with a template parameter constrained to be an
3301 Iterator.
3302 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3304 A class template with a template parameter constrained to be
3306 LessThanComparable.
3307 They are rendered as follows.
3309 std::Iterator{It} void advance(It &it)
3311 A function template with a template parameter constrained to be
3312 an Iterator.
3313 std::LessThanComparable{T} class MySortedContainer
3315 A class template with a template parameter constrained to be
3316 LessThanComparable.
3317 Note however that no checking is performed with respect to parameter
3319 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3320 tion even though it would not be valid C++.
3321 Inline Expressions and Types
3323 :cpp:expr:
3324 :cpp:texpr:
3326 Insert a C++ expression or type either as inline code (cpp:expr)
3327 or inline text (cpp:texpr). For example:
3328 .. cpp:var:: int a = 42
3330 .. cpp:function:: int f(int i)
3332 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
3334 A type: :cpp:expr:`const MySortedContainer<int>&`
3336 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
3337 will be rendered as follows:
3339 int a = 42
3341 int f(int i)
3343 An expression: a * f(a) (or as text: a * f(a)).
3345 A type: const MySortedContainer<int>& (or as text const MySort‐
3347 edContainer<int>&).
3348 Namespacing
3350 Declarations in the C++ domain are as default placed in global scope.
3351 The current scope can be changed using three namespace directives.
3352 They manage a stack declarations where cpp:namespace resets the stack
3353 and changes a given scope.
3354 The cpp:namespace-push directive changes the scope to a given inner
3356 scope of the current one.
3357 The cpp:namespace-pop directive undoes the most recent cpp:names‐
3359 pace-push directive.
3360 .. cpp:namespace:: scope specification
3362 Changes the current scope for the subsequent objects to the
3363 given scope, and resets the namespace directive stack. Note
3364 that the namespace does not need to correspond to C++ names‐
3365 paces, but can end in names of classes, e.g.,:
3366 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3368 All subsequent objects will be defined as if their name were
3370 declared with the scope prepended. The subsequent cross-refer‐
3371 ences will be searched for starting in the current scope.
3372 Using NULL, 0, or nullptr as the scope will change to global
3374 scope.
3375 A namespace declaration can also be templated, e.g.,:
3377 .. cpp:class:: template<typename T> \
3379 std::vector
3380 .. cpp:namespace:: template<typename T> std::vector
3382 .. cpp:function:: std::size_t size() const
3384 declares size as a member function of the class template
3386 std::vector. Equivalently this could have been declared using:
3387 .. cpp:class:: template<typename T> \
3389 std::vector
3390 .. cpp:function:: std::size_t size() const
3392 or:
3394 .. cpp:class:: template<typename T> \
3396 std::vector
3397 .. cpp:namespace-push:: scope specification
3399 Change the scope relatively to the current scope. For example,
3400 after:
3401 .. cpp:namespace:: A::B
3403 .. cpp:namespace-push:: C::D
3405 the current scope will be A::B::C::D.
3407 .. cpp:namespace-pop::
3409 Undo the previous cpp:namespace-push directive (not just pop a
3410 scope). For example, after:
3411 .. cpp:namespace:: A::B
3413 .. cpp:namespace-push:: C::D
3415 .. cpp:namespace-pop::
3417 the current scope will be A::B (not A::B::C).
3419 If no previous cpp:namespace-push directive has been used, but
3421 only a cpp:namespace directive, then the current scope will be
3422 reset to global scope. That is, .. cpp:namespace:: A::B is
3423 equivalent to:
3424 .. cpp:namespace:: nullptr
3426 .. cpp:namespace-push:: A::B
3428 Info field lists
3430 The C++ directives support the following info fields (see also Info
3431 field lists):
3432 · param, parameter, arg, argument: Description of a parameter.
3434 · tparam: Description of a template parameter.
3436 · returns, return: Description of a return value.
3438 · throws, throw, exception: Description of a possibly thrown exception.
3440 Cross-referencing
3442 These roles link to the given declaration types:
3443 :cpp:any:
3445 :cpp:class:
3447 :cpp:func:
3449 :cpp:member:
3451 :cpp:var:
3453 :cpp:type:
3455 :cpp:concept:
3457 :cpp:enum:
3459 :cpp:enumerator:
3461 Reference a C++ declaration by name (see below for details).
3462 The name must be properly qualified relative to the position of
3463 the link.
3464 Note on References with Templates Parameters/Arguments
3466 These roles follow the Sphinx xref-syntax rules. This means
3468 care must be taken when referencing a (partial) template spe‐
3469 cialization, e.g. if the link looks like this:
3470 :cpp:class:`MyClass<int>`. This is interpreted as a link to
3471 int with a title of MyClass. In this case, escape the open‐
3472 ing angle bracket with a backslash, like this:
3473 :cpp:class:`MyClass\<int>`.
3474 When a custom title is not needed it may be useful to use the
3476 roles for inline expressions, cpp:expr and cpp:texpr, where
3477 angle brackets do not need escaping.
3478 Declarations without template parameters and template arguments
3480 For linking to non-templated declarations the name must be a nested
3481 name, e.g., f or MyClass::f.
3482 Overloaded (member) functions
3484 When a (member) function is referenced using just its name, the refer‐
3485 ence will point to an arbitrary matching overload. The cpp:any and
3486 cpp:func roles will an alternative format, which simply is a complete
3487 function declaration. This will resolve to the exact matching over‐
3488 load. As example, consider the following class declaration:
3489 class C
3491 void f(double d) const
3493 void f(double d)
3495 void f(int i)
3497 void f()
3499 References using the cpp:func role:
3501 · Arbitrary overload: C::f, C::f()
3503 · Also arbitrary overload: C::f(), C::f()
3505 · Specific overload: void C::f(), void C::f()
3507 · Specific overload: void C::f(int), void C::f(int)
3509 · Specific overload: void C::f(double), void C::f(double)
3511 · Specific overload: void C::f(double) const, void C::f(double) const
3513 Note that the add_function_parentheses configuration variable does not
3515 influence specific overload references.
3516 Templated declarations
3518 Assume the following declarations.
3519 class Wrapper
3521 template<typename TOuter> class Outer
3523 template<typename TInner> class Inner
3525 In general the reference must include the template parameter declara‐
3527 tions, and template arguments for the prefix of qualified names. For
3528 example:
3529 · template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
3531 Wrapper::Outer)
3532 · template\<typename TOuter> template\<typename TInner> Wrap‐
3534 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
3535 name TInner> Wrapper::Outer<TOuter>::Inner)
3536 Currently the lookup only succeed if the template parameter identifiers
3538 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
3539 will not work.
3540 As a shorthand notation, if a template parameter list is omitted, then
3542 the lookup will assume either a primary template or a non-template, but
3543 not a partial template specialisation. This means the following refer‐
3544 ences work as well:
3545 · Wrapper::Outer (Wrapper::Outer)
3547 · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
3549 · template\<typename TInner> Wrapper::Outer::Inner (template<typename
3551 TInner> Wrapper::Outer::Inner)
3552 (Full) Template Specialisations
3554 Assume the following declarations.
3555 template<typename TOuter> class Outer
3557 template<typename TInner> class Inner
3559 template<> class Outer<int>
3561 template<typename TInner> class Inner
3563 template<> class Inner<bool>
3565 In general the reference must include a template parameter list for
3567 each template argument list. The full specialisation above can there‐
3568 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
3569 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
3570 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
3571 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
3572 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
3573 Partial Template Specialisations
3575 Assume the following declaration.
3576 template<typename T> class Outer<T *>
3578 References to partial specialisations must always include the template
3580 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
3581 template<typename T> Outer<T*>). Currently the lookup only succeed if
3582 the template parameter identifiers are equal strings.
3583 Configuration Variables
3585 See cpp-config.
3586 The Standard Domain
3588 The so-called “standard” domain collects all markup that doesn’t war‐
3589 rant a domain of its own. Its directives and roles are not prefixed
3590 with a domain name.
3591 The standard domain is also where custom object descriptions, added
3593 using the add_object_type() API, are placed.
3594 There is a set of directives allowing documenting command-line pro‐
3596 grams:
3597 .. option:: name args, name args, ...
3599 Describes a command line argument or switch. Option argument
3600 names should be enclosed in angle brackets. Examples:
3601 .. option:: dest_dir
3603 Destination directory.
3605 .. option:: -m <module>, --module <module>
3607 Run a module as a script.
3609 The directive will create cross-reference targets for the given
3611 options, referenceable by option (in the example case, you’d use
3612 something like :option:`dest_dir`, :option:`-m`, or
3613 :option:`--module`).
3614 cmdoption directive is a deprecated alias for the option direc‐
3616 tive.
3617 .. envvar:: name
3619 Describes an environment variable that the documented code or
3620 program uses or defines. Referenceable by envvar.
3621 .. program:: name
3623 Like py:currentmodule, this directive produces no output.
3624 Instead, it serves to notify Sphinx that all following option
3625 directives document options for the program called name.
3626 If you use program, you have to qualify the references in your
3628 option roles by the program name, so if you have the following
3629 situation
3630 .. program:: rm
3632 .. option:: -r
3634 Work recursively.
3636 .. program:: svn
3638 .. option:: -r revision
3640 Specify the revision to work upon.
3642 then :option:`rm -r` would refer to the first option, while
3644 :option:`svn -r` would refer to the second one.
3645 The program name may contain spaces (in case you want to docu‐
3647 ment subcommands like svn add and svn commit separately).
3648 New in version 0.5.
3650 There is also a very generic object description directive, which is not
3653 tied to any domain:
3654 .. describe:: text
3656 .. object:: text
3658 This directive produces the same formatting as the specific ones
3659 provided by domains, but does not create index entries or
3660 cross-referencing targets. Example:
3661 .. describe:: PAPER
3663 You can set this variable to select a paper size.
3665 The JavaScript Domain
3667 The JavaScript domain (name js) provides the following directives:
3668 .. js:module:: name
3670 This directive sets the module name for object declarations that
3671 follow after. The module name is used in the global module index
3672 and in cross references. This directive does not create an
3673 object heading like py:class would, for example.
3674 By default, this directive will create a linkable entity and
3676 will cause an entry in the global module index, unless the noin‐
3677 dex option is specified. If this option is specified, the
3678 directive will only update the current module name.
3679 To clear the current module, set the module name to null or None
3681 New in version 1.6.
3683 .. js:function:: name(signature)
3686 Describes a JavaScript function or method. If you want to
3687 describe arguments as optional use square brackets as documented
3688 for Python signatures.
3689 You can use fields to give more details about arguments and
3691 their expected types, errors which may be thrown by the func‐
3692 tion, and the value being returned:
3693 .. js:function:: $.getJSON(href, callback[, errback])
3695 :param string href: An URI to the location of the resource.
3697 :param callback: Gets called with the object.
3698 :param errback:
3699 Gets called in case the request fails. And a lot of other
3700 text so we need multiple lines.
3701 :throws SomeError: For whatever reason in that case.
3702 :returns: Something.
3703 This is rendered as:
3705 $.getJSON(href, callback[, errback])
3707 Arguments
3709 · href (string) – An URI to the location of the
3711 resource.
3712 · callback – Gets called with the object.
3714 · errback – Gets called in case the request
3716 fails. And a lot of other text so we need
3717 multiple lines.
3718 Throws SomeError – For whatever reason in that case.
3720 Returns
3722 Something.
3723 .. js:method:: name(signature)
3725 This directive is an alias for js:function, however it describes
3726 a function that is implemented as a method on a class object.
3727 New in version 1.6.
3729 .. js:class:: name
3732 Describes a constructor that creates an object. This is basi‐
3733 cally like a function but will show up with a class prefix:
3734 .. js:class:: MyAnimal(name[, age])
3736 :param string name: The name of the animal
3738 :param number age: an optional age for the animal
3739 This is rendered as:
3741 class MyAnimal(name[, age])
3743 Arguments
3745 · name (string) – The name of the animal
3747 · age (number) – an optional age for the animal
3749 .. js:data:: name
3751 Describes a global variable or constant.
3752 .. js:attribute:: object.name
3754 Describes the attribute name of object.
3755 These roles are provided to refer to the described objects:
3757 :js:mod:
3759 :js:func:
3761 :js:meth:
3763 :js:class:
3765 :js:data:
3767 :js:attr:
3769 The reStructuredText domain
3771 The reStructuredText domain (name rst) provides the following direc‐
3772 tives:
3773 .. rst:directive:: name
3775 Describes a reST directive. The name can be a single directive
3776 name or actual directive syntax (.. prefix and :: suffix) with
3777 arguments that will be rendered differently. For example:
3778 .. rst:directive:: foo
3780 Foo description.
3782 .. rst:directive:: .. bar:: baz
3784 Bar description.
3786 will be rendered as:
3788 .. foo::
3790 Foo description.
3791 .. bar:: baz
3793 Bar description.
3794 .. rst:role:: name
3796 Describes a reST role. For example:
3797 .. rst:role:: foo
3799 Foo description.
3801 will be rendered as:
3803 :foo: Foo description.
3805 These roles are provided to refer to the described objects:
3807 :rst:dir:
3809 :rst:role:
3811 The Math Domain
3813 The math domain (name math) provides the following roles:
3814 .. rst:role:: math:numref
3816 Role for cross-referencing equations defined by math directive via
3817 their label. Example:
3818 .. math:: e^{i\pi} + 1 = 0
3820 :label: euler
3821 Euler's identity, equation :math:numref:`euler`, was elected one of the
3823 most beautiful mathematical formulas.
3824 New in version 1.8.
3826 More domains
3829 The sphinx-contrib repository contains more domains available as exten‐
3830 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
3831 and Ruby domains. Also available are domains for Chapel, Common Lisp,
3832 dqn, Go, Jinja, Operation, and Scala.
3833
3835 Markdown is a lightweight markup language with a simplistic plain text
3836 formatting syntax. It exists in many syntactically different flavors.
3837 To support Markdown-based documentation, Sphinx can use recommonmark.
3838 recommonmark is a Docutils bridge to CommonMark-py, a Python package
3839 for parsing the CommonMark Markdown flavor.
3840 Configuration
3842 To configure your Sphinx project for Markdown support, proceed as fol‐
3843 lows:
3844 1. Install recommonmark:
3846 pip install recommonmark
3848 2. Add the Markdown parser to the source_parsers configuration variable
3850 in your Sphinx configuration file:
3851 source_parsers = {
3853 '.md': 'recommonmark.parser.CommonMarkParser',
3854 }
3855 You can replace .md with a filename extension of your choice.
3857 3. Add the Markdown filename extension to the source_suffix configura‐
3859 tion variable:
3860 source_suffix = ['.rst', '.md']
3862 4. You can further configure recommonmark to allow custom syntax that
3864 standard CommonMark doesn’t support. Read more in the recommonmark
3865 documentation.
3866
3868 The configuration directory must contain a file named conf.py. This
3869 file (containing Python code) is called the “build configuration file”
3870 and contains (almost) all configuration needed to customize Sphinx
3871 input and output behavior.
3872 An optional file docutils.conf can be added to the configuration
3873 directory to adjust Docutils configuration if not otherwise overrid‐
3874 den or set by Sphinx.
3875 The configuration file is executed as Python code at build time (using
3877 execfile(), and with the current directory set to its containing direc‐
3878 tory), and therefore can execute arbitrarily complex code. Sphinx then
3879 reads simple names from the file’s namespace as its configuration.
3880 Important points to note:
3882 · If not otherwise documented, values must be strings, and their
3884 default is the empty string.
3885 · The term “fully-qualified name” refers to a string that names an
3887 importable Python object inside a module; for example, the FQN
3888 "sphinx.builders.Builder" means the Builder class in the
3889 sphinx.builders module.
3890 · Remember that document names use / as the path separator and don’t
3892 contain the file name extension.
3893 · Since conf.py is read as a Python file, the usual rules apply for
3895 encodings and Unicode support: declare the encoding using an encoding
3896 cookie (a comment like # -*- coding: utf-8 -*-) and use Unicode
3897 string literals when you include non-ASCII characters in configura‐
3898 tion values.
3899 · The contents of the config namespace are pickled (so that Sphinx can
3901 find out when configuration changes), so it may not contain unpick‐
3902 leable values – delete them from the namespace with del if appropri‐
3903 ate. Modules are removed automatically, so you don’t need to del
3904 your imports after use.
3905 · There is a special object named tags available in the config file.
3907 It can be used to query and change the tags (see tags). Use
3908 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
3909 change. Only tags set via the -t command-line option or via
3910 tags.add('tag') can be queried using tags.has('tag'). Note that the
3911 current builder tag is not available in conf.py, as it is created
3912 after the builder is initialized.
3913 General configuration
3915 extensions
3916 A list of strings that are module names of extensions. These can
3917 be extensions coming with Sphinx (named sphinx.ext.*) or custom
3918 ones.
3919 Note that you can extend sys.path within the conf file if your
3921 extensions live in another directory – but make sure you use
3922 absolute paths. If your extension path is relative to the con‐
3923 figuration directory, use os.path.abspath() like so:
3924 import sys, os
3926 sys.path.append(os.path.abspath('sphinxext'))
3928 extensions = ['extname']
3930 That way, you can load an extension called extname from the sub‐
3932 directory sphinxext.
3933 The configuration file itself can be an extension; for that, you
3935 only need to provide a setup() function in it.
3936 source_suffix
3938 The file extensions of source files. Sphinx considers the files
3939 with this suffix as sources. The value can be a dictionary map‐
3940 ping file extensions to file types. For example:
3941 source_suffix = {
3943 '.rst': 'restructuredtext',
3944 '.txt': 'restructuredtext',
3945 '.md': 'markdown',
3946 }
3947 By default, Sphinx only supports 'restructuredtext' file type.
3949 You can add a new file type using source parser extensions.
3950 Please read a document of the extension to know which file type
3951 the extension supports.
3952 The value may also be a list of file extensions: then Sphinx
3954 will consider that they all map to the 'restructuredtext' file
3955 type.
3956 Default is {'.rst': 'restructuredtext'}.
3958 NOTE:
3960 file extensions have to start with a dot (e.g. .rst).
3961 Changed in version 1.3: Can now be a list of extensions.
3963 Changed in version 1.8: Support file type mapping
3966 source_encoding
3969 The encoding of all reST source files. The recommended encod‐
3970 ing, and the default value, is 'utf-8-sig'.
3971 New in version 0.5: Previously, Sphinx accepted only UTF-8
3973 encoded sources.
3974 source_parsers
3977 If given, a dictionary of parser classes for different source
3978 suffices. The keys are the suffix, the values can be either a
3979 class or a string giving a fully-qualified name of a parser
3980 class. The parser class can be either docutils.parsers.Parser
3981 or sphinx.parsers.Parser. Files with a suffix that is not in
3982 the dictionary will be parsed with the default reStructuredText
3983 parser.
3984 For example:
3986 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
3988 NOTE:
3990 Refer to /usage/markdown for more information on using Mark‐
3991 down with Sphinx.
3992 New in version 1.3.
3994 Deprecated since version 1.8: Now Sphinx provides an API
3997 Sphinx.add_source_parser() to register a source parser. Please
3998 use it instead.
3999 master_doc
4002 The document name of the “master” document, that is, the docu‐
4003 ment that contains the root toctree directive. Default is 'con‐
4004 tents'.
4005 exclude_patterns
4007 A list of glob-style patterns that should be excluded when look‐
4008 ing for source files. [1] They are matched against the source
4009 file names relative to the source directory, using slashes as
4010 directory separators on all platforms.
4011 Example patterns:
4013 · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4015 entry in unused_docs)
4016 · 'library/xml' – ignores the library/xml directory
4018 · 'library/xml*' – ignores all files and directories starting
4020 with library/xml
4021 · '**/.svn' – ignores all .svn directories
4023 exclude_patterns is also consulted when looking for static files
4025 in html_static_path and html_extra_path.
4026 New in version 1.0.
4028 templates_path
4031 A list of paths that contain extra templates (or templates that
4032 overwrite builtin/theme-specific templates). Relative paths are
4033 taken as relative to the configuration directory.
4034 Changed in version 1.3: As these files are not meant to be
4036 built, they are automatically added to exclude_patterns.
4037 template_bridge
4040 A string with the fully-qualified name of a callable (or simply
4041 a class) that returns an instance of TemplateBridge. This
4042 instance is then used to render HTML documents, and possibly the
4043 output of other builders (currently the changes builder). (Note
4044 that the template bridge must be made theme-aware if HTML themes
4045 are to be used.)
4046 rst_epilog
4048 A string of reStructuredText that will be included at the end of
4049 every source file that is read. This is a possible place to add
4050 substitutions that should be available in every file (another
4051 being rst_prolog). An example:
4052 rst_epilog = """
4054 .. |psf| replace:: Python Software Foundation
4055 """
4056 New in version 0.6.
4058 rst_prolog
4061 A string of reStructuredText that will be included at the begin‐
4062 ning of every source file that is read. This is a possible
4063 place to add substitutions that should be available in every
4064 file (another being rst_epilog). An example:
4065 rst_prolog = """
4067 .. |psf| replace:: Python Software Foundation
4068 """
4069 New in version 1.0.
4071 primary_domain
4074 The name of the default domain. Can also be None to disable a
4075 default domain. The default is 'py'. Those objects in other
4076 domains (whether the domain name is given explicitly, or
4077 selected by a default-domain directive) will have the domain
4078 name explicitly prepended when named (e.g., when the default
4079 domain is C, Python functions will be named “Python function”,
4080 not just “function”).
4081 New in version 1.0.
4083 default_role
4086 The name of a reST role (builtin or Sphinx extension) to use as
4087 the default role, that is, for text marked up `like this`. This
4088 can be set to 'py:obj' to make `filter` a cross-reference to the
4089 Python function “filter”. The default is None, which doesn’t
4090 reassign the default role.
4091 The default role can always be set within individual documents
4093 using the standard reST default-role directive.
4094 New in version 0.4.
4096 keep_warnings
4099 If true, keep warnings as “system message” paragraphs in the
4100 built documents. Regardless of this setting, warnings are
4101 always written to the standard error stream when sphinx-build is
4102 run.
4103 The default is False, the pre-0.5 behavior was to always keep
4105 them.
4106 New in version 0.5.
4108 suppress_warnings
4111 A list of warning types to suppress arbitrary warning messages.
4112 Sphinx supports following warning types:
4114 · app.add_node
4116 · app.add_directive
4118 · app.add_role
4120 · app.add_generic_role
4122 · app.add_source_parser
4124 · download.not_readable
4126 · image.not_readable
4128 · ref.term
4130 · ref.ref
4132 · ref.numref
4134 · ref.keyword
4136 · ref.option
4138 · ref.citation
4140 · ref.footnote
4142 · ref.doc
4144 · ref.python
4146 · misc.highlighting_failure
4148 · toc.secnum
4150 · epub.unknown_project_files
4152 You can choose from these types.
4154 Now, this option should be considered experimental.
4156 New in version 1.4.
4158 Changed in version 1.5: Added misc.highlighting_failure
4161 Changed in version 1.5.1: Added epub.unknown_project_files
4164 Changed in version 1.6: Added ref.footnote
4167 needs_sphinx
4170 If set to a major.minor version string like '1.1', Sphinx will
4171 compare it with its version and refuse to build if it is too
4172 old. Default is no requirement.
4173 New in version 1.0.
4175 Changed in version 1.4: also accepts micro version string
4178 needs_extensions
4181 This value can be a dictionary specifying version requirements
4182 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4183 contrib.something': '1.5'}. The version strings should be in
4184 the form major.minor. Requirements do not have to be specified
4185 for all extensions, only for those you want to check.
4186 This requires that the extension specifies its version to Sphinx
4188 (see dev-extensions for how to do that).
4189 New in version 1.3.
4191 manpages_url
4194 A URL to cross-reference manpage directives. If this is defined
4195 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4196 role will link to <https://manpages.debian.org/man(1)>. The pat‐
4197 terns available are:
4198 · page - the manual page (man)
4200 · section - the manual section (1)
4202 · path - the original manual page and section specified
4204 (man(1))
4205 This also supports manpages specified as man.1.
4207 NOTE:
4209 This currently affects only HTML writers but could be
4210 expanded in the future.
4211 New in version 1.7.
4213 nitpicky
4216 If true, Sphinx will warn about all references where the target
4217 cannot be found. Default is False. You can activate this mode
4218 temporarily using the -n command-line switch.
4219 New in version 1.0.
4221 nitpick_ignore
4224 A list of (type, target) tuples (by default empty) that should
4225 be ignored when generating warnings in “nitpicky mode”. Note
4226 that type should include the domain name if present. Example
4227 entries would be ('py:func', 'int') or ('envvar',
4228 'LD_LIBRARY_PATH').
4229 New in version 1.1.
4231 numfig If true, figures, tables and code-blocks are automatically num‐
4234 bered if they have a caption. The numref role is enabled.
4235 Obeyed so far only by HTML and LaTeX builders. Default is False.
4236 NOTE:
4238 The LaTeX builder always assigns numbers whether this option
4239 is enabled or not.
4240 New in version 1.3.
4242 numfig_format
4245 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4246 tion' to strings that are used for format of figure numbers. As
4247 a special character, %s will be replaced to figure number.
4248 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4250 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4251 New in version 1.3.
4253 numfig_secnum_depth
4256 · if set to 0, figures, tables and code-blocks are continuously
4258 numbered starting at 1.
4259 · if 1 (default) numbers will be x.1, x.2, … with x the section
4261 number (top level sectioning; no x. if no section). This nat‐
4262 urally applies only if section numbering has been activated
4263 via the :numbered: option of the toctree directive.
4264 · 2 means that numbers will be x.y.1, x.y.2, … if located in a
4266 sub-section (but still x.1, x.2, … if located directly under a
4267 section and 1, 2, … if not in any top level section.)
4268 · etc…
4270 New in version 1.3.
4272 Changed in version 1.7: The LaTeX builder obeys this setting (if
4275 numfig is set to True).
4276 smartquotes
4279 If true, the Docutils Smart Quotes transform, originally based
4280 on SmartyPants (limited to English) and currently applying to
4281 many languages, will be used to convert quotes and dashes to
4282 typographically correct entities. Default: True.
4283 New in version 1.6.6: It replaces deprecated
4285 html_use_smartypants. It applies by default to all builders
4286 except man and text (see smartquotes_excludes.)
4287 A docutils.conf file located in the configuration directory (or
4290 a global ~/.docutils file) is obeyed unconditionally if it deac‐
4291 tivates smart quotes via the corresponding Docutils option. But
4292 if it activates them, then smartquotes does prevail.
4293 smartquotes_action
4295 This string, for use with Docutils 0.14 or later, customizes the
4296 Smart Quotes transform. See the file smartquotes.py at the
4297 Docutils repository for details. The default 'qDe' educates
4298 normal quote characters ", ', em- and en-Dashes ---, --, and
4299 ellipses ....
4300 New in version 1.6.6.
4302 smartquotes_excludes
4305 This is a dict whose default is:
4306 {'languages': ['ja'], 'builders': ['man', 'text']}
4308 Each entry gives a sufficient condition to ignore the
4310 smartquotes setting and deactivate the Smart Quotes transform.
4311 Accepted keys are as above 'builders' or 'languages'. The val‐
4312 ues are lists.
4313 NOTE:
4315 Currently, in case of invocation of make with multiple tar‐
4316 gets, the first target name is the only one which is tested
4317 against the 'builders' entry and it decides for all. Also, a
4318 make text following make html needs to be issued in the form
4319 make text O="-E" to force re-parsing of source files, as the
4320 cached ones are already transformed. On the other hand the
4321 issue does not arise with direct usage of sphinx-build as it
4322 caches (in its default usage) the parsed source files in per
4323 builder locations.
4324 New in version 1.6.6.
4326 tls_verify
4329 If true, Sphinx verifies server certifications. Default is
4330 True.
4331 New in version 1.5.
4333 tls_cacerts
4336 A path to a certification file of CA or a path to directory
4337 which contains the certificates. This also allows a dictionary
4338 mapping hostname to the path to certificate file. The certifi‐
4339 cates are used to verify server certifications.
4340 New in version 1.5.
4342 Project information
4345 project
4346 The documented project’s name.
4347 author The author name(s) of the document. The default value is
4349 'unknown'.
4350 copyright
4352 A copyright statement in the style '2008, Author Name'.
4353 version
4355 The major project version, used as the replacement for |ver‐
4356 sion|. For example, for the Python documentation, this may be
4357 something like 2.6.
4358 release
4360 The full project version, used as the replacement for |release|
4361 and e.g. in the HTML templates. For example, for the Python
4362 documentation, this may be something like 2.6.0rc1.
4363 If you don’t need the separation provided between version and
4365 release, just set them both to the same value.
4366 today
4368 today_fmt
4370 These values determine how to format the current date, used as
4371 the replacement for |today|.
4372 · If you set today to a non-empty value, it is used.
4374 · Otherwise, the current time is formatted using time.strftime()
4376 and the format given in today_fmt.
4377 The default is now today and a today_fmt of '%B %d, %Y' (or, if
4379 translation is enabled with language, an equivalent format for
4380 the selected locale).
4381 highlight_language
4383 The default language to highlight source code in. The default
4384 is 'python3'. The value should be a valid Pygments lexer name,
4385 see code-examples for more details.
4386 New in version 0.5.
4388 Changed in version 1.4: The default is now 'default'. It is sim‐
4391 ilar to 'python3'; it is mostly a superset of 'python' but it
4392 fallbacks to 'none' without warning if failed. 'python3' and
4393 other languages will emit warning if failed. If you prefer
4394 Python 2 only highlighting, you can set it back to 'python'.
4395 highlight_options
4398 A dictionary of options that modify how the lexer specified by
4399 highlight_language generates highlighted source code. These are
4400 lexer-specific; for the options understood by each, see the
4401 Pygments documentation.
4402 New in version 1.3.
4404 pygments_style
4407 The style name to use for Pygments highlighting of source code.
4408 If not set, either the theme’s default style or 'sphinx' is
4409 selected for HTML output.
4410 Changed in version 0.3: If the value is a fully-qualified name
4412 of a custom Pygments style class, this is then used as custom
4413 style.
4414 add_function_parentheses
4417 A boolean that decides whether parentheses are appended to func‐
4418 tion and method role text (e.g. the content of :func:`input`) to
4419 signify that the name is callable. Default is True.
4420 add_module_names
4422 A boolean that decides whether module names are prepended to all
4423 object names (for object types where a “module” of some kind is
4424 defined), e.g. for py:function directives. Default is True.
4425 show_authors
4427 A boolean that decides whether codeauthor and sectionauthor
4428 directives produce any output in the built files.
4429 modindex_common_prefix
4431 A list of prefixes that are ignored for sorting the Python mod‐
4432 ule index (e.g., if this is set to ['foo.'], then foo.bar is
4433 shown under B, not F). This can be handy if you document a
4434 project that consists of a single package. Works only for the
4435 HTML builder currently. Default is [].
4436 New in version 0.6.
4438 trim_footnote_reference_space
4441 Trim spaces before footnote references that are necessary for
4442 the reST parser to recognize the footnote, but do not look too
4443 nice in the output.
4444 New in version 0.6.
4446 trim_doctest_flags
4449 If true, doctest flags (comments looking like # doctest: FLAG,
4450 ...) at the ends of lines and <BLANKLINE> markers are removed
4451 for all code blocks showing interactive Python sessions (i.e.
4452 doctests). Default is True. See the extension doctest for more
4453 possibilities of including doctests.
4454 New in version 1.0.
4456 Changed in version 1.1: Now also removes <BLANKLINE>.
4459 Options for internationalization
4462 These options influence Sphinx’s Native Language Support. See the doc‐
4463 umentation on intl for details.
4464 language
4466 The code for the language the docs are written in. Any text
4467 automatically generated by Sphinx will be in that language.
4468 Also, Sphinx will try to substitute individual paragraphs from
4469 your documents with the translation sets obtained from
4470 locale_dirs. Sphinx will search language-specific figures named
4471 by figure_language_filename and substitute them for original
4472 figures. In the LaTeX builder, a suitable language will be
4473 selected as an option for the Babel package. Default is None,
4474 which means that no translation will be done.
4475 New in version 0.5.
4477 Changed in version 1.4: Support figure substitution
4480 Currently supported languages by Sphinx are:
4483 · bn – Bengali
4485 · ca – Catalan
4487 · cs – Czech
4489 · da – Danish
4491 · de – German
4493 · en – English
4495 · es – Spanish
4497 · et – Estonian
4499 · eu – Basque
4501 · fa – Iranian
4503 · fi – Finnish
4505 · fr – French
4507 · he – Hebrew
4509 · hr – Croatian
4511 · hu – Hungarian
4513 · id – Indonesian
4515 · it – Italian
4517 · ja – Japanese
4519 · ko – Korean
4521 · lt – Lithuanian
4523 · lv – Latvian
4525 · mk – Macedonian
4527 · nb_NO – Norwegian Bokmal
4529 · ne – Nepali
4531 · nl – Dutch
4533 · pl – Polish
4535 · pt_BR – Brazilian Portuguese
4537 · pt_PT – European Portuguese
4539 · ru – Russian
4541 · si – Sinhala
4543 · sk – Slovak
4545 · sl – Slovenian
4547 · sv – Swedish
4549 · tr – Turkish
4551 · uk_UA – Ukrainian
4553 · vi – Vietnamese
4555 · zh_CN – Simplified Chinese
4557 · zh_TW – Traditional Chinese
4559 locale_dirs
4561 New in version 0.5.
4562 Directories in which to search for additional message catalogs
4565 (see language), relative to the source directory. The directo‐
4566 ries on this path are searched by the standard gettext module.
4567 Internal messages are fetched from a text domain of sphinx; so
4569 if you add the directory ./locale to this setting, the message
4570 catalogs (compiled from .po format using msgfmt) must be in
4571 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
4572 individual documents depends on gettext_compact.
4573 The default is ['locales'].
4575 Changed in version 1.5: Use locales directory as a default value
4577 gettext_compact
4580 New in version 1.1.
4581 If true, a document’s text domain is its docname if it is a
4584 top-level project file and its very base directory otherwise.
4585 By default, the document markup/code.rst ends up in the markup
4587 text domain. With this option set to False, it is markup/code.
4588 gettext_uuid
4590 If true, Sphinx generates uuid information for version tracking
4591 in message catalogs. It is used for:
4592 · Add uid line for each msgids in .pot files.
4594 · Calculate similarity between new msgids and previously saved
4596 old msgids. This calculation takes a long time.
4597 If you want to accelerate the calculation, you can use
4599 python-levenshtein 3rd-party package written in C by using pip
4600 install python-levenshtein.
4601 The default is False.
4603 New in version 1.3.
4605 gettext_location
4608 If true, Sphinx generates location information for messages in
4609 message catalogs.
4610 The default is True.
4612 New in version 1.3.
4614 gettext_auto_build
4617 If true, Sphinx builds mo file for each translation catalog
4618 files.
4619 The default is True.
4621 New in version 1.3.
4623 gettext_additional_targets
4626 To specify names to enable gettext extracting and translation
4627 applying for i18n additionally. You can specify below names:
4628 Index index terms
4630 Literal-block
4632 literal blocks: :: and code-block.
4633 Doctest-block
4635 doctest block
4636 Raw raw content
4638 Image image/figure uri and alt
4640 For example: gettext_additional_targets = ['literal-block',
4642 'image'].
4643 The default is [].
4645 New in version 1.3.
4647 figure_language_filename
4650 The filename format for language-specific figures. The default
4651 value is {root}.{language}{ext}. It will be expanded to
4652 dirname/filename.en.png from .. image:: dirname/filename.png.
4653 The available format tokens are:
4654 · {root} - the filename, including any path component, without
4656 the file extension, e.g. dirname/filename
4657 · {path} - the directory path component of the filename, with a
4659 trailing slash if non-empty, e.g. dirname/
4660 · {basename} - the filename without the directory path or file
4662 extension components, e.g. filename
4663 · {ext} - the file extension, e.g. .png
4665 · {language} - the translation language, e.g. en
4667 For example, setting this to {path}{language}/{basename}{ext}
4669 will expand to dirname/en/filename.png instead.
4670 New in version 1.4.
4672 Changed in version 1.5: Added {path} and {basename} tokens.
4675 Options for Math
4678 These options influence Math notations.
4679 math_number_all
4681 Set this option to True if you want all displayed math to be
4682 numbered. The default is False.
4683 math_eqref_format
4685 A string used for formatting the labels of references to equa‐
4686 tions. The {number} place-holder stands for the equation num‐
4687 ber.
4688 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
4690 math_numfig
4692 If True, displayed math equations are numbered across pages when
4693 numfig is enabled. The numfig_secnum_depth setting is
4694 respected. The eq, not numref, role must be used to reference
4695 equation numbers. Default is True.
4696 New in version 1.7.
4698 Options for HTML output
4701 These options influence HTML as well as HTML Help output, and other
4702 builders that use Sphinx’s HTMLWriter class.
4703 html_theme
4705 The “theme” that the HTML output should use. See the section
4706 about theming. The default is 'alabaster'.
4707 New in version 0.6.
4709 html_theme_options
4712 A dictionary of options that influence the look and feel of the
4713 selected theme. These are theme-specific. For the options
4714 understood by the builtin themes, see this section.
4715 New in version 0.6.
4717 html_theme_path
4720 A list of paths that contain custom themes, either as subdirec‐
4721 tories or as zip files. Relative paths are taken as relative to
4722 the configuration directory.
4723 New in version 0.6.
4725 html_style
4728 The style sheet to use for HTML pages. A file of that name must
4729 exist either in Sphinx’s static/ path, or in one of the custom
4730 paths given in html_static_path. Default is the stylesheet
4731 given by the selected theme. If you only want to add or over‐
4732 ride a few things compared to the theme’s stylesheet, use CSS
4733 @import to import the theme’s stylesheet.
4734 html_title
4736 The “title” for HTML documentation generated with Sphinx’s own
4737 templates. This is appended to the <title> tag of individual
4738 pages, and used in the navigation bar as the “topmost” element.
4739 It defaults to '<project> v<revision> documentation'.
4740 html_short_title
4742 A shorter “title” for the HTML docs. This is used in for links
4743 in the header and in the HTML Help docs. If not given, it
4744 defaults to the value of html_title.
4745 New in version 0.4.
4747 html_baseurl
4750 The URL which points to the root of the HTML documentation. It
4751 is used to indicate the location of document like canonical_url.
4752 html_context
4754 A dictionary of values to pass into the template engine’s con‐
4755 text for all pages. Single values can also be put in this dic‐
4756 tionary using the -A command-line option of sphinx-build.
4757 New in version 0.5.
4759 html_logo
4762 If given, this must be the name of an image file (path relative
4763 to the configuration directory) that is the logo of the docs.
4764 It is placed at the top of the sidebar; its width should there‐
4765 fore not exceed 200 pixels. Default: None.
4766 New in version 0.4.1: The image file will be copied to the
4768 _static directory of the output HTML, but only if the file does
4769 not already exist there.
4770 html_favicon
4773 If given, this must be the name of an image file (path relative
4774 to the configuration directory) that is the favicon of the docs.
4775 Modern browsers use this as the icon for tabs, windows and book‐
4776 marks. It should be a Windows-style icon file (.ico), which is
4777 16x16 or 32x32 pixels large. Default: None.
4778 New in version 0.4: The image file will be copied to the _static
4780 directory of the output HTML, but only if the file does not
4781 already exist there.
4782 html_css_files
4785 A list of CSS files. The entry must be a filename string or a
4786 tuple containing the filename string and the attributes dictio‐
4787 nary. The filename must be relative to the html_static_path, or
4788 a full URI with scheme like http://example.org/style.css. The
4789 attributes is used for attributes of <link> tag. It defaults to
4790 an empty list.
4791 Example:
4793 html_css_files = ['custom.css'
4795 'https://example.com/css/custom.css',
4796 ('print.css', {'media': 'print'})]
4797 New in version 1.8.
4799 html_js_files
4802 A list of JavaScript filename. The entry must be a filename
4803 string or a tuple containing the filename string and the
4804 attributes dictionary. The filename must be relative to the
4805 html_static_path, or a full URI with scheme like http://exam‐
4806 ple.org/script.js. The attributes is used for attributes of
4807 <script> tag. It defaults to an empty list.
4808 Example:
4810 html_js_files = ['script.js',
4812 'https://example.com/scripts/custom.js',
4813 ('custom.js', {'async': 'async'})]
4814 New in version 1.8.
4816 html_static_path
4819 A list of paths that contain custom static files (such as style
4820 sheets or script files). Relative paths are taken as relative
4821 to the configuration directory. They are copied to the output’s
4822 _static directory after the theme’s static files, so a file
4823 named default.css will overwrite the theme’s default.css.
4824 As these files are not meant to be built, they are automatically
4826 excluded from source files.
4827 NOTE:
4829 For security reasons, dotfiles under html_static_path will
4830 not be copied. If you would like to copy them intentionally,
4831 please add each filepath to this setting:
4832 html_static_path = ['_static', '_static/.htaccess']
4834 Another way to do that, you can also use html_extra_path. It
4836 allows to copy dotfiles under the directories.
4837 Changed in version 0.4: The paths in html_static_path can now
4839 contain subdirectories.
4840 Changed in version 1.0: The entries in html_static_path can now
4843 be single files.
4844 Changed in version 1.8: The files under html_static_path are
4847 excluded from source files.
4848 html_extra_path
4851 A list of paths that contain extra files not directly related to
4852 the documentation, such as robots.txt or .htaccess. Relative
4853 paths are taken as relative to the configuration directory.
4854 They are copied to the output directory. They will overwrite
4855 any existing file of the same name.
4856 As these files are not meant to be built, they are automatically
4858 excluded from source files.
4859 New in version 1.2.
4861 Changed in version 1.4: The dotfiles in the extra directory will
4864 be copied to the output directory. And it refers
4865 exclude_patterns on copying extra files and directories, and
4866 ignores if path matches to patterns.
4867 html_last_updated_fmt
4870 If this is not None, a ‘Last updated on:’ timestamp is inserted
4871 at every page bottom, using the given strftime() format. The
4872 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
4873 equivalent).
4874 html_use_smartypants
4876 If true, quotes and dashes are converted to typographically cor‐
4877 rect entities. Default: True.
4878 Deprecated since version 1.6: To disable smart quotes, use
4880 rather smartquotes.
4881 html_add_permalinks
4884 Sphinx will add “permalinks” for each heading and description
4885 environment as paragraph signs that become visible when the
4886 mouse hovers over them.
4887 This value determines the text for the permalink; it defaults to
4889 "¶". Set it to None or the empty string to disable permalinks.
4890 New in version 0.6: Previously, this was always activated.
4892 Changed in version 1.1: This can now be a string to select the
4895 actual text of the link. Previously, only boolean values were
4896 accepted.
4897 html_sidebars
4900 Custom sidebar templates, must be a dictionary that maps docu‐
4901 ment names to template names.
4902 The keys can contain glob-style patterns [1], in which case all
4904 matching documents will get the specified sidebars. (A warning
4905 is emitted when a more than one glob-style pattern matches for
4906 any document.)
4907 The values can be either lists or single strings.
4909 · If a value is a list, it specifies the complete list of side‐
4911 bar templates to include. If all or some of the default side‐
4912 bars are to be included, they must be put into this list as
4913 well.
4914 The default sidebars (for documents that don’t match any pat‐
4916 tern) are defined by theme itself. Builtin themes are using
4917 these templates by default: ['localtoc.html', 'rela‐
4918 tions.html', 'sourcelink.html', 'searchbox.html'].
4919 · If a value is a single string, it specifies a custom sidebar
4921 to be added between the 'sourcelink.html' and 'searchbox.html'
4922 entries. This is for compatibility with Sphinx versions
4923 before 1.0.
4924 Deprecated since version 1.7: a single string value for
4926 html_sidebars will be removed in 2.0
4927 Builtin sidebar templates that can be rendered are:
4930 · localtoc.html – a fine-grained table of contents of the cur‐
4932 rent document
4933 · globaltoc.html – a coarse-grained table of contents for the
4935 whole documentation set, collapsed
4936 · relations.html – two links to the previous and next documents
4938 · sourcelink.html – a link to the source of the current docu‐
4940 ment, if enabled in html_show_sourcelink
4941 · searchbox.html – the “quick search” box
4943 Example:
4945 html_sidebars = {
4947 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
4948 'using/windows': ['windowssidebar.html', 'searchbox.html'],
4949 }
4950 This will render the custom template windowssidebar.html and the
4952 quick search box within the sidebar of the given document, and
4953 render the default sidebars for all other pages (except that the
4954 local TOC is replaced by the global TOC).
4955 New in version 1.0: The ability to use globbing keys and to
4957 specify multiple sidebars.
4958 Note that this value only has no effect if the chosen theme does
4961 not possess a sidebar, like the builtin scrolls and haiku
4962 themes.
4963 html_additional_pages
4965 Additional templates that should be rendered to HTML pages, must
4966 be a dictionary that maps document names to template names.
4967 Example:
4969 html_additional_pages = {
4971 'download': 'customdownload.html',
4972 }
4973 This will render the template customdownload.html as the page
4975 download.html.
4976 html_domain_indices
4978 If true, generate domain-specific indices in addition to the
4979 general index. For e.g. the Python domain, this is the global
4980 module index. Default is True.
4981 This value can be a bool or a list of index names that should be
4983 generated. To find out the index name for a specific index,
4984 look at the HTML file name. For example, the Python module
4985 index has the name 'py-modindex'.
4986 New in version 1.0.
4988 html_use_index
4991 If true, add an index to the HTML documents. Default is True.
4992 New in version 0.4.
4994 html_split_index
4997 If true, the index is generated twice: once as a single page
4998 with all the entries, and once as one page per starting letter.
4999 Default is False.
5000 New in version 0.4.
5002 html_copy_source
5005 If true, the reST sources are included in the HTML build as
5006 _sources/name. The default is True.
5007 WARNING:
5009 If this config value is set to False, the JavaScript search
5010 function will only display the titles of matching documents,
5011 and no excerpt from the matching contents.
5012 html_show_sourcelink
5014 If true (and html_copy_source is true as well), links to the
5015 reST sources will be added to the sidebar. The default is True.
5016 New in version 0.6.
5018 html_sourcelink_suffix
5021 Suffix to be appended to source links (see
5022 html_show_sourcelink), unless they have this suffix already.
5023 Default is '.txt'.
5024 New in version 1.5.
5026 html_use_opensearch
5029 If nonempty, an OpenSearch description file will be output, and
5030 all pages will contain a <link> tag referring to it. Since
5031 OpenSearch doesn’t support relative URLs for its search page
5032 location, the value of this option must be the base URL from
5033 which these documents are served (without trailing slash), e.g.
5034 "https://docs.python.org". The default is ''.
5035 html_file_suffix
5037 This is the file name suffix for generated HTML files. The
5038 default is ".html".
5039 New in version 0.4.
5041 html_link_suffix
5044 Suffix for generated links to HTML files. The default is what‐
5045 ever html_file_suffix is set to; it can be set differently (e.g.
5046 to support different web server setups).
5047 New in version 0.6.
5049 html_show_copyright
5052 If true, “(C) Copyright …” is shown in the HTML footer. Default
5053 is True.
5054 New in version 1.0.
5056 html_show_sphinx
5059 If true, “Created using Sphinx” is shown in the HTML footer.
5060 Default is True.
5061 New in version 0.4.
5063 html_output_encoding
5066 Encoding of HTML output files. Default is 'utf-8'. Note that
5067 this encoding name must both be a valid Python encoding name and
5068 a valid HTML charset value.
5069 New in version 1.0.
5071 html_compact_lists
5074 If true, a list all whose items consist of a single paragraph
5075 and/or a sub-list all whose items etc… (recursive definition)
5076 will not use the <p> element for any of its items. This is stan‐
5077 dard docutils behavior. Default: True.
5078 New in version 1.0.
5080 html_secnumber_suffix
5083 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5084 press the final dot on section numbers.
5085 New in version 1.0.
5087 html_search_language
5090 Language to be used for generating the HTML full-text search
5091 index. This defaults to the global language selected with
5092 language. If there is no support for this language, "en" is
5093 used which selects the English language.
5094 Support is present for these languages:
5096 · da – Danish
5098 · nl – Dutch
5100 · en – English
5102 · fi – Finnish
5104 · fr – French
5106 · de – German
5108 · hu – Hungarian
5110 · it – Italian
5112 · ja – Japanese
5114 · no – Norwegian
5116 · pt – Portuguese
5118 · ro – Romanian
5120 · ru – Russian
5122 · es – Spanish
5124 · sv – Swedish
5126 · tr – Turkish
5128 · zh – Chinese
5130 Accelerating build speed
5132 Each language (except Japanese) provides its own stem‐
5134 ming algorithm. Sphinx uses a Python implementation
5135 by default. You can use a C implementation to accel‐
5136 erate building the index file.
5137 · PorterStemmer (en)
5139 · PyStemmer (all languages)
5141 New in version 1.1: With support for en and ja.
5143 Changed in version 1.3: Added additional languages.
5146 html_search_options
5149 A dictionary with options for the search language support, empty
5150 by default. The meaning of these options depends on the lan‐
5151 guage selected.
5152 The English support has no options.
5154 The Japanese support has these options:
5156 Type
5158 is dotted module path string to specify Splitter imple‐
5159 mentation which should be derived from
5160 sphinx.search.ja.BaseSplitter. If not specified or None
5161 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5162 used.
5163 You can choose from these modules:
5165 ‘sphinx.search.ja.DefaultSplitter’
5167 TinySegmenter algorithm. This is default splitter.
5168 ‘sphinx.search.ja.MeCabSplitter’
5170 MeCab binding. To use this splitter, ‘mecab’
5171 python binding or dynamic link library (‘libme‐
5172 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5173 required.
5174 ‘sphinx.search.ja.JanomeSplitter’
5176 Janome binding. To use this splitter, Janome is
5177 required.
5178 Deprecated since version 1.6: 'mecab', 'janome' and
5180 'default' is deprecated. To keep compatibility, 'mecab',
5181 'janome' and 'default' are also acceptable.
5182 Other option values depend on splitter value which you choose.
5185 Options for 'mecab':
5187 dic_enc
5189 is the encoding for the MeCab algorithm.
5190 dict
5192 is the dictionary to use for the MeCab algorithm.
5193 lib
5195 is the library name for finding the MeCab library
5196 via ctypes if the Python binding is not installed.
5197 For example:
5199 html_search_options = {
5201 'type': 'mecab',
5202 'dic_enc': 'utf-8',
5203 'dict': '/path/to/mecab.dic',
5204 'lib': '/path/to/libmecab.so',
5205 }
5206 Options for 'janome':
5208 user_dic
5210 is the user dictionary file path for Janome.
5211 user_dic_enc
5213 is the encoding for the user dictionary file
5214 specified by user_dic option. Default is ‘utf8’.
5215 New in version 1.1.
5217 Changed in version 1.4: html_search_options for Japanese is
5220 re-organized and any custom splitter can be used by type set‐
5221 tings.
5222 The Chinese support has these options:
5225 · dict – the jieba dictionary path if want to use custom dic‐
5227 tionary.
5228 html_search_scorer
5230 The name of a JavaScript file (relative to the configuration
5231 directory) that implements a search results scorer. If empty,
5232 the default will be used.
5233 New in version 1.2.
5235 html_scaled_image_link
5238 If true, images itself links to the original image if it doesn’t
5239 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5240 ‘height’. The default is True.
5241 New in version 1.3.
5243 html_math_renderer
5246 The name of math_renderer extension for HTML output. The
5247 default is 'mathjax'.
5248 New in version 1.8.
5250 html_experimental_html5_writer
5253 Output is processed with HTML5 writer. This feature needs docu‐
5254 tils 0.13 or newer. Default is False.
5255 New in version 1.6.
5257 Options for Single HTML output
5260 singlehtml_sidebars
5261 Custom sidebar templates, must be a dictionary that maps docu‐
5262 ment names to template names. And it only allows a key named
5263 ‘index’. All other keys are ignored. For more information,
5264 refer to html_sidebars. By default, it is same as
5265 html_sidebars.
5266 Options for HTML help output
5268 htmlhelp_basename
5269 Output file base name for HTML help builder. Default is
5270 'pydoc'.
5271 Options for Apple Help output
5273 New in version 1.3.
5274 These options influence the Apple Help output. This builder derives
5277 from the HTML builder, so the HTML options also apply where appropri‐
5278 ate.
5279 NOTE:
5281 Apple Help output will only work on Mac OS X 10.6 and higher, as it
5282 requires the hiutil and codesign command line tools, neither of
5283 which are Open Source.
5284 You can disable the use of these tools using
5286 applehelp_disable_external_tools, but the result will not be a valid
5287 help book until the indexer is run over the .lproj folders within
5288 the bundle.
5289 applehelp_bundle_name
5291 The basename for the Apple Help Book. Defaults to the project
5292 name.
5293 applehelp_bundle_id
5295 The bundle ID for the help book bundle.
5296 WARNING:
5298 You must set this value in order to generate Apple Help.
5299 applehelp_dev_region
5301 The development region. Defaults to 'en-us', which is Apple’s
5302 recommended setting.
5303 applehelp_bundle_version
5305 The bundle version (as a string). Defaults to '1'.
5306 applehelp_icon
5308 The help bundle icon file, or None for no icon. According to
5309 Apple’s documentation, this should be a 16-by-16 pixel version
5310 of the application’s icon with a transparent background, saved
5311 as a PNG file.
5312 applehelp_kb_product
5314 The product tag for use with applehelp_kb_url. Defaults to
5315 '<project>-<release>'.
5316 applehelp_kb_url
5318 The URL for your knowledgebase server, e.g. https://exam‐
5319 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
5320 will replace the values 'product', 'query' and 'lang' at runtime
5321 with the contents of applehelp_kb_product, the text entered by
5322 the user in the search box and the user’s system language
5323 respectively.
5324 Defaults to None for no remote search.
5326 applehelp_remote_url
5328 The URL for remote content. You can place a copy of your Help
5329 Book’s Resources folder at this location and Help Viewer will
5330 attempt to use it to fetch updated content.
5331 e.g. if you set it to https://example.com/help/Foo/ and Help
5333 Viewer wants a copy of index.html for an English speaking cus‐
5334 tomer, it will look at https://exam‐
5335 ple.com/help/Foo/en.lproj/index.html.
5336 Defaults to None for no remote content.
5338 applehelp_index_anchors
5340 If True, tell the help indexer to index anchors in the generated
5341 HTML. This can be useful for jumping to a particular topic
5342 using the AHLookupAnchor function or the openHelpAnchor:inBook:
5343 method in your code. It also allows you to use help:anchor
5344 URLs; see the Apple documentation for more information on this
5345 topic.
5346 applehelp_min_term_length
5348 Controls the minimum term length for the help indexer. Defaults
5349 to None, which means the default will be used.
5350 applehelp_stopwords
5352 Either a language specification (to use the built-in stopwords),
5353 or the path to a stopwords plist, or None if you do not want to
5354 use stopwords. The default stopwords plist can be found at
5355 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
5356 ing, stopwords for the following languages:
5357 ┌──────────┬──────┐
5359 │Language │ Code │
5360 ├──────────┼──────┤
5361 │English │ en │
5362 ├──────────┼──────┤
5363 │German │ de │
5364 ├──────────┼──────┤
5365 │Spanish │ es │
5366 ├──────────┼──────┤
5367 │French │ fr │
5368 ├──────────┼──────┤
5369 │Swedish │ sv │
5370 ├──────────┼──────┤
5371 │Hungarian │ hu │
5372 ├──────────┼──────┤
5373 │Italian │ it │
5374 └──────────┴──────┘
5375 Defaults to language, or if that is not set, to en.
5377 applehelp_locale
5379 Specifies the locale to generate help for. This is used to
5380 determine the name of the .lproj folder inside the Help Book’s
5381 Resources, and is passed to the help indexer.
5382 Defaults to language, or if that is not set, to en.
5384 applehelp_title
5386 Specifies the help book title. Defaults to '<project> Help'.
5387 applehelp_codesign_identity
5389 Specifies the identity to use for code signing, or None if code
5390 signing is not to be performed.
5391 Defaults to the value of the environment variable
5393 CODE_SIGN_IDENTITY, which is set by Xcode for script build
5394 phases, or None if that variable is not set.
5395 applehelp_codesign_flags
5397 A list of additional arguments to pass to codesign when signing
5398 the help book.
5399 Defaults to a list based on the value of the environment vari‐
5401 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
5402 build phases, or the empty list if that variable is not set.
5403 applehelp_indexer_path
5405 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
5406 applehelp_codesign_path
5408 The path to the codesign program. Defaults to '/usr/bin/code‐
5409 sign'.
5410 applehelp_disable_external_tools
5412 If True, the builder will not run the indexer or the code sign‐
5413 ing tool, no matter what other settings are specified.
5414 This is mainly useful for testing, or where you want to run the
5416 Sphinx build on a non-Mac OS X platform and then complete the
5417 final steps on OS X for some reason.
5418 Defaults to False.
5420 Options for epub output
5422 These options influence the epub output. As this builder derives from
5423 the HTML builder, the HTML options also apply where appropriate. The
5424 actual values for some of the options is not really important, they
5425 just have to be entered into the Dublin Core metadata.
5426 epub_basename
5428 The basename for the epub file. It defaults to the project
5429 name.
5430 epub_theme
5432 The HTML theme for the epub output. Since the default themes
5433 are not optimized for small screen space, using the same theme
5434 for HTML and epub output is usually not wise. This defaults to
5435 'epub', a theme designed to save visual space.
5436 epub_theme_options
5438 A dictionary of options that influence the look and feel of the
5439 selected theme. These are theme-specific. For the options
5440 understood by the builtin themes, see this section.
5441 New in version 1.2.
5443 epub_title
5446 The title of the document. It defaults to the html_title option
5447 but can be set independently for epub creation.
5448 epub_description
5450 The description of the document. The default value is 'unknown'.
5451 New in version 1.4.
5453 Changed in version 1.5: Renamed from epub3_description
5456 epub_author
5459 The author of the document. This is put in the Dublin Core
5460 metadata. It defaults to the author option.
5461 epub_contributor
5463 The name of a person, organization, etc. that played a secondary
5464 role in the creation of the content of an EPUB Publication. The
5465 default value is 'unknown'.
5466 New in version 1.4.
5468 Changed in version 1.5: Renamed from epub3_contributor
5471 epub_language
5474 The language of the document. This is put in the Dublin Core
5475 metadata. The default is the language option or 'en' if unset.
5476 epub_publisher
5478 The publisher of the document. This is put in the Dublin Core
5479 metadata. You may use any sensible string, e.g. the project
5480 homepage. The defaults to the author option.
5481 epub_copyright
5483 The copyright of the document. It defaults to the copyright
5484 option but can be set independently for epub creation.
5485 epub_identifier
5487 An identifier for the document. This is put in the Dublin Core
5488 metadata. For published documents this is the ISBN number, but
5489 you can also use an alternative scheme, e.g. the project home‐
5490 page. The default value is 'unknown'.
5491 epub_scheme
5493 The publication scheme for the epub_identifier. This is put in
5494 the Dublin Core metadata. For published books the scheme is
5495 'ISBN'. If you use the project homepage, 'URL' seems reason‐
5496 able. The default value is 'unknown'.
5497 epub_uid
5499 A unique identifier for the document. This is put in the Dublin
5500 Core metadata. You may use a XML’s Name format string. You
5501 can’t use hyphen, period, numbers as a first character. The
5502 default value is 'unknown'.
5503 epub_cover
5505 The cover page information. This is a tuple containing the
5506 filenames of the cover image and the html template. The ren‐
5507 dered html cover page is inserted as the first item in the spine
5508 in content.opf. If the template filename is empty, no html
5509 cover page is created. No cover at all is created if the tuple
5510 is empty. Examples:
5511 epub_cover = ('_static/cover.png', 'epub-cover.html')
5513 epub_cover = ('_static/cover.png', '')
5514 epub_cover = ()
5515 The default value is ().
5517 New in version 1.1.
5519 epub_css_files
5522 A list of CSS files. The entry must be a filename string or a
5523 tuple containing the filename string and the attributes dictio‐
5524 nary. For more information, see html_css_files.
5525 New in version 1.8.
5527 epub_guide
5530 Meta data for the guide element of content.opf. This is a
5531 sequence of tuples containing the type, the uri and the title of
5532 the optional guide information. See the OPF documentation at
5533 http://idpf.org/epub for details. If possible, default entries
5534 for the cover and toc types are automatically inserted. However,
5535 the types can be explicitly overwritten if the default entries
5536 are not appropriate. Example:
5537 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
5539 The default value is ().
5541 epub_pre_files
5543 Additional files that should be inserted before the text gener‐
5544 ated by Sphinx. It is a list of tuples containing the file name
5545 and the title. If the title is empty, no entry is added to
5546 toc.ncx. Example:
5547 epub_pre_files = [
5549 ('index.html', 'Welcome'),
5550 ]
5551 The default value is [].
5553 epub_post_files
5555 Additional files that should be inserted after the text gener‐
5556 ated by Sphinx. It is a list of tuples containing the file name
5557 and the title. This option can be used to add an appendix. If
5558 the title is empty, no entry is added to toc.ncx. The default
5559 value is [].
5560 epub_exclude_files
5562 A list of files that are generated/copied in the build directory
5563 but should not be included in the epub file. The default value
5564 is [].
5565 epub_tocdepth
5567 The depth of the table of contents in the file toc.ncx. It
5568 should be an integer greater than zero. The default value is 3.
5569 Note: A deeply nested table of contents may be difficult to nav‐
5570 igate.
5571 epub_tocdup
5573 This flag determines if a toc entry is inserted again at the
5574 beginning of its nested toc listing. This allows easier naviga‐
5575 tion to the top of a chapter, but can be confusing because it
5576 mixes entries of different depth in one list. The default value
5577 is True.
5578 epub_tocscope
5580 This setting control the scope of the epub table of contents.
5581 The setting can have the following values:
5582 · 'default' – include all toc entries that are not hidden
5584 (default)
5585 · 'includehidden' – include all toc entries
5587 New in version 1.2.
5589 epub_fix_images
5592 This flag determines if sphinx should try to fix image formats
5593 that are not supported by some epub readers. At the moment pal‐
5594 ette images with a small color table are upgraded. You need the
5595 Python Image Library (Pillow the successor of the PIL) installed
5596 to use this option. The default value is False because the
5597 automatic conversion may lose information.
5598 New in version 1.2.
5600 epub_max_image_width
5603 This option specifies the maximum width of images. If it is set
5604 to a value greater than zero, images with a width larger than
5605 the given value are scaled accordingly. If it is zero, no scal‐
5606 ing is performed. The default value is 0. You need the Python
5607 Image Library (Pillow) installed to use this option.
5608 New in version 1.2.
5610 epub_show_urls
5613 Control whether to display URL addresses. This is very useful
5614 for readers that have no other means to display the linked URL.
5615 The settings can have the following values:
5616 · 'inline' – display URLs inline in parentheses (default)
5618 · 'footnote' – display URLs in footnotes
5620 · 'no' – do not display URLs
5622 The display of inline URLs can be customized by adding CSS rules
5624 for the class link-target.
5625 New in version 1.2.
5627 epub_use_index
5630 If true, add an index to the epub document. It defaults to the
5631 html_use_index option but can be set independently for epub cre‐
5632 ation.
5633 New in version 1.2.
5635 epub_writing_mode
5638 It specifies writing direction. It can accept 'horizontal'
5639 (default) and 'vertical'
5640 ┌────────────────────┬─────────────────────┬─────────────────────┐
5642 │epub_writing_mode │ 'horizontal' │ 'vertical' │
5643 ├────────────────────┼─────────────────────┼─────────────────────┤
5644 │writing-mode [2] │ horizontal-tb │ vertical-rl │
5645 ├────────────────────┼─────────────────────┼─────────────────────┤
5646 │page progression │ left to right │ right to left │
5647 ├────────────────────┼─────────────────────┼─────────────────────┤
5648 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
5649 │Theme support │ tical. │ izontal. │
5650 └────────────────────┴─────────────────────┴─────────────────────┘
5651 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
5653 Options for LaTeX output
5655 These options influence LaTeX output. Refer to /latex for more informa‐
5656 tion.
5657 latex_engine
5659 The LaTeX engine to build the docs. The setting can have the
5660 following values:
5661 · 'pdflatex' – PDFLaTeX (default)
5663 · 'xelatex' – XeLaTeX
5665 · 'lualatex' – LuaLaTeX
5667 · 'platex' – pLaTeX (default if language is 'ja')
5669 PDFLaTeX’s support for Unicode characters covers those from the
5671 document language (the LaTeX babel and inputenc packages map
5672 them to glyph slots in the document font, at various encodings
5673 allowing each only 256 characters; Sphinx uses by default
5674 (except for Cyrillic languages) the times package), but stray
5675 characters from other scripts or special symbols may require
5676 adding extra LaTeX packages or macros to the LaTeX preamble.
5677 If your project uses such extra Unicode characters, switching
5679 the engine to XeLaTeX or LuaLaTeX and setting up the document to
5680 use an OpenType font with wide-enough glyph coverage is often
5681 easier than sticking with PDFLaTeX and trying to get it to work
5682 with the Unicode characters.
5683 The latex_elements 'fontpkg' key allows to set up the document
5685 fonts, see this example. Currently, for XeLaTeX and LuaLaTeX,
5686 Sphinx leaves this key empty and LaTeX then defaults to the
5687 Latin Modern font family (from the TeX distribution fonts).
5688 This font family provides good coverage of Latin scripts (Euro‐
5689 pean languages, Vietnamese) but Cyrillic requires some other
5690 OpenType font; for example Computer Modern Unicode (see
5691 babel-russian documentation on how to load it in the LaTeX docu‐
5692 ment). In future, it is planned Sphinx will provide another
5693 default choice of OpenType font than Latin Modern, perhaps
5694 Libertinus, which is included in recent TeX distributions and
5695 supports Latin and Cyrillic and also has an accompanying math
5696 font.
5697 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document
5699 to use polyglossia. For some languages the babel support
5700 appears preferable; Sphinx uses currently babel for French and
5701 perhaps will also for some more languages in future. One can
5702 use the latex_elements 'babel' key to override Sphinx’s default.
5703 latex_documents
5705 This value determines how to group the document tree into LaTeX
5706 source files. It must be a list of tuples (startdocname, tar‐
5707 getname, title, author, documentclass, toctree_only), where the
5708 items are:
5709 startdocname
5711 String that specifies the document name of the LaTeX
5712 file’s master document. All documents referenced by the
5713 startdoc document in TOC trees will be included in the
5714 LaTeX file. (If you want to use the default master docu‐
5715 ment for your LaTeX build, provide your master_doc here.)
5716 targetname
5718 File name of the LaTeX file in the output directory.
5719 title LaTeX document title. Can be empty to use the title of
5721 the startdoc document. This is inserted as LaTeX markup,
5722 so special characters like a backslash or ampersand must
5723 be represented by the proper LaTeX commands if they are
5724 to be inserted literally.
5725 author Author for the LaTeX document. The same LaTeX markup
5727 caveat as for title applies. Use \\and to separate mul‐
5728 tiple authors, as in: 'John \\and Sarah' (backslashes
5729 must be Python-escaped to reach LaTeX).
5730 documentclass
5732 Normally, one of 'manual' or 'howto' (provided by Sphinx
5733 and based on 'report', resp. 'article'; Japanese docu‐
5734 ments use 'jsbook', resp. 'jreport'.) “howto” (non-Japa‐
5735 nese) documents will not get appendices. Also they have a
5736 simpler title page. Other document classes can be given.
5737 Independently of the document class, the “sphinx” package
5738 is always loaded in order to define Sphinx’s custom LaTeX
5739 commands.
5740 toctree_only
5742 Must be True or False. If true, the startdoc document
5743 itself is not included in the output, only the documents
5744 referenced by it via TOC trees. With this option, you
5745 can put extra stuff in the master document that shows up
5746 in the HTML, but not the LaTeX output.
5747 New in version 1.2: In the past including your own document
5749 class required you to prepend the document class name with the
5750 string “sphinx”. This is not necessary anymore.
5751 New in version 0.3: The 6th item toctree_only. Tuples with 5
5754 items are still accepted.
5755 latex_logo
5758 If given, this must be the name of an image file (relative to
5759 the configuration directory) that is the logo of the docs. It
5760 is placed at the top of the title page. Default: None.
5761 latex_toplevel_sectioning
5763 This value determines the topmost sectioning unit. It should be
5764 chosen from 'part', 'chapter' or 'section'. The default is None;
5765 the topmost sectioning unit is switched by documentclass: sec‐
5766 tion is used if documentclass will be howto, otherwise chapter
5767 will be used.
5768 Note that if LaTeX uses \part command, then the numbering of
5770 sectioning units one level deep gets off-sync with HTML number‐
5771 ing, because LaTeX numbers continuously \chapter (or \section
5772 for howto.)
5773 New in version 1.4.
5775 latex_appendices
5778 A list of document names to append as an appendix to all manu‐
5779 als.
5780 latex_domain_indices
5782 If true, generate domain-specific indices in addition to the
5783 general index. For e.g. the Python domain, this is the global
5784 module index. Default is True.
5785 This value can be a bool or a list of index names that should be
5787 generated, like for html_domain_indices.
5788 New in version 1.0.
5790 latex_show_pagerefs
5793 If true, add page references after internal references. This is
5794 very useful for printed copies of the manual. Default is False.
5795 New in version 1.0.
5797 latex_show_urls
5800 Control whether to display URL addresses. This is very useful
5801 for printed copies of the manual. The setting can have the fol‐
5802 lowing values:
5803 · 'no' – do not display URLs (default)
5805 · 'footnote' – display URLs in footnotes
5807 · 'inline' – display URLs inline in parentheses
5809 New in version 1.0.
5811 Changed in version 1.1: This value is now a string; previously
5814 it was a boolean value, and a true value selected the 'inline'
5815 display. For backwards compatibility, True is still accepted.
5816 latex_use_latex_multicolumn
5819 The default is False: it means that Sphinx’s own macros are used
5820 for merged cells from grid tables. They allow general contents
5821 (literal blocks, lists, blockquotes, …) but may have problems if
5822 the tabularcolumns directive was used to inject LaTeX mark-up of
5823 the type >{..}, <{..}, @{..} as column specification.
5824 Setting to True means to use LaTeX’s standard \multicolumn; this
5826 is incompatible with literal blocks in the horizontally merged
5827 cell, and also with multiple paragraphs in such cell if the ta‐
5828 ble is rendered using tabulary.
5829 New in version 1.6.
5831 latex_use_xindy
5834 If True, the PDF build from the LaTeX files created by Sphinx
5835 will use xindy (doc) rather than makeindex for preparing the
5836 index of general terms (from index usage). This means that
5837 words with UTF-8 characters will get ordered correctly for the
5838 language.
5839 · This option is ignored if latex_engine is 'platex' (Japanese
5841 documents; mendex replaces makeindex then).
5842 · The default is True for 'xelatex' or 'lualatex' as makeindex,
5844 if any indexed term starts with a non-ascii character, creates
5845 .ind files containing invalid bytes for UTF-8 encoding. With
5846 'lualatex' this then breaks the PDF build.
5847 · The default is False for 'pdflatex' but True is recommended
5849 for non-English documents as soon as some indexed terms use
5850 non-ascii characters from the language script.
5851 Sphinx adds to xindy base distribution some dedicated support
5853 for using 'pdflatex' engine with Cyrillic scripts. And whether
5854 with 'pdflatex' or Unicode engines, Cyrillic documents handle
5855 correctly the indexing of Latin names, even with diacritics.
5856 New in version 1.8.
5858 latex_elements
5861 New in version 0.5.
5862 A dictionary that contains LaTeX snippets that override those
5865 Sphinx usually puts into the generated .tex files.
5866 Keep in mind that backslashes must be doubled in Python string
5868 literals to avoid interpretation as escape sequences.
5869 · Keys that you may want to override include:
5871 'papersize'
5873 Paper size option of the document class ('a4paper' or
5874 'letterpaper'), default 'letterpaper'.
5875 'pointsize'
5877 Point size option of the document class ('10pt', '11pt'
5878 or '12pt'), default '10pt'.
5879 'pxunit'
5881 the value of the px when used in image attributes width
5882 and height. The default value is '0.75bp' which
5883 achieves 96px=1in (in TeX 1in = 72bp = 72.27pt.) To
5884 obtain for example 100px=1in use '0.01in' or '0.7227pt'
5885 (the latter leads to TeX computing a more precise
5886 value, due to the smaller unit used in the specifica‐
5887 tion); for 72px=1in, simply use '1bp'; for 90px=1in,
5888 use '0.8bp' or '0.803pt'.
5889 New in version 1.5.
5891 'sphinxsetup'
5894 A comma separated list of key=value package options for
5895 the Sphinx LaTeX style, default empty. See /latex.
5896 New in version 1.5.
5898 'passoptionstopackages'
5901 A string which will be positioned early in the pream‐
5902 ble, designed to contain \\PassOptionsToPack‐
5903 age{options}{foo} commands. Default empty.
5904 New in version 1.4.
5906 'babel'
5909 “babel” package inclusion, default '\\usepack‐
5910 age{babel}' (the suitable document language string is
5911 passed as class option, and english is used if no lan‐
5912 guage.) For Japanese documents, the default is the
5913 empty string.
5914 Changed in version 1.5: For latex_engine set to 'xela‐
5916 tex', the default is '\\usepackage{polyglossia}\n\\set‐
5917 mainlanguage{<language>}'.
5918 Changed in version 1.6: 'lualatex' uses same default
5921 setting as 'xelatex'
5922 Changed in version 1.7.6: For French, xelatex and
5925 lualatex default to using babel, not polyglossia.
5926 'fontpkg'
5929 Font package inclusion, default '\\usepackage{times}'
5930 (which uses Times for text, Helvetica for sans serif
5931 and Courier for code-blocks).
5932 Changed in version 1.2: Defaults to '' when the
5934 language uses the Cyrillic script.
5935 Changed in version 1.5: Defaults to '' when
5938 latex_engine is 'xelatex'.
5939 Changed in version 1.6: Defaults to '' also with
5942 'lualatex'.
5943 'fncychap'
5946 Inclusion of the “fncychap” package (which makes fancy
5947 chapter titles), default '\\usepackage[Bjarne]{fncy‐
5948 chap}' for English documentation (this option is
5949 slightly customized by Sphinx), '\\usepack‐
5950 age[Sonny]{fncychap}' for internationalized docs
5951 (because the “Bjarne” style uses numbers spelled out in
5952 English). Other “fncychap” styles you can try are
5953 “Lenny”, “Glenn”, “Conny”, “Rejne” and “Bjornstrup”.
5954 You can also set this to '' to disable fncychap.
5955 'preamble'
5957 Additional preamble content, default empty. See /latex.
5958 'atendofbody'
5960 Additional document content (right before the indices),
5961 default empty.
5962 New in version 1.5.
5964 'figure_align'
5967 Latex figure float alignment, default ‘htbp’ (here,
5968 top, bottom, page). Whenever an image doesn’t fit into
5969 the current page, it will be ‘floated’ into the next
5970 page but may be preceded by any other text. If you
5971 don’t like this behavior, use ‘H’ which will disable
5972 floating and position figures strictly in the order
5973 they appear in the source.
5974 New in version 1.3.
5976 'footer'
5979 Additional footer content (before the indices), default
5980 empty.
5981 Deprecated since version 1.5: Use 'atendofbody' key
5983 instead.
5984 · Keys that don’t need to be overridden unless in special cases
5987 are:
5988 'extraclassoptions'
5990 The default is the empty string. Example: 'extraclas‐
5991 soptions': 'openany' will allow chapters (for documents
5992 of the 'manual' type) to start on any page.
5993 New in version 1.2.
5995 Changed in version 1.6: Added this documentation.
5998 'maxlistdepth'
6001 LaTeX allows by default at most 6 levels for nesting
6002 list and quote-like environments, with at most 4 enu‐
6003 merated lists, and 4 bullet lists. Setting this key for
6004 example to '10' (as a string) will allow up to 10
6005 nested levels (of all sorts). Leaving it to the empty
6006 string means to obey the LaTeX default.
6007 WARNING:
6009 · Using this key may prove incompatible with some
6011 LaTeX packages or special document classes which
6012 do their own list customization.
6013 · The key setting is silently ignored if \usepack‐
6015 age{enumitem} is executed inside the document pre‐
6016 amble. Use then rather the dedicated commands of
6017 this LaTeX package.
6018 New in version 1.5.
6020 'inputenc'
6023 “inputenc” package inclusion, defaults to '\\usepack‐
6024 age[utf8]{inputenc}' when using pdflatex. Otherwise
6025 empty.
6026 Changed in version 1.4.3: Previously '\\usepack‐
6028 age[utf8]{inputenc}' was used for all compilers.
6029 'cmappkg'
6032 “cmap” package inclusion, default '\\usepackage{cmap}'.
6033 New in version 1.2.
6035 'fontenc'
6038 “fontenc” package inclusion, default '\\usepack‐
6039 age[T1]{fontenc}'.
6040 Changed in version 1.5: Defaults to '\\usepack‐
6042 age{fontspec}' when latex_engine is 'xelatex'.
6043 Changed in version 1.6: 'lualatex' also uses fontspec
6046 per default.
6047 'geometry'
6050 “geometry” package inclusion, the default definition
6051 is:
6052 '\\usepackage{geometry}'
6053 with an additional [dvipdfm] for Japanese documents.
6055 The Sphinx LaTeX style file executes:
6056 \PassOptionsToPackage{hmargin=1in,vmar‐
6057 gin=1in,marginpar=0.5in}{geometry}
6058 which can be customized via corresponding ‘sphinxsetup’
6060 options.
6061 New in version 1.5.
6063 Changed in version 1.5.2: dvipdfm option if
6066 latex_engine is 'platex'.
6067 New in version 1.5.3: The ‘sphinxsetup’ keys for the
6070 margins.
6071 Changed in version 1.5.3: The location in the LaTeX
6074 file has been moved to after \usepackage{sphinx} and
6075 \sphinxsetup{..}, hence also after insertion of
6076 'fontpkg' key. This is in order to handle the paper
6077 layout options in a special way for Japanese documents:
6078 the text width will be set to an integer multiple of
6079 the zenkaku width, and the text height to an integer
6080 multiple of the baseline. See the hmargin documentation
6081 for more.
6082 'hyperref'
6085 “hyperref” package inclusion; also loads package “hyp‐
6086 cap” and issues \urlstyle{same}. This is done after
6087 sphinx.sty file is loaded and before executing the con‐
6088 tents of 'preamble' key.
6089 ATTENTION:
6091 Loading of packages “hyperref” and “hypcap” is
6092 mandatory.
6093 New in version 1.5: Previously this was done from
6095 inside sphinx.sty.
6096 'maketitle'
6099 “maketitle” call, default '\\sphinxmaketitle'. Override
6100 if you want to generate a differently styled title
6101 page.
6102 HINT:
6104 If the key value is set to r'\newcommand\sphinxback‐
6105 oftitlepage{<Extra material>}\sphinxmaketitle', then
6106 <Extra material> will be typeset on back of title
6107 page ('manual' docclass only).
6108 Changed in version 1.8.3: Original \maketitle from doc‐
6110 ument class is not overwritten, hence is re-usable as
6111 part of some custom setting for this key.
6112 New in version 1.8.3: \sphinxbackoftitlepage optional
6115 macro. It can also be defined inside 'preamble' key
6116 rather than this one.
6117 'releasename'
6120 value that prefixes 'release' element on title page,
6121 default 'Release'. As for title and author used in the
6122 tuples of latex_documents, it is inserted as LaTeX
6123 markup.
6124 'tableofcontents'
6126 “tableofcontents” call, default '\\sphinxtableofcon‐
6127 tents' (it is a wrapper of unmodified \tableofcontents,
6128 which may itself be customized by user loaded pack‐
6129 ages.) Override if you want to generate a different
6130 table of contents or put content between the title page
6131 and the TOC.
6132 Changed in version 1.5: Previously the meaning of
6134 \tableofcontents itself was modified by Sphinx. This
6135 created an incompatibility with dedicated packages mod‐
6136 ifying it also such as “tocloft” or “etoc”.
6137 'transition'
6140 Commands used to display transitions, default
6141 '\n\n\\bigskip\\hrule\\bigskip\n\n'. Override if you
6142 want to display transitions differently.
6143 New in version 1.2.
6145 Changed in version 1.6: Remove unneeded {} after
6148 \\hrule.
6149 'printindex'
6152 “printindex” call, the last thing in the file, default
6153 '\\printindex'. Override if you want to generate the
6154 index differently or append some content after the
6155 index. For example '\\footnote‐
6156 size\\raggedright\\printindex' is advisable when the
6157 index is full of long entries.
6158 'fvset'
6160 Customization of fancyvrb LaTeX package. Currently,
6161 Sphinx uses this key to set the fontsize in code-blocks
6162 according to the latex_engine.
6163 · 'pdflatex' uses 'fvset': '\\fvset{fontsize=\\small}',
6165 to mitigate the size difference between the default
6166 monospaced font (Courier) and the default text font
6167 (Times). You may need to modify this if you use cus‐
6168 tom fonts.
6169 · 'xelatex' and 'lualatex' use '\\fvset{font‐
6171 size=auto}', as there is no size difference between
6172 the regular and the monospaced fonts used by default
6173 by Sphinx with these engines.
6174 New in version 1.8.
6176 · Keys that are set by other options and therefore should not be
6179 overridden are:
6180 'docclass' 'classoptions' 'title' 'date' 'release' 'author'
6182 'logo' 'makeindex'
6183 latex_docclass
6185 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6186 ment classes that will be used as the base for the two Sphinx
6187 classes. Default is to use 'article' for 'howto' and 'report'
6188 for 'manual'.
6189 New in version 1.0.
6191 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6194 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6195 latex_additional_files
6198 A list of file names, relative to the configuration directory,
6199 to copy to the build directory when building LaTeX output. This
6200 is useful to copy files that Sphinx doesn’t copy automatically,
6201 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6202 ments. Image files that are referenced in source files (e.g.
6203 via .. image::) are copied automatically.
6204 You have to make sure yourself that the filenames don’t collide
6206 with those of any automatically copied files.
6207 New in version 0.6.
6209 Changed in version 1.2: This overrides the files which is pro‐
6212 vided from Sphinx such as sphinx.sty.
6213 Options for text output
6216 These options influence text output.
6217 text_newlines
6219 Determines which end-of-line character(s) are used in text out‐
6220 put.
6221 · 'unix': use Unix-style line endings (\n)
6223 · 'windows': use Windows-style line endings (\r\n)
6225 · 'native': use the line ending style of the platform the docu‐
6227 mentation is built on
6228 Default: 'unix'.
6230 New in version 1.1.
6232 text_sectionchars
6235 A string of 7 characters that should be used for underlining
6236 sections. The first character is used for first-level headings,
6237 the second for second-level headings and so on.
6238 The default is '*=-~"+`'.
6240 New in version 1.1.
6242 text_add_secnumbers
6245 A boolean that decides whether section numbers are included in
6246 text output. Default is True.
6247 New in version 1.7.
6249 text_secnumber_suffix
6252 Suffix for section numbers in text output. Default: ". ". Set
6253 to " " to suppress the final dot on section numbers.
6254 New in version 1.7.
6256 Options for manual page output
6259 These options influence manual page output.
6260 man_pages
6262 This value determines how to group the document tree into manual
6263 pages. It must be a list of tuples (startdocname, name,
6264 description, authors, section), where the items are:
6265 startdocname
6267 String that specifies the document name of the manual
6268 page’s master document. All documents referenced by the
6269 startdoc document in TOC trees will be included in the
6270 manual file. (If you want to use the default master doc‐
6271 ument for your manual pages build, use your master_doc
6272 here.)
6273 name Name of the manual page. This should be a short string
6275 without spaces or special characters. It is used to
6276 determine the file name as well as the name of the manual
6277 page (in the NAME section).
6278 description
6280 Description of the manual page. This is used in the NAME
6281 section.
6282 authors
6284 A list of strings with authors, or a single string. Can
6285 be an empty string or list if you do not want to automat‐
6286 ically generate an AUTHORS section in the manual page.
6287 section
6289 The manual page section. Used for the output file name
6290 as well as in the manual page header.
6291 New in version 1.0.
6293 man_show_urls
6296 If true, add URL addresses after links. Default is False.
6297 New in version 1.1.
6299 Options for Texinfo output
6302 These options influence Texinfo output.
6303 texinfo_documents
6305 This value determines how to group the document tree into Tex‐
6306 info source files. It must be a list of tuples (startdocname,
6307 targetname, title, author, dir_entry, description, category,
6308 toctree_only), where the items are:
6309 startdocname
6311 String that specifies the document name of the the Tex‐
6312 info file’s master document. All documents referenced by
6313 the startdoc document in TOC trees will be included in
6314 the Texinfo file. (If you want to use the default master
6315 document for your Texinfo build, provide your master_doc
6316 here.)
6317 targetname
6319 File name (no extension) of the Texinfo file in the out‐
6320 put directory.
6321 title Texinfo document title. Can be empty to use the title of
6323 the startdoc document. Inserted as Texinfo markup, so
6324 special characters like @ and {} will need to be escaped
6325 to be inserted literally.
6326 author Author for the Texinfo document. Inserted as Texinfo
6328 markup. Use @* to separate multiple authors, as in:
6329 'John@*Sarah'.
6330 dir_entry
6332 The name that will appear in the top-level DIR menu file.
6333 description
6335 Descriptive text to appear in the top-level DIR menu
6336 file.
6337 category
6339 Specifies the section which this entry will appear in the
6340 top-level DIR menu file.
6341 toctree_only
6343 Must be True or False. If true, the startdoc document
6344 itself is not included in the output, only the documents
6345 referenced by it via TOC trees. With this option, you
6346 can put extra stuff in the master document that shows up
6347 in the HTML, but not the Texinfo output.
6348 New in version 1.1.
6350 texinfo_appendices
6353 A list of document names to append as an appendix to all manu‐
6354 als.
6355 New in version 1.1.
6357 texinfo_domain_indices
6360 If true, generate domain-specific indices in addition to the
6361 general index. For e.g. the Python domain, this is the global
6362 module index. Default is True.
6363 This value can be a bool or a list of index names that should be
6365 generated, like for html_domain_indices.
6366 New in version 1.1.
6368 texinfo_show_urls
6371 Control how to display URL addresses.
6372 · 'footnote' – display URLs in footnotes (default)
6374 · 'no' – do not display URLs
6376 · 'inline' – display URLs inline in parentheses
6378 New in version 1.1.
6380 texinfo_no_detailmenu
6383 If true, do not generate a @detailmenu in the “Top” node’s menu
6384 containing entries for each sub-node in the document. Default
6385 is False.
6386 New in version 1.2.
6388 texinfo_elements
6391 A dictionary that contains Texinfo snippets that override those
6392 Sphinx usually puts into the generated .texi files.
6393 · Keys that you may want to override include:
6395 'paragraphindent'
6397 Number of spaces to indent the first line of each para‐
6398 graph, default 2. Specify 0 for no indentation.
6399 'exampleindent'
6401 Number of spaces to indent the lines for examples or
6402 literal blocks, default 4. Specify 0 for no indenta‐
6403 tion.
6404 'preamble'
6406 Texinfo markup inserted near the beginning of the file.
6407 'copying'
6409 Texinfo markup inserted within the @copying block and
6410 displayed after the title. The default value consists
6411 of a simple title page identifying the project.
6412 · Keys that are set by other options and therefore should not be
6414 overridden are:
6415 'author' 'body' 'date' 'direntry' 'filename' 'project'
6417 'release' 'title'
6418 New in version 1.1.
6420 Options for QtHelp output
6423 These options influence qthelp output. As this builder derives from
6424 the HTML builder, the HTML options also apply where appropriate.
6425 qthelp_basename
6427 The basename for the qthelp file. It defaults to the project
6428 name.
6429 qthelp_namespace
6431 The namespace for the qthelp file. It defaults to
6432 org.sphinx.<project_name>.<project_version>.
6433 qthelp_theme
6435 The HTML theme for the qthelp output. This defaults to 'nonav'.
6436 qthelp_theme_options
6438 A dictionary of options that influence the look and feel of the
6439 selected theme. These are theme-specific. For the options
6440 understood by the builtin themes, see this section.
6441 Options for the linkcheck builder
6443 linkcheck_ignore
6444 A list of regular expressions that match URIs that should not be
6445 checked when doing a linkcheck build. Example:
6446 linkcheck_ignore = [r'http://localhost:\d+/']
6448 New in version 1.1.
6450 linkcheck_retries
6453 The number of times the linkcheck builder will attempt to check
6454 a URL before declaring it broken. Defaults to 1 attempt.
6455 New in version 1.4.
6457 linkcheck_timeout
6460 A timeout value, in seconds, for the linkcheck builder. The
6461 default is to use Python’s global socket timeout.
6462 New in version 1.1.
6464 linkcheck_workers
6467 The number of worker threads to use when checking links.
6468 Default is 5 threads.
6469 New in version 1.1.
6471 linkcheck_anchors
6474 If true, check the validity of #anchors in links. Since this
6475 requires downloading the whole document, it’s considerably
6476 slower when enabled. Default is True.
6477 New in version 1.2.
6479 linkcheck_anchors_ignore
6482 A list of regular expressions that match anchors Sphinx should
6483 skip when checking the validity of anchors in links. This allows
6484 skipping anchors that a website’s JavaScript adds to control
6485 dynamic pages or when triggering an internal REST request.
6486 Default is ["^!"].
6487 NOTE:
6489 If you want to ignore anchors of a specific page or of pages
6490 that match a specific pattern (but still check occurrences of
6491 the same page(s) that don’t have anchors), use
6492 linkcheck_ignore instead, for example as follows:
6493 linkcheck_ignore = [
6495 'http://www.sphinx-doc.org/en/1.7/intro.html#'
6496 ]
6497 New in version 1.5.
6499 Options for the XML builder
6502 xml_pretty
6503 If true, pretty-print the XML. Default is True.
6504 New in version 1.2.
6506
6509 [1] A note on available globbing syntax: you can use the standard
6510 shell constructs *, ?, [...] and [!...] with the feature that
6511 these all don’t match slashes. A double star ** can be used to
6512 match any sequence of characters including slashes.
6513 Options for the C++ domain
6515 cpp_index_common_prefix
6516 A list of prefixes that will be ignored when sorting C++ objects
6517 in the global index. For example ['awesome_lib::'].
6518 New in version 1.5.
6520 cpp_id_attributes
6523 A list of strings that the parser additionally should accept as
6524 attributes. This can for example be used when attributes have
6525 been #define d for portability.
6526 New in version 1.5.
6528 cpp_paren_attributes
6531 A list of strings that the parser additionally should accept as
6532 attributes with one argument. That is, if my_align_as is in the
6533 list, then my_align_as(X) is parsed as an attribute for all
6534 strings X that have balanced braces ((), [], and {}). This can
6535 for example be used when attributes have been #define d for
6536 portability.
6537 New in version 1.5.
6539 Example of configuration file
6542 # -*- coding: utf-8 -*-
6543 #
6544 # test documentation build configuration file, created by
6545 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
6546 #
6547 # This file is execfile()d with the current directory set to its
6548 # containing dir.
6549 #
6550 # Note that not all possible configuration values are present in this
6551 # autogenerated file.
6552 #
6553 # All configuration values have a default; values that are commented out
6554 # serve to show the default.
6555 # If extensions (or modules to document with autodoc) are in another directory,
6557 # add these directories to sys.path here. If the directory is relative to the
6558 # documentation root, use os.path.abspath to make it absolute, like shown here.
6559 #
6560 # import os
6561 # import sys
6562 # sys.path.insert(0, os.path.abspath('.'))
6563 # -- General configuration ------------------------------------------------
6565 # If your documentation needs a minimal Sphinx version, state it here.
6567 #
6568 # needs_sphinx = '1.0'
6569 # Add any Sphinx extension module names here, as strings. They can be
6571 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
6572 # ones.
6573 extensions = []
6574 # Add any paths that contain templates here, relative to this directory.
6576 templates_path = ['_templates']
6577 # The suffix(es) of source filenames.
6579 # You can specify multiple suffix as a list of string:
6580 #
6581 # source_suffix = ['.rst', '.md']
6582 source_suffix = '.rst'
6583 # The encoding of source files.
6585 #
6586 # source_encoding = 'utf-8-sig'
6587 # The master toctree document.
6589 master_doc = 'index'
6590 # General information about the project.
6592 project = u'test'
6593 copyright = u'2016, test'
6594 author = u'test'
6595 # The version info for the project you're documenting, acts as replacement for
6597 # |version| and |release|, also used in various other places throughout the
6598 # built documents.
6599 #
6600 # The short X.Y version.
6601 version = u'test'
6602 # The full version, including alpha/beta/rc tags.
6603 release = u'test'
6604 # The language for content autogenerated by Sphinx. Refer to documentation
6606 # for a list of supported languages.
6607 #
6608 # This is also used if you do content translation via gettext catalogs.
6609 # Usually you set "language" from the command line for these cases.
6610 language = None
6611 # There are two options for replacing |today|: either, you set today to some
6613 # non-false value, then it is used:
6614 #
6615 # today = ''
6616 #
6617 # Else, today_fmt is used as the format for a strftime call.
6618 #
6619 # today_fmt = '%B %d, %Y'
6620 # List of patterns, relative to source directory, that match files and
6622 # directories to ignore when looking for source files.
6623 # These patterns also affect html_static_path and html_extra_path
6624 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
6625 # The reST default role (used for this markup: `text`) to use for all
6627 # documents.
6628 #
6629 # default_role = None
6630 # If true, '()' will be appended to :func: etc. cross-reference text.
6632 #
6633 # add_function_parentheses = True
6634 # If true, the current module name will be prepended to all description
6636 # unit titles (such as .. function::).
6637 #
6638 # add_module_names = True
6639 # If true, sectionauthor and moduleauthor directives will be shown in the
6641 # output. They are ignored by default.
6642 #
6643 # show_authors = False
6644 # The name of the Pygments (syntax highlighting) style to use.
6646 pygments_style = 'sphinx'
6647 # A list of ignored prefixes for module index sorting.
6649 # modindex_common_prefix = []
6650 # If true, keep warnings as "system message" paragraphs in the built documents.
6652 # keep_warnings = False
6653 # If true, `todo` and `todoList` produce output, else they produce nothing.
6655 todo_include_todos = False
6656 # -- Options for HTML output ----------------------------------------------
6659 # The theme to use for HTML and HTML Help pages. See the documentation for
6661 # a list of builtin themes.
6662 #
6663 html_theme = 'alabaster'
6664 # Theme options are theme-specific and customize the look and feel of a theme
6666 # further. For a list of options available for each theme, see the
6667 # documentation.
6668 #
6669 # html_theme_options = {}
6670 # Add any paths that contain custom themes here, relative to this directory.
6672 # html_theme_path = []
6673 # The name for this set of Sphinx documents.
6675 # "<project> v<release> documentation" by default.
6676 #
6677 # html_title = u'test vtest'
6678 # A shorter title for the navigation bar. Default is the same as html_title.
6680 #
6681 # html_short_title = None
6682 # The name of an image file (relative to this directory) to place at the top
6684 # of the sidebar.
6685 #
6686 # html_logo = None
6687 # The name of an image file (relative to this directory) to use as a favicon of
6689 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
6690 # pixels large.
6691 #
6692 # html_favicon = None
6693 # Add any paths that contain custom static files (such as style sheets) here,
6695 # relative to this directory. They are copied after the builtin static files,
6696 # so a file named "default.css" will overwrite the builtin "default.css".
6697 html_static_path = ['_static']
6698 # Add any extra paths that contain custom files (such as robots.txt or
6700 # .htaccess) here, relative to this directory. These files are copied
6701 # directly to the root of the documentation.
6702 #
6703 # html_extra_path = []
6704 # If not None, a 'Last updated on:' timestamp is inserted at every page
6706 # bottom, using the given strftime format.
6707 # The empty string is equivalent to '%b %d, %Y'.
6708 #
6709 # html_last_updated_fmt = None
6710 # Custom sidebar templates, maps document names to template names.
6712 #
6713 # html_sidebars = {}
6714 # Additional templates that should be rendered to pages, maps page names to
6716 # template names.
6717 #
6718 # html_additional_pages = {}
6719 # If false, no module index is generated.
6721 #
6722 # html_domain_indices = True
6723 # If false, no index is generated.
6725 #
6726 # html_use_index = True
6727 # If true, the index is split into individual pages for each letter.
6729 #
6730 # html_split_index = False
6731 # If true, links to the reST sources are added to the pages.
6733 #
6734 # html_show_sourcelink = True
6735 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
6737 #
6738 # html_show_sphinx = True
6739 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
6741 #
6742 # html_show_copyright = True
6743 # If true, an OpenSearch description file will be output, and all pages will
6745 # contain a <link> tag referring to it. The value of this option must be the
6746 # base URL from which the finished HTML is served.
6747 #
6748 # html_use_opensearch = ''
6749 # This is the file name suffix for HTML files (e.g. ".xhtml").
6751 # html_file_suffix = None
6752 # Language to be used for generating the HTML full-text search index.
6754 # Sphinx supports the following languages:
6755 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
6756 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
6757 #
6758 # html_search_language = 'en'
6759 # A dictionary with options for the search language support, empty by default.
6761 # 'ja' uses this config value.
6762 # 'zh' user can custom change `jieba` dictionary path.
6763 #
6764 # html_search_options = {'type': 'default'}
6765 # The name of a javascript file (relative to the configuration directory) that
6767 # implements a search results scorer. If empty, the default will be used.
6768 #
6769 # html_search_scorer = 'scorer.js'
6770 # Output file base name for HTML help builder.
6772 htmlhelp_basename = 'testdoc'
6773 # -- Options for LaTeX output ---------------------------------------------
6775 latex_elements = {
6777 # The paper size ('letterpaper' or 'a4paper').
6778 #
6779 # 'papersize': 'letterpaper',
6780 # The font size ('10pt', '11pt' or '12pt').
6782 #
6783 # 'pointsize': '10pt',
6784 # Additional stuff for the LaTeX preamble.
6786 #
6787 # 'preamble': '',
6788 # Latex figure (float) alignment
6790 #
6791 # 'figure_align': 'htbp',
6792 }
6793 # Grouping the document tree into LaTeX files. List of tuples
6795 # (source start file, target name, title,
6796 # author, documentclass [howto, manual, or own class]).
6797 latex_documents = [
6798 (master_doc, 'test.tex', u'test Documentation',
6799 u'test', 'manual'),
6800 ]
6801 # The name of an image file (relative to this directory) to place at the top of
6803 # the title page.
6804 #
6805 # latex_logo = None
6806 # If true, show page references after internal links.
6808 #
6809 # latex_show_pagerefs = False
6810 # If true, show URL addresses after external links.
6812 #
6813 # latex_show_urls = False
6814 # Documents to append as an appendix to all manuals.
6816 #
6817 # latex_appendices = []
6818 # If false, no module index is generated.
6820 #
6821 # latex_domain_indices = True
6822 # -- Options for manual page output ---------------------------------------
6825 # One entry per manual page. List of tuples
6827 # (source start file, name, description, authors, manual section).
6828 man_pages = [
6829 (master_doc, 'test', u'test Documentation',
6830 [author], 1)
6831 ]
6832 # If true, show URL addresses after external links.
6834 #
6835 # man_show_urls = False
6836 # -- Options for Texinfo output -------------------------------------------
6839 # Grouping the document tree into Texinfo files. List of tuples
6841 # (source start file, target name, title, author,
6842 # dir menu entry, description, category)
6843 texinfo_documents = [
6844 (master_doc, 'test', u'test Documentation',
6845 author, 'test', 'One line description of project.',
6846 'Miscellaneous'),
6847 ]
6848 # Documents to append as an appendix to all manuals.
6850 #
6851 # texinfo_appendices = []
6852 # If false, no module index is generated.
6854 #
6855 # texinfo_domain_indices = True
6856 # How to display URL addresses: 'footnote', 'no', or 'inline'.
6858 #
6859 # texinfo_show_urls = 'footnote'
6860 # If true, do not generate a @detailmenu in the "Top" node's menu.
6862 #
6863 # texinfo_no_detailmenu = False
6864 # -- A random example -----------------------------------------------------
6866 import sys, os
6868 sys.path.insert(0, os.path.abspath('.'))
6869 exclude_patterns = ['zzz']
6870 numfig = True
6872 #language = 'ja'
6873 extensions.append('sphinx.ext.todo')
6875 extensions.append('sphinx.ext.autodoc')
6876 #extensions.append('sphinx.ext.autosummary')
6877 extensions.append('sphinx.ext.intersphinx')
6878 extensions.append('sphinx.ext.mathjax')
6879 extensions.append('sphinx.ext.viewcode')
6880 extensions.append('sphinx.ext.graphviz')
6881 autosummary_generate = True
6884 html_theme = 'default'
6885 #source_suffix = ['.rst', '.txt']
6886
6889 These are the built-in Sphinx builders. More builders can be added by
6890 extensions.
6891 The builder’s “name” must be given to the -b command-line option of
6893 sphinx-build to select a builder.
6894 class sphinx.builders.html.StandaloneHTMLBuilder
6896 This is the standard HTML builder. Its output is a directory
6897 with HTML files, complete with style sheets and optionally the
6898 reST sources. There are quite a few configuration values that
6899 customize the output of this builder, see the chapter
6900 html-options for details.
6901 name = 'html'
6903 format = 'html'
6905 supported_image_types = ['image/svg+xml', 'image/png',
6907 'image/gif', 'image/jpeg']
6908 class sphinx.builders.html.DirectoryHTMLBuilder
6910 This is a subclass of the standard HTML builder. Its output is
6911 a directory with HTML files, where each file is called
6912 index.html and placed in a subdirectory named like its page
6913 name. For example, the document markup/rest.rst will not result
6914 in an output file markup/rest.html, but markup/rest/index.html.
6915 When generating links between pages, the index.html is omitted,
6916 so that the URL would look like markup/rest/.
6917 name = 'dirhtml'
6919 format = 'html'
6921 supported_image_types = ['image/svg+xml', 'image/png',
6923 'image/gif', 'image/jpeg']
6924 New in version 0.6.
6926 class sphinx.builders.html.SingleFileHTMLBuilder
6929 This is an HTML builder that combines the whole project in one
6930 output file. (Obviously this only works with smaller projects.)
6931 The file is named like the master document. No indices will be
6932 generated.
6933 name = 'singlehtml'
6935 format = 'html'
6937 supported_image_types = ['image/svg+xml', 'image/png',
6939 'image/gif', 'image/jpeg']
6940 New in version 1.0.
6942 class sphinx.builders.htmlhelp.HTMLHelpBuilder
6945 This builder produces the same output as the standalone HTML
6946 builder, but also generates HTML Help support files that allow
6947 the Microsoft HTML Help Workshop to compile them into a CHM
6948 file.
6949 name = 'htmlhelp'
6951 format = 'html'
6953 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
6955 class sphinx.builders.qthelp.QtHelpBuilder
6957 This builder produces the same output as the standalone HTML
6958 builder, but also generates Qt help collection support files
6959 that allow the Qt collection generator to compile them.
6960 name = 'qthelp'
6962 format = 'html'
6964 supported_image_types = ['image/svg+xml', 'image/png',
6966 'image/gif', 'image/jpeg']
6967 class sphinx.builders.applehelp.AppleHelpBuilder
6969 This builder produces an Apple Help Book based on the same out‐
6970 put as the standalone HTML builder.
6971 If the source directory contains any .lproj folders, the one
6973 corresponding to the selected language will have its contents
6974 merged with the generated output. These folders will be ignored
6975 by all other documentation types.
6976 In order to generate a valid help book, this builder requires
6978 the command line tool hiutil, which is only available on Mac OS
6979 X 10.6 and above. You can disable the indexing step by setting
6980 applehelp_disable_external_tools to True, in which case the out‐
6981 put will not be valid until hiutil has been run on all of the
6982 .lproj folders within the bundle.
6983 name = 'applehelp'
6985 format = 'html'
6987 supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
6989 'image/tiff', 'image/jp2', 'image/svg+xml']
6990 New in version 1.3.
6992 class sphinx.builders.devhelp.DevhelpBuilder
6995 This builder produces the same output as the standalone HTML
6996 builder, but also generates GNOME Devhelp support file that
6997 allows the GNOME Devhelp reader to view them.
6998 name = 'devhelp'
7000 format = 'html'
7002 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
7004 class sphinx.builders.epub3.Epub3Builder
7006 This builder produces the same output as the standalone HTML
7007 builder, but also generates an epub file for ebook readers. See
7008 epub-faq for details about it. For definition of the epub for‐
7009 mat, have a look at http://idpf.org/epub or
7010 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
7011 files.
7012 name = 'epub'
7014 format = 'html'
7016 supported_image_types = ['image/svg+xml', 'image/png',
7018 'image/gif', 'image/jpeg']
7019 New in version 1.4.
7021 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7024 used for the default builder of epub.
7025 class sphinx.builders.latex.LaTeXBuilder
7028 This builder produces a bunch of LaTeX files in the output
7029 directory. You have to specify which documents are to be
7030 included in which LaTeX files via the latex_documents configura‐
7031 tion value. There are a few configuration values that customize
7032 the output of this builder, see the chapter latex-options for
7033 details.
7034 The produced LaTeX file uses several LaTeX packages that may not
7036 be present in a “minimal” TeX distribution installation. For
7037 example, on Ubuntu, the following packages need to be installed
7038 for successful PDF builds:
7039 · texlive-latex-recommended
7041 · texlive-fonts-recommended
7043 · texlive-latex-extra
7045 · latexmk (for make latexpdf on GNU/Linux and MacOS X)
7047 · latex-xcolor (old Ubuntu)
7049 · texlive-luatex, texlive-xetex (see latex_engine)
7051 The testing of Sphinx LaTeX is done on Ubuntu trusty with the
7053 above mentioned packages, which are from a TeXLive 2013 snapshot
7054 dated February 2014.
7055 Changed in version 1.6: Formerly, testing had been done on
7057 Ubuntu precise (TeXLive 2009).
7058 NOTE:
7061 Since 1.6, make latexpdf uses latexmk (not on Windows). This
7062 makes sure the needed number of runs is automatically exe‐
7063 cuted to get the cross-references, bookmarks, indices, and
7064 tables of contents right.
7065 One can pass to latexmk options via the LATEXMKOPTS Makefile
7067 variable. For example:
7068 make latexpdf LATEXMKOPTS="-silent"
7070 reduces console output to a minimum.
7072 Also, if latexmk version is 4.52b or higher (Jan 17)
7074 LATEXMKOPTS="-xelatex" will speed up PDF builds via XeLateX
7075 in case of numerous graphics inclusions.
7076 make latexpdf LATEXMKOPTS="-xelatex"
7078 To pass options directly to the (pdf|xe|lua)latex executable,
7080 use variable LATEXOPTS.
7081 make latexpdf LATEXOPTS="--interaction=nonstopmode"
7083 name = 'latex'
7085 format = 'latex'
7087 supported_image_types = ['application/pdf', 'image/png',
7089 'image/jpeg']
7090 Note that a direct PDF builder is being provided by rinohtype. The
7092 builder’s name is rinoh. Refer to the rinohtype manual for details.
7093 class sphinx.builders.text.TextBuilder
7095 This builder produces a text file for each reST file – this is
7096 almost the same as the reST source, but with much of the markup
7097 stripped for better readability.
7098 name = 'text'
7100 format = 'text'
7102 supported_image_types = []
7104 New in version 0.4.
7106 class sphinx.builders.manpage.ManualPageBuilder
7109 This builder produces manual pages in the groff format. You
7110 have to specify which documents are to be included in which man‐
7111 ual pages via the man_pages configuration value.
7112 name = 'man'
7114 format = 'man'
7116 supported_image_types = []
7118 New in version 1.0.
7120 class sphinx.builders.texinfo.TexinfoBuilder
7123 This builder produces Texinfo files that can be processed into
7124 Info files by the makeinfo program. You have to specify which
7125 documents are to be included in which Texinfo files via the tex‐
7126 info_documents configuration value.
7127 The Info format is the basis of the on-line help system used by
7129 GNU Emacs and the terminal-based program info. See texinfo-faq
7130 for more details. The Texinfo format is the official documenta‐
7131 tion system used by the GNU project. More information on Tex‐
7132 info can be found at https://www.gnu.org/software/texinfo/.
7133 name = 'texinfo'
7135 format = 'texinfo'
7137 supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
7139 New in version 1.1.
7141 class sphinx.builders.html.SerializingHTMLBuilder
7144 This builder uses a module that implements the Python serializa‐
7145 tion API (pickle, simplejson, phpserialize, and others) to dump
7146 the generated HTML documentation. The pickle builder is a sub‐
7147 class of it.
7148 A concrete subclass of this builder serializing to the PHP seri‐
7150 alization format could look like this:
7151 import phpserialize
7153 class PHPSerializedBuilder(SerializingHTMLBuilder):
7155 name = 'phpserialized'
7156 implementation = phpserialize
7157 out_suffix = '.file.phpdump'
7158 globalcontext_filename = 'globalcontext.phpdump'
7159 searchindex_filename = 'searchindex.phpdump'
7160 implementation
7162 A module that implements dump(), load(), dumps() and
7163 loads() functions that conform to the functions with the
7164 same names from the pickle module. Known modules imple‐
7165 menting this interface are simplejson, phpserialize,
7166 plistlib, and others.
7167 out_suffix
7169 The suffix for all regular files.
7170 globalcontext_filename
7172 The filename for the file that contains the “global con‐
7173 text”. This is a dict with some general configuration
7174 values such as the name of the project.
7175 searchindex_filename
7177 The filename for the search index Sphinx generates.
7178 See Serialization builder details for details about the output
7180 format.
7181 New in version 0.5.
7183 class sphinx.builders.html.PickleHTMLBuilder
7186 This builder produces a directory with pickle files containing
7187 mostly HTML fragments and TOC information, for use of a web
7188 application (or custom postprocessing tool) that doesn’t use the
7189 standard HTML templates.
7190 See Serialization builder details for details about the output
7192 format.
7193 name = 'pickle'
7195 The old name web still works as well.
7196 format = 'html'
7198 supported_image_types = ['image/svg+xml', 'image/png',
7200 'image/gif', 'image/jpeg']
7201 The file suffix is .fpickle. The global context is called glob‐
7203 alcontext.pickle, the search index searchindex.pickle.
7204 class sphinx.builders.html.JSONHTMLBuilder
7206 This builder produces a directory with JSON files containing
7207 mostly HTML fragments and TOC information, for use of a web
7208 application (or custom postprocessing tool) that doesn’t use the
7209 standard HTML templates.
7210 See Serialization builder details for details about the output
7212 format.
7213 name = 'json'
7215 format = 'html'
7217 supported_image_types = ['image/svg+xml', 'image/png',
7219 'image/gif', 'image/jpeg']
7220 The file suffix is .fjson. The global context is called global‐
7222 context.json, the search index searchindex.json.
7223 New in version 0.5.
7225 class sphinx.builders.gettext.MessageCatalogBuilder
7228 This builder produces gettext-style message catalogs. Each
7229 top-level file or subdirectory grows a single .pot catalog tem‐
7230 plate.
7231 See the documentation on intl for further reference.
7233 name = 'gettext'
7235 format = ''
7237 supported_image_types = []
7239 New in version 1.1.
7241 class sphinx.builders.changes.ChangesBuilder
7244 This builder produces an HTML overview of all versionadded, ver‐
7245 sionchanged and deprecated directives for the current version.
7246 This is useful to generate a ChangeLog file, for example.
7247 name = 'changes'
7249 format = ''
7251 supported_image_types = []
7253 class sphinx.builders.dummy.DummyBuilder
7255 This builder produces no output. The input is only parsed and
7256 checked for consistency. This is useful for linting purposes.
7257 name = 'dummy'
7259 supported_image_types = []
7261 New in version 1.4.
7263 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
7266 This builder scans all documents for external links, tries to
7267 open them with requests, and writes an overview which ones are
7268 broken and redirected to standard output and to output.txt in
7269 the output directory.
7270 name = 'linkcheck'
7272 format = ''
7274 supported_image_types = []
7276 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
7278 comes to use requests module.
7279 class sphinx.builders.xml.XMLBuilder
7282 This builder produces Docutils-native XML files. The output can
7283 be transformed with standard XML tools such as XSLT processors
7284 into arbitrary final forms.
7285 name = 'xml'
7287 format = 'xml'
7289 supported_image_types = []
7291 New in version 1.2.
7293 class sphinx.builders.xml.PseudoXMLBuilder
7296 This builder is used for debugging the Sphinx/Docutils “Reader
7297 to Transform to Writer” pipeline. It produces compact
7298 pretty-printed “pseudo-XML”, files where nesting is indicated by
7299 indentation (no end-tags). External attributes for all elements
7300 are output, and internal attributes for any leftover “pending”
7301 elements are also given.
7302 name = 'pseudoxml'
7304 format = 'pseudoxml'
7306 supported_image_types = []
7308 New in version 1.2.
7310 Built-in Sphinx extensions that offer more builders are:
7313 · doctest
7315 · coverage
7317 Serialization builder details
7319 All serialization builders outputs one file per source file and a few
7320 special files. They also copy the reST source files in the directory
7321 _sources under the output directory.
7322 The PickleHTMLBuilder is a builtin subclass that implements the pickle
7324 serialization interface.
7325 The files per source file have the extensions of out_suffix, and are
7327 arranged in directories just as the source files are. They unserialize
7328 to a dictionary (or dictionary like structure) with these keys:
7329 body The HTML “body” (that is, the HTML rendering of the source
7331 file), as rendered by the HTML translator.
7332 title The title of the document, as HTML (may contain markup).
7334 toc The table of contents for the file, rendered as an HTML <ul>.
7336 display_toc
7338 A boolean that is True if the toc contains more than one entry.
7339 current_page_name
7341 The document name of the current file.
7342 parents, prev and next
7344 Information about related chapters in the TOC tree. Each rela‐
7345 tion is a dictionary with the keys link (HREF for the relation)
7346 and title (title of the related document, as HTML). parents is
7347 a list of relations, while prev and next are a single relation.
7348 sourcename
7350 The name of the source file under _sources.
7351 The special files are located in the root output directory. They are:
7353 SerializingHTMLBuilder.globalcontext_filename
7355 A pickled dict with these keys:
7356 project, copyright, release, version
7358 The same values as given in the configuration file.
7359 style html_style.
7361 last_updated
7363 Date of last build.
7364 builder
7366 Name of the used builder, in the case of pickles this is
7367 always 'pickle'.
7368 titles A dictionary of all documents’ titles, as HTML strings.
7370 SerializingHTMLBuilder.searchindex_filename
7372 An index that can be used for searching the documentation. It
7373 is a pickled list with these entries:
7374 · A list of indexed docnames.
7376 · A list of document titles, as HTML strings, in the same order
7378 as the first list.
7379 · A dict mapping word roots (processed by an English-language
7381 stemmer) to a list of integers, which are indices into the
7382 first list.
7383 environment.pickle
7385 The build environment. This is always a pickle file, indepen‐
7386 dent of the builder and a copy of the environment that was used
7387 when the builder was started.
7388 Todo
7390 Document common members.
7391 Unlike the other pickle files this pickle file requires that the
7393 sphinx package is available on unpickling.
7394
7396 Since many projects will need special features in their documentation,
7397 Sphinx allows adding “extensions” to the build process, each of which
7398 can modify almost any aspect of document processing.
7399 This chapter describes the extensions bundled with Sphinx. For the API
7401 documentation on writing your own extension, refer to dev-extensions.
7402 Built-in extensions
7404 These extensions are built in and can be activated by respective
7405 entries in the extensions configuration value:
7406 sphinx.ext.autodoc – Include documentation from docstrings
7408 This extension can import the modules you are documenting, and pull in
7409 documentation from docstrings in a semi-automatic way.
7410 NOTE:
7412 For Sphinx (actually, the Python interpreter that executes Sphinx)
7413 to find your module, it must be importable. That means that the
7414 module or the package must be in one of the directories on sys.path
7415 – adapt your sys.path in the configuration file accordingly.
7416 WARNING:
7418 autodoc imports the modules to be documented. If any modules have
7419 side effects on import, these will be executed by autodoc when
7420 sphinx-build is run.
7421 If you document scripts (as opposed to library modules), make sure
7423 their main routine is protected by a if __name__ == '__main__' con‐
7424 dition.
7425 For this to work, the docstrings must of course be written in correct
7427 reStructuredText. You can then use all of the usual Sphinx markup in
7428 the docstrings, and it will end up correctly in the documentation.
7429 Together with hand-written documentation, this technique eases the pain
7430 of having to maintain two locations for documentation, while at the
7431 same time avoiding auto-generated-looking pure API documentation.
7432 If you prefer NumPy or Google style docstrings over reStructuredText,
7434 you can also enable the napoleon extension. napoleon is a preprocessor
7435 that converts your docstrings to correct reStructuredText before
7436 autodoc processes them.
7437 autodoc provides several directives that are versions of the usual
7439 py:module, py:class and so forth. On parsing time, they import the
7440 corresponding module and extract the docstring of the given objects,
7441 inserting them into the page source under a suitable py:module,
7442 py:class etc. directive.
7443 NOTE:
7445 Just as py:class respects the current py:module, autoclass will also
7446 do so. Likewise, automethod will respect the current py:class.
7447 .. automodule::
7449 .. autoclass::
7451 .. autoexception::
7453 Document a module, class or exception. All three directives
7454 will by default only insert the docstring of the object itself:
7455 .. autoclass:: Noodle
7457 will produce source like this:
7459 .. class:: Noodle
7461 Noodle's docstring.
7463 The “auto” directives can also contain content of their own, it
7465 will be inserted into the resulting non-auto directive source
7466 after the docstring (but before any automatic member documenta‐
7467 tion).
7468 Therefore, you can also mix automatic and non-automatic member
7470 documentation, like so:
7471 .. autoclass:: Noodle
7473 :members: eat, slurp
7474 .. method:: boil(time=10)
7476 Boil the noodle *time* minutes.
7478 Options and advanced usage
7480 · If you want to automatically document members, there’s a mem‐
7482 bers option:
7483 .. automodule:: noodle
7485 :members:
7486 will document all module members (recursively), and
7488 .. autoclass:: Noodle
7490 :members:
7491 will document all non-private member functions and properties
7493 (that is, those whose name doesn’t start with _).
7494 For modules, __all__ will be respected when looking for mem‐
7496 bers unless you give the ignore-module-all flag option. With‐
7497 out ignore-module-all, the order of the members will also be
7498 the order in __all__.
7499 You can also give an explicit list of members; only these will
7501 then be documented:
7502 .. autoclass:: Noodle
7504 :members: eat, slurp
7505 · If you want to make the members option (or other options
7507 described below) the default, see autodoc_default_options.
7508 TIP:
7510 You can use a negated form, 'no-flag', as an option of
7511 autodoc directive, to disable it temporarily. For example:
7512 .. automodule:: foo
7514 :no-undoc-members:
7515 · Members without docstrings will be left out, unless you give
7517 the undoc-members flag option:
7518 .. automodule:: noodle
7520 :members:
7521 :undoc-members:
7522 · “Private” members (that is, those named like _private or
7524 __private) will be included if the private-members flag option
7525 is given.
7526 New in version 1.1.
7528 · Python “special” members (that is, those named like __spe‐
7531 cial__) will be included if the special-members flag option is
7532 given:
7533 .. autoclass:: my.Class
7535 :members:
7536 :private-members:
7537 :special-members:
7538 would document both “private” and “special” members of the
7540 class.
7541 New in version 1.1.
7543 Changed in version 1.2: The option can now take arguments,
7546 i.e. the special members to document.
7547 · For classes and exceptions, members inherited from base
7550 classes will be left out when documenting all members, unless
7551 you give the inherited-members flag option, in addition to
7552 members:
7553 .. autoclass:: Noodle
7555 :members:
7556 :inherited-members:
7557 This can be combined with undoc-members to document all avail‐
7559 able members of the class or module.
7560 Note: this will lead to markup errors if the inherited members
7562 come from a module whose docstrings are not reST formatted.
7563 New in version 0.3.
7565 · It’s possible to override the signature for explicitly docu‐
7568 mented callable objects (functions, methods, classes) with the
7569 regular syntax that will override the signature gained from
7570 introspection:
7571 .. autoclass:: Noodle(type)
7573 .. automethod:: eat(persona)
7575 This is useful if the signature from the method is hidden by a
7577 decorator.
7578 New in version 0.4.
7580 · The automodule, autoclass and autoexception directives also
7583 support a flag option called show-inheritance. When given, a
7584 list of base classes will be inserted just below the class
7585 signature (when used with automodule, this will be inserted
7586 for every class that is documented in the module).
7587 New in version 0.4.
7589 · All autodoc directives support the noindex flag option that
7592 has the same effect as for standard py:function etc. direc‐
7593 tives: no index entries are generated for the documented
7594 object (and all autodocumented members).
7595 New in version 0.4.
7597 · automodule also recognizes the synopsis, platform and depre‐
7600 cated options that the standard py:module directive supports.
7601 New in version 0.5.
7603 · automodule and autoclass also has an member-order option that
7606 can be used to override the global value of
7607 autodoc_member_order for one directive.
7608 New in version 0.6.
7610 · The directives supporting member documentation also have a
7613 exclude-members option that can be used to exclude single mem‐
7614 ber names from documentation, if all members are to be docu‐
7615 mented.
7616 New in version 0.6.
7618 · In an automodule directive with the members option set, only
7621 module members whose __module__ attribute is equal to the mod‐
7622 ule name as given to automodule will be documented. This is
7623 to prevent documentation of imported classes or functions.
7624 Set the imported-members option if you want to prevent this
7625 behavior and document all available members. Note that
7626 attributes from imported modules will not be documented,
7627 because attribute documentation is discovered by parsing the
7628 source file of the current module.
7629 New in version 1.2.
7631 · Add a list of modules in the autodoc_mock_imports to prevent
7634 import errors to halt the building process when some external
7635 dependencies are not importable at build time.
7636 New in version 1.3.
7638 .. autofunction::
7641 .. autodata::
7643 .. automethod::
7645 .. autoattribute::
7647 These work exactly like autoclass etc., but do not offer the
7648 options used for automatic member documentation.
7649 autodata and autoattribute support the annotation option. With‐
7651 out this option, the representation of the object will be shown
7652 in the documentation. When the option is given without argu‐
7653 ments, only the name of the object will be printed:
7654 .. autodata:: CD_DRIVE
7656 :annotation:
7657 You can tell sphinx what should be printed after the name:
7659 .. autodata:: CD_DRIVE
7661 :annotation: = your CD device name
7662 For module data members and class attributes, documentation can
7664 either be put into a comment with special formatting (using a #:
7665 to start the comment instead of just #), or in a docstring after
7666 the definition. Comments need to be either on a line of their
7667 own before the definition, or immediately after the assignment
7668 on the same line. The latter form is restricted to one line
7669 only.
7670 This means that in the following class definition, all
7672 attributes can be autodocumented:
7673 class Foo:
7675 """Docstring for class Foo."""
7676 #: Doc comment for class attribute Foo.bar.
7678 #: It can have multiple lines.
7679 bar = 1
7680 flox = 1.5 #: Doc comment for Foo.flox. One line only.
7682 baz = 2
7684 """Docstring for class attribute Foo.baz."""
7685 def __init__(self):
7687 #: Doc comment for instance attribute qux.
7688 self.qux = 3
7689 self.spam = 4
7691 """Docstring for instance attribute spam."""
7692 Changed in version 0.6: autodata and autoattribute can now
7694 extract docstrings.
7695 Changed in version 1.1: Comment docs are now allowed on the same
7698 line after an assignment.
7699 Changed in version 1.2: autodata and autoattribute have an anno‐
7702 tation option.
7703 NOTE:
7706 If you document decorated functions or methods, keep in mind
7707 that autodoc retrieves its docstrings by importing the module
7708 and inspecting the __doc__ attribute of the given function or
7709 method. That means that if a decorator replaces the deco‐
7710 rated function with another, it must copy the original
7711 __doc__ to the new function.
7712 From Python 2.5, functools.wraps() can be used to create
7714 well-behaved decorating functions.
7715 There are also new config values that you can set:
7717 autoclass_content
7719 This value selects what content will be inserted into the main
7720 body of an autoclass directive. The possible values are:
7721 "class"
7723 Only the class’ docstring is inserted. This is the
7724 default. You can still document __init__ as a separate
7725 method using automethod or the members option to
7726 autoclass.
7727 "both" Both the class’ and the __init__ method’s docstring are
7729 concatenated and inserted.
7730 "init" Only the __init__ method’s docstring is inserted.
7732 New in version 0.3.
7734 If the class has no __init__ method or if the __init__ method’s
7737 docstring is empty, but the class has a __new__ method’s doc‐
7738 string, it is used instead.
7739 New in version 1.4.
7741 autodoc_member_order
7744 This value selects if automatically documented members are
7745 sorted alphabetical (value 'alphabetical'), by member type
7746 (value 'groupwise') or by source order (value 'bysource'). The
7747 default is alphabetical.
7748 Note that for source order, the module must be a Python module
7750 with the source code available.
7751 New in version 0.6.
7753 Changed in version 1.0: Support for 'bysource'.
7756 autodoc_default_flags
7759 This value is a list of autodoc directive flags that should be
7760 automatically applied to all autodoc directives. The supported
7761 flags are 'members', 'undoc-members', 'private-members', 'spe‐
7762 cial-members', 'inherited-members', 'show-inheritance',
7763 'ignore-module-all' and 'exclude-members'.
7764 New in version 1.0.
7766 Deprecated since version 1.8: Integrated into
7769 autodoc_default_options.
7770 autodoc_default_options
7773 The default options for autodoc directives. They are applied to
7774 all autodoc directives automatically. It must be a dictionary
7775 which maps option names to the values. For example:
7776 autodoc_default_options = {
7778 'members': 'var1, var2',
7779 'member-order': 'bysource',
7780 'special-members': '__init__',
7781 'undoc-members': None,
7782 'exclude-members': '__weakref__'
7783 }
7784 Setting None is equivalent to giving the option name in the list
7786 format (i.e. it means “yes/true/on”).
7787 The supported options are 'members', 'undoc-members', 'pri‐
7789 vate-members', 'special-members', 'inherited-members',
7790 'show-inheritance', 'ignore-module-all' and 'exclude-members'.
7791 New in version 1.8.
7793 autodoc_docstring_signature
7796 Functions imported from C modules cannot be introspected, and
7797 therefore the signature for such functions cannot be automati‐
7798 cally determined. However, it is an often-used convention to
7799 put the signature into the first line of the function’s doc‐
7800 string.
7801 If this boolean value is set to True (which is the default),
7803 autodoc will look at the first line of the docstring for func‐
7804 tions and methods, and if it looks like a signature, use the
7805 line as the signature and remove it from the docstring content.
7806 New in version 1.1.
7808 autodoc_mock_imports
7811 This value contains a list of modules to be mocked up. This is
7812 useful when some external dependencies are not met at build time
7813 and break the building process. You may only specify the root
7814 package of the dependencies themselves and omit the sub-modules:
7815 autodoc_mock_imports = ["django"]
7817 Will mock all imports under the django package.
7819 New in version 1.3.
7821 Changed in version 1.6: This config value only requires to
7824 declare the top-level modules that should be mocked.
7825 autodoc_warningiserror
7828 This value controls the behavior of sphinx-build -W during
7829 importing modules. If False is given, autodoc forcedly sup‐
7830 presses the error if the imported module emits warnings. By
7831 default, True.
7832 autodoc_inherit_docstrings
7834 This value controls the docstrings inheritance. If set to True
7835 the docstring for classes or methods, if not explicitly set, is
7836 inherited form parents.
7837 The default is True.
7839 New in version 1.7.
7841 Docstring preprocessing
7844 autodoc provides the following additional events:
7845 autodoc-process-docstring(app, what, name, obj, options, lines)
7847 New in version 0.4.
7848 Emitted when autodoc has read and processed a docstring. lines
7851 is a list of strings – the lines of the processed docstring –
7852 that the event handler can modify in place to change what Sphinx
7853 puts into the output.
7854 Parameters
7856 · app – the Sphinx application object
7858 · what – the type of the object which the docstring
7860 belongs to (one of "module", "class", "exception",
7861 "function", "method", "attribute")
7862 · name – the fully qualified name of the object
7864 · obj – the object itself
7866 · options – the options given to the directive: an object
7868 with attributes inherited_members, undoc_members,
7869 show_inheritance and noindex that are true if the flag
7870 option of same name was given to the auto directive
7871 · lines – the lines of the docstring, see above
7873 autodoc-process-signature(app, what, name, obj, options, signature,
7875 return_annotation)
7876 New in version 0.5.
7877 Emitted when autodoc has formatted a signature for an object.
7880 The event handler can return a new tuple (signature,
7881 return_annotation) to change what Sphinx puts into the output.
7882 Parameters
7884 · app – the Sphinx application object
7886 · what – the type of the object which the docstring
7888 belongs to (one of "module", "class", "exception",
7889 "function", "method", "attribute")
7890 · name – the fully qualified name of the object
7892 · obj – the object itself
7894 · options – the options given to the directive: an object
7896 with attributes inherited_members, undoc_members,
7897 show_inheritance and noindex that are true if the flag
7898 option of same name was given to the auto directive
7899 · signature – function signature, as a string of the form
7901 "(parameter_1, parameter_2)", or None if introspection
7902 didn’t succeed and signature wasn’t specified in the
7903 directive.
7904 · return_annotation – function return annotation as a
7906 string of the form " -> annotation", or None if there
7907 is no return annotation
7908 The sphinx.ext.autodoc module provides factory functions for commonly
7910 needed docstring processing in event autodoc-process-docstring:
7911 sphinx.ext.autodoc.cut_lines(pre, post=0, what=None)
7913 Return a listener that removes the first pre and last post lines
7914 of every docstring. If what is a sequence of strings, only doc‐
7915 strings of a type in what will be processed.
7916 Use like this (e.g. in the setup() function of conf.py):
7918 from sphinx.ext.autodoc import cut_lines
7920 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
7921 This can (and should) be used in place of automodule_skip_lines.
7923 sphinx.ext.autodoc.between(marker, what=None, keepempty=False,
7925 exclude=False)
7926 Return a listener that either keeps, or if exclude is True
7927 excludes, lines between lines that match the marker regular
7928 expression. If no line matches, the resulting docstring would
7929 be empty, so no change will be made unless keepempty is true.
7930 If what is a sequence of strings, only docstrings of a type in
7932 what will be processed.
7933 Skipping members
7935 autodoc allows the user to define a custom method for determining
7936 whether a member should be included in the documentation by using the
7937 following event:
7938 autodoc-skip-member(app, what, name, obj, skip, options)
7940 New in version 0.5.
7941 Emitted when autodoc has to decide whether a member should be
7944 included in the documentation. The member is excluded if a han‐
7945 dler returns True. It is included if the handler returns False.
7946 If more than one enabled extension handles the autodoc-skip-mem‐
7948 ber event, autodoc will use the first non-None value returned by
7949 a handler. Handlers should return None to fall back to the
7950 skipping behavior of autodoc and other enabled extensions.
7951 Parameters
7953 · app – the Sphinx application object
7955 · what – the type of the object which the docstring
7957 belongs to (one of "module", "class", "exception",
7958 "function", "method", "attribute")
7959 · name – the fully qualified name of the object
7961 · obj – the object itself
7963 · skip – a boolean indicating if autodoc will skip this
7965 member if the user handler does not override the deci‐
7966 sion
7967 · options – the options given to the directive: an object
7969 with attributes inherited_members, undoc_members,
7970 show_inheritance and noindex that are true if the flag
7971 option of same name was given to the auto directive
7972 sphinx.ext.autosectionlabel – Allow reference sections using its title
7974 New in version 1.4.
7975 This extension allows you to refer sections its title. This affects to
7978 the reference role (ref).
7979 For example:
7981 A Plain Title
7983 -------------
7984 This is the text of the section.
7986 It refers to the section title, see :ref:`A Plain Title`.
7988 Internally, this extension generates the labels for each section. If
7990 same section names are used in whole of document, any one is used for a
7991 target by default. The autosectionlabel_prefix_document configuration
7992 variable can be used to make headings which appear multiple times but
7993 in different documents unique.
7994 Configuration
7996 autosectionlabel_prefix_document
7997 True to prefix each section label with the name of the document
7998 it is in, followed by a colon. For example, index:Introduction
7999 for a section called Introduction that appears in document
8000 index.rst. Useful for avoiding ambiguity when the same section
8001 heading appears in different documents.
8002 sphinx.ext.autosummary – Generate autodoc summaries
8004 New in version 0.6.
8005 This extension generates function/method/attribute summary lists, simi‐
8008 lar to those output e.g. by Epydoc and other API doc generation tools.
8009 This is especially useful when your docstrings are long and detailed,
8010 and putting each one of them on a separate page makes them easier to
8011 read.
8012 The sphinx.ext.autosummary extension does this in two parts:
8014 1. There is an autosummary directive for generating summary listings
8016 that contain links to the documented items, and short summary blurbs
8017 extracted from their docstrings.
8018 2. Optionally, the convenience script sphinx-autogen or the new
8020 autosummary_generate config value can be used to generate short
8021 “stub” files for the entries listed in the autosummary directives.
8022 These files by default contain only the corresponding
8023 sphinx.ext.autodoc directive, but can be customized with templates.
8024 .. autosummary::
8026 Insert a table that contains links to documented items, and a
8027 short summary blurb (the first sentence of the docstring) for
8028 each of them.
8029 The autosummary directive can also optionally serve as a toctree
8031 entry for the included items. Optionally, stub .rst files for
8032 these items can also be automatically generated.
8033 For example,
8035 .. currentmodule:: sphinx
8037 .. autosummary::
8039 environment.BuildEnvironment
8041 util.relative_uri
8042 produces a table like this:
8044 ┌──────────────────────────┬────────────────────────────┐
8046 │environment.BuildEnviron‐ │ The environment in which │
8047 │ment([app]) │ the ReST files are trans‐ │
8048 │ │ lated. │
8049 ├──────────────────────────┼────────────────────────────┤
8050 │util.relative_uri(base, │ Return a relative URL from │
8051 │to) │ base to to. │
8052 └──────────────────────────┴────────────────────────────┘
8053 Autosummary preprocesses the docstrings and signatures with the
8055 same autodoc-process-docstring and autodoc-process-signature
8056 hooks as autodoc.
8057 Options
8059 · If you want the autosummary table to also serve as a toctree
8061 entry, use the toctree option, for example:
8062 .. autosummary::
8064 :toctree: DIRNAME
8065 sphinx.environment.BuildEnvironment
8067 sphinx.util.relative_uri
8068 The toctree option also signals to the sphinx-autogen script
8070 that stub pages should be generated for the entries listed in
8071 this directive. The option accepts a directory name as an
8072 argument; sphinx-autogen will by default place its output in
8073 this directory. If no argument is given, output is placed in
8074 the same directory as the file that contains the directive.
8075 · If you don’t want the autosummary to show function signatures
8077 in the listing, include the nosignatures option:
8078 .. autosummary::
8080 :nosignatures:
8081 sphinx.environment.BuildEnvironment
8083 sphinx.util.relative_uri
8084 · You can specify a custom template with the template option.
8086 For example,
8087 .. autosummary::
8089 :template: mytemplate.rst
8090 sphinx.environment.BuildEnvironment
8092 would use the template mytemplate.rst in your templates_path
8094 to generate the pages for all entries listed. See Customizing
8095 templates below.
8096 New in version 1.0.
8098 sphinx-autogen – generate autodoc stub pages
8101 The sphinx-autogen script can be used to conveniently generate stub
8102 documentation pages for items included in autosummary listings.
8103 For example, the command
8105 $ sphinx-autogen -o generated *.rst
8107 will read all autosummary tables in the *.rst files that have the :toc‐
8109 tree: option set, and output corresponding stub pages in directory gen‐
8110 erated for all documented items. The generated pages by default con‐
8111 tain text of the form:
8112 sphinx.util.relative_uri
8114 ========================
8115 .. autofunction:: sphinx.util.relative_uri
8117 If the -o option is not given, the script will place the output files
8119 in the directories specified in the :toctree: options.
8120 For more information, refer to the sphinx-autogen documentation
8122 Generating stub pages automatically
8124 If you do not want to create stub pages with sphinx-autogen, you can
8125 also use this new config value:
8126 autosummary_generate
8128 Boolean indicating whether to scan all found documents for auto‐
8129 summary directives, and to generate stub pages for each.
8130 Can also be a list of documents for which stub pages should be
8132 generated.
8133 The new files will be placed in the directories specified in the
8135 :toctree: options of the directives.
8136 Customizing templates
8138 New in version 1.0.
8139 You can customize the stub page templates, in a similar way as the HTML
8142 Jinja templates, see templating. (TemplateBridge is not supported.)
8143 NOTE:
8145 If you find yourself spending much time tailoring the stub tem‐
8146 plates, this may indicate that it’s a better idea to write custom
8147 narrative documentation instead.
8148 Autosummary uses the following Jinja template files:
8150 · autosummary/base.rst – fallback template
8152 · autosummary/module.rst – template for modules
8154 · autosummary/class.rst – template for classes
8156 · autosummary/function.rst – template for functions
8158 · autosummary/attribute.rst – template for class attributes
8160 · autosummary/method.rst – template for class methods
8162 The following variables available in the templates:
8164 name Name of the documented object, excluding the module and class
8166 parts.
8167 objname
8169 Name of the documented object, excluding the module parts.
8170 fullname
8172 Full name of the documented object, including module and class
8173 parts.
8174 module Name of the module the documented object belongs to.
8176 class Name of the class the documented object belongs to. Only avail‐
8178 able for methods and attributes.
8179 underline
8181 A string containing len(full_name) * '='. Use the underline fil‐
8182 ter instead.
8183 members
8185 List containing names of all members of the module or class.
8186 Only available for modules and classes.
8187 inherited_members
8189 List containing names of all inherited members of class. Only
8190 available for classes.
8191 New in version 1.8.0.
8193 functions
8196 List containing names of “public” functions in the module.
8197 Here, “public” here means that the name does not start with an
8198 underscore. Only available for modules.
8199 classes
8201 List containing names of “public” classes in the module. Only
8202 available for modules.
8203 exceptions
8205 List containing names of “public” exceptions in the module.
8206 Only available for modules.
8207 methods
8209 List containing names of “public” methods in the class. Only
8210 available for classes.
8211 attributes
8213 List containing names of “public” attributes in the class. Only
8214 available for classes.
8215 Additionally, the following filters are available
8217 escape(s)
8219 Escape any special characters in the text to be used in format‐
8220 ting RST contexts. For instance, this prevents asterisks making
8221 things bold. This replaces the builtin Jinja escape filter that
8222 does html-escaping.
8223 underline(s, line='=')
8225 Add a title underline to a piece of text.
8226 For instance, {{ fullname | escape | underline }} should be used to
8228 produce the title of a page.
8229 NOTE:
8231 You can use the autosummary directive in the stub pages. Stub pages
8232 are generated also based on these directives.
8233 sphinx.ext.coverage – Collect doc coverage stats
8235 This extension features one additional builder, the CoverageBuilder.
8236 class sphinx.ext.coverage.CoverageBuilder
8238 To use this builder, activate the coverage extension in your
8239 configuration file and give -b coverage on the command line.
8240 Todo
8242 Write this section.
8243 Several new configuration values can be used to specify what the
8245 builder should check:
8246 coverage_ignore_modules
8248 coverage_ignore_functions
8250 coverage_ignore_classes
8252 coverage_c_path
8254 coverage_c_regexes
8256 coverage_ignore_c_items
8258 coverage_write_headline
8260 Set to False to not write headlines.
8261 New in version 1.1.
8263 coverage_skip_undoc_in_source
8266 Skip objects that are not documented in the source with a doc‐
8267 string. False by default.
8268 New in version 1.1.
8270 sphinx.ext.doctest – Test snippets in the documentation
8273 This extension allows you to test snippets in the documentation in a
8274 natural way. It works by collecting specially-marked up code blocks
8275 and running them as doctest tests.
8276 Within one document, test code is partitioned in groups, where each
8278 group consists of:
8279 · zero or more setup code blocks (e.g. importing the module to test)
8281 · one or more test blocks
8283 When building the docs with the doctest builder, groups are collected
8285 for each document and run one after the other, first executing setup
8286 code blocks, then the test blocks in the order they appear in the file.
8287 There are two kinds of test blocks:
8289 · doctest-style blocks mimic interactive sessions by interleaving
8291 Python code (including the interpreter prompt) and output.
8292 · code-output-style blocks consist of an ordinary piece of Python code,
8294 and optionally, a piece of output for that code.
8295 Directives
8297 The group argument below is interpreted as follows: if it is empty, the
8298 block is assigned to the group named default. If it is *, the block is
8299 assigned to all groups (including the default group). Otherwise, it
8300 must be a comma-separated list of group names.
8301 .. testsetup:: [group]
8303 A setup code block. This code is not shown in the output for
8304 other builders, but executed before the doctests of the group(s)
8305 it belongs to.
8306 .. testcleanup:: [group]
8308 A cleanup code block. This code is not shown in the output for
8309 other builders, but executed after the doctests of the group(s)
8310 it belongs to.
8311 New in version 1.1.
8313 .. doctest:: [group]
8316 A doctest-style code block. You can use standard doctest flags
8317 for controlling how actual output is compared with what you give
8318 as output. The default set of flags is specified by the
8319 doctest_default_flags configuration variable.
8320 This directive supports three options:
8322 · hide, a flag option, hides the doctest block in other
8324 builders. By default it is shown as a highlighted doctest
8325 block.
8326 · options, a string option, can be used to give a comma-sepa‐
8328 rated list of doctest flags that apply to each example in the
8329 tests. (You still can give explicit flags per example, with
8330 doctest comments, but they will show up in other builders
8331 too.)
8332 · pyversion, a string option, can be used to specify the
8334 required Python version for the example to be tested. For
8335 instance, in the following case the example will be tested
8336 only for Python versions greater than 3.3:
8337 .. doctest::
8339 :pyversion: > 3.3
8340 The following operands are supported:
8342 · ~=: Compatible release clause
8344 · ==: Version matching clause
8346 · !=: Version exclusion clause
8348 · <=, >=: Inclusive ordered comparison clause
8350 · <, >: Exclusive ordered comparison clause
8352 · ===: Arbitrary equality clause.
8354 pyversion option is followed PEP-440: Version Specifiers.
8356 New in version 1.6.
8358 Changed in version 1.7: Supported PEP-440 operands and nota‐
8361 tions
8362 Note that like with standard doctests, you have to use
8365 <BLANKLINE> to signal a blank line in the expected output. The
8366 <BLANKLINE> is removed when building presentation output (HTML,
8367 LaTeX etc.).
8368 Also, you can give inline doctest options, like in doctest:
8370 >>> datetime.date.now() # doctest: +SKIP
8372 datetime.date(2008, 1, 1)
8373 They will be respected when the test is run, but stripped from
8375 presentation output.
8376 .. testcode:: [group]
8378 A code block for a code-output-style test.
8379 This directive supports one option:
8381 · hide, a flag option, hides the code block in other builders.
8383 By default it is shown as a highlighted code block.
8384 NOTE:
8386 Code in a testcode block is always executed all at once, no
8387 matter how many statements it contains. Therefore, output
8388 will not be generated for bare expressions – use print.
8389 Example:
8390 .. testcode::
8392 1+1 # this will give no output!
8394 print 2+2 # this will give output
8395 .. testoutput::
8397 4
8399 Also, please be aware that since the doctest module does not
8401 support mixing regular output and an exception message in the
8402 same snippet, this applies to testcode/testoutput as well.
8403 .. testoutput:: [group]
8405 The corresponding output, or the exception message, for the last
8406 testcode block.
8407 This directive supports two options:
8409 · hide, a flag option, hides the output block in other builders.
8411 By default it is shown as a literal block without highlight‐
8412 ing.
8413 · options, a string option, can be used to give doctest flags
8415 (comma-separated) just like in normal doctest blocks.
8416 Example:
8418 .. testcode::
8420 print 'Output text.'
8422 .. testoutput::
8424 :hide:
8425 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
8426 Output text.
8428 The following is an example for the usage of the directives. The test
8430 via doctest and the test via testcode and testoutput are equivalent.
8431 The parrot module
8433 =================
8434 .. testsetup:: *
8436 import parrot
8438 The parrot module is a module about parrots.
8440 Doctest example:
8442 .. doctest::
8444 >>> parrot.voom(3000)
8446 This parrot wouldn't voom if you put 3000 volts through it!
8447 Test-Output example:
8449 .. testcode::
8451 parrot.voom(3000)
8453 This would output:
8455 .. testoutput::
8457 This parrot wouldn't voom if you put 3000 volts through it!
8459 Skipping tests conditionally
8461 skipif, a string option, can be used to skip directives conditionally.
8462 This may be useful e.g. when a different set of tests should be run
8463 depending on the environment (hardware, network/VPN, optional dependen‐
8464 cies or different versions of dependencies). The skipif option is sup‐
8465 ported by all of the doctest directives. Below are typical use cases
8466 for skipif when used for different directives:
8467 · testsetup and testcleanup
8469 · conditionally skip test setup and/or cleanup
8471 · customize setup/cleanup code per environment
8473 · doctest
8475 · conditionally skip both a test and its output verification
8477 · testcode
8479 · conditionally skip a test
8481 · customize test code per environment
8483 · testoutput
8485 · conditionally skip output assertion for a skipped test
8487 · expect different output depending on the environment
8489 The value of the skipif option is evaluated as a Python expression. If
8491 the result is a true value, the directive is omitted from the test run
8492 just as if it wasn’t present in the file at all.
8493 Instead of repeating an expression, the doctest_global_setup configura‐
8495 tion option can be used to assign it to a variable which can then be
8496 used instead.
8497 Here’s an example which skips some tests if Pandas is not installed:
8499 conf.py.INDENT 0.0
8500 extensions = ['sphinx.ext.doctest']
8502 doctest_global_setup = '''
8503 try:
8504 import pandas as pd
8505 except ImportError:
8506 pd = None
8507 '''
8508contents.rst.INDENT 0.0
8509 .. testsetup::
8511 :skipif: pd is None
8512 data = pd.Series([42])
8514 .. doctest::
8516 :skipif: pd is None
8517 >>> data.iloc[0]
8519 42
8520 .. testcode::
8522 :skipif: pd is None
8523 print(data.iloc[-1])
8525 .. testoutput::
8527 :skipif: pd is None
8528 42
8530 Configuration
8532 The doctest extension uses the following configuration values:
8533 doctest_default_flags
8535 By default, these options are enabled:
8536 · ELLIPSIS, allowing you to put ellipses in the expected output
8538 that match anything in the actual output;
8539 · IGNORE_EXCEPTION_DETAIL, causing everything following the
8541 leftmost colon and any module information in the exception
8542 name to be ignored;
8543 · DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
8545 “1” is given – the default behavior of accepting this substi‐
8546 tution is a relic of pre-Python 2.2 times.
8547 New in version 1.5.
8549 doctest_path
8552 A list of directories that will be added to sys.path when the
8553 doctest builder is used. (Make sure it contains absolute
8554 paths.)
8555 doctest_global_setup
8557 Python code that is treated like it were put in a testsetup
8558 directive for every file that is tested, and for every group.
8559 You can use this to e.g. import modules you will always need in
8560 your doctests.
8561 New in version 0.6.
8563 doctest_global_cleanup
8566 Python code that is treated like it were put in a testcleanup
8567 directive for every file that is tested, and for every group.
8568 You can use this to e.g. remove any temporary files that the
8569 tests leave behind.
8570 New in version 1.1.
8572 doctest_test_doctest_blocks
8575 If this is a nonempty string (the default is 'default'), stan‐
8576 dard reST doctest blocks will be tested too. They will be
8577 assigned to the group name given.
8578 reST doctest blocks are simply doctests put into a paragraph of
8580 their own, like so:
8581 Some documentation text.
8583 >>> print 1
8585 1
8586 Some more documentation text.
8588 (Note that no special :: is used to introduce a doctest block;
8590 docutils recognizes them from the leading >>>. Also, no addi‐
8591 tional indentation is used, though it doesn’t hurt.)
8592 If this value is left at its default value, the above snippet is
8594 interpreted by the doctest builder exactly like the following:
8595 Some documentation text.
8597 .. doctest::
8599 >>> print 1
8601 1
8602 Some more documentation text.
8604 This feature makes it easy for you to test doctests in doc‐
8606 strings included with the autodoc extension without marking them
8607 up with a special directive.
8608 Note though that you can’t have blank lines in reST doctest
8610 blocks. They will be interpreted as one block ending and
8611 another one starting. Also, removal of <BLANKLINE> and #
8612 doctest: options only works in doctest blocks, though you may
8613 set trim_doctest_flags to achieve that in all code blocks with
8614 Python console content.
8615 sphinx.ext.extlinks – Markup to shorten external links
8617 Module author: Georg Brandl
8618 New in version 1.0.
8620 This extension is meant to help with the common pattern of having many
8623 external links that point to URLs on one and the same site, e.g. links
8624 to bug trackers, version control web interfaces, or simply subpages in
8625 other websites. It does so by providing aliases to base URLs, so that
8626 you only need to give the subpage name when creating a link.
8627 Let’s assume that you want to include many links to issues at the
8629 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
8630 Typing this URL again and again is tedious, so you can use extlinks to
8631 avoid repeating yourself.
8632 The extension adds one new config value:
8634 extlinks
8636 This config value must be a dictionary of external sites, map‐
8637 ping unique short alias names to a base URL and a prefix. For
8638 example, to create an alias for the above mentioned issues, you
8639 would add
8640 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
8642 'issue ')}
8643 Now, you can use the alias name as a new role, e.g.
8645 :issue:`123`. This then inserts a link to
8646 https://github.com/sphinx-doc/sphinx/issues/123. As you can
8647 see, the target given in the role is substituted in the base URL
8648 in the place of %s.
8649 The link caption depends on the second item in the tuple, the
8651 prefix:
8652 · If the prefix is None, the link caption is the full URL.
8654 · If the prefix is the empty string, the link caption is the
8656 partial URL given in the role content (123 in this case.)
8657 · If the prefix is a non-empty string, the link caption is the
8659 partial URL, prepended by the prefix – in the above example,
8660 the link caption would be issue 123.
8661 You can also use the usual “explicit title” syntax supported by
8663 other roles that generate links, i.e. :issue:`this issue <123>`.
8664 In this case, the prefix is not relevant.
8665 NOTE:
8667 Since links are generated from the role in the reading stage, they
8668 appear as ordinary links to e.g. the linkcheck builder.
8669 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
8671 New in version 1.4.
8672 This extension creates .nojekyll file on generated HTML directory to
8675 publish the document on GitHub Pages.
8676 sphinx.ext.graphviz – Add Graphviz graphs
8678 New in version 0.6.
8679 This extension allows you to embed Graphviz graphs in your documents.
8682 It adds these directives:
8684 .. graphviz::
8686 Directive to embed graphviz code. The input code for dot is
8687 given as the content. For example:
8688 .. graphviz::
8690 digraph foo {
8692 "bar" -> "baz";
8693 }
8694 In HTML output, the code will be rendered to a PNG or SVG image
8696 (see graphviz_output_format). In LaTeX output, the code will be
8697 rendered to an embeddable PDF file.
8698 You can also embed external dot files, by giving the file name
8700 as an argument to graphviz and no additional content:
8701 .. graphviz:: external.dot
8703 As for all file references in Sphinx, if the filename is abso‐
8705 lute, it is taken as relative to the source directory.
8706 Changed in version 1.1: Added support for external files.
8708 .. graph::
8711 Directive for embedding a single undirected graph. The name is
8712 given as a directive argument, the contents of the graph are the
8713 directive content. This is a convenience directive to generate
8714 graph <name> { <content> }.
8715 For example:
8717 .. graph:: foo
8719 "bar" -- "baz";
8721 NOTE:
8723 The graph name is passed unchanged to Graphviz. If it con‐
8724 tains non-alphanumeric characters (e.g. a dash), you will
8725 have to double-quote it.
8726 .. digraph::
8728 Directive for embedding a single directed graph. The name is
8729 given as a directive argument, the contents of the graph are the
8730 directive content. This is a convenience directive to generate
8731 digraph <name> { <content> }.
8732 For example:
8734 .. digraph:: foo
8736 "bar" -> "baz" -> "quux";
8738 New in version 1.0: All three directives support an alt option that
8740 determines the image’s alternate text for HTML output. If not given,
8741 the alternate text defaults to the graphviz code.
8742 New in version 1.1: All three directives support a caption option that
8745 can be used to give a caption to the diagram.
8746 Changed in version 1.4: All three directives support a graphviz_dot
8749 option that can be switch the dot command within the directive.
8750 New in version 1.5: All three directives support a align option to
8753 align the graph horizontal. The values “left”, “center”, “right” are
8754 allowed.
8755 New in version 1.6: All three directives support a name option to set
8758 the label to graph.
8759 There are also these new config values:
8762 graphviz_dot
8764 The command name with which to invoke dot. The default is
8765 'dot'; you may need to set this to a full path if dot is not in
8766 the executable search path.
8767 Since this setting is not portable from system to system, it is
8769 normally not useful to set it in conf.py; rather, giving it on
8770 the sphinx-build command line via the -D option should be
8771 preferable, like this:
8772 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
8774 graphviz_dot_args
8776 Additional command-line arguments to give to dot, as a list.
8777 The default is an empty list. This is the right place to set
8778 global graph, node or edge attributes via dot’s -G, -N and -E
8779 options.
8780 graphviz_output_format
8782 The output format for Graphviz when building HTML files. This
8783 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
8784 used, in order to make the URL links work properly, an appropri‐
8785 ate target attribute must be set, such as "_top" and "_blank".
8786 For example, the link in the following graph should work in the
8787 svg output:
8788 .. graphviz::
8790 digraph example {
8792 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
8793 b [label="other"];
8794 a -> b;
8795 }
8796 New in version 1.0: Previously, output always was PNG.
8798 sphinx.ext.ifconfig – Include content based on configuration
8801 This extension is quite simple, and features only one directive:
8802 .. ifconfig::
8804 Include content of the directive only if the Python expression
8805 given as an argument is True, evaluated in the namespace of the
8806 project’s configuration (that is, all registered variables from
8807 conf.py are available).
8808 For example, one could write
8810 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
8812 This stuff is only included in the built docs for unstable versions.
8814 To make a custom config value known to Sphinx, use add_con‐
8816 fig_value() in the setup function in conf.py, e.g.:
8817 def setup(app):
8819 app.add_config_value('releaselevel', '', 'env')
8820 The second argument is the default value, the third should
8822 always be 'env' for such values (it selects if Sphinx re-reads
8823 the documents if the value changes).
8824 sphinx.ext.imgconverter – A reference image converter using Imagemagick
8826 New in version 1.6.
8827 This extension converts images in your document to appropriate format
8830 for builders. For example, it allows you to use SVG images with LaTeX
8831 builder. As a result, you don’t mind what image format the builder
8832 supports.
8833 Internally, this extension uses Imagemagick to convert images.
8835 NOTE:
8837 Imagemagick rasterizes a SVG image on conversion. As a result, the
8838 image becomes not scalable. To avoid that, please use other image
8839 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
8840 or rsvg-convert).
8841 Configuration
8843 image_converter
8844 A path to convert command. By default, the imgconverter uses
8845 the command from search paths.
8846 image_converter_args
8848 Additional command-line arguments to give to convert, as a list.
8849 The default is an empty list [].
8850 sphinx.ext.inheritance_diagram – Include inheritance diagrams
8852 New in version 0.6.
8853 This extension allows you to include inheritance diagrams, rendered via
8856 the Graphviz extension.
8857 It adds this directive:
8859 .. inheritance-diagram::
8861 This directive has one or more arguments, each giving a module
8862 or class name. Class names can be unqualified; in that case
8863 they are taken to exist in the currently described module (see
8864 py:module).
8865 For each given class, and each class in each given module, the
8867 base classes are determined. Then, from all classes and their
8868 base classes, a graph is generated which is then rendered via
8869 the graphviz extension to a directed graph.
8870 This directive supports an option called parts that, if given,
8872 must be an integer, advising the directive to remove that many
8873 parts of module names from the displayed names. (For example,
8874 if all your class names start with lib., you can give :parts: 1
8875 to remove that prefix from the displayed node names.)
8876 It also supports a private-bases flag option; if given, private
8878 base classes (those whose name starts with _) will be included.
8879 You can use caption option to give a caption to the diagram.
8881 Changed in version 1.1: Added private-bases option; previously,
8883 all bases were always included.
8884 Changed in version 1.5: Added caption option
8887 It also supports a top-classes option which requires one or more
8890 class names separated by comma. If specified inheritance traver‐
8891 sal will stop at the specified class names. Given the following
8892 Python module:
8893 """
8895 A
8896 / \
8897 B C
8898 / \ / \
8899 E D F
8900 """
8901 class A(object):
8903 pass
8904 class B(A):
8906 pass
8907 class C(A):
8909 pass
8910 class D(B, C):
8912 pass
8913 class E(B):
8915 pass
8916 class F(C):
8918 pass
8919 If you have specified a module in the inheritance diagram like
8921 this:
8922 .. inheritance-diagram:: dummy.test
8924 :top-classes: dummy.test.B, dummy.test.C
8925 any base classes which are ancestors to top-classes and are also
8927 defined in the same module will be rendered as stand alone
8928 nodes. In this example class A will be rendered as stand alone
8929 node in the graph. This is a known issue due to how this exten‐
8930 sion works internally.
8931 If you don’t want class A (or any other ancestors) to be visible
8933 then specify only the classes you would like to generate the
8934 diagram for like this:
8935 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
8937 :top-classes: dummy.test.B, dummy.test.C
8938 Changed in version 1.7: Added top-classes option to limit the
8940 scope of inheritance graphs.
8941 Configuration
8944 inheritance_graph_attrs
8945 A dictionary of graphviz graph attributes for inheritance dia‐
8946 grams.
8947 For example:
8949 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
8951 fontsize=14, ratio='compress')
8952 inheritance_node_attrs
8954 A dictionary of graphviz node attributes for inheritance dia‐
8955 grams.
8956 For example:
8958 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
8960 color='dodgerblue1', style='filled')
8961 inheritance_edge_attrs
8963 A dictionary of graphviz edge attributes for inheritance dia‐
8964 grams.
8965 inheritance_alias
8967 Allows mapping the full qualified name of the class to custom
8968 values (useful when exposing the underlying path of a class is
8969 not desirable, e.g. it’s a private class and should not be
8970 instantiated by the user).
8971 For example:
8973 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
8975 sphinx.ext.intersphinx – Link to other projects’ documentation
8977 New in version 0.5.
8978 This extension can generate automatic links to the documentation of
8981 objects in other projects.
8982 Usage is simple: whenever Sphinx encounters a cross-reference that has
8984 no matching target in the current documentation set, it looks for tar‐
8985 gets in the documentation sets configured in intersphinx_mapping. A
8986 reference like :py:class:`zipfile.ZipFile` can then link to the Python
8987 documentation for the ZipFile class, without you having to specify
8988 where it is located exactly.
8989 When using the “new” format (see below), you can even force lookup in a
8991 foreign set by prefixing the link target appropriately. A link like
8992 :ref:`comparison manual <python:comparisons>` will then link to the
8993 label “comparisons” in the doc set “python”, if it exists.
8994 Behind the scenes, this works as follows:
8996 · Each Sphinx HTML build creates a file named objects.inv that contains
8998 a mapping from object names to URIs relative to the HTML set’s root.
8999 · Projects using the Intersphinx extension can specify the location of
9001 such mapping files in the intersphinx_mapping config value. The map‐
9002 ping will then be used to resolve otherwise missing references to
9003 objects into links to the other documentation.
9004 · By default, the mapping file is assumed to be at the same location as
9006 the rest of the documentation; however, the location of the mapping
9007 file can also be specified individually, e.g. if the docs should be
9008 buildable without Internet access.
9009 Configuration
9011 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
9012 sions config value, and use these new config values to activate link‐
9013 ing:
9014 intersphinx_mapping
9016 This config value contains the locations and names of other
9017 projects that should be linked to in this documentation.
9018 Relative local paths for target locations are taken as relative
9020 to the base of the built documentation, while relative local
9021 paths for inventory locations are taken as relative to the
9022 source directory.
9023 When fetching remote inventory files, proxy settings will be
9025 read from the $HTTP_PROXY environment variable.
9026 Old format for this config value
9028 This is the format used before Sphinx 1.0. It is still recog‐
9030 nized.
9031 A dictionary mapping URIs to either None or an URI. The keys
9033 are the base URI of the foreign Sphinx documentation sets and
9034 can be local paths or HTTP URIs. The values indicate where the
9035 inventory file can be found: they can be None (at the same loca‐
9036 tion as the base URI) or another local or HTTP URI.
9037 New format for this config value
9039 New in version 1.0.
9041 A dictionary mapping unique identifiers to a tuple (target,
9044 inventory). Each target is the base URI of a foreign Sphinx
9045 documentation set and can be a local path or an HTTP URI. The
9046 inventory indicates where the inventory file can be found: it
9047 can be None (at the same location as the base URI) or another
9048 local or HTTP URI.
9049 The unique identifier can be used to prefix cross-reference tar‐
9051 gets, so that it is clear which intersphinx set the target
9052 belongs to. A link like :ref:`comparison manual <python:compar‐
9053 isons>` will link to the label “comparisons” in the doc set
9054 “python”, if it exists.
9055 Example
9057 To add links to modules and objects in the Python standard
9059 library documentation, use:
9060 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
9062 This will download the corresponding objects.inv file from the
9064 Internet and generate links to the pages under the given URI.
9065 The downloaded inventory is cached in the Sphinx environment, so
9066 it must be re-downloaded whenever you do a full rebuild.
9067 A second example, showing the meaning of a non-None value of the
9069 second tuple item:
9070 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9072 'python-inv.txt')}
9073 This will read the inventory from python-inv.txt in the source
9075 directory, but still generate links to the pages under
9076 https://docs.python.org/3. It is up to you to update the inven‐
9077 tory file as new objects are added to the Python documentation.
9078 Multiple target for the inventory
9080 New in version 1.3.
9082 Alternative files can be specified for each inventory. One can
9085 give a tuple for the second inventory tuple item as shown in the
9086 following example. This will read the inventory iterating
9087 through the (second) tuple items until the first successful
9088 fetch. The primary use case for this to specify mirror sites for
9089 server downtime of the primary inventory:
9090 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9092 (None, 'python-inv.txt'))}
9093 intersphinx_cache_limit
9095 The maximum number of days to cache remote inventories. The
9096 default is 5, meaning five days. Set this to a negative value
9097 to cache inventories for unlimited time.
9098 intersphinx_timeout
9100 The number of seconds for timeout. The default is None, meaning
9101 do not timeout.
9102 NOTE:
9104 timeout is not a time limit on the entire response download;
9105 rather, an exception is raised if the server has not issued a
9106 response for timeout seconds.
9107 Showing all links of an Intersphinx mapping file
9109 To show all Intersphinx links and their targets of an Intersphinx map‐
9110 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
9111 helpful when searching for the root cause of a broken Intersphinx link
9112 in a documentation project. The following example prints the Inter‐
9113 sphinx mapping of the Python 3 documentation:
9114 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
9116 sphinx.ext.linkcode – Add external links to source code
9118 Module author: Pauli Virtanen
9119 New in version 1.2.
9121 This extension looks at your object descriptions (.. class::, .. func‐
9124 tion:: etc.) and adds external links to code hosted somewhere on the
9125 web. The intent is similar to the sphinx.ext.viewcode extension, but
9126 assumes the source code can be found somewhere on the Internet.
9127 In your configuration, you need to specify a linkcode_resolve function
9129 that returns an URL based on the object.
9130 Configuration
9132 linkcode_resolve
9133 This is a function linkcode_resolve(domain, info), which should
9134 return the URL to source code corresponding to the object in
9135 given domain with given information.
9136 The function should return None if no link is to be added.
9138 The argument domain specifies the language domain the object is
9140 in. info is a dictionary with the following keys guaranteed to
9141 be present (dependent on the domain):
9142 · py: module (name of the module), fullname (name of the object)
9144 · c: names (list of names for the object)
9146 · cpp: names (list of names for the object)
9148 · javascript: object (name of the object), fullname (name of the
9150 item)
9151 Example:
9153 def linkcode_resolve(domain, info):
9155 if domain != 'py':
9156 return None
9157 if not info['module']:
9158 return None
9159 filename = info['module'].replace('.', '/')
9160 return "https://somesite/sourcerepo/%s.py" % filename
9161 Math support for HTML outputs in Sphinx
9163 New in version 0.5.
9164 Changed in version 1.8: Math support for non-HTML builders is inte‐
9167 grated to sphinx-core. So mathbase extension is no longer needed.
9168 Since mathematical notation isn’t natively supported by HTML in any
9171 way, Sphinx gives a math support to HTML document with several exten‐
9172 sions.
9173 sphinx.ext.imgmath – Render math as images
9175 New in version 1.4.
9176 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
9179 SVG images. This of course means that the computer where the docs are
9180 built must have both programs available.
9181 There are various config values you can set to influence how the images
9183 are built:
9184 imgmath_image_format
9186 The output image format. The default is 'png'. It should be
9187 either 'png' or 'svg'.
9188 imgmath_latex
9190 The command name with which to invoke LaTeX. The default is
9191 'latex'; you may need to set this to a full path if latex is not
9192 in the executable search path.
9193 Since this setting is not portable from system to system, it is
9195 normally not useful to set it in conf.py; rather, giving it on
9196 the sphinx-build command line via the -D option should be
9197 preferable, like this:
9198 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
9200 This value should only contain the path to the latex executable,
9202 not further arguments; use imgmath_latex_args for that purpose.
9203 imgmath_dvipng
9205 The command name with which to invoke dvipng. The default is
9206 'dvipng'; you may need to set this to a full path if dvipng is
9207 not in the executable search path. This option is only used when
9208 imgmath_image_format is set to 'png'.
9209 imgmath_dvisvgm
9211 The command name with which to invoke dvisvgm. The default is
9212 'dvisvgm'; you may need to set this to a full path if dvisvgm is
9213 not in the executable search path. This option is only used
9214 when imgmath_image_format is 'svg'.
9215 imgmath_latex_args
9217 Additional arguments to give to latex, as a list. The default
9218 is an empty list.
9219 imgmath_latex_preamble
9221 Additional LaTeX code to put into the preamble of the short
9222 LaTeX files that are used to translate the math snippets. This
9223 is empty by default. Use it e.g. to add more packages whose
9224 commands you want to use in the math.
9225 imgmath_dvipng_args
9227 Additional arguments to give to dvipng, as a list. The default
9228 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
9229 which makes the image a bit darker and larger then it is by
9230 default, and produces PNGs with a transparent background. This
9231 option is used only when imgmath_image_format is 'png'.
9232 imgmath_dvisvgm_args
9234 Additional arguments to give to dvisvgm, as a list. The default
9235 value is ['--no-fonts']. This option is used only when img‐
9236 math_image_format is 'svg'.
9237 imgmath_use_preview
9239 dvipng has the ability to determine the “depth” of the rendered
9240 text: for example, when typesetting a fraction inline, the base‐
9241 line of surrounding text should not be flush with the bottom of
9242 the image, rather the image should extend a bit below the base‐
9243 line. This is what TeX calls “depth”. When this is enabled,
9244 the images put into the HTML document will get a vertical-align
9245 style that correctly aligns the baselines.
9246 Unfortunately, this only works when the preview-latex package is
9248 installed. Therefore, the default for this option is False.
9249 Currently this option is only used when imgmath_image_format is
9251 'png'.
9252 imgmath_add_tooltips
9254 Default: True. If false, do not add the LaTeX code as an “alt”
9255 attribute for math images.
9256 imgmath_font_size
9258 The font size (in pt) of the displayed math. The default value
9259 is 12. It must be a positive integer.
9260 sphinx.ext.mathjax – Render math via JavaScript
9262 New in version 1.1.
9263 This extension puts math as-is into the HTML files. The JavaScript
9266 package MathJax is then loaded and transforms the LaTeX markup to read‐
9267 able math live in the browser.
9268 Because MathJax (and the necessary fonts) is very large, it is not
9270 included in Sphinx.
9271 mathjax_path
9273 The path to the JavaScript file to include in the HTML files in
9274 order to load MathJax.
9275 The default is the https:// URL that loads the JS files from the
9277 cdnjs Content Delivery Network. See the MathJax Getting Started
9278 page for details. If you want MathJax to be available offline,
9279 you have to download it and set this value to a different path.
9280 The path can be absolute or relative; if it is relative, it is
9282 relative to the _static directory of the built docs.
9283 For example, if you put MathJax into the static path of the
9285 Sphinx docs, this value would be MathJax/MathJax.js. If you
9286 host more than one Sphinx documentation set on one server, it is
9287 advisable to install MathJax in a shared location.
9288 You can also give a full https:// URL different from the CDN
9290 URL.
9291 mathjax_options
9293 The options to script tag for mathjax. For example, you can set
9294 integrity option with following setting:
9295 mathjax_options = {
9297 'integrity': 'sha384-......',
9298 }
9299 The default is empty ({}).
9301 mathjax_config
9303 The inline configuration options for mathjax. The value is used
9304 as a parameter of MathJax.Hub.Config(). For more information,
9305 please read Using in-line configuration options.
9306 For example:
9308 mathjax_config = {
9310 'extensions': ['tex2jax.js'],
9311 'jax': ['input/TeX', 'output/HTML-CSS'],
9312 }
9313 The default is empty (not configured).
9315 sphinx.ext.jsmath – Render math via JavaScript
9317 This extension works just as the MathJax extension does, but uses the
9318 older package jsMath. It provides this config value:
9319 jsmath_path
9321 The path to the JavaScript file to include in the HTML files in
9322 order to load JSMath. There is no default.
9323 The path can be absolute or relative; if it is relative, it is
9325 relative to the _static directory of the built docs.
9326 For example, if you put JSMath into the static path of the
9328 Sphinx docs, this value would be jsMath/easy/load.js. If you
9329 host more than one Sphinx documentation set on one server, it is
9330 advisable to install jsMath in a shared location.
9331 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
9333 Module author: Rob Ruana
9334 New in version 1.3.
9336 Overview
9339 Are you tired of writing docstrings that look like this:
9340 :param path: The path of the file to wrap
9342 :type path: str
9343 :param field_storage: The :class:`FileStorage` instance to wrap
9344 :type field_storage: FileStorage
9345 :param temporary: Whether or not to delete the file when the File
9346 instance is destructed
9347 :type temporary: bool
9348 :returns: A buffered writable file descriptor
9349 :rtype: BufferedFileStorage
9350 reStructuredText is great, but it creates visually dense, hard to read
9352 docstrings. Compare the jumble above to the same thing rewritten
9353 according to the Google Python Style Guide:
9354 Args:
9356 path (str): The path of the file to wrap
9357 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
9358 temporary (bool): Whether or not to delete the file when the File
9359 instance is destructed
9360 Returns:
9362 BufferedFileStorage: A buffered writable file descriptor
9363 Much more legible, no?
9365 Napoleon is a extension that enables Sphinx to parse both NumPy and
9367 Google style docstrings - the style recommended by Khan Academy.
9368 Napoleon is a pre-processor that parses NumPy and Google style doc‐
9370 strings and converts them to reStructuredText before Sphinx attempts to
9371 parse them. This happens in an intermediate step while Sphinx is pro‐
9372 cessing the documentation, so it doesn’t modify any of the docstrings
9373 in your actual source code files.
9374 Getting Started
9376 1. After setting up Sphinx to build your docs, enable napoleon in the
9377 Sphinx conf.py file:
9378 # conf.py
9380 # Add napoleon to the extensions list
9382 extensions = ['sphinx.ext.napoleon']
9383 2. Use sphinx-apidoc to build your API documentation:
9385 $ sphinx-apidoc -f -o docs/source projectdir
9387 Docstrings
9389 Napoleon interprets every docstring that autodoc can find, including
9390 docstrings on: modules, classes, attributes, methods, functions, and
9391 variables. Inside each docstring, specially formatted Sections are
9392 parsed and converted to reStructuredText.
9393 All standard reStructuredText formatting still works as expected.
9395 Docstring Sections
9397 All of the following section headers are supported:
9398 · Args (alias of Parameters)
9400 · Arguments (alias of Parameters)
9402 · Attention
9404 · Attributes
9406 · Caution
9408 · Danger
9410 · Error
9412 · Example
9414 · Examples
9416 · Hint
9418 · Important
9420 · Keyword Args (alias of Keyword Arguments)
9422 · Keyword Arguments
9424 · Methods
9426 · Note
9428 · Notes
9430 · Other Parameters
9432 · Parameters
9434 · Return (alias of Returns)
9436 · Returns
9438 · Raises
9440 · References
9442 · See Also
9444 · Tip
9446 · Todo
9448 · Warning
9450 · Warnings (alias of Warning)
9452 · Warns
9454 · Yield (alias of Yields)
9456 · Yields
9458 Google vs NumPy
9460 Napoleon supports two styles of docstrings: Google and NumPy. The main
9461 difference between the two styles is that Google uses indentation to
9462 separate sections, whereas NumPy uses underlines.
9463 Google style:
9465 def func(arg1, arg2):
9467 """Summary line.
9468 Extended description of function.
9470 Args:
9472 arg1 (int): Description of arg1
9473 arg2 (str): Description of arg2
9474 Returns:
9476 bool: Description of return value
9477 """
9479 return True
9480 NumPy style:
9482 def func(arg1, arg2):
9484 """Summary line.
9485 Extended description of function.
9487 Parameters
9489 ----------
9490 arg1 : int
9491 Description of arg1
9492 arg2 : str
9493 Description of arg2
9494 Returns
9496 -------
9497 bool
9498 Description of return value
9499 """
9501 return True
9502 NumPy style tends to require more vertical space, whereas Google style
9504 tends to use more horizontal space. Google style tends to be easier to
9505 read for short and simple docstrings, whereas NumPy style tends be eas‐
9506 ier to read for long and in-depth docstrings.
9507 The Khan Academy recommends using Google style.
9509 The choice between styles is largely aesthetic, but the two styles
9511 should not be mixed. Choose one style for your project and be consis‐
9512 tent with it.
9513 SEE ALSO:
9515 For complete examples:
9516 · example_google
9518 · example_numpy
9520 Type Annotations
9522 PEP 484 introduced a standard way to express types in Python code.
9523 This is an alternative to expressing types directly in docstrings. One
9524 benefit of expressing types according to PEP 484 is that type checkers
9525 and IDEs can take advantage of them for static code analysis.
9526 Google style with Python 3 type annotations:
9528 def func(arg1: int, arg2: str) -> bool:
9530 """Summary line.
9531 Extended description of function.
9533 Args:
9535 arg1: Description of arg1
9536 arg2: Description of arg2
9537 Returns:
9539 Description of return value
9540 """
9542 return True
9543 Google style with types in docstrings:
9545 def func(arg1, arg2):
9547 """Summary line.
9548 Extended description of function.
9550 Args:
9552 arg1 (int): Description of arg1
9553 arg2 (str): Description of arg2
9554 Returns:
9556 bool: Description of return value
9557 """
9559 return True
9560 NOTE:
9562 Python 2/3 compatible annotations aren’t currently supported by
9563 Sphinx and won’t show up in the docs.
9564 Configuration
9566 Listed below are all the settings used by napoleon and their default
9567 values. These settings can be changed in the Sphinx conf.py file. Make
9568 sure that “sphinx.ext.napoleon” is enabled in conf.py:
9569 # conf.py
9571 # Add any Sphinx extension module names here, as strings
9573 extensions = ['sphinx.ext.napoleon']
9574 # Napoleon settings
9576 napoleon_google_docstring = True
9577 napoleon_numpy_docstring = True
9578 napoleon_include_init_with_doc = False
9579 napoleon_include_private_with_doc = False
9580 napoleon_include_special_with_doc = True
9581 napoleon_use_admonition_for_examples = False
9582 napoleon_use_admonition_for_notes = False
9583 napoleon_use_admonition_for_references = False
9584 napoleon_use_ivar = False
9585 napoleon_use_param = True
9586 napoleon_use_rtype = True
9587 napoleon_google_docstring
9589 True to parse Google style docstrings. False to disable support
9590 for Google style docstrings. Defaults to True.
9591 napoleon_numpy_docstring
9593 True to parse NumPy style docstrings. False to disable support
9594 for NumPy style docstrings. Defaults to True.
9595 napoleon_include_init_with_doc
9597 True to list __init___ docstrings separately from the class doc‐
9598 string. False to fall back to Sphinx’s default behavior, which
9599 considers the __init___ docstring as part of the class documen‐
9600 tation. Defaults to False.
9601 If True:
9603 def __init__(self):
9605 \"\"\"
9606 This will be included in the docs because it has a docstring
9607 \"\"\"
9608 def __init__(self):
9610 # This will NOT be included in the docs
9611 napoleon_include_private_with_doc
9613 True to include private members (like _membername) with doc‐
9614 strings in the documentation. False to fall back to Sphinx’s
9615 default behavior. Defaults to False.
9616 If True:
9618 def _included(self):
9620 """
9621 This will be included in the docs because it has a docstring
9622 """
9623 pass
9624 def _skipped(self):
9626 # This will NOT be included in the docs
9627 pass
9628 napoleon_include_special_with_doc
9630 True to include special members (like __membername__) with doc‐
9631 strings in the documentation. False to fall back to Sphinx’s
9632 default behavior. Defaults to True.
9633 If True:
9635 def __str__(self):
9637 """
9638 This will be included in the docs because it has a docstring
9639 """
9640 return unicode(self).encode('utf-8')
9641 def __unicode__(self):
9643 # This will NOT be included in the docs
9644 return unicode(self.__class__.__name__)
9645 napoleon_use_admonition_for_examples
9647 True to use the .. admonition:: directive for the Example and
9648 Examples sections. False to use the .. rubric:: directive
9649 instead. One may look better than the other depending on what
9650 HTML theme is used. Defaults to False.
9651 This NumPy style snippet will be converted as follows:
9653 Example
9655 -------
9656 This is just a quick example
9657 If True:
9659 .. admonition:: Example
9661 This is just a quick example
9663 If False:
9665 .. rubric:: Example
9667 This is just a quick example
9669 napoleon_use_admonition_for_notes
9671 True to use the .. admonition:: directive for Notes sections.
9672 False to use the .. rubric:: directive instead. Defaults to
9673 False.
9674 NOTE:
9676 The singular Note section will always be converted to a ..
9677 note:: directive.
9678 SEE ALSO:
9680 napoleon_use_admonition_for_examples
9681 napoleon_use_admonition_for_references
9683 True to use the .. admonition:: directive for References sec‐
9684 tions. False to use the .. rubric:: directive instead. Defaults
9685 to False.
9686 SEE ALSO:
9688 napoleon_use_admonition_for_examples
9689 napoleon_use_ivar
9691 True to use the :ivar: role for instance variables. False to use
9692 the .. attribute:: directive instead. Defaults to False.
9693 This NumPy style snippet will be converted as follows:
9695 Attributes
9697 ----------
9698 attr1 : int
9699 Description of `attr1`
9700 If True:
9702 :ivar attr1: Description of `attr1`
9704 :vartype attr1: int
9705 If False:
9707 .. attribute:: attr1
9709 *int*
9711 Description of `attr1`
9713 napoleon_use_param
9715 True to use a :param: role for each function parameter. False to
9716 use a single :parameters: role for all the parameters. Defaults
9717 to True.
9718 This NumPy style snippet will be converted as follows:
9720 Parameters
9722 ----------
9723 arg1 : str
9724 Description of `arg1`
9725 arg2 : int, optional
9726 Description of `arg2`, defaults to 0
9727 If True:
9729 :param arg1: Description of `arg1`
9731 :type arg1: str
9732 :param arg2: Description of `arg2`, defaults to 0
9733 :type arg2: int, optional
9734 If False:
9736 :parameters: * **arg1** (*str*) --
9738 Description of `arg1`
9739 * **arg2** (*int, optional*) --
9740 Description of `arg2`, defaults to 0
9741 napoleon_use_keyword
9743 True to use a :keyword: role for each function keyword argument.
9744 False to use a single :keyword arguments: role for all the key‐
9745 words. Defaults to True.
9746 This behaves similarly to napoleon_use_param. Note unlike docu‐
9748 tils, :keyword: and :param: will not be treated the same way -
9749 there will be a separate “Keyword Arguments” section, rendered
9750 in the same fashion as “Parameters” section (type links created
9751 if possible)
9752 SEE ALSO:
9754 napoleon_use_param
9755 napoleon_use_rtype
9757 True to use the :rtype: role for the return type. False to out‐
9758 put the return type inline with the description. Defaults to
9759 True.
9760 This NumPy style snippet will be converted as follows:
9762 Returns
9764 -------
9765 bool
9766 True if successful, False otherwise
9767 If True:
9769 :returns: True if successful, False otherwise
9771 :rtype: bool
9772 If False:
9774 :returns: *bool* -- True if successful, False otherwise
9776 sphinx.ext.todo – Support for todo items
9778 Module author: Daniel Bültmann
9779 New in version 0.5.
9781 There are two additional directives when using this extension:
9784 .. todo::
9786 Use this directive like, for example, note.
9787 It will only show up in the output if todo_include_todos is
9789 True.
9790 New in version 1.3.2: This directive supports an class option
9792 that determines the class attribute for HTML output. If not
9793 given, the class defaults to admonition-todo.
9794 .. todolist::
9797 This directive is replaced by a list of all todo directives in
9798 the whole documentation, if todo_include_todos is True.
9799 These can be configured as seen below.
9801 Configuration
9803 todo_include_todos
9804 If this is True, todo and todolist produce output, else they
9805 produce nothing. The default is False.
9806 todo_emit_warnings
9808 If this is True, todo emits a warning for each TODO entries.
9809 The default is False.
9810 New in version 1.5.
9812 todo_link_only
9815 If this is True, todolist produce output without file path and
9816 line, The default is False.
9817 New in version 1.4.
9819 autodoc provides the following an additional event:
9822 todo-defined(app, node)
9824 New in version 1.5.
9825 Emitted when a todo is defined. node is the defined
9828 sphinx.ext.todo.todo_node node.
9829 sphinx.ext.viewcode – Add links to highlighted source code
9831 Module author: Georg Brandl
9832 New in version 1.0.
9834 This extension looks at your Python object descriptions (.. class::, ..
9837 function:: etc.) and tries to find the source files where the objects
9838 are contained. When found, a separate HTML page will be output for
9839 each module with a highlighted version of the source code, and a link
9840 will be added to all object descriptions that leads to the source code
9841 of the described object. A link back from the source to the descrip‐
9842 tion will also be inserted.
9843 WARNING:
9845 Basically, viewcode extension will import the modules being linked
9846 to. If any modules have side effects on import, these will be exe‐
9847 cuted when sphinx-build is run.
9848 If you document scripts (as opposed to library modules), make sure
9850 their main routine is protected by a if __name__ == '__main__' con‐
9851 dition.
9852 In addition, if you don’t want to import the modules by viewcode,
9854 you can tell the location of the location of source code to viewcode
9855 using the viewcode-find-source event.
9856 If viewcode_follow_imported_members is enabled, you will also need
9858 to resolve imported attributes using the viewcode-follow-imported
9859 event.
9860 This extension works only on HTML related builders like html, apple‐
9862 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
9863 epub builder doesn’t support this extension (see viewcode_enable_epub).
9864 Configuration
9866 viewcode_follow_imported_members
9867 If this is True, viewcode extension will follow alias objects
9868 that imported from another module such as functions, classes and
9869 attributes. As side effects, this option else they produce
9870 nothing. The default is True.
9871 New in version 1.3.
9873 Changed in version 1.8: Renamed from viewcode_import to view‐
9876 code_follow_imported_members.
9877 viewcode_enable_epub
9880 If this is True, viewcode extension is also enabled even if you
9881 use epub builders. This extension generates pages outside toc‐
9882 tree, but this is not preferred as epub format.
9883 Until 1.4.x, this extension is always enabled. If you want to
9885 generate epub as same as 1.4.x, you should set True, but epub
9886 format checker’s score becomes worse.
9887 The default is False.
9889 New in version 1.5.
9891 WARNING:
9894 Not all epub readers support pages generated by viewcode
9895 extension. These readers ignore links to pages are not under
9896 toctree.
9897 Some reader’s rendering result are corrupted and epubcheck’s
9899 score becomes worse even if the reader supports.
9900 viewcode-find-source(app, modname)
9902 New in version 1.8.
9903 Find the source code for a module. An event handler for this
9906 event should return a tuple of the source code itself and a dic‐
9907 tionary of tags. The dictionary maps the name of a class, func‐
9908 tion, attribute, etc to a tuple of its type, the start line num‐
9909 ber, and the end line number. The type should be one of
9910 “class”, “def”, or “other”.
9911 Parameters
9913 · app – The Sphinx application object.
9915 · modname – The name of the module to find source code
9917 for.
9918 viewcode-follow-imported(app, modname, attribute)
9920 New in version 1.8.
9921 Find the name of the original module for an attribute.
9924 Parameters
9926 · app – The Sphinx application object.
9928 · modname – The name of the module that the attribute
9930 belongs to.
9931 · attribute – The name of the member to follow.
9933 Third-party extensions
9935 Todo
9936 This should reference the GitHub organization now
9937 You can find several extensions contributed by users in the Sphinx Con‐
9939 trib repository. It is open for anyone who wants to maintain an exten‐
9940 sion publicly; just send a short message asking for write permissions.
9941 There are also several extensions hosted elsewhere. The Sphinx exten‐
9943 sion survey and awesome-sphinxdoc contains a comprehensive list.
9944 If you write an extension that you think others will find useful or you
9946 think should be included as a part of Sphinx, please write to the
9947 project mailing list (join here).
9948 Where to put your own extensions?
9950 Extensions local to a project should be put within the project’s direc‐
9951 tory structure. Set Python’s module search path, sys.path, accordingly
9952 so that Sphinx can find them. For example, if your extension foo.py
9953 lies in the exts subdirectory of the project root, put into conf.py:
9954 import sys, os
9956 sys.path.append(os.path.abspath('exts'))
9958 extensions = ['foo']
9960 You can also install extensions anywhere else on sys.path, e.g. in the
9962 site-packages directory.
9963
9965 This is the documentation for the Sphinx documentation builder. Sphinx
9966 is a tool that translates a set of reStructuredText source files into
9967 various output formats, automatically producing cross-references,
9968 indices, etc. That is, if you have a directory containing a bunch of
9969 reST-formatted documents (and possibly subdirectories of docs in there
9970 as well), Sphinx can generate a nicely-organized arrangement of HTML
9971 files (in some other directory) for easy browsing and navigation. But
9972 from the same source, it can also generate a PDF file using LaTeX.
9973 The focus is on hand-written documentation, rather than auto-generated
9975 API docs. Though there is support for that kind of documentation as
9976 well (which is intended to be freely mixed with hand-written content),
9977 if you need pure API docs have a look at Epydoc, which also understands
9978 reST.
9979 For a great “introduction” to writing docs in general – the whys and
9981 hows, see also Write the docs, written by Eric Holscher.
9982 Conversion from other systems
9984 This section is intended to collect helpful hints for those wanting to
9985 migrate to reStructuredText/Sphinx from other documentation systems.
9986 · Gerard Flanagan has written a script to convert pure HTML to reST; it
9988 can be found at the Python Package Index.
9989 · For converting the old Python docs to Sphinx, a converter was written
9991 which can be found at the Python SVN repository. It contains generic
9992 code to convert Python-doc-style LaTeX markup to Sphinx reST.
9993 · Marcin Wojdyr has written a script to convert Docbook to reST with
9995 Sphinx markup; it is at GitHub.
9996 · Christophe de Vienne wrote a tool to convert from Open/LibreOffice
9998 documents to Sphinx: odt2sphinx.
9999 · To convert different markups, Pandoc is a very helpful tool.
10001 Use with other systems
10003 See the pertinent section in the FAQ list.
10004 Prerequisites
10006 Sphinx needs at least Python 2.7 or Python 3.4 to run, as well as the
10007 docutils and Jinja2 libraries. Sphinx should work with docutils ver‐
10008 sion 0.10 or some (not broken) SVN trunk snapshot. If you like to have
10009 source code highlighting support, you must also install the Pygments
10010 library.
10011 Usage
10013 See /usage/quickstart for an introduction. It also contains links to
10014 more advanced sections in this manual for the topics it discusses.
10015
10017 These are the applications provided as part of Sphinx.
10018 Core Applications
10020 sphinx-quickstart
10021 Synopsis
10022 sphinx-quickstart
10023 Description
10025 sphinx-quickstart is an interactive tool that asks some questions about
10026 your project and then generates a complete documentation directory and
10027 sample Makefile to be used with sphinx-build(1).
10028 Options
10030 -q, --quiet
10031 Quiet mode that will skip interactive wizard to specify options.
10032 This option requires -p, -a and -v options.
10033 -h, --help, --version
10035 Display usage summary or Sphinx version.
10036 Structure Options.INDENT 0.0
10037 --sep If specified, separate source and build directories.
10039 --dot=DOT
10041 Inside the root directory, two more directories will be created;
10042 “_templates” for custom HTML templates and “_static” for custom
10043 stylesheets and other static files. You can enter another prefix
10044 (such as “.”) to replace the underscore.
10045 Project Basic Options.INDENT 0.0
10046 -p PROJECT, --project=PROJECT
10048 Project name will be set. (see project).
10049 -a AUTHOR, --author=AUTHOR
10051 Author names. (see copyright).
10052 -v VERSION
10054 Version of project. (see version).
10055 -r RELEASE, --release=RELEASE
10057 Release of project. (see release).
10058 -l LANGUAGE, --language=LANGUAGE
10060 Document language. (see language).
10061 --suffix=SUFFIX
10063 Source file suffix. (see source_suffix).
10064 --master=MASTER
10066 Master document name. (see master_doc).
10067 --epub Use epub.
10069 Extension Options.INDENT 0.0
10070 --ext-autodoc
10072 Enable sphinx.ext.autodoc extension.
10073 --ext-doctest
10075 Enable sphinx.ext.doctest extension.
10076 --ext-intersphinx
10078 Enable sphinx.ext.intersphinx extension.
10079 --ext-todo
10081 Enable sphinx.ext.todo extension.
10082 --ext-coverage
10084 Enable sphinx.ext.coverage extension.
10085 --ext-imgmath
10087 Enable sphinx.ext.imgmath extension.
10088 --ext-mathjax
10090 Enable sphinx.ext.mathjax extension.
10091 --ext-ifconfig
10093 Enable sphinx.ext.ifconfig extension.
10094 --ext-viewcode
10096 Enable sphinx.ext.viewcode extension.
10097 --ext-githubpages
10099 Enable sphinx.ext.githubpages extension.
10100 --extensions=EXTENSIONS
10102 Enable arbitrary extensions.
10103 Makefile and Batchfile Creation Options.INDENT 0.0
10104 --use-make-mode (-m), --no-use-make-mode (-M)
10106 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
10107 use, which generates a more concise Makefile/make.bat.
10108 Changed in version 1.5: make-mode is default.
10110 --makefile, --no-makefile
10113 Create (or not create) makefile.
10114 --batchfile, --no-batchfile
10116 Create (or not create) batchfile
10117 Project templating
10118 New in version 1.5: Project templating options for sphinx-quickstart
10120 -t, --templatedir=TEMPLATEDIR
10123 Template directory for template files. You can modify the tem‐
10124 plates of sphinx project files generated by quickstart. Follow‐
10125 ing Jinja2 template files are allowed:
10126 · master_doc.rst_t
10128 · conf.py_t
10130 · Makefile_t
10132 · Makefile.new_t
10134 · make.bat_t
10136 · make.bat.new_t
10138 In detail, please refer the system template files Sphinx pro‐
10140 vides. (sphinx/templates/quickstart)
10141 -d NAME=VALUE
10143 Define a template variable
10144 See also
10146 sphinx-build(1)
10147 sphinx-build
10149 Synopsis
10150 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
10151 Description
10153 sphinx-build generates documentation from the files in <sourcedir> and
10154 places it in the <outputdir>.
10155 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
10157 tings. sphinx-quickstart(1) may be used to generate template files,
10158 including conf.py.
10159 sphinx-build can create documentation in different formats. A format
10161 is selected by specifying the builder name on the command line; it
10162 defaults to HTML. Builders can also perform other tasks related to
10163 documentation processing.
10164 By default, everything that is outdated is built. Output only for
10166 selected files can be built by specifying individual filenames.
10167 For a list of available options, refer to sphinx-build -b.
10169 Options
10171 -b buildername
10172 The most important option: it selects a builder. The most com‐
10173 mon builders are:
10174 html Build HTML pages. This is the default builder.
10176 dirhtml
10178 Build HTML pages, but with a single directory per docu‐
10179 ment. Makes for prettier URLs (no .html) if served from
10180 a webserver.
10181 singlehtml
10183 Build a single HTML with the whole content.
10184 htmlhelp, qthelp, devhelp, epub
10186 Build HTML files with additional information for building
10187 a documentation collection in one of these formats.
10188 applehelp
10190 Build an Apple Help Book. Requires hiutil and codesign,
10191 which are not Open Source and presently only available on
10192 Mac OS X 10.6 and higher.
10193 latex Build LaTeX sources that can be compiled to a PDF docu‐
10195 ment using pdflatex.
10196 man Build manual pages in groff format for UNIX systems.
10198 texinfo
10200 Build Texinfo files that can be processed into Info files
10201 using makeinfo.
10202 text Build plain text files.
10204 gettext
10206 Build gettext-style message catalogs (.pot files).
10207 doctest
10209 Run all doctests in the documentation, if the doctest
10210 extension is enabled.
10211 linkcheck
10213 Check the integrity of all external links.
10214 xml Build Docutils-native XML files.
10216 pseudoxml
10218 Build compact pretty-printed “pseudo-XML” files display‐
10219 ing the internal structure of the intermediate document
10220 trees.
10221 See /usage/builders/index for a list of all builders shipped
10223 with Sphinx. Extensions can add their own builders.
10224 -M buildername
10226 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
10227 vides the same build functionality as a default Makefile or
10228 Make.bat. In addition to all Sphinx /usage/builders/index, the
10229 following build pipelines are available:
10230 latexpdf
10232 Build LaTeX files and run them through pdflatex, or as
10233 per latex_engine setting. If language is set to 'ja',
10234 will use automatically the platex/dvipdfmx latex to PDF
10235 pipeline.
10236 info Build Texinfo files and run them through makeinfo.
10238 IMPORTANT:
10240 Sphinx only recognizes the -M option if it is placed first.
10241 New in version 1.2.1.
10243 -a If given, always write all output files. The default is to only
10246 write output files for new and changed source files. (This may
10247 not apply to all builders.)
10248 -E Don’t use a saved environment (the structure caching all
10250 cross-references), but rebuild it completely. The default is to
10251 only read and parse source files that are new or have changed
10252 since the last run.
10253 -t tag Define the tag tag. This is relevant for only directives that
10255 only include their content if this tag is set.
10256 New in version 0.6.
10258 -d path
10261 Since Sphinx has to read and parse all source files before it
10262 can write an output file, the parsed source files are cached as
10263 “doctree pickles”. Normally, these files are put in a directory
10264 called .doctrees under the build directory; with this option you
10265 can select a different cache directory (the doctrees can be
10266 shared between all builders).
10267 -j N Distribute the build over N processes in parallel, to make
10269 building on multiprocessor machines more effective. Note that
10270 not all parts and not all builders of Sphinx can be paral‐
10271 lelized. If auto argument is given, Sphinx uses the number of
10272 CPUs as N.
10273 New in version 1.2: This option should be considered experimen‐
10275 tal.
10276 Changed in version 1.7: Support auto argument.
10279 -c path
10282 Don’t look for the conf.py in the source directory, but use the
10283 given configuration directory instead. Note that various other
10284 files and paths given by configuration values are expected to be
10285 relative to the configuration directory, so they will have to be
10286 present at this location too.
10287 New in version 0.3.
10289 -C Don’t look for a configuration file; only take options via the
10292 -D option.
10293 New in version 0.5.
10295 -D setting=value
10298 Override a configuration value set in the conf.py file. The
10299 value must be a number, string, list or dictionary value.
10300 For lists, you can separate elements with a comma like this: -D
10302 html_theme_path=path1,path2.
10303 For dictionary values, supply the setting name and key like
10305 this: -D latex_elements.docclass=scrartcl.
10306 For boolean values, use 0 or 1 as the value.
10308 Changed in version 0.6: The value can now be a dictionary value.
10310 Changed in version 1.3: The value can now also be a list value.
10313 -A name=value
10316 Make the name assigned to value in the HTML templates.
10317 New in version 0.5.
10319 -n Run in nit-picky mode. Currently, this generates warnings for
10322 all missing references. See the config value nitpick_ignore for
10323 a way to exclude some references as “known missing”.
10324 -N Do not emit colored output.
10326 -v Increase verbosity (loglevel). This option can be given up to
10328 three times to get more debug logging output. It implies -T.
10329 New in version 1.2.
10331 -q Do not output anything on standard output, only write warnings
10334 and errors to standard error.
10335 -Q Do not output anything on standard output, also suppress warn‐
10337 ings. Only errors are written to standard error.
10338 -w file
10340 Write warnings (and errors) to the given file, in addition to
10341 standard error.
10342 -W Turn warnings into errors. This means that the build stops at
10344 the first warning and sphinx-build exits with exit status 1.
10345 --keep-going
10347 With -W option, keep going processing when getting warnings to
10348 the end of build, and sphinx-build exits with exit status 1.
10349 New in version 1.8.
10351 -T Display the full traceback when an unhandled exception occurs.
10354 Otherwise, only a summary is displayed and the traceback infor‐
10355 mation is saved to a file for further analysis.
10356 New in version 1.2.
10358 -P (Useful for debugging only.) Run the Python debugger, pdb, if
10361 an unhandled exception occurs while building.
10362 -h, --help, --version
10364 Display usage summary or Sphinx version.
10365 New in version 1.2.
10367 You can also give one or more filenames on the command line after the
10370 source and build directories. Sphinx will then try to build only these
10371 output files (and their dependencies).
10372 Environment Variables
10374 The sphinx-build refers following environment variables:
10375 MAKE A path to make command. A command name is also allowed.
10377 sphinx-build uses it to invoke sub-build process on make-mode.
10378 Makefile Options
10379 The Makefile and make.bat files created by sphinx-quickstart usually
10381 run sphinx-build only with the -b and -d options. However, they sup‐
10382 port the following variables to customize behavior:
10383 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
10385 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
10386 NOTE:
10388 Usage of this environment variable got broken at Sphinx 1.5
10389 as a4 or letter ended up as option to LaTeX document in place
10390 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
10391 SPHINXBUILD
10393 The command to use instead of sphinx-build.
10394 BUILDDIR
10396 The build directory to use instead of the one chosen in
10397 sphinx-quickstart.
10398 SPHINXOPTS
10400 Additional options for sphinx-build.
10401 Deprecation Warnings
10403 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
10404 when building a user’s document, some Sphinx extension is using depre‐
10405 cated features. In that case, please report it to author of the exten‐
10406 sion.
10407 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
10409 ronment variable to your environment. For example:
10410 · PYTHONWARNINGS= make html (Linux/Mac)
10412 · export PYTHONWARNINGS= and do make html (Linux/Mac)
10414 · set PYTHONWARNINGS= and do make html (Windows)
10416 · modify your Makefile/make.bat and set the environment variable
10418 See also
10420 sphinx-quickstart(1)
10421 Additional Applications
10423 sphinx-apidoc
10424 Synopsis
10425 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PAT‐
10426 TERN, …]
10427 Description
10429 sphinx-apidoc is a tool for automatic generation of Sphinx sources
10430 that, using the autodoc extension, document a whole package in the
10431 style of other automatic API documentation tools.
10432 MODULE_PATH is the path to a Python package to document, and OUT‐
10434 PUT_PATH is the directory where the generated sources are placed. Any
10435 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
10436 that will be excluded from generation.
10437 WARNING:
10439 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
10440 document all found modules. If any modules have side effects on
10441 import, these will be executed by autodoc when sphinx-build is run.
10442 If you document scripts (as opposed to library modules), make sure
10444 their main routine is protected by a if __name__ == '__main__' con‐
10445 dition.
10446 Options
10448 -o <OUTPUT_PATH>
10449 Directory to place the output files. If it does not exist, it is
10450 created.
10451 -f, --force
10453 Force overwriting of any existing generated files.
10454 -l, --follow-links
10456 Follow symbolic links.
10457 -n, --dry-run
10459 Do not create any files.
10460 -s <suffix>
10462 Suffix for the source files generated. Defaults to rst.
10463 -d <MAXDEPTH>
10465 Maximum depth for the generated table of contents file.
10466 --tocfile
10468 Filename for a table of contents file. Defaults to modules.
10469 -T, --no-toc
10471 Do not create a table of contents file. Ignored when --full is
10472 provided.
10473 -F, --full
10475 Generate a full Sphinx project (conf.py, Makefile etc.) using
10476 the same mechanism as sphinx-quickstart.
10477 -e, --separate
10479 Put documentation for each module on its own page.
10480 New in version 1.2.
10482 -E, --no-headings
10485 Do not create headings for the modules/packages. This is useful,
10486 for example, when docstrings already contain headings.
10487 -P, --private
10489 Include “_private” modules.
10490 New in version 1.2.
10492 --implicit-namespaces
10495 By default sphinx-apidoc processes sys.path searching for mod‐
10496 ules only. Python 3.3 introduced PEP 420 implicit namespaces
10497 that allow module path structures such as foo/bar/module.py or
10498 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
10499 not modules).
10500 Interpret paths recursively according to PEP-0420.
10502 -M, --module-first
10504 Put module documentation before submodule documentation.
10505 These options are used when --full is specified:
10507 -a Append module_path to sys.path.
10509 -H <project>
10511 Sets the project name to put in generated files (see project).
10512 -A <author>
10514 Sets the author name(s) to put in generated files (see copy‐
10515 right).
10516 -V <version>
10518 Sets the project version to put in generated files (see ver‐
10519 sion).
10520 -R <release>
10522 Sets the project release to put in generated files (see
10523 release).
10524 Environment
10526 SPHINX_APIDOC_OPTIONS
10527 A comma-separated list of option to append to generated automod‐
10528 ule directives. Defaults to members,undoc-members,show-inheri‐
10529 tance.
10530 See also
10532 sphinx-build(1), sphinx-autogen(1)
10533 sphinx-autogen
10535 Synopsis
10536 sphinx-autogen [options] <sourcefile> …
10537 Description
10539 sphinx-autogen is a tool for automatic generation of Sphinx sources
10540 that, using the autodoc extension, document items included in autosum‐
10541 mary listing(s).
10542 sourcefile is the path to one or more reStructuredText documents con‐
10544 taining autosummary entries with the :toctree:: option set. sourcefile
10545 can be an fnmatch-style pattern.
10546 Options
10548 -o <outputdir>
10549 Directory to place the output file. If it does not exist, it is
10550 created. Defaults to the value passed to the :toctree: option.
10551 -s <suffix>, --suffix <suffix>
10553 Default suffix to use for generated files. Defaults to rst.
10554 -t <templates>, --templates <templates>
10556 Custom template directory. Defaults to None.
10557 -i, --imported-members
10559 Document imported members.
10560 Example
10562 Given the following directory structure:
10563 docs
10565 ├── index.rst
10566 └── ...
10567 foobar
10568 ├── foo
10569 │ └── __init__.py
10570 └── bar
10571 ├── __init__.py
10572 └── baz
10573 └── __init__.py
10574 and assuming docs/index.rst contained the following:
10576 Modules
10578 =======
10579 .. autosummary::
10581 :toctree: modules
10582 foobar.foo
10584 foobar.bar
10585 foobar.bar.baz
10586 If you run the following:
10588 $ PYTHONPATH=. sphinx-autodoc doc/index.rst
10590 then the following stub files will be created in docs:
10592 docs
10594 ├── index.rst
10595 └── modules
10596 ├── foobar.bar.rst
10597 ├── foobar.bar.baz.rst
10598 └── foobar.foo.rst
10599 and each of those files will contain a autodoc directive and some other
10601 information.
10602 See also
10604 sphinx-build(1), sphinx-apidoc(1)
10605
10607 New in version 1.1.
10608 Complementary to translations provided for Sphinx-generated messages
10611 such as navigation bars, Sphinx provides mechanisms facilitating docu‐
10612 ment translations in itself. See the intl-options for details on con‐
10613 figuration.
10614 [image] Workflow visualization of translations in Sphinx. (The
10615 stick-figure is taken from an XKCD comic.).UNINDENT
10616 · Sphinx internationalization details
10618 · Translating with sphinx-intl
10620 · Quick guide
10622 · Translating
10624 · Update your po files by new pot files
10626 · Using Transifex service for team translation
10628 · Contributing to Sphinx reference translation
10630 Sphinx internationalization details
10632 gettext [1] is an established standard for internationalization and
10633 localization. It naively maps messages in a program to a translated
10634 string. Sphinx uses these facilities to translate whole documents.
10635 Initially project maintainers have to collect all translatable strings
10637 (also referred to as messages) to make them known to translators.
10638 Sphinx extracts these through invocation of sphinx-build -b gettext.
10639 Every single element in the doctree will end up in a single message
10641 which results in lists being equally split into different chunks while
10642 large paragraphs will remain as coarsely-grained as they were in the
10643 original document. This grants seamless document updates while still
10644 providing a little bit of context for translators in free-text pas‐
10645 sages. It is the maintainer’s task to split up paragraphs which are
10646 too large as there is no sane automated way to do that.
10647 After Sphinx successfully ran the MessageCatalogBuilder you will find a
10649 collection of .pot files in your output directory. These are catalog
10650 templates and contain messages in your original language only.
10651 They can be delivered to translators which will transform them to .po
10653 files — so called message catalogs — containing a mapping from the
10654 original messages to foreign-language strings.
10655 Gettext compiles them into a binary format known as binary catalogs
10657 through msgfmt for efficiency reasons. If you make these files discov‐
10658 erable with locale_dirs for your language, Sphinx will pick them up
10659 automatically.
10660 An example: you have a document usage.rst in your Sphinx project. The
10662 gettext builder will put its messages into usage.pot. Imagine you have
10663 Spanish translations [2] on your hands in usage.po — for your builds to
10664 be translated you need to follow these instructions:
10665 · Compile your message catalog to a locale directory, say locale, so it
10667 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
10668 (where es is the language code for Spanish.)
10669 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
10671 · Set locale_dirs to ["locale/"].
10673 · Set language to es (also possible via -D).
10675 · Run your desired build.
10677 Translating with sphinx-intl
10679 Quick guide
10680 sphinx-intl is a useful tool to work with Sphinx translation flow.
10681 This section describe an easy way to translate with sphinx-intl.
10682 1. Install sphinx-intl by pip install sphinx-intl or easy_install
10684 sphinx-intl.
10685 2. Add configurations to your conf.py:
10687 locale_dirs = ['locale/'] # path is example but recommended.
10689 gettext_compact = False # optional.
10690 This case-study assumes that locale_dirs is set to ‘locale/’ and
10692 gettext_compact is set to False (the Sphinx document is already con‐
10693 figured as such).
10694 3. Extract document’s translatable messages into pot files:
10696 $ make gettext
10698 As a result, many pot files are generated under _build/gettext
10700 directory.
10701 4. Setup/Update your locale_dir:
10703 $ sphinx-intl update -p _build/gettext -l de -l ja
10705 Done. You got these directories that contain po files:
10707 · ./locale/de/LC_MESSAGES/
10709 · ./locale/ja/LC_MESSAGES/
10711 5. Translate your po files under ./locale/<lang>/LC_MESSAGES/.
10713 6. make translated document.
10715 You need a language parameter in conf.py or you may also specify the
10717 parameter on the command line (for BSD/GNU make):
10718 $ make -e SPHINXOPTS="-D language='de'" html
10720 command line (for Windows cmd.exe):
10722 > set SPHINXOPTS=-D language=de
10724 > .\make.bat html
10725 command line (for PowerShell):
10727 > Set-Item env:SPHINXOPTS "-D language=de"
10729 > .\make.bat html
10730 Congratulations! You got the translated documentation in the
10732 _build/html directory.
10733 New in version 1.3: sphinx-build that is invoked by make command will
10735 build po files into mo files.
10736 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
10738 mand before make command.
10739 Translating
10742 Translate po file under ./locale/de/LC_MESSAGES directory. The case of
10743 builders.po file for sphinx document:
10744 # a5600c3d2e3d48fc8c261ea0284db79b
10746 #: ../../builders.rst:4
10747 msgid "Available builders"
10748 msgstr "<FILL HERE BY TARGET LANGUAGE>"
10749 Another case, msgid is multi-line text and contains reStructuredText
10751 syntax:
10752 # 302558364e1d41c69b3277277e34b184
10754 #: ../../builders.rst:9
10755 msgid ""
10756 "These are the built-in Sphinx builders. More builders can be added by "
10757 ":ref:`extensions <extensions>`."
10758 msgstr ""
10759 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
10760 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
10761 Please be careful not to break reST notation. Most po-editors will
10763 help you with that.
10764 Update your po files by new pot files
10766 If a document is updated, it is necessary to generate updated pot files
10767 and to apply differences to translated po files. In order to apply the
10768 updating difference of a pot file to po file, use the sphinx-intl
10769 update command.
10770 $ sphinx-intl update -p _build/locale
10772 Using Transifex service for team translation
10774 Transifex is one of several services that allow collaborative transla‐
10775 tion via a web interface. It has a nifty Python-based command line
10776 client that makes it easy to fetch and push translations.
10777 1. Install transifex-client
10779 You need tx command to upload resources (pot files).
10781 $ pip install transifex-client
10783 SEE ALSO:
10785 Transifex Client documentation
10786 2. Create your transifex account and create new project for your docu‐
10788 ment
10789 Currently, transifex does not allow for a translation project to
10791 have more than one version of the document, so you’d better include
10792 a version number in your project name.
10793 For example:
10795 Project ID
10797 sphinx-document-test_1_0
10798 Project URL
10800 https://www.transifex.com/projects/p/sphinx-docu‐
10801 ment-test_1_0/
10802 3. Create config files for tx command
10804 This process will create .tx/config in the current directory, as
10806 well as a ~/.transifexrc file that includes auth information.
10807 $ tx init
10809 Creating .tx folder...
10810 Transifex instance [https://www.transifex.com]:
10811 ...
10812 Please enter your transifex username: <transifex-username>
10813 Password: <transifex-password>
10814 ...
10815 Done.
10816 4. Upload pot files to transifex service
10818 Register pot files to .tx/config file:
10820 $ cd /your/document/root
10822 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
10823 --transifex-project-name sphinx-document-test_1_0
10824 and upload pot files:
10826 $ tx push -s
10828 Pushing translations for resource sphinx-document-test_1_0.builders:
10829 Pushing source file (locale/pot/builders.pot)
10830 Resource does not exist. Creating...
10831 ...
10832 Done.
10833 5. Forward the translation on transifex
10835 6. Pull translated po files and make translated html
10837 Get translated catalogs and build mo files (ex. for ‘de’):
10839 $ cd /your/document/root
10841 $ tx pull -l de
10842 Pulling translations for resource sphinx-document-test_1_0.builders (...)
10843 -> de: locale/de/LC_MESSAGES/builders.po
10844 ...
10845 Done.
10846 Invoke make html (for BSD/GNU make):
10848 $ make -e SPHINXOPTS="-D language='de'" html
10850 That’s all!
10852 TIP:
10854 Translating locally and on Transifex
10855 If you want to push all language’s po files, you can be done by
10857 using tx push -t command. Watch out! This operation overwrites
10858 translations in transifex.
10859 In other words, if you have updated each in the service and local po
10861 files, it would take much time and effort to integrate them.
10862 Contributing to Sphinx reference translation
10864 The recommended way for new contributors to translate Sphinx reference
10865 is to join the translation team on Transifex.
10866 There is sphinx translation page for Sphinx (master) documentation.
10868 1. Login to transifex service.
10870 2. Go to sphinx translation page.
10872 3. Click Request language and fill form.
10874 4. Wait acceptance by transifex sphinx translation maintainers.
10876 5. (after acceptance) translate on transifex.
10878
10880 [1] See the GNU gettext utilities for details on that software suite.
10881 [2] Because nobody expects the Spanish Inquisition!
10883
10885 New in version 0.6.
10886 Sphinx supports changing the appearance of its HTML output via themes.
10889 A theme is a collection of HTML templates, stylesheet(s) and other
10890 static files. Additionally, it has a configuration file which speci‐
10891 fies from which theme to inherit, which highlighting style to use, and
10892 what options exist for customizing the theme’s look and feel.
10893 Themes are meant to be project-unaware, so they can be used for differ‐
10895 ent projects without change.
10896 Using a theme
10898 Using an existing theme is easy. If the theme is builtin to Sphinx,
10899 you only need to set the html_theme config value. With the
10900 html_theme_options config value you can set theme-specific options that
10901 change the look and feel. For example, you could have the following in
10902 your conf.py:
10903 html_theme = "classic"
10905 html_theme_options = {
10906 "rightsidebar": "true",
10907 "relbarbgcolor": "black"
10908 }
10909 That would give you the classic theme, but with a sidebar on the right
10911 side and a black background for the relation bar (the bar with the nav‐
10912 igation links at the page’s top and bottom).
10913 If the theme does not come with Sphinx, it can be in two static forms:
10915 either a directory (containing theme.conf and other needed files), or a
10916 zip file with the same contents. Either of them must be put where
10917 Sphinx can find it; for this there is the config value html_theme_path.
10918 It gives a list of directories, relative to the directory containing
10919 conf.py, that can contain theme directories or zip files. For example,
10920 if you have a theme in the file blue.zip, you can put it right in the
10921 directory containing conf.py and use this configuration:
10922 html_theme = "blue"
10924 html_theme_path = ["."]
10925 The third form is a python package. If a theme you want to use is dis‐
10927 tributed as a python package, you can use it after installing
10928 # installing theme package
10930 $ pip install sphinxjp.themes.dotted
10931 # use it in your conf.py
10933 html_theme = "dotted"
10934 Builtin themes
10936 ┌───────────────────────────┬────────────────────────────┐
10937 │Theme overview │ │
10938 ├───────────────────────────┼────────────────────────────┤
10939 │[image: alabaster] [image] │ [image: classic] [image] │
10940 │ │ │
10941 │ │ │
10942 │alabaster │ classic │
10943 ├───────────────────────────┼────────────────────────────┤
10944 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
10945 │ │ │
10946 │ │ │
10947 │sphinxdoc │ scrolls │
10948 ├───────────────────────────┼────────────────────────────┤
10949 │[image: agogo] [image] │ [image: traditional] │
10950 │ │ [image] │
10951 │ │ │
10952 │agogo │ │
10953 │ │ traditional │
10954 ├───────────────────────────┼────────────────────────────┤
10955 │[image: nature] [image] │ [image: haiku] [image] │
10956 │ │ │
10957 │ │ │
10958 │nature │ haiku │
10959 ├───────────────────────────┼────────────────────────────┤
10960 │[image: pyramid] [image] │ [image: bizstyle] [image] │
10961 │ │ │
10962 │ │ │
10963 │pyramid │ bizstyle │
10964 └───────────────────────────┴────────────────────────────┘
10965 Sphinx comes with a selection of themes to choose from.
10967 These themes are:
10969 · basic – This is a basically unstyled layout used as the base for the
10971 other themes, and usable as the base for custom themes as well. The
10972 HTML contains all important elements like sidebar and relation bar.
10973 There are these options (which are inherited by the other themes):
10974 · nosidebar (true or false): Don’t include the sidebar. Defaults to
10976 False.
10977 · sidebarwidth (int or str): Width of the sidebar in pixels. This
10979 can be an int, which is interpreted as pixels or a valid CSS dimen‐
10980 sion string such as ‘70em’ or ‘50%’. Defaults to 230 pixels.
10981 · body_min_width (int or str): Minimal width of the document body.
10983 This can be an int, which is interpreted as pixels or a valid CSS
10984 dimension string such as ‘70em’ or ‘50%’. Use 0 if you don’t want a
10985 width limit. Defaults may depend on the theme (often 450px).
10986 · body_max_width (int or str): Maximal width of the document body.
10988 This can be an int, which is interpreted as pixels or a valid CSS
10989 dimension string such as ‘70em’ or ‘50%’. Use ‘none’ if you don’t
10990 want a width limit. Defaults may depend on the theme (often 800px).
10991 · alabaster – Alabaster theme is a modified “Kr” Sphinx theme from
10993 @kennethreitz (especially as used in his Requests project), which was
10994 itself originally based on @mitsuhiko’s theme used for Flask &
10995 related projects. Check out at its installation page how to set up
10996 properly html_sidebars for its use.
10997 · classic – This is the classic theme, which looks like the Python 2
10999 documentation. It can be customized via these options:
11000 · rightsidebar (true or false): Put the sidebar on the right side.
11002 Defaults to False.
11003 · stickysidebar (true or false): Make the sidebar “fixed” so that it
11005 doesn’t scroll out of view for long body content. This may not
11006 work well with all browsers. Defaults to False.
11007 · collapsiblesidebar (true or false): Add an experimental JavaScript
11009 snippet that makes the sidebar collapsible via a button on its
11010 side. Defaults to False.
11011 · externalrefs (true or false): Display external links differently
11013 from internal links. Defaults to False.
11014 There are also various color and font options that can change the
11016 color scheme without having to write a custom stylesheet:
11017 · footerbgcolor (CSS color): Background color for the footer line.
11019 · footertextcolor (CSS color): Text color for the footer line.
11021 · sidebarbgcolor (CSS color): Background color for the sidebar.
11023 · sidebarbtncolor (CSS color): Background color for the sidebar col‐
11025 lapse button (used when collapsiblesidebar is True).
11026 · sidebartextcolor (CSS color): Text color for the sidebar.
11028 · sidebarlinkcolor (CSS color): Link color for the sidebar.
11030 · relbarbgcolor (CSS color): Background color for the relation bar.
11032 · relbartextcolor (CSS color): Text color for the relation bar.
11034 · relbarlinkcolor (CSS color): Link color for the relation bar.
11036 · bgcolor (CSS color): Body background color.
11038 · textcolor (CSS color): Body text color.
11040 · linkcolor (CSS color): Body link color.
11042 · visitedlinkcolor (CSS color): Body color for visited links.
11044 · headbgcolor (CSS color): Background color for headings.
11046 · headtextcolor (CSS color): Text color for headings.
11048 · headlinkcolor (CSS color): Link color for headings.
11050 · codebgcolor (CSS color): Background color for code blocks.
11052 · codetextcolor (CSS color): Default text color for code blocks, if
11054 not set differently by the highlighting style.
11055 · bodyfont (CSS font-family): Font for normal text.
11057 · headfont (CSS font-family): Font for headings.
11059 · sphinxdoc – The theme originally used by this documentation. It fea‐
11061 tures a sidebar on the right side. There are currently no options
11062 beyond nosidebar and sidebarwidth.
11063 NOTE:
11065 The Sphinx documentation now uses an adjusted version of the
11066 sphinxdoc theme.
11067 · scrolls – A more lightweight theme, based on the Jinja documentation.
11069 The following color options are available:
11070 · headerbordercolor
11072 · subheadlinecolor
11074 · linkcolor
11076 · visitedlinkcolor
11078 · admonitioncolor
11080 · agogo – A theme created by Andi Albrecht. The following options are
11082 supported:
11083 · bodyfont (CSS font family): Font for normal text.
11085 · headerfont (CSS font family): Font for headings.
11087 · pagewidth (CSS length): Width of the page content, default 70em.
11089 · documentwidth (CSS length): Width of the document (without side‐
11091 bar), default 50em.
11092 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
11094 · bgcolor (CSS color): Background color.
11096 · headerbg (CSS value for “background”): background for the header
11098 area, default a grayish gradient.
11099 · footerbg (CSS value for “background”): background for the footer
11101 area, default a light gray gradient.
11102 · linkcolor (CSS color): Body link color.
11104 · headercolor1, headercolor2 (CSS color): colors for <h1> and <h2>
11106 headings.
11107 · headerlinkcolor (CSS color): Color for the backreference link in
11109 headings.
11110 · textalign (CSS text-align value): Text alignment for the body,
11112 default is justify.
11113 · nature – A greenish theme. There are currently no options beyond
11115 nosidebar and sidebarwidth.
11116 · pyramid – A theme from the Pyramid web framework project, designed by
11118 Blaise Laflamme. There are currently no options beyond nosidebar and
11119 sidebarwidth.
11120 · haiku – A theme without sidebar inspired by the Haiku OS user guide.
11122 The following options are supported:
11123 · full_logo (true or false, default False): If this is true, the
11125 header will only show the html_logo. Use this for large logos. If
11126 this is false, the logo (if present) will be shown floating right,
11127 and the documentation title will be put in the header.
11128 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlink‐
11130 color (CSS colors): Colors for various body elements.
11131 · traditional – A theme resembling the old Python documentation. There
11133 are currently no options beyond nosidebar and sidebarwidth.
11134 · epub – A theme for the epub builder. This theme tries to save visual
11136 space which is a sparse resource on ebook readers. The following
11137 options are supported:
11138 · relbar1 (true or false, default True): If this is true, the relbar1
11140 block is inserted in the epub output, otherwise it is omitted.
11141 · footer (true or false, default True): If this is true, the footer
11143 block is inserted in the epub output, otherwise it is omitted.
11144 · bizstyle – A simple bluish theme. The following options are supported
11146 beyond nosidebar and sidebarwidth:
11147 · rightsidebar (true or false): Put the sidebar on the right side.
11149 Defaults to False.
11150 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
11152 theme.
11153 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
11156 sic’. ‘default’ is still available, however it will emit a notice that
11157 it is an alias for the new ‘alabaster’ theme.
11158 Creating themes
11161 As said, themes are either a directory or a zipfile (whose name is the
11162 theme name), containing the following:
11163 · A theme.conf file, see below.
11165 · HTML templates, if needed.
11167 · A static/ directory containing any static files that will be copied
11169 to the output static directory on build. These can be images,
11170 styles, script files.
11171 The theme.conf file is in INI format [1] (readable by the standard
11173 Python ConfigParser module) and has the following structure:
11174 [theme]
11176 inherit = base theme
11177 stylesheet = main CSS name
11178 pygments_style = stylename
11179 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
11180 [options]
11182 variable = default value
11183 · The inherit setting gives the name of a “base theme”, or none. The
11185 base theme will be used to locate missing templates (most themes will
11186 not have to supply most templates if they use basic as the base
11187 theme), its options will be inherited, and all of its static files
11188 will be used as well.
11189 · The stylesheet setting gives the name of a CSS file which will be
11191 referenced in the HTML header. If you need more than one CSS file,
11192 either include one from the other via CSS’ @import, or use a custom
11193 HTML template that adds <link rel="stylesheet"> tags as necessary.
11194 Setting the html_style config value will override this setting.
11195 · The pygments_style setting gives the name of a Pygments style to use
11197 for highlighting. This can be overridden by the user in the pyg‐
11198 ments_style config value.
11199 · The sidebars setting gives the comma separated list of sidebar tem‐
11201 plates for constructing sidebars. This can be overridden by the user
11202 in the html_sidebars config value.
11203 · The options section contains pairs of variable names and default val‐
11205 ues. These options can be overridden by the user in
11206 html_theme_options and are accessible from all templates as
11207 theme_<name>.
11208 New in version 1.7: sidebar settings
11210 Distribute your theme as a python package
11213 As a way to distribute your theme, you can use python package. Python
11214 package brings to users easy setting up ways.
11215 To distribute your theme as a python package, please define an entry
11217 point called sphinx.html_themes in your setup.py file, and write a set‐
11218 up() function to register your themes using add_html_theme() API in it:
11219 # 'setup.py'
11221 setup(
11222 ...
11223 entry_points = {
11224 'sphinx.html_themes': [
11225 'name_of_theme = your_package',
11226 ]
11227 },
11228 ...
11229 )
11230 # 'your_package.py'
11232 from os import path
11233 def setup(app):
11235 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
11236 If your theme package contains two or more themes, please call
11238 add_html_theme() twice or more.
11239 New in version 1.2: ‘sphinx_themes’ entry_points feature.
11241 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
11244 recated.
11245 New in version 1.6: sphinx.html_themes entry_points feature.
11248 Templating
11251 The guide to templating is helpful if you want to write your own tem‐
11252 plates. What is important to keep in mind is the order in which Sphinx
11253 searches for templates:
11254 · First, in the user’s templates_path directories.
11256 · Then, in the selected theme.
11258 · Then, in its base theme, its base’s base theme, etc.
11260 When extending a template in the base theme with the same name, use the
11262 theme name as an explicit directory: {% extends "basic/layout.html" %}.
11263 From a user templates_path template, you can still use the “exclamation
11264 mark” syntax as described in the templating document.
11265 Static templates
11267 Since theme options are meant for the user to configure a theme more
11268 easily, without having to write a custom stylesheet, it is necessary to
11269 be able to template static files as well as HTML files. Therefore,
11270 Sphinx supports so-called “static templates”, like this:
11271 If the name of a file in the static/ directory of a theme (or in the
11273 user’s static path, for that matter) ends with _t, it will be processed
11274 by the template engine. The _t will be left from the final file name.
11275 For example, the classic theme has a file static/classic.css_t which
11276 uses templating to put the color options into the stylesheet. When a
11277 documentation is built with the classic theme, the output directory
11278 will contain a _static/classic.css file where all template tags have
11279 been processed.
11280 [1] It is not an executable Python file, as opposed to conf.py,
11282 because that would pose an unnecessary security risk if themes are
11283 shared.
11284 Third Party Themes
11286 ┌───────────────────────────┬───┐
11287 │Theme overview │ │
11288 └───────────────────────────┴───┘
11289 │[image: sphinx_rtd_theme] │ │
11294 │[image] │ │
11295 │ │ │
11296 │ │ │
11297 │sphinx_rtd_theme │ │
11298 └───────────────────────────┴───┘
11299 · sphinx_rtd_theme – Read the Docs Sphinx Theme. This is a
11301 mobile-friendly sphinx theme that was made for readthedocs.org. View
11302 a working demo over on readthedocs.org. You can get install and
11303 options information at Read the Docs Sphinx Theme page.
11304 Changed in version 1.4: sphinx_rtd_theme has become optional.
11306 Besides this, there are a lot of third party themes. You can find them
11309 on PyPI, GitHub, sphinx-themes.org and so on.
11310
11312 Sphinx supports integration with setuptools and distutils through a
11313 custom command - BuildDoc.
11314 Using setuptools integration
11316 The Sphinx build can then be triggered from distutils, and some Sphinx
11317 options can be set in setup.py or setup.cfg instead of Sphinx’s own
11318 configuration file.
11319 For instance, from setup.py:
11321 # this is only necessary when not using setuptools/distribute
11323 from sphinx.setup_command import BuildDoc
11324 cmdclass = {'build_sphinx': BuildDoc}
11325 name = 'My project'
11327 version = '1.2'
11328 release = '1.2.0'
11329 setup(
11330 name=name,
11331 author='Bernard Montgomery',
11332 version=release,
11333 cmdclass=cmdclass,
11334 # these are optional and override conf.py settings
11335 command_options={
11336 'build_sphinx': {
11337 'project': ('setup.py', name),
11338 'version': ('setup.py', version),
11339 'release': ('setup.py', release),
11340 'source_dir': ('setup.py', 'doc')}},
11341 )
11342 NOTE:
11344 If you set Sphinx options directly in the setup() command, replace
11345 hyphens in variable names with underscores. In the example above,
11346 source-dir becomes source_dir.
11347 Or add this section in setup.cfg:
11349 [build_sphinx]
11351 project = 'My project'
11352 version = 1.2
11353 release = 1.2.0
11354 source-dir = 'doc'
11355 Once configured, call this by calling the relevant command on setup.py:
11357 $ python setup.py build_sphinx
11359 Options for setuptools integration
11361 fresh-env
11362 A boolean that determines whether the saved environment should
11363 be discarded on build. Default is false.
11364 This can also be set by passing the -E flag to setup.py:
11366 $ python setup.py build_sphinx -E
11368 all-files
11370 A boolean that determines whether all files should be built from
11371 scratch. Default is false.
11372 This can also be set by passing the -a flag to setup.py:
11374 $ python setup.py build_sphinx -a
11376 source-dir
11378 The target source directory. This can be relative to the set‐
11379 up.py or setup.cfg file, or it can be absolute. It defaults to
11380 ./doc or ./docs if either contains a file named conf.py (check‐
11381 ing ./doc first); otherwise it defaults to the current direc‐
11382 tory.
11383 This can also be set by passing the -s flag to setup.py:
11385 $ python setup.py build_sphinx -s $SOURCE_DIR
11387 build-dir
11389 The target build directory. This can be relative to the setup.py
11390 or setup.cfg file, or it can be absolute. Default is
11391 ./build/sphinx.
11392 config-dir
11394 Location of the configuration directory. This can be relative to
11395 the setup.py or setup.cfg file, or it can be absolute. Default
11396 is to use source-dir.
11397 This can also be set by passing the -c flag to setup.py:
11399 $ python setup.py build_sphinx -c $CONFIG_DIR
11401 New in version 1.0.
11403 builder
11406 The builder or list of builders to use. Default is html.
11407 This can also be set by passing the -b flag to setup.py:
11409 $ python setup.py build_sphinx -b $BUILDER
11411 Changed in version 1.6: This can now be a comma- or space-sepa‐
11413 rated list of builders
11414 warning-is-error
11417 A boolean that ensures Sphinx warnings will result in a failed
11418 build. Default is false.
11419 This can also be set by passing the -W flag to setup.py:
11421 $ python setup.py build_sphinx -W
11423 New in version 1.5.
11425 project
11428 The documented project’s name. Default is ''.
11429 New in version 1.0.
11431 version
11434 The short X.Y version. Default is ''.
11435 New in version 1.0.
11437 release
11440 The full version, including alpha/beta/rc tags. Default is ''.
11441 New in version 1.0.
11443 today How to format the current date, used as the replacement for
11446 |today|. Default is ''.
11447 New in version 1.0.
11449 link-index
11452 A boolean that ensures index.html will be linked to the master
11453 doc. Default is false.
11454 This can also be set by passing the -i flag to setup.py:
11456 $ python setup.py build_sphinx -i
11458 New in version 1.0.
11460 copyright
11463 The copyright string. Default is ''.
11464 New in version 1.3.
11466 nitpicky
11469 Run in nit-picky mode. Currently, this generates warnings for
11470 all missing references. See the config value nitpick_ignore for
11471 a way to exclude some references as “known missing”.
11472 New in version 1.8.
11474 pdb A boolean to configure pdb on exception. Default is false.
11477 New in version 1.5.
11479
11482 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
11483 is a text-based engine, and inspired by Django templates, so anyone
11484 having used Django will already be familiar with it. It also has
11485 excellent documentation for those who need to make themselves familiar
11486 with it.
11487 Do I need to use Sphinx’s templates to produce HTML?
11489 No. You have several other options:
11490 · You can write a TemplateBridge subclass that calls your template
11492 engine of choice, and set the template_bridge configuration value
11493 accordingly.
11494 · You can write a custom builder that derives from StandaloneHTML‐
11496 Builder and calls your template engine of choice.
11497 · You can use the PickleHTMLBuilder that produces pickle files with the
11499 page contents, and postprocess them using a custom tool, or use them
11500 in your Web application.
11501 Jinja/Sphinx Templating Primer
11503 The default templating language in Sphinx is Jinja. It’s Django/Smarty
11504 inspired and easy to understand. The most important concept in Jinja
11505 is template inheritance, which means that you can overwrite only spe‐
11506 cific blocks within a template, customizing it while also keeping the
11507 changes at a minimum.
11508 To customize the output of your documentation you can override all the
11510 templates (both the layout templates and the child templates) by adding
11511 files with the same name as the original filename into the template
11512 directory of the structure the Sphinx quickstart generated for you.
11513 Sphinx will look for templates in the folders of templates_path first,
11515 and if it can’t find the template it’s looking for there, it falls back
11516 to the selected theme’s templates.
11517 A template contains variables, which are replaced with values when the
11519 template is evaluated, tags, which control the logic of the template
11520 and blocks which are used for template inheritance.
11521 Sphinx’s basic theme provides base templates with a couple of blocks it
11523 will fill with data. These are located in the themes/basic subdirec‐
11524 tory of the Sphinx installation directory, and used by all builtin
11525 Sphinx themes. Templates with the same name in the templates_path
11526 override templates supplied by the selected theme.
11527 For example, to add a new link to the template area containing related
11529 links all you have to do is to add a new template called layout.html
11530 with the following contents:
11531 {% extends "!layout.html" %}
11533 {% block rootrellink %}
11534 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
11535 {{ super() }}
11536 {% endblock %}
11537 By prefixing the name of the overridden template with an exclamation
11539 mark, Sphinx will load the layout template from the underlying HTML
11540 theme.
11541 Important: If you override a block, call {{ super() }} somewhere to
11543 render the block’s original content in the extended template – unless
11544 you don’t want that content to show up.
11545 Working with the builtin templates
11547 The builtin basic theme supplies the templates that all builtin Sphinx
11548 themes are based on. It has the following elements you can override or
11549 use:
11550 Blocks
11552 The following blocks exist in the layout.html template:
11553 doctype
11555 The doctype of the output format. By default this is XHTML 1.0
11556 Transitional as this is the closest to what Sphinx and Docutils
11557 generate and it’s a good idea not to change it unless you want
11558 to switch to HTML 5 or a different but compatible XHTML doctype.
11559 linktags
11561 This block adds a couple of <link> tags to the head section of
11562 the template.
11563 extrahead
11565 This block is empty by default and can be used to add extra con‐
11566 tents into the <head> tag of the generated HTML file. This is
11567 the right place to add references to JavaScript or extra CSS
11568 files.
11569 relbar1 / relbar2
11571 This block contains the relation bar, the list of related links
11572 (the parent documents on the left, and the links to index, mod‐
11573 ules etc. on the right). relbar1 appears before the document,
11574 relbar2 after the document. By default, both blocks are filled;
11575 to show the relbar only before the document, you would override
11576 relbar2 like this:
11577 {% block relbar2 %}{% endblock %}
11579 rootrellink / relbaritems
11581 Inside the relbar there are three sections: The rootrellink, the
11582 links from the documentation and the custom relbaritems. The
11583 rootrellink is a block that by default contains a list item
11584 pointing to the master document by default, the relbaritems is
11585 an empty block. If you override them to add extra links into
11586 the bar make sure that they are list items and end with the
11587 reldelim1.
11588 document
11590 The contents of the document itself. It contains the block
11591 “body” where the individual content is put by subtemplates like
11592 page.html.
11593 sidebar1 / sidebar2
11595 A possible location for a sidebar. sidebar1 appears before the
11596 document and is empty by default, sidebar2 after the document
11597 and contains the default sidebar. If you want to swap the side‐
11598 bar location override this and call the sidebar helper:
11599 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
11601 {% block sidebar2 %}{% endblock %}
11602 (The sidebar2 location for the sidebar is needed by the sphinx‐
11604 doc.css stylesheet, for example.)
11605 sidebarlogo
11607 The logo location within the sidebar. Override this if you want
11608 to place some content at the top of the sidebar.
11609 footer The block for the footer div. If you want a custom footer or
11611 markup before or after it, override this one.
11612 The following four blocks are only used for pages that do not have
11614 assigned a list of custom sidebars in the html_sidebars config value.
11615 Their use is deprecated in favor of separate sidebar templates, which
11616 can be included via html_sidebars.
11617 sidebartoc
11619 The table of contents within the sidebar.
11620 Deprecated since version 1.0.
11622 sidebarrel
11625 The relation links (previous, next document) within the sidebar.
11626 Deprecated since version 1.0.
11628 sidebarsourcelink
11631 The “Show source” link within the sidebar (normally only shown
11632 if this is enabled by html_show_sourcelink).
11633 Deprecated since version 1.0.
11635 sidebarsearch
11638 The search box within the sidebar. Override this if you want to
11639 place some content at the bottom of the sidebar.
11640 Deprecated since version 1.0.
11642 Configuration Variables
11645 Inside templates you can set a couple of variables used by the layout
11646 template using the {% set %} tag:
11647 reldelim1
11649 The delimiter for the items on the left side of the related bar.
11650 This defaults to ' »' Each item in the related bar ends
11651 with the value of this variable.
11652 reldelim2
11654 The delimiter for the items on the right side of the related
11655 bar. This defaults to ' |'. Each item except of the last one
11656 in the related bar ends with the value of this variable.
11657 Overriding works like this:
11659 {% extends "!layout.html" %}
11661 {% set reldelim1 = ' >' %}
11662 script_files
11664 Add additional script files here, like this:
11665 {% set script_files = script_files + ["_static/myscript.js"] %}
11667 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
11669 instead.
11670 Helper Functions
11673 Sphinx provides various Jinja functions as helpers in the template.
11674 You can use them to generate links or output multiply used elements.
11675 pathto(document)
11677 Return the path to a Sphinx document as a URL. Use this to
11678 refer to built documents.
11679 pathto(file, 1)
11681 Return the path to a file which is a filename relative to the
11682 root of the generated output. Use this to refer to static
11683 files.
11684 hasdoc(document)
11686 Check if a document with the name document exists.
11687 sidebar()
11689 Return the rendered sidebar.
11690 relbar()
11692 Return the rendered relation bar.
11693 warning(message)
11695 Emit a warning message.
11696 Global Variables
11698 These global variables are available in every template and are safe to
11699 use. There are more, but most of them are an implementation detail and
11700 might change in the future.
11701 builder
11703 The name of the builder (e.g. html or htmlhelp).
11704 copyright
11706 The value of copyright.
11707 docstitle
11709 The title of the documentation (the value of html_title), except
11710 when the “single-file” builder is used, when it is set to None.
11711 embedded
11713 True if the built HTML is meant to be embedded in some viewing
11714 application that handles navigation, not the web browser, such
11715 as for HTML help or Qt help formats. In this case, the sidebar
11716 is not included.
11717 favicon
11719 The path to the HTML favicon in the static path, or ''.
11720 file_suffix
11722 The value of the builder’s out_suffix attribute, i.e. the file
11723 name extension that the output files will get. For a standard
11724 HTML builder, this is usually .html.
11725 has_source
11727 True if the reST document sources are copied (if
11728 html_copy_source is True).
11729 language
11731 The value of language.
11732 last_updated
11734 The build date.
11735 logo The path to the HTML logo image in the static path, or ''.
11737 master_doc
11739 The value of master_doc, for usage with pathto().
11740 pagename
11742 The “page name” of the current file, i.e. either the document
11743 name if the file is generated from a reST source, or the equiva‐
11744 lent hierarchical name relative to the output directory ([direc‐
11745 tory/]filename_without_extension).
11746 project
11748 The value of project.
11749 release
11751 The value of release.
11752 rellinks
11754 A list of links to put at the left side of the relbar, next to
11755 “next” and “prev”. This usually contains links to the general
11756 index and other indices, such as the Python module index. If
11757 you add something yourself, it must be a tuple (pagename, link
11758 title, accesskey, link text).
11759 shorttitle
11761 The value of html_short_title.
11762 show_source
11764 True if html_show_sourcelink is True.
11765 sphinx_version
11767 The version of Sphinx used to build.
11768 style The name of the main stylesheet, as given by the theme or
11770 html_style.
11771 title The title of the current document, as used in the <title> tag.
11773 use_opensearch
11775 The value of html_use_opensearch.
11776 version
11778 The value of version.
11779 In addition to these values, there are also all theme options available
11781 (prefixed by theme_), as well as the values given by the user in
11782 html_context.
11783 In documents that are created from source files (as opposed to automat‐
11785 ically-generated files like the module index, or documents that already
11786 are in HTML form), these variables are also available:
11787 body A string containing the content of the page in HTML form as pro‐
11789 duced by the HTML builder, before the theme is applied.
11790 display_toc
11792 A boolean that is True if the toc contains more than one entry.
11793 meta Document metadata (a dictionary), see metadata.
11795 metatags
11797 A string containing the page’s HTML meta tags.
11798 next The next document for the navigation. This variable is either
11800 false or has two attributes link and title. The title contains
11801 HTML markup. For example, to generate a link to the next page,
11802 you can use this snippet:
11803 {% if next %}
11805 <a href="{{ next.link|e }}">{{ next.title }}</a>
11806 {% endif %}
11807 page_source_suffix
11809 The suffix of the file that was rendered. Since we support a
11810 list of source_suffix, this will allow you to properly link to
11811 the original source file.
11812 parents
11814 A list of parent documents for navigation, structured like the
11815 next item.
11816 prev Like next, but for the previous page.
11818 sourcename
11820 The name of the copied source file for the current document.
11821 This is only nonempty if the html_copy_source value is True.
11822 This has empty value on creating automatically-generated files.
11823 title The page title.
11825 toc The local table of contents for the current page, rendered as
11827 HTML bullet lists.
11828 toctree
11830 A callable yielding the global TOC tree containing the current
11831 page, rendered as HTML bullet lists. Optional keyword argu‐
11832 ments:
11833 · collapse (True by default): if true, all TOC entries that are
11835 not ancestors of the current page are collapsed
11836 · maxdepth (defaults to the max depth selected in the toctree
11838 directive): the maximum depth of the tree; set it to -1 to
11839 allow unlimited depth
11840 · titles_only (False by default): if true, put only toplevel
11842 document titles in the tree
11843 · includehidden (False by default): if true, the TOC tree will
11845 also contain hidden entries.
11846
11848 For details of the LaTeX/PDF builder command line invocation, refer to
11849 LaTeXBuilder.
11850 Basic customization
11852 The latex target does not benefit from prepared themes.
11853 Basic customization is obtained via usage of the latex-options. For
11855 example:
11856 # inside conf.py
11858 latex_engine = 'xelatex'
11859 latex_elements = {
11860 'fontpkg': r'''
11861 \setmainfont{DejaVu Serif}
11862 \setsansfont{DejaVu Sans}
11863 \setmonofont{DejaVu Sans Mono}
11864 ''',
11865 'preamble': r'''
11866 \usepackage[titles]{tocloft}
11867 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
11868 \setlength{\cftchapnumwidth}{0.75cm}
11869 \setlength{\cftsecindent}{\cftchapnumwidth}
11870 \setlength{\cftsecnumwidth}{1.25cm}
11871 ''',
11872 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
11873 'printindex': r'\footnotesize\raggedright\printindex',
11874 }
11875 latex_show_urls = 'footnote'
11876 If the size of the 'preamble' contents becomes inconvenient, one may
11878 move all needed macros into some file mystyle.tex.txt of the project
11879 source repertory, and get LaTeX to import it at run time:
11880 'preamble': r'\input{mystyle.tex.txt}',
11882 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
11883 'preamble': r'\usepackage{mystyle}',
11884 It is then needed to set appropriately latex_additional_files, for
11886 example:
11887 latex_additional_files = ["mystyle.sty"]
11889 The LaTeX style file options
11891 Additional customization is possible via LaTeX options of the Sphinx
11892 style file.
11893 The sphinxsetup interface
11895 The 'sphinxsetup' key of latex_elements provides a convenient inter‐
11896 face:
11897 latex_elements = {
11899 'sphinxsetup': 'key1=value1, key2=value2, ...',
11900 }
11901 · some values may be LaTeX macros, then the backslashes must be
11903 Python-escaped, or the whole must be a Python raw string,
11904 · LaTeX boolean keys require lowercase true or false values,
11906 · spaces around the commas and equal signs are ignored, spaces inside
11908 LaTeX macros may be significant.
11909 If non-empty, it will be passed as argument to the \sphinxsetup macro
11911 inside the document preamble, like this:
11912 \usepackage{sphinx}
11914 \sphinxsetup{key1=value1, key2=value2,...}
11915 New in version 1.5.
11917 HINT:
11920 It is possible to insert further uses of the \sphinxsetup LaTeX
11921 macro directly into the body of the document, via the help of the
11922 raw directive. Here is how this present chapter in PDF is styled:
11923 .. raw:: latex
11925 \begingroup
11927 \sphinxsetup{%
11928 verbatimwithframe=false,
11929 VerbatimColor={named}{OldLace},
11930 TitleColor={named}{DarkGoldenrod},
11931 hintBorderColor={named}{LightCoral},
11932 attentionborder=3pt,
11933 attentionBorderColor={named}{Crimson},
11934 attentionBgColor={named}{FloralWhite},
11935 noteborder=2pt,
11936 noteBorderColor={named}{Olive},
11937 cautionborder=3pt,
11938 cautionBorderColor={named}{Cyan},
11939 cautionBgColor={named}{LightCyan}}
11940 at the start of the chapter and:
11942 .. raw:: latex
11944 \endgroup
11946 at its end.
11948 The colors used in the above are provided by the svgnames option of
11950 the “xcolor” package:
11951 latex_elements = {
11953 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
11954 }
11955 The available styling options
11957 hmargin, vmargin
11958 The dimensions of the horizontal (resp. vertical) margins,
11959 passed as hmargin (resp. vmargin) option to the geometry pack‐
11960 age. The default is 1in, which is equivalent to {1in,1in}. Exam‐
11961 ple:
11962 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
11964 Japanese documents currently accept only the one-dimension for‐
11966 mat for these parameters. The geometry package is then passed
11967 suitable options to get the text width set to an exact multiple
11968 of the zenkaku width, and the text height set to an integer mul‐
11969 tiple of the baselineskip, with the closest fit for the margins.
11970 HINT:
11972 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
11973 use the nomag extra document class option (cf. 'extraclas‐
11974 soptions' key of latex_elements) or so-called TeX “true”
11975 units:
11976 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
11978 New in version 1.5.3.
11980 marginpar
11983 The \marginparwidth LaTeX dimension, defaults to 0.5in. For Ja‐
11984 panese documents, the value is modified to be the closest inte‐
11985 ger multiple of the zenkaku width.
11986 New in version 1.5.3.
11988 verbatimwithframe
11991 default true. Boolean to specify if code-blocks and literal
11992 includes are framed. Setting it to false does not deactivate use
11993 of package “framed”, because it is still in use for the optional
11994 background colour.
11995 verbatimwrapslines
11997 default true. Tells whether long lines in code-block’s contents
11998 should wrap.
11999 literalblockcappos
12001 default t for “top”. Decides the caption position. Alternative
12002 is b (“bottom”).
12003 New in version 1.7.
12005 verbatimhintsturnover
12008 default true. If true, code-blocks display “continued on next
12009 page”, “continued from previous page” hints in case of page‐
12010 breaks.
12011 New in version 1.6.3.
12013 Changed in version 1.7: the default changed from false to true.
12016 verbatimcontinuedalign, verbatimcontinuesalign
12019 default r. Horizontal position relative to the framed contents:
12020 either l (left aligned), r (right aligned) or c (centered).
12021 New in version 1.7.
12023 parsedliteralwraps
12026 default true. Tells whether long lines in parsed-literal’s con‐
12027 tents should wrap.
12028 New in version 1.5.2: set this option value to false to recover
12030 former behaviour.
12031 inlineliteralwraps
12034 default true. Allows linebreaks inside inline literals: but
12035 extra potential break-points (additionally to those allowed by
12036 LaTeX at spaces or for hyphenation) are currently inserted only
12037 after the characters . , ; ? ! /. Due to TeX internals, white
12038 space in the line will be stretched (or shrunk) in order to
12039 accomodate the linebreak.
12040 New in version 1.5: set this option value to false to recover
12042 former behaviour.
12043 verbatimvisiblespace
12046 default \textcolor{red}{\textvisiblespace}. When a long code
12047 line is split, the last space character from the source code
12048 line right before the linebreak location is typeset using this.
12049 verbatimcontinued
12051 A LaTeX macro inserted at start of continuation code lines. Its
12052 (complicated…) default typesets a small red hook pointing to the
12053 right:
12054 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
12056 Changed in version 1.5: The breaking of long code lines was
12058 added at 1.4.2. The default definition of the continuation sym‐
12059 bol was changed at 1.5 to accomodate various font sizes (e.g.
12060 code-blocks can be in footnotes).
12061 TitleColor
12064 default {rgb}{0.126,0.263,0.361}. The colour for titles (as con‐
12065 figured via use of package “titlesec”.)
12066 WARNING:
12068 Colours set via 'sphinxsetup' must obey the syntax of the argument
12069 of the color/xcolor packages \definecolor command.
12070 InnerLinkColor
12072 default {rgb}{0.208,0.374,0.486}. A colour passed to hyperref as
12073 value of linkcolor and citecolor.
12074 OuterLinkColor
12076 default {rgb}{0.216,0.439,0.388}. A colour passed to hyperref as
12077 value of filecolor, menucolor, and urlcolor.
12078 VerbatimColor
12080 default {rgb}{1,1,1}. The background colour for code-blocks. The
12081 default is white.
12082 VerbatimBorderColor
12084 default {rgb}{0,0,0}. The frame color, defaults to black.
12085 VerbatimHighlightColor
12087 default {rgb}{0.878,1,1}. The color for highlighted lines.
12088 New in version 1.6.6.
12090 NOTE:
12093 Starting with this colour key, and for all others coming next, the
12094 actual names declared to “color” or “xcolor” are prefixed with
12095 “sphinx”.
12096 verbatimsep
12098 default \fboxsep. The separation between code lines and the
12099 frame.
12100 verbatimborder
12102 default \fboxrule. The width of the frame around code-blocks.
12103 shadowsep
12105 default 5pt. The separation between contents and frame for
12106 contents and topic boxes.
12107 shadowsize
12109 default 4pt. The width of the lateral “shadow” to the right.
12110 shadowrule
12112 default \fboxrule. The width of the frame around topic boxes.
12113 noteBorderColor, hintBorderColor,
12115 importantBorderColor, tipBorderColor default {rgb}{0,0,0}
12116 (black). The colour for the two horizontal rules used by Sphinx
12117 in LaTeX for styling a note type admonition.
12118 noteborder, hintborder, importantborder, tipborder
12120 default 0.5pt. The width of the two horizontal rules.
12121 warningBorderColor, cautionBorderColor,
12123 attentionBorderColor, dangerBorderColor, errorBorderColor
12124 default {rgb}{0,0,0} (black). The colour for the admonition
12125 frame.
12126 warningBgColor, cautionBgColor,
12128 attentionBgColor, dangerBgColor, errorBgColor default
12129 {rgb}{1,1,1} (white). The background colours for the respective
12130 admonitions.
12131 warningborder, cautionborder,
12133 attentionborder, dangerborder, errorborder default 1pt. The
12134 width of the frame.
12135 AtStartFootnote
12137 default \mbox{ }. LaTeX macros inserted at the start of the
12138 footnote text at bottom of page, after the footnote number.
12139 BeforeFootnote
12141 default \leavevmode\unskip. LaTeX macros inserted before the
12142 footnote mark. The default removes possible space before it
12143 (else, TeX could insert a linebreak there).
12144 New in version 1.5.
12146 HeaderFamily
12149 default \sffamily\bfseries. Sets the font used by headings.
12150 LaTeX macros and environments
12152 Here are some macros from the package file sphinx.sty and class files
12153 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
12154 ing redefinitions. Check the respective files for the defaults.
12155 Macros
12157 · text styling commands \sphinx<foo> with <foo> being one of strong,
12158 bfcode, email, tablecontinued, titleref, menuselection, accelerator,
12159 crossref, termref, optional.
12160 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
12162 possibilities of conflict with LaTeX packages.
12163 · more text styling: \sphinxstyle<bar> with <bar> one of indexentry,
12166 indexextra, indexpageref, topictitle, sidebartitle, othertitle, side‐
12167 barsubtitle, theadfamily, emphasis, literalemphasis, strong, literal‐
12168 strong, abbreviation, literalintitle, codecontinued, codecontinues
12169 New in version 1.5: these macros were formerly hard-coded as non cus‐
12171 tomizable \texttt, \emph, etc…
12172 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
12175 ily and allows multiple paragraphs in header cells of tables.
12176 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
12179 continues.
12180 · the table of contents is typeset via \sphinxtableofcontents which is
12183 a wrapper (whose definition can be found in sphinxhowto.cls or in
12184 sphinxmanual.cls) of standard \tableofcontents.
12185 Changed in version 1.5: formerly, the meaning of \tableofcontents was
12187 modified by Sphinx.
12188 · a custom \sphinxmaketitle is defined in the class files sphinxman‐
12191 ual.cls and sphinxhowto.cls and is used as default setting of
12192 'maketitle' latex_elements key.
12193 Changed in version 1.8.3: formerly, \maketitle from LaTeX document
12195 class was modified by Sphinx.
12196 · for 'manual' docclass a macro \sphinxbackoftitlepage, if it is
12199 defined, gets executed at end of \sphinxmaketitle, before the final
12200 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
12201 latex_elements to add a custom definition of \sphinxbackoftitlepage.
12202 New in version 1.8.3.
12204 · the citation reference is typeset via \sphinxcite which is a wrapper
12207 of standard \cite.
12208 Environments
12210 · a figure may have an optional legend with arbitrary body elements:
12211 they are rendered in a sphinxlegend environment. The default defini‐
12212 tion issues \small, and ends with \par.
12213 New in version 1.5.6: formerly, the \small was hardcoded in LaTeX
12215 writer and the ending \par was lacking.
12216 · for each admonition type <foo>, the used environment is named
12219 sphinx<foo>. They may be \renewenvironment ‘d individually, and must
12220 then be defined with one argument (it is the heading of the notice,
12221 for example Warning: for warning directive, if English is the docu‐
12222 ment language). Their default definitions use either the sphinxheavy‐
12223 box (for the first listed directives) or the sphinxlightbox environ‐
12224 ments, configured to use the parameters (colours, border thickness)
12225 specific to each type, which can be set via 'sphinxsetup' string.
12226 Changed in version 1.5: use of public environment names, separate
12228 customizability of the parameters, such as noteBorderColor, notebor‐
12229 der, warningBgColor, warningBorderColor, warningborder, …
12230 · the contents directive (with :local: option) and the topic directive
12233 are implemented by environment sphinxShadowBox.
12234 New in version 1.4.2: former code refactored into an environment
12236 allowing page breaks.
12237 Changed in version 1.5: options shadowsep, shadowsize, shadowrule.
12240 · the literal blocks (via :: or code-block), are implemented using
12243 sphinxVerbatim environment which is a wrapper of Verbatim environment
12244 from package fancyvrb.sty. It adds the handling of the top caption
12245 and the wrapping of long lines, and a frame which allows pagebreaks.
12246 Inside tables the used environment is sphinxVerbatimintable (it does
12247 not draw a frame, but allows a caption).
12248 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
12250 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
12251 intable is used inside tables.
12252 New in version 1.5: options verbatimwithframe, verbatimwrapslines,
12255 verbatimsep, verbatimborder.
12256 New in version 1.6.6: support for :emphasize-lines: option
12259 New in version 1.6.6: easier customizability of the formatting via
12262 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
12263 · the bibliography uses sphinxthebibliography and the Python Module
12266 index as well as the general index both use sphinxtheindex; these
12267 environments are wrappers of the thebibliography and respectively
12268 theindex environments as provided by the document class (or pack‐
12269 ages).
12270 Changed in version 1.5: formerly, the original environments were mod‐
12272 ified by Sphinx.
12273 Miscellany
12276 · the section, subsection, … headings are set using titlesec’s
12277 \titleformat command.
12278 · for the 'manual' docclass, the chapter headings can be customized
12280 using fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
12281 sphinx.sty has custom re-definitions in case of fncychap option
12282 Bjarne.
12283 Changed in version 1.5: formerly, use of fncychap with other styles
12285 than Bjarne was dysfunctional.
12286 HINT:
12289 As an experimental feature, Sphinx can use user-defined template
12290 file for LaTeX source if you have a file named _tem‐
12291 plates/latex.tex_t in your project.
12292 New in version 1.5: currently all template variables are unstable
12294 and undocumented.
12295 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
12298 can be added to _templates/ to configure some aspects of table ren‐
12299 dering (such as the caption position).
12300 New in version 1.6: currently all template variables are unstable
12302 and undocumented.
12303
12306 Since many projects will need special features in their documentation,
12307 Sphinx is designed to be extensible on several levels.
12308 This is what you can do in an extension: First, you can add new
12310 builders to support new output formats or actions on the parsed docu‐
12311 ments. Then, it is possible to register custom reStructuredText roles
12312 and directives, extending the markup. And finally, there are so-called
12313 “hook points” at strategic places throughout the build process, where
12314 an extension can register a hook and run specialized code.
12315 An extension is simply a Python module. When an extension is loaded,
12317 Sphinx imports this module and executes its setup() function, which in
12318 turn notifies Sphinx of everything the extension offers – see the
12319 extension tutorial for examples.
12320 The configuration file itself can be treated as an extension if it con‐
12322 tains a setup() function. All other extensions to load must be listed
12323 in the extensions configuration value.
12324 Discovery of builders by entry point
12326 New in version 1.6.
12327 Builder extensions can be discovered by means of entry points so that
12330 they do not have to be listed in the extensions configuration value.
12331 Builder extensions should define an entry point in the sphinx.builders
12333 group. The name of the entry point needs to match your builder’s name
12334 attribute, which is the name passed to the sphinx-build -b option. The
12335 entry point value should equal the dotted name of the extension module.
12336 Here is an example of how an entry point for ‘mybuilder’ can be defined
12337 in the extension’s setup.py:
12338 setup(
12340 # ...
12341 entry_points={
12342 'sphinx.builders': [
12343 'mybuilder = my.extension.module',
12344 ],
12345 }
12346 )
12347 Note that it is still necessary to register the builder using
12349 add_builder() in the extension’s setup() function.
12350 Extension metadata
12352 New in version 1.3.
12353 The setup() function can return a dictionary. This is treated by
12356 Sphinx as metadata of the extension. Metadata keys currently recog‐
12357 nized are:
12358 · 'version': a string that identifies the extension version. It is
12360 used for extension version requirement checking (see needs_exten‐
12361 sions) and informational purposes. If not given, "unknown version"
12362 is substituted.
12363 · 'env_version': an integer that identifies the version of env data
12365 structure if the extension stores any data to environment. It is
12366 used to detect the data structure has been changed from last build.
12367 The extensions have to increment the version when data structure has
12368 changed. If not given, Sphinx considers the extension does not
12369 stores any data to environment.
12370 · 'parallel_read_safe': a boolean that specifies if parallel reading of
12372 source files can be used when the extension is loaded. It defaults
12373 to False, i.e. you have to explicitly specify your extension to be
12374 parallel-read-safe after checking that it is.
12375 · 'parallel_write_safe': a boolean that specifies if parallel writing
12377 of output files can be used when the extension is loaded. Since
12378 extensions usually don’t negatively influence the process, this
12379 defaults to True.
12380 APIs used for writing extensions
12382 Tutorial: Writing a simple extension
12383 This section is intended as a walkthrough for the creation of custom
12384 extensions. It covers the basics of writing and activating an exten‐
12385 sion, as well as commonly used features of extensions.
12386 As an example, we will cover a “todo” extension that adds capabilities
12388 to include todo entries in the documentation, and to collect these in a
12389 central place. (A similar “todo” extension is distributed with
12390 Sphinx.)
12391 Important objects
12393 There are several key objects whose API you will use while writing an
12394 extension. These are:
12395 Application
12397 The application object (usually called app) is an instance of
12398 Sphinx. It controls most high-level functionality, such as the
12399 setup of extensions, event dispatching and producing output
12400 (logging).
12401 If you have the environment object, the application is available
12403 as env.app.
12404 Environment
12406 The build environment object (usually called env) is an instance
12407 of BuildEnvironment. It is responsible for parsing the source
12408 documents, stores all metadata about the document collection and
12409 is serialized to disk after each build.
12410 Its API provides methods to do with access to metadata, resolv‐
12412 ing references, etc. It can also be used by extensions to cache
12413 information that should persist for incremental rebuilds.
12414 If you have the application or builder object, the environment
12416 is available as app.env or builder.env.
12417 Builder
12419 The builder object (usually called builder) is an instance of a
12420 specific subclass of Builder. Each builder class knows how to
12421 convert the parsed documents into an output format, or otherwise
12422 process them (e.g. check external links).
12423 If you have the application object, the builder is available as
12425 app.builder.
12426 Config The config object (usually called config) provides the values of
12428 configuration values set in conf.py as attributes. It is an
12429 instance of Config.
12430 The config is available as app.config or env.config.
12432 Build Phases
12434 One thing that is vital in order to understand extension mechanisms is
12435 the way in which a Sphinx project is built: this works in several
12436 phases.
12437 Phase 0: Initialization
12439 In this phase, almost nothing of interest to us happens. The source
12440 directory is searched for source files, and extensions are initial‐
12441 ized. Should a stored build environment exist, it is loaded, other‐
12442 wise a new one is created.
12443 Phase 1: Reading
12445 In Phase 1, all source files (and on subsequent builds, those that
12446 are new or changed) are read and parsed. This is the phase where
12447 directives and roles are encountered by docutils, and the corre‐
12448 sponding code is executed. The output of this phase is a doctree
12449 for each source file; that is a tree of docutils nodes. For docu‐
12450 ment elements that aren’t fully known until all existing files are
12451 read, temporary nodes are created.
12452 There are nodes provided by docutils, which are documented in the
12454 docutils documentation. Additional nodes are provided by Sphinx and
12455 documented here.
12456 During reading, the build environment is updated with all meta- and
12458 cross reference data of the read documents, such as labels, the
12459 names of headings, described Python objects and index entries. This
12460 will later be used to replace the temporary nodes.
12461 The parsed doctrees are stored on the disk, because it is not possi‐
12463 ble to hold all of them in memory.
12464 Phase 2: Consistency checks
12466 Some checking is done to ensure no surprises in the built documents.
12467 Phase 3: Resolving
12469 Now that the metadata and cross-reference data of all existing docu‐
12470 ments is known, all temporary nodes are replaced by nodes that can
12471 be converted into output using components called transforms. For
12472 example, links are created for object references that exist, and
12473 simple literal nodes are created for those that don’t.
12474 Phase 4: Writing
12476 This phase converts the resolved doctrees to the desired output for‐
12477 mat, such as HTML or LaTeX. This happens via a so-called docutils
12478 writer that visits the individual nodes of each doctree and produces
12479 some output in the process.
12480 NOTE:
12482 Some builders deviate from this general build plan, for example, the
12483 builder that checks external links does not need anything more than
12484 the parsed doctrees and therefore does not have phases 2–4.
12485 Extension Design
12487 We want the extension to add the following to Sphinx:
12488 · A “todo” directive, containing some content that is marked with
12490 “TODO”, and only shown in the output if a new config value is set.
12491 (Todo entries should not be in the output by default.)
12492 · A “todolist” directive that creates a list of all todo entries
12494 throughout the documentation.
12495 For that, we will need to add the following elements to Sphinx:
12497 · New directives, called todo and todolist.
12499 · New document tree nodes to represent these directives, conventionally
12501 also called todo and todolist. We wouldn’t need new nodes if the new
12502 directives only produced some content representable by existing
12503 nodes.
12504 · A new config value todo_include_todos (config value names should
12506 start with the extension name, in order to stay unique) that controls
12507 whether todo entries make it into the output.
12508 · New event handlers: one for the doctree-resolved event, to replace
12510 the todo and todolist nodes, and one for env-purge-doc (the reason
12511 for that will be covered later).
12512 The Setup Function
12514 The new elements are added in the extension’s setup function. Let us
12515 create a new Python module called todo.py and add the setup function:
12516 def setup(app):
12518 app.add_config_value('todo_include_todos', False, 'html')
12519 app.add_node(todolist)
12521 app.add_node(todo,
12522 html=(visit_todo_node, depart_todo_node),
12523 latex=(visit_todo_node, depart_todo_node),
12524 text=(visit_todo_node, depart_todo_node))
12525 app.add_directive('todo', TodoDirective)
12527 app.add_directive('todolist', TodolistDirective)
12528 app.connect('doctree-resolved', process_todo_nodes)
12529 app.connect('env-purge-doc', purge_todos)
12530 return {'version': '0.1'} # identifies the version of our extension
12532 The calls in this function refer to classes and functions not yet writ‐
12534 ten. What the individual calls do is the following:
12535 · add_config_value() lets Sphinx know that it should recognize the new
12537 config value todo_include_todos, whose default value should be False
12538 (this also tells Sphinx that it is a boolean value).
12539 If the third argument was 'html', HTML documents would be full
12541 rebuild if the config value changed its value. This is needed for
12542 config values that influence reading (build phase 1).
12543 · add_node() adds a new node class to the build system. It also can
12545 specify visitor functions for each supported output format. These
12546 visitor functions are needed when the new nodes stay until phase 4 –
12547 since the todolist node is always replaced in phase 3, it doesn’t
12548 need any.
12549 We need to create the two node classes todo and todolist later.
12551 · add_directive() adds a new directive, given by name and class.
12553 The handler functions are created later.
12555 · Finally, connect() adds an event handler to the event whose name is
12557 given by the first argument. The event handler function is called
12558 with several arguments which are documented with the event.
12559 The Node Classes
12561 Let’s start with the node classes:
12562 from docutils import nodes
12564 class todo(nodes.Admonition, nodes.Element):
12566 pass
12567 class todolist(nodes.General, nodes.Element):
12569 pass
12570 def visit_todo_node(self, node):
12572 self.visit_admonition(node)
12573 def depart_todo_node(self, node):
12575 self.depart_admonition(node)
12576 Node classes usually don’t have to do anything except inherit from the
12578 standard docutils classes defined in docutils.nodes. todo inherits
12579 from Admonition because it should be handled like a note or warning,
12580 todolist is just a “general” node.
12581 NOTE:
12583 Many extensions will not have to create their own node classes and
12584 work fine with the nodes already provided by docutils and Sphinx.
12585 The Directive Classes
12587 A directive class is a class deriving usually from docu‐
12588 tils.parsers.rst.Directive. The directive interface is also covered in
12589 detail in the docutils documentation; the important thing is that the
12590 class should have attributes that configure the allowed markup, and a
12591 run method that returns a list of nodes.
12592 The todolist directive is quite simple:
12594 from docutils.parsers.rst import Directive
12596 class TodolistDirective(Directive):
12598 def run(self):
12600 return [todolist('')]
12601 An instance of our todolist node class is created and returned. The
12603 todolist directive has neither content nor arguments that need to be
12604 handled.
12605 The todo directive function looks like this:
12607 from sphinx.locale import _
12609 class TodoDirective(Directive):
12611 # this enables content in the directive
12613 has_content = True
12614 def run(self):
12616 env = self.state.document.settings.env
12617 targetid = "todo-%d" % env.new_serialno('todo')
12619 targetnode = nodes.target('', '', ids=[targetid])
12620 todo_node = todo('\n'.join(self.content))
12622 todo_node += nodes.title(_('Todo'), _('Todo'))
12623 self.state.nested_parse(self.content, self.content_offset, todo_node)
12624 if not hasattr(env, 'todo_all_todos'):
12626 env.todo_all_todos = []
12627 env.todo_all_todos.append({
12628 'docname': env.docname,
12629 'lineno': self.lineno,
12630 'todo': todo_node.deepcopy(),
12631 'target': targetnode,
12632 })
12633 return [targetnode, todo_node]
12635 Several important things are covered here. First, as you can see, you
12637 can refer to the build environment instance using self.state.docu‐
12638 ment.settings.env.
12639 Then, to act as a link target (from the todolist), the todo directive
12641 needs to return a target node in addition to the todo node. The target
12642 ID (in HTML, this will be the anchor name) is generated by using
12643 env.new_serialno which returns a new unique integer on each call and
12644 therefore leads to unique target names. The target node is instanti‐
12645 ated without any text (the first two arguments).
12646 On creating admonition node, the content body of the directive are
12648 parsed using self.state.nested_parse. The first argument gives the
12649 content body, and the second one gives content offset. The third argu‐
12650 ment gives the parent node of parsed result, in our case the todo node.
12651 Then, the todo node is added to the environment. This is needed to be
12653 able to create a list of all todo entries throughout the documentation,
12654 in the place where the author puts a todolist directive. For this
12655 case, the environment attribute todo_all_todos is used (again, the name
12656 should be unique, so it is prefixed by the extension name). It does
12657 not exist when a new environment is created, so the directive must
12658 check and create it if necessary. Various information about the todo
12659 entry’s location are stored along with a copy of the node.
12660 In the last line, the nodes that should be put into the doctree are
12662 returned: the target node and the admonition node.
12663 The node structure that the directive returns looks like this:
12665 +--------------------+
12667 | target node |
12668 +--------------------+
12669 +--------------------+
12670 | todo node |
12671 +--------------------+
12672 \__+--------------------+
12673 | admonition title |
12674 +--------------------+
12675 | paragraph |
12676 +--------------------+
12677 | ... |
12678 +--------------------+
12679 The Event Handlers
12681 Finally, let’s look at the event handlers. First, the one for the
12682 env-purge-doc event:
12683 def purge_todos(app, env, docname):
12685 if not hasattr(env, 'todo_all_todos'):
12686 return
12687 env.todo_all_todos = [todo for todo in env.todo_all_todos
12688 if todo['docname'] != docname]
12689 Since we store information from source files in the environment, which
12691 is persistent, it may become out of date when the source file changes.
12692 Therefore, before each source file is read, the environment’s records
12693 of it are cleared, and the env-purge-doc event gives extensions a
12694 chance to do the same. Here we clear out all todos whose docname
12695 matches the given one from the todo_all_todos list. If there are todos
12696 left in the document, they will be added again during parsing.
12697 The other handler belongs to the doctree-resolved event. This event is
12699 emitted at the end of phase 3 and allows custom resolving to be done:
12700 def process_todo_nodes(app, doctree, fromdocname):
12702 if not app.config.todo_include_todos:
12703 for node in doctree.traverse(todo):
12704 node.parent.remove(node)
12705 # Replace all todolist nodes with a list of the collected todos.
12707 # Augment each todo with a backlink to the original location.
12708 env = app.builder.env
12709 for node in doctree.traverse(todolist):
12711 if not app.config.todo_include_todos:
12712 node.replace_self([])
12713 continue
12714 content = []
12716 for todo_info in env.todo_all_todos:
12718 para = nodes.paragraph()
12719 filename = env.doc2path(todo_info['docname'], base=None)
12720 description = (
12721 _('(The original entry is located in %s, line %d and can be found ') %
12722 (filename, todo_info['lineno']))
12723 para += nodes.Text(description, description)
12724 # Create a reference
12726 newnode = nodes.reference('', '')
12727 innernode = nodes.emphasis(_('here'), _('here'))
12728 newnode['refdocname'] = todo_info['docname']
12729 newnode['refuri'] = app.builder.get_relative_uri(
12730 fromdocname, todo_info['docname'])
12731 newnode['refuri'] += '#' + todo_info['target']['refid']
12732 newnode.append(innernode)
12733 para += newnode
12734 para += nodes.Text('.)', '.)')
12735 # Insert into the todolist
12737 content.append(todo_info['todo'])
12738 content.append(para)
12739 node.replace_self(content)
12741 It is a bit more involved. If our new “todo_include_todos” config
12743 value is false, all todo and todolist nodes are removed from the docu‐
12744 ments.
12745 If not, todo nodes just stay where and how they are. Todolist nodes
12747 are replaced by a list of todo entries, complete with backlinks to the
12748 location where they come from. The list items are composed of the
12749 nodes from the todo entry and docutils nodes created on the fly: a
12750 paragraph for each entry, containing text that gives the location, and
12751 a link (reference node containing an italic node) with the backrefer‐
12752 ence. The reference URI is built by app.builder.get_relative_uri which
12753 creates a suitable URI depending on the used builder, and appending the
12754 todo node’s (the target’s) ID as the anchor name.
12755 Application API
12757 Each Sphinx extension is a Python module with at least a setup() func‐
12758 tion. This function is called at initialization time with one argu‐
12759 ment, the application object representing the Sphinx process.
12760 class sphinx.application.Sphinx
12762 This application object has the public API described in the fol‐
12763 lowing.
12764 Extension setup
12766 These methods are usually called in an extension’s setup() function.
12767 Examples of using the Sphinx extension API can be seen in the
12769 sphinx.ext package.
12770 Sphinx.setup_extension(name)
12772 Import and setup a Sphinx extension module.
12773 Load the extension given by the module name. Use this if your
12775 extension needs the features provided by another extension.
12776 No-op if called twice.
12777 Sphinx.require_sphinx(version)
12779 Check the Sphinx version if requested.
12780 Compare version (which must be a major.minor version string,
12782 e.g. '1.1') with the version of the running Sphinx, and abort
12783 the build when it is too old.
12784 New in version 1.0.
12786 Sphinx.connect(event, callback)
12789 Register callback to be called when event is emitted.
12790 For details on available core events and the arguments of call‐
12792 back functions, please see Sphinx core events.
12793 The method returns a “listener ID” that can be used as an argu‐
12795 ment to disconnect().
12796 Sphinx.disconnect(listener_id)
12798 Unregister callback by listener_id.
12799 Sphinx.add_builder(builder)
12801 Register a new builder.
12802 builder must be a class that inherits from Builder.
12804 Changed in version 1.8: Add override keyword.
12806 Sphinx.add_config_value(name, default, rebuild)
12809 Register a configuration value.
12810 This is necessary for Sphinx to recognize new values and set
12812 default values accordingly. The name should be prefixed with
12813 the extension name, to avoid clashes. The default value can be
12814 any Python object. The string value rebuild must be one of
12815 those values:
12816 · 'env' if a change in the setting only takes effect when a doc‐
12818 ument is parsed – this means that the whole environment must
12819 be rebuilt.
12820 · 'html' if a change in the setting needs a full rebuild of HTML
12822 documents.
12823 · '' if a change in the setting will not need any special
12825 rebuild.
12826 Changed in version 0.6: Changed rebuild from a simple boolean
12828 (equivalent to '' or 'env') to a string. However, booleans are
12829 still accepted and converted internally.
12830 Changed in version 0.4: If the default value is a callable, it
12833 will be called with the config object as its argument in order
12834 to get the default value. This can be used to implement config
12835 values whose default depends on other values.
12836 Sphinx.add_event(name)
12839 Register an event called name.
12840 This is needed to be able to emit it.
12842 Sphinx.set_translator(name, translator_class)
12844 Register or override a Docutils translator class.
12845 This is used to register a custom output translator or to
12847 replace a builtin translator. This allows extensions to use
12848 custom translator and define custom nodes for the translator
12849 (see add_node()).
12850 New in version 1.3.
12852 Changed in version 1.8: Add override keyword.
12855 Sphinx.add_node(node, **kwds)
12858 Register a Docutils node class.
12859 This is necessary for Docutils internals. It may also be used
12861 in the future to validate nodes in the parsed documents.
12862 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
12864 page writers can be given as keyword arguments: the keyword
12865 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
12866 info' or any other supported translators, the value a 2-tuple of
12867 (visit, depart) methods. depart can be None if the visit func‐
12868 tion raises docutils.nodes.SkipNode. Example:
12869 class math(docutils.nodes.Element): pass
12871 def visit_math_html(self, node):
12873 self.body.append(self.starttag(node, 'math'))
12874 def depart_math_html(self, node):
12875 self.body.append('</math>')
12876 app.add_node(math, html=(visit_math_html, depart_math_html))
12878 Obviously, translators for which you don’t specify visitor meth‐
12880 ods will choke on the node when encountered in a document to
12881 translate.
12882 Changed in version 0.5: Added the support for keyword arguments
12884 giving visit functions.
12885 Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
12888 Register a Docutils node class as a numfig target.
12889 Sphinx numbers the node automatically. And then the users can
12891 refer it using numref.
12892 figtype is a type of enumerable nodes. Each figtypes have indi‐
12894 vidual numbering sequences. As a system figtypes, figure, table
12895 and code-block are defined. It is able to add custom nodes to
12896 these default figtypes. It is also able to define new custom
12897 figtype if new figtype is given.
12898 title_getter is a getter function to obtain the title of node.
12900 It takes an instance of the enumerable node, and it must return
12901 its title as string. The title is used to the default title of
12902 references for ref. By default, Sphinx searches docu‐
12903 tils.nodes.caption or docutils.nodes.title from the node as a
12904 title.
12905 Other keyword arguments are used for node visitor functions. See
12907 the Sphinx.add_node() for details.
12908 New in version 1.4.
12910 Sphinx.add_directive(name, func, content, arguments, **options)
12913 Sphinx.add_directive(name, directiveclass)
12915 Register a Docutils directive.
12916 name must be the prospective directive name. There are two pos‐
12918 sible ways to write a directive:
12919 · In the docutils 0.4 style, obj is the directive function.
12921 content, arguments and options are set as attributes on the
12922 function and determine whether the directive has content,
12923 arguments and options, respectively. This style is depre‐
12924 cated.
12925 · In the docutils 0.5 style, obj is the directive class. It
12927 must already have attributes named has_content, required_argu‐
12928 ments, optional_arguments, final_argument_whitespace and
12929 option_spec that correspond to the options for the function
12930 way. See the Docutils docs for details.
12931 The directive class must inherit from the class docu‐
12933 tils.parsers.rst.Directive.
12934 For example, the (already existing) literalinclude directive
12936 would be added like this:
12937 from docutils.parsers.rst import Directive, directives
12939 class LiteralIncludeDirective(Directive):
12941 has_content = True
12942 required_arguments = 1
12943 optional_arguments = 0
12944 final_argument_whitespace = True
12945 option_spec = {
12946 'class': directives.class_option,
12947 'name': directives.unchanged,
12948 }
12949 def run(self):
12951 ...
12952 add_directive('literalinclude', LiteralIncludeDirective)
12954 Changed in version 0.6: Docutils 0.5-style directive classes are
12956 now supported.
12957 Deprecated since version 1.8: Docutils 0.4-style (function
12960 based) directives support is deprecated.
12961 Changed in version 1.8: Add override keyword.
12964 Sphinx.add_role(name, role)
12967 Register a Docutils role.
12968 name must be the role name that occurs in the source, role the
12970 role function. Refer to the Docutils documentation for more
12971 information.
12972 Changed in version 1.8: Add override keyword.
12974 Sphinx.add_generic_role(name, nodeclass)
12977 Register a generic Docutils role.
12978 Register a Docutils role that does nothing but wrap its contents
12980 in the node given by nodeclass.
12981 New in version 0.6.
12983 Changed in version 1.8: Add override keyword.
12986 Sphinx.add_domain(domain)
12989 Register a domain.
12990 Make the given domain (which must be a class; more precisely, a
12992 subclass of Domain) known to Sphinx.
12993 New in version 1.0.
12995 Changed in version 1.8: Add override keyword.
12998 Sphinx.override_domain(domain)
13001 Override a registered domain.
13002 Make the given domain class known to Sphinx, assuming that there
13004 is already a domain with its .name. The new domain must be a
13005 subclass of the existing one.
13006 New in version 1.0.
13008 Deprecated since version 1.8: Integrated to add_domain().
13011 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
13014 **options)
13015 Sphinx.add_directive_to_domain(domain, name, directiveclass)
13017 Register a Docutils directive in a domain.
13018 Like add_directive(), but the directive is added to the domain
13020 named domain.
13021 New in version 1.0.
13023 Changed in version 1.8: Add override keyword.
13026 Sphinx.add_role_to_domain(domain, name, role)
13029 Register a Docutils role in a domain.
13030 Like add_role(), but the role is added to the domain named
13032 domain.
13033 New in version 1.0.
13035 Changed in version 1.8: Add override keyword.
13038 Sphinx.add_index_to_domain(domain, index)
13041 Register a custom index for a domain.
13042 Add a custom index class to the domain named domain. index must
13044 be a subclass of Index.
13045 New in version 1.0.
13047 Changed in version 1.8: Add override keyword.
13050 Sphinx.add_object_type(directivename, rolename, indextemplate='',
13053 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
13054 Register a new object type.
13055 This method is a very convenient way to add a new object type
13057 that can be cross-referenced. It will do this:
13058 · Create a new directive (called directivename) for documenting
13060 an object. It will automatically add index entries if index‐
13061 template is nonempty; if given, it must contain exactly one
13062 instance of %s. See the example below for how the template
13063 will be interpreted.
13064 · Create a new role (called rolename) to cross-reference to
13066 these object descriptions.
13067 · If you provide parse_node, it must be a function that takes a
13069 string and a docutils node, and it must populate the node with
13070 children parsed from the string. It must then return the name
13071 of the item to be used in cross-referencing and index entries.
13072 See the conf.py file in the source for this documentation for
13073 an example.
13074 · The objname (if not given, will default to directivename)
13076 names the type of object. It is used when listing objects,
13077 e.g. in search results.
13078 For example, if you have this call in a custom Sphinx extension:
13080 app.add_object_type('directive', 'dir', 'pair: %s; directive')
13082 you can use this markup in your documents:
13084 .. rst:directive:: function
13086 Document a function.
13088 <...>
13090 See also the :rst:dir:`function` directive.
13092 For the directive, an index entry will be generated as if you
13094 had prepended
13095 .. index:: pair: function; directive
13097 The reference node will be of class literal (so it will be ren‐
13099 dered in a proportional font, as appropriate for code) unless
13100 you give the ref_nodeclass argument, which must be a docutils
13101 node class. Most useful are docutils.nodes.emphasis or docu‐
13102 tils.nodes.strong – you can also use docutils.nodes.generated if
13103 you want no further text decoration. If the text should be
13104 treated as literal (e.g. no smart quote replacement), but not
13105 have typewriter styling, use sphinx.addnodes.literal_emphasis or
13106 sphinx.addnodes.literal_strong.
13107 For the role content, you have the same syntactical possibili‐
13109 ties as for standard Sphinx roles (see xref-syntax).
13110 This method is also available under the deprecated alias
13112 add_description_unit().
13113 Changed in version 1.8: Add override keyword.
13115 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
13118 ref_nodeclass=None, objname='')
13119 Register a new crossref object type.
13120 This method is very similar to add_object_type() except that the
13122 directive it generates must be empty, and will produce no out‐
13123 put.
13124 That means that you can add semantic targets to your sources,
13126 and refer to them using custom roles instead of generic ones
13127 (like ref). Example call:
13128 app.add_crossref_type('topic', 'topic', 'single: %s',
13130 docutils.nodes.emphasis)
13131 Example usage:
13133 .. topic:: application API
13135 The application API
13137 -------------------
13138 Some random text here.
13140 See also :topic:`this section <application API>`.
13142 (Of course, the element following the topic directive needn’t be
13144 a section.)
13145 Changed in version 1.8: Add override keyword.
13147 Sphinx.add_transform(transform)
13150 Register a Docutils transform to be applied after parsing.
13151 Add the standard docutils Transform subclass transform to the
13153 list of transforms that are applied after Sphinx parses a reST
13154 document.
13155 priority range categories for Sphinx transforms
13157 ┌─────────┬────────────────────────────┐
13158 │Priority │ Main purpose in Sphinx │
13159 ├─────────┼────────────────────────────┤
13160 │0-99 │ Fix invalid nodes by docu‐ │
13161 │ │ tils. Translate a doctree. │
13162 ├─────────┼────────────────────────────┤
13163 │100-299 │ Preparation │
13164 ├─────────┼────────────────────────────┤
13165 │300-399 │ early │
13166 ├─────────┼────────────────────────────┤
13167 │400-699 │ main │
13168 ├─────────┼────────────────────────────┤
13169 │700-799 │ Post processing. Deadline │
13170 │ │ to modify text and refer‐ │
13171 │ │ encing. │
13172 ├─────────┼────────────────────────────┤
13173 │800-899 │ Collect referencing and │
13174 │ │ referenced nodes. Domain │
13175 │ │ processing. │
13176 └─────────┴────────────────────────────┘
13177 │900-999 │ Finalize and clean up. │
13179 └─────────┴────────────────────────────┘
13180 refs: Transform Priority Range Categories
13182 Sphinx.add_post_transform(transform)
13184 Register a Docutils transform to be applied before writing.
13185 Add the standard docutils Transform subclass transform to the
13187 list of transforms that are applied before Sphinx writes a docu‐
13188 ment.
13189 Sphinx.add_js_file(filename, **kwargs)
13191 Register a JavaScript file to include in the HTML output.
13192 Add filename to the list of JavaScript files that the default
13194 HTML template will include. The filename must be relative to
13195 the HTML static path , or a full URI with scheme. The keyword
13196 arguments are also accepted for attributes of <script> tag.
13197 Example:
13199 app.add_js_file('example.js')
13201 # => <script src="_static/example.js"></script>
13202 app.add_js_file('example.js', async="async")
13204 # => <script src="_static/example.js" async="async"></script>
13205 New in version 0.5.
13207 Changed in version 1.8: Renamed from app.add_javascript(). And
13210 it allows keyword arguments as attributes of script tag.
13211 Sphinx.add_css_file(filename, **kwargs)
13214 Register a stylesheet to include in the HTML output.
13215 Add filename to the list of CSS files that the default HTML tem‐
13217 plate will include. The filename must be relative to the HTML
13218 static path, or a full URI with scheme. The keyword arguments
13219 are also accepted for attributes of <link> tag.
13220 Example:
13222 app.add_css_file('custom.css')
13224 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
13225 app.add_css_file('print.css', media='print')
13227 # => <link rel="stylesheet" href="_static/print.css"
13228 # type="text/css" media="print" />
13229 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
13231 # => <link rel="alternate stylesheet" href="_static/fancy.css"
13232 # type="text/css" title="fancy" />
13233 New in version 1.0.
13235 Changed in version 1.6: Optional alternate and/or title
13238 attributes can be supplied with the alternate (of boolean type)
13239 and title (a string) arguments. The default is no title and
13240 alternate = False. For more information, refer to the
13241 documentation.
13242 Changed in version 1.8: Renamed from app.add_stylesheet(). And
13245 it allows keyword arguments as attributes of link tag.
13246 Sphinx.add_latex_package(packagename, options=None)
13249 Register a package to include in the LaTeX source code.
13250 Add packagename to the list of packages that LaTeX source code
13252 will include. If you provide options, it will be taken to usep‐
13253 ackage declaration.
13254 app.add_latex_package('mypackage')
13256 # => \usepackage{mypackage}
13257 app.add_latex_package('mypackage', 'foo,bar')
13258 # => \usepackage[foo,bar]{mypackage}
13259 New in version 1.3.
13261 Sphinx.add_lexer(alias, lexer)
13264 Register a new lexer for source code.
13265 Use lexer, which must be an instance of a Pygments lexer class,
13267 to highlight code blocks with the given language alias.
13268 New in version 0.6.
13270 Sphinx.add_autodocumenter(cls)
13273 Register a new documenter class for the autodoc extension.
13274 Add cls as a new documenter class for the sphinx.ext.autodoc
13276 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
13277 menter. This allows to auto-document new types of objects. See
13278 the source of the autodoc module for examples on how to subclass
13279 Documenter.
13280 Todo
13282 Add real docs for Documenter and subclassing
13283 New in version 0.6.
13285 Sphinx.add_autodoc_attrgetter(type, getter)
13288 Register a new getattr-like function for the autodoc extension.
13289 Add getter, which must be a function with an interface compati‐
13291 ble to the getattr() builtin, as the autodoc attribute getter
13292 for objects that are instances of typ. All cases where autodoc
13293 needs to get an attribute of a type are then handled by this
13294 function instead of getattr().
13295 New in version 0.6.
13297 Sphinx.add_search_language(cls)
13300 Register a new language for the HTML search index.
13301 Add cls, which must be a subclass of sphinx.search.Search‐
13303 Language, as a support language for building the HTML full-text
13304 search index. The class must have a lang attribute that indi‐
13305 cates the language it should be used for. See html_search_lan‐
13306 guage.
13307 New in version 1.1.
13309 Sphinx.add_source_suffix(suffix, filetype)
13312 Register a suffix of source files.
13313 Same as source_suffix. The users can override this using the
13315 setting.
13316 New in version 1.8.
13318 Sphinx.add_source_parser(parser)
13321 Register a parser class.
13322 New in version 1.4.
13324 Changed in version 1.8: suffix argument is deprecated. It only
13327 accepts parser argument. Use add_source_suffix() API to regis‐
13328 ter suffix instead.
13329 Changed in version 1.8: Add override keyword.
13332 Sphinx.add_env_collector(collector)
13335 Register an environment collector class.
13336 Refer to collector-api.
13338 New in version 1.6.
13340 Sphinx.add_html_theme(name, theme_path)
13343 Register a HTML Theme.
13344 The name is a name of theme, and path is a full path to the
13346 theme (refs: distribute-your-theme).
13347 New in version 1.6.
13349 Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
13352 Register a math renderer for HTML.
13353 The name is a name of math renderer. Both inline_renderers and
13355 block_renderers are used as visitor functions for the HTML
13356 writer: the former for inline math node (nodes.math), the latter
13357 for block math node (nodes.math_block). Regarding visitor func‐
13358 tions, see add_node() for details.
13359 New in version 1.8.
13361 Sphinx.add_message_catalog(catalog, locale_dir)
13364 Register a message catalog.
13365 The catalog is a name of catalog, and locale_dir is a base path
13367 of message catalog. For more details, see
13368 sphinx.locale.get_translation().
13369 New in version 1.8.
13371 Sphinx.is_parallel_allowed(typ)
13374 Check parallel processing is allowed or not.
13375 typ is a type of processing; 'read' or 'write'.
13377 exception sphinx.application.ExtensionError
13379 All these methods raise this exception if something went wrong
13380 with the extension API.
13381 Emitting events
13383 class sphinx.application.Sphinx
13384 emit(event, *arguments)
13386 Emit event and pass arguments to the callback functions.
13387 Return the return values of all callbacks as a list. Do
13389 not emit core Sphinx events in extensions!
13390 emit_firstresult(event, *arguments)
13392 Emit event and pass arguments to the callback functions.
13393 Return the result of the first callback that doesn’t
13395 return None.
13396 New in version 0.5.
13398 Producing messages / logging
13401 The application object also provides support for emitting leveled mes‐
13402 sages.
13403 NOTE:
13405 There is no “error” call: in Sphinx, errors are defined as things
13406 that stop the build; just raise an exception (‐
13407 sphinx.errors.SphinxError or a custom subclass) to do that.
13408 Deprecated since version 1.6: Please use logging-api instead.
13410 Sphinx.warn(message, location=None, type=None, subtype=None)
13413 Emit a warning.
13414 If location is given, it should either be a tuple of (docname,
13416 lineno) or a string describing the location of the warning as
13417 well as possible.
13418 type and subtype are used to suppress warnings with sup‐
13420 press_warnings.
13421 Deprecated since version 1.6: Use sphinx.util.logging instead.
13423 Sphinx.info(message='', nonl=False)
13426 Emit an informational message.
13427 If nonl is true, don’t emit a newline at the end (which implies
13429 that more info output will follow soon.)
13430 Deprecated since version 1.6: Use sphinx.util.logging instead.
13432 Sphinx.verbose(message, *args, **kwargs)
13435 Emit a verbose informational message.
13436 Deprecated since version 1.6: Use sphinx.util.logging instead.
13438 Sphinx.debug(message, *args, **kwargs)
13441 Emit a debug-level informational message.
13442 Deprecated since version 1.6: Use sphinx.util.logging instead.
13444 Sphinx.debug2(message, *args, **kwargs)
13447 Emit a lowlevel debug-level informational message.
13448 Deprecated since version 1.6: Use sphinx.util.logging instead.
13450 Sphinx runtime information
13453 The application object also provides runtime information as attributes.
13454 Sphinx.srcdir
13456 Source directory.
13457 Sphinx.confdir
13459 Directory containing conf.py.
13460 Sphinx.doctreedir
13462 Directory for storing pickled doctrees.
13463 Sphinx.outdir
13465 Directory for storing built document.
13466 Sphinx core events
13468 These events are known to the core. The arguments shown are given to
13469 the registered event handlers. Use connect() in an extension’s setup
13470 function (note that conf.py can also have a setup function) to connect
13471 handlers to the events. Example:
13472 def source_read_handler(app, docname, source):
13474 print('do something here...')
13475 def setup(app):
13477 app.connect('source-read', source_read_handler)
13478 builder-inited(app)
13480 Emitted when the builder object has been created. It is avail‐
13481 able as app.builder.
13482 config-inited(app, config)
13484 Emitted when the config object has been initialized.
13485 New in version 1.8.
13487 env-get-outdated(app, env, added, changed, removed)
13490 Emitted when the environment determines which source files have
13491 changed and should be re-read. added, changed and removed are
13492 sets of docnames that the environment has determined. You can
13493 return a list of docnames to re-read in addition to these.
13494 New in version 1.1.
13496 env-purge-doc(app, env, docname)
13499 Emitted when all traces of a source file should be cleaned from
13500 the environment, that is, if the source file is removed or
13501 before it is freshly read. This is for extensions that keep
13502 their own caches in attributes of the environment.
13503 For example, there is a cache of all modules on the environment.
13505 When a source file has been changed, the cache’s entries for the
13506 file are cleared, since the module declarations could have been
13507 removed from the file.
13508 New in version 0.5.
13510 env-before-read-docs(app, env, docnames)
13513 Emitted after the environment has determined the list of all
13514 added and changed files and just before it reads them. It
13515 allows extension authors to reorder the list of docnames
13516 (inplace) before processing, or add more docnames that Sphinx
13517 did not consider changed (but never add any docnames that are
13518 not in env.found_docs).
13519 You can also remove document names; do this with caution since
13521 it will make Sphinx treat changed files as unchanged.
13522 New in version 1.3.
13524 source-read(app, docname, source)
13527 Emitted when a source file has been read. The source argument
13528 is a list whose single element is the contents of the source
13529 file. You can process the contents and replace this item to
13530 implement source-level transformations.
13531 For example, if you want to use $ signs to delimit inline math,
13533 like in LaTeX, you can use a regular expression to replace $...$
13534 by :math:`...`.
13535 New in version 0.5.
13537 doctree-read(app, doctree)
13540 Emitted when a doctree has been parsed and read by the environ‐
13541 ment, and is about to be pickled. The doctree can be modified
13542 in-place.
13543 missing-reference(app, env, node, contnode)
13545 Emitted when a cross-reference to a Python module or object can‐
13546 not be resolved. If the event handler can resolve the refer‐
13547 ence, it should return a new docutils node to be inserted in the
13548 document tree in place of the node node. Usually this node is a
13549 reference node containing contnode as a child.
13550 Parameters
13552 · env – The build environment (app.builder.env).
13554 · node – The pending_xref node to be resolved. Its
13556 attributes reftype, reftarget, modname and classname
13557 attributes determine the type and target of the refer‐
13558 ence.
13559 · contnode – The node that carries the text and format‐
13561 ting inside the future reference and should be a child
13562 of the returned reference node.
13563 New in version 0.5.
13565 doctree-resolved(app, doctree, docname)
13568 Emitted when a doctree has been “resolved” by the environment,
13569 that is, all references have been resolved and TOCs have been
13570 inserted. The doctree can be modified in place.
13571 Here is the place to replace custom nodes that don’t have visi‐
13573 tor methods in the writers, so that they don’t cause errors when
13574 the writers encounter them.
13575 env-merge-info(app, env, docnames, other)
13577 This event is only emitted when parallel reading of documents is
13578 enabled. It is emitted once for every subprocess that has read
13579 some documents.
13580 You must handle this event in an extension that stores data in
13582 the environment in a custom location. Otherwise the environment
13583 in the main process will not be aware of the information stored
13584 in the subprocess.
13585 other is the environment object from the subprocess, env is the
13587 environment from the main process. docnames is a set of docu‐
13588 ment names that have been read in the subprocess.
13589 For a sample of how to deal with this event, look at the stan‐
13591 dard sphinx.ext.todo extension. The implementation is often
13592 similar to that of env-purge-doc, only that information is not
13593 removed, but added to the main environment from the other envi‐
13594 ronment.
13595 New in version 1.3.
13597 env-updated(app, env)
13600 Emitted when the update() method of the build environment has
13601 completed, that is, the environment and all doctrees are now
13602 up-to-date.
13603 You can return an iterable of docnames from the handler. These
13605 documents will then be considered updated, and will be
13606 (re-)written during the writing phase.
13607 New in version 0.5.
13609 Changed in version 1.3: The handlers’ return value is now used.
13612 env-check-consistency(app, env)
13615 Emitted when Consistency checks phase. You can check consis‐
13616 tency of metadata for whole of documents.
13617 New in version 1.6: As a experimental event
13619 html-collect-pages(app)
13622 Emitted when the HTML builder is starting to write non-document
13623 pages. You can add pages to write by returning an iterable from
13624 this event consisting of (pagename, context, templatename).
13625 New in version 1.0.
13627 html-page-context(app, pagename, templatename, context, doctree)
13630 Emitted when the HTML builder has created a context dictionary
13631 to render a template with – this can be used to add custom ele‐
13632 ments to the context.
13633 The pagename argument is the canonical name of the page being
13635 rendered, that is, without .html suffix and using slashes as
13636 path separators. The templatename is the name of the template
13637 to render, this will be 'page.html' for all pages from reST doc‐
13638 uments.
13639 The context argument is a dictionary of values that are given to
13641 the template engine to render the page and can be modified to
13642 include custom values. Keys must be strings.
13643 The doctree argument will be a doctree when the page is created
13645 from a reST documents; it will be None when the page is created
13646 from an HTML template alone.
13647 You can return a string from the handler, it will then replace
13649 'page.html' as the HTML template for this page.
13650 New in version 0.4.
13652 Changed in version 1.3: The return value can now specify a tem‐
13655 plate name.
13656 build-finished(app, exception)
13659 Emitted when a build has finished, before Sphinx exits, usually
13660 used for cleanup. This event is emitted even when the build
13661 process raised an exception, given as the exception argument.
13662 The exception is reraised in the application after the event
13663 handlers have run. If the build process raised no exception,
13664 exception will be None. This allows to customize cleanup
13665 actions depending on the exception status.
13666 New in version 0.5.
13668 Checking the Sphinx version
13671 Use this to adapt your extension to API changes in Sphinx.
13672 sphinx.version_info = (1, 8, 4, 'final', 0)
13674 Version info for better programmatic use.
13675 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
13677 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
13678 alpha, beta, rc, final. final always has 0 as the last element.
13679 New in version 1.2: Before version 1.2, check the string
13681 sphinx.__version__.
13682 The Config object
13685 class sphinx.config.Config(*args)
13686 Configuration file abstraction.
13687 The config object makes the values of all config values avail‐
13689 able as attributes.
13690 It is exposed via the sphinx.application.Application.config and
13692 sphinx.environment.Environment.config attributes. For example,
13693 to get the value of language, use either app.config.language or
13694 env.config.language.
13695 The template bridge
13697 class sphinx.application.TemplateBridge
13698 This class defines the interface for a “template bridge”, that
13699 is, a class that renders templates given a template name and a
13700 context.
13701 init(builder, theme=None, dirs=None)
13703 Called by the builder to initialize the template system.
13704 builder is the builder object; you’ll probably want to
13706 look at the value of builder.config.templates_path.
13707 theme is a sphinx.theming.Theme object or None; in the
13709 latter case, dirs can be list of fixed directories to
13710 look for templates.
13711 newest_template_mtime()
13713 Called by the builder to determine if output files are
13714 outdated because of template changes. Return the mtime
13715 of the newest template file that was changed. The
13716 default implementation returns 0.
13717 render(template, context)
13719 Called by the builder to render a template given as a
13720 filename with a specified context (a Python dictionary).
13721 render_string(template, context)
13723 Called by the builder to render a template given as a
13724 string with a specified context (a Python dictionary).
13725 Exceptions
13727 exception sphinx.errors.SphinxError
13728 Base class for Sphinx errors.
13729 This is the base class for “nice” exceptions. When such an
13731 exception is raised, Sphinx will abort the build and present the
13732 exception category and message to the user.
13733 Extensions are encouraged to derive from this exception for
13735 their custom errors.
13736 Exceptions not derived from SphinxError are treated as unex‐
13738 pected and shown to the user with a part of the traceback (and
13739 the full traceback saved in a temporary file).
13740 category
13742 Description of the exception “category”, used in convert‐
13743 ing the exception to a string (“category: message”).
13744 Should be set accordingly in subclasses.
13745 exception sphinx.errors.ConfigError
13747 Configuration error.
13748 exception sphinx.errors.ExtensionError(message, orig_exc=None)
13750 Extension error.
13751 exception sphinx.errors.ThemeError
13753 Theme error.
13754 exception sphinx.errors.VersionRequirementError
13756 Incompatible Sphinx version error.
13757 Build environment API
13759 class sphinx.environment.BuildEnvironment
13760 Attributes
13761 app Reference to the Sphinx (application) object.
13763 config Reference to the Config object.
13765 srcdir Source directory.
13767 doctreedir
13769 Directory for storing pickled doctrees.
13770 found_docs
13772 A set of all existing docnames.
13773 metadata
13775 Dictionary mapping docnames to “metadata” (see metadata).
13776 titles Dictionary mapping docnames to the docutils node for
13778 their main title.
13779 docname
13781 Returns the docname of the document currently being
13782 parsed.
13783 Utility methods
13785 warn(docname, msg, lineno=None, **kwargs)
13787 Emit a warning.
13788 This differs from using app.warn() in that the warning
13790 may not be emitted instantly, but collected for emitting
13791 all warnings after the update of the environment.
13792 warn_node(msg, node, **kwargs)
13794 Like warn(), but with source information taken from node.
13795 doc2path(docname, base=True, suffix=None)
13797 Return the filename for the document name.
13798 If base is True, return absolute path under self.srcdir.
13800 If base is None, return relative path to self.srcdir. If
13801 base is a path string, return absolute path under that.
13802 If suffix is not None, add it instead of con‐
13803 fig.source_suffix.
13804 relfn2path(filename, docname=None)
13806 Return paths to a file referenced from a document, rela‐
13807 tive to documentation root and absolute.
13808 In the input “filename”, absolute filenames are taken as
13810 relative to the source dir, while relative filenames are
13811 relative to the dir of the containing document.
13812 note_dependency(filename)
13814 Add filename as a dependency of the current document.
13815 This means that the document will be rebuilt if this file
13817 changes.
13818 filename should be absolute or relative to the source
13820 directory.
13821 new_serialno(category='')
13823 Return a serial number, e.g. for index entry targets.
13824 The number is guaranteed to be unique in the current doc‐
13826 ument.
13827 note_reread()
13829 Add the current document to the list of documents that
13830 will automatically be re-read at the next build.
13831 Builder API
13833 Todo
13834 Expand this.
13835 class sphinx.builders.Builder
13837 This is the base class for all builders.
13838 These attributes should be set on builder classes:
13840 name = ''
13842 The builder’s name, for the -b command line option.
13843 format = ''
13845 The builder’s output format, or ‘’ if no document output
13846 is produced.
13847 epilog = ''
13849 The message emitted upon successful build completion.
13850 This can be a printf-style template string with the fol‐
13851 lowing keys: outdir, project
13852 supported_image_types = []
13854 The list of MIME types of image formats supported by the
13855 builder. Image files are searched in the order in which
13856 they appear here.
13857 supported_remote_images = False
13859 The builder supports remote images or not.
13860 supported_data_uri_images = False
13862 The builder supports data URIs or not.
13863 default_translator_class = None
13865 default translator class for the builder. This can be
13866 overridden by app.set_translator().
13867 These methods are predefined and will be called from the appli‐
13869 cation:
13870 get_relative_uri(from_, to, typ=None)
13872 Return a relative URI between two source filenames.
13873 May raise environment.NoUri if there’s no way to return a
13875 sensible URI.
13876 build_all()
13878 Build all source files.
13879 build_specific(filenames)
13881 Only rebuild as much as needed for changes in the file‐
13882 names.
13883 build_update()
13885 Only rebuild what was changed or added since last build.
13886 build(docnames, summary=None, method='update')
13888 Main build method.
13889 First updates the environment, and then calls write().
13891 These methods can be overridden in concrete builder classes:
13893 init() Load necessary templates and perform initialization. The
13895 default implementation does nothing.
13896 get_outdated_docs()
13898 Return an iterable of output files that are outdated, or
13899 a string describing what an update build will build.
13900 If the builder does not output individual files corre‐
13902 sponding to source files, return a string here. If it
13903 does, return an iterable of those files that need to be
13904 written.
13905 get_target_uri(docname, typ=None)
13907 Return the target URI for a document name.
13908 typ can be used to qualify the link characteristic for
13910 individual builders.
13911 prepare_writing(docnames)
13913 A place where you can add logic before write_doc() is run
13914 write_doc(docname, doctree)
13916 Where you actually write something to the filesystem.
13917 finish()
13919 Finish the building process.
13920 The default implementation does nothing.
13922 Environment Collector API
13924 class sphinx.environment.collectors.EnvironmentCollector
13925 An EnvironmentCollector is a specific data collector from each
13926 document.
13927 It gathers data and stores BuildEnvironment as a database.
13929 Examples of specific data would be images, download files, sec‐
13930 tion titles, metadatas, index entries and toctrees, etc.
13931 clear_doc(app, env, docname)
13933 Remove specified data of a document.
13934 This method is called on the removal of the document.
13936 get_outdated_docs(app, env, added, changed, removed)
13938 Return a list of docnames to re-read.
13939 This methods is called before reading the documents.
13941 get_updated_docs(app, env)
13943 Return a list of docnames to re-read.
13944 This methods is called after reading the whole of docu‐
13946 ments (experimental).
13947 merge_other(app, env, docnames, other)
13949 Merge in specified data regarding docnames from a differ‐
13950 ent BuildEnvironment object which coming from a subpro‐
13951 cess in parallel builds.
13952 process_doc(app, doctree)
13954 Process a document and gather specific data from it.
13955 This method is called after the document is read.
13957 Docutils markup API
13959 This section describes the API for adding ReST markup elements (roles
13960 and directives).
13961 Roles
13963 Directives
13964 Directives are handled by classes derived from docu‐
13965 tils.parsers.rst.Directive. They have to be registered by an extension
13966 using Sphinx.add_directive() or Sphinx.add_directive_to_domain().
13967 class docutils.parsers.rst.Directive
13969 The markup syntax of the new directive is determined by the fol‐
13970 low five class attributes:
13971 required_arguments = 0
13973 Number of required directive arguments.
13974 optional_arguments = 0
13976 Number of optional arguments after the required argu‐
13977 ments.
13978 final_argument_whitespace = False
13980 May the final argument contain whitespace?
13981 option_spec = None
13983 Mapping of option names to validator functions.
13984 Option validator functions take a single parameter, the
13986 option argument (or None if not given), and should vali‐
13987 date it or convert it to the proper form. They raise
13988 ValueError or TypeError to indicate failure.
13989 There are several predefined and possibly useful valida‐
13991 tors in the docutils.parsers.rst.directives module.
13992 has_content = False
13994 May the directive have content?
13995 New directives must implement the run() method:
13997 run() This method must process the directive arguments, options
13999 and content, and return a list of Docutils/Sphinx nodes
14000 that will be inserted into the document tree at the point
14001 where the directive was encountered.
14002 Instance attributes that are always set on the directive are:
14004 name The directive name (useful when registering the same
14006 directive class under multiple names).
14007 arguments
14009 The arguments given to the directive, as a list.
14010 options
14012 The options given to the directive, as a dictionary map‐
14013 ping option names to validated/converted values.
14014 content
14016 The directive content, if given, as a ViewList.
14017 lineno The absolute line number on which the directive appeared.
14019 This is not always a useful value; use srcline instead.
14020 content_offset
14022 Internal offset of the directive content. Used when
14023 calling nested_parse (see below).
14024 block_text
14026 The string containing the entire directive.
14027 state
14029 state_machine
14031 The state and state machine which controls the parsing.
14032 Used for nested_parse.
14033 ViewLists
14035 Docutils represents document source lines in a class docutils.statema‐
14036 chine.ViewList. This is a list with extended functionality – for one,
14037 slicing creates views of the original list, and also the list contains
14038 information about the source line numbers.
14039 The Directive.content attribute is a ViewList. If you generate content
14041 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
14042 tant for content generation are the following points:
14043 · The constructor takes a list of strings (lines) and a source (docu‐
14045 ment) name.
14046 · The .append() method takes a line and a source name as well.
14048 Parsing directive content as ReST
14050 Many directives will contain more markup that must be parsed. To do
14051 this, use one of the following APIs from the Directive.run() method:
14052 · self.state.nested_parse
14054 · sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
14056 the parsed content.
14057 Both APIs parse the content into a given node. They are used like this:
14059 node = docutils.nodes.paragraph()
14061 # either
14062 nested_parse_with_titles(self.state, self.result, node)
14063 # or
14064 self.state.nested_parse(self.result, 0, node)
14065 NOTE:
14067 sphinx.util.docutils.switch_source_input() allows to change a target
14068 file during nested_parse. It is useful to mixed contents. For
14069 example, sphinx. ext.autodoc uses it to parse docstrings:
14070 from sphinx.util.docutils import switch_source_input
14072 # Switch source_input between parsing content.
14074 # Inside this context, all parsing errors and warnings are reported as
14075 # happened in new source_input (in this case, ``self.result``).
14076 with switch_source_input(self.state, self.result):
14077 node = docutils.nodes.paragraph()
14078 self.state.nested_parse(self.result, 0, node)
14079 Deprecated since version 1.7: Until Sphinx-1.6,
14081 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
14082 now, it is replaced by switch_source_input().
14083 If you don’t need the wrapping node, you can use any concrete node type
14086 and return node.children from the Directive.
14087 SEE ALSO:
14089 Creating directives
14091 HOWTO of the Docutils documentation
14092 Domain API
14094 class sphinx.domains.Domain(env)
14095 A Domain is meant to be a group of “object” description direc‐
14096 tives for objects of a similar nature, and corresponding roles
14097 to create references to them. Examples would be Python modules,
14098 classes, functions etc., elements of a templating language,
14099 Sphinx roles and directives, etc.
14100 Each domain has a separate storage for information about exist‐
14102 ing objects and how to reference them in self.data, which must
14103 be a dictionary. It also must implement several functions that
14104 expose the object information in a uniform way to parts of
14105 Sphinx that allow the user to reference or search for objects in
14106 a domain-agnostic way.
14107 About self.data: since all object and cross-referencing informa‐
14109 tion is stored on a BuildEnvironment instance, the domain.data
14110 object is also stored in the env.domaindata dict under the key
14111 domain.name. Before the build process starts, every active
14112 domain is instantiated and given the environment object; the
14113 domaindata dict must then either be nonexistent or a dictionary
14114 whose ‘version’ key is equal to the domain class’ data_version
14115 attribute. Otherwise, IOError is raised and the pickled envi‐
14116 ronment is discarded.
14117 add_object_type(name, objtype)
14119 Add an object type.
14120 check_consistency()
14122 Do consistency checks (experimental).
14123 clear_doc(docname)
14125 Remove traces of a document in the domain-specific inven‐
14126 tories.
14127 directive(name)
14129 Return a directive adapter class that always gives the
14130 registered directive its full name (‘domain:name’) as
14131 self.name.
14132 get_enumerable_node_type(node)
14134 Get type of enumerable nodes (experimental).
14135 get_full_qualified_name(node)
14137 Return full qualified name for given node.
14138 get_objects()
14140 Return an iterable of “object descriptions”, which are
14141 tuples with five items:
14142 · name – fully qualified name
14144 · dispname – name to display when searching/linking
14146 · type – object type, a key in self.object_types
14148 · docname – the document where it is to be found
14150 · anchor – the anchor name for the object
14152 · priority – how “important” the object is (determines
14154 placement in search results)
14155 · 1: default priority (placed before full-text matches)
14157 · 0: object is important (placed before default-prior‐
14159 ity objects)
14160 · 2: object is unimportant (placed after full-text
14162 matches)
14163 · -1: object should not show up in search at all
14165 get_type_name(type, primary=False)
14167 Return full name for given ObjType.
14168 merge_domaindata(docnames, otherdata)
14170 Merge in data regarding docnames from a different domain‐
14171 data inventory (coming from a subprocess in parallel
14172 builds).
14173 process_doc(env, docname, document)
14175 Process a document after it is read by the environment.
14176 process_field_xref(pnode)
14178 Process a pending xref created in a doc field. For exam‐
14179 ple, attach information about the current scope.
14180 resolve_any_xref(env, fromdocname, builder, target, node, contn‐
14182 ode)
14183 Resolve the pending_xref node with the given target.
14184 The reference comes from an “any” or similar role, which
14186 means that we don’t know the type. Otherwise, the argu‐
14187 ments are the same as for resolve_xref().
14188 The method must return a list (potentially empty) of
14190 tuples ('domain:role', newnode), where 'domain:role' is
14191 the name of a role that could have created the same ref‐
14192 erence, e.g. 'py:func'. newnode is what resolve_xref()
14193 would return.
14194 New in version 1.3.
14196 resolve_xref(env, fromdocname, builder, typ, target, node, con‐
14199 tnode)
14200 Resolve the pending_xref node with the given typ and tar‐
14201 get.
14202 This method should return a new node, to replace the xref
14204 node, containing the contnode which is the markup content
14205 of the cross-reference.
14206 If no resolution can be found, None can be returned; the
14208 xref node will then given to the missing-reference event,
14209 and if that yields no resolution, replaced by contnode.
14210 The method can also raise sphinx.environment.NoUri to
14212 suppress the missing-reference event being emitted.
14213 role(name)
14215 Return a role adapter function that always gives the reg‐
14216 istered role its full name (‘domain:name’) as the first
14217 argument.
14218 dangling_warnings = {}
14220 role name -> a warning message if reference is missing
14221 data = None
14223 data value
14224 data_version = 0
14226 data version, bump this when the format of self.data
14227 changes
14228 directives = {}
14230 directive name -> directive class
14231 enumerable_nodes = {}
14233 node_class -> (enum_node_type, title_getter)
14234 indices = []
14236 a list of Index subclasses
14237 initial_data = {}
14239 data value for a fresh environment
14240 label = ''
14242 domain label: longer, more descriptive (used in messages)
14243 name = ''
14245 domain name: should be short, but unique
14246 object_types = {}
14248 type (usually directive) name -> ObjType instance
14249 roles = {}
14251 role name -> role callable
14252 class sphinx.domains.ObjType(lname, *roles, **attrs)
14254 An ObjType is the description for a type of object that a domain
14255 can document. In the object_types attribute of Domain sub‐
14256 classes, object type names are mapped to instances of this
14257 class.
14258 Constructor arguments:
14260 · lname: localized name of the type (do not include domain name)
14262 · roles: all the roles that can refer to an object of this type
14264 · attrs: object attributes – currently only “searchprio” is
14266 known, which defines the object’s priority in the full-text
14267 search index, see Domain.get_objects().
14268 class sphinx.domains.Index(domain)
14270 An Index is the description for a domain-specific index. To add
14271 an index to a domain, subclass Index, overriding the three name
14272 attributes:
14273 · name is an identifier used for generating file names.
14275 · localname is the section title for the index.
14277 · shortname is a short name for the index, for use in the rela‐
14279 tion bar in HTML output. Can be empty to disable entries in
14280 the relation bar.
14281 and providing a generate() method. Then, add the index class to
14283 your domain’s indices list. Extensions can add indices to
14284 existing domains using add_index_to_domain().
14285 generate(docnames=None)
14287 Return entries for the index given by name. If docnames
14288 is given, restrict to entries referring to these doc‐
14289 names.
14290 The return value is a tuple of (content, collapse), where
14292 collapse is a boolean that determines if sub-entries
14293 should start collapsed (for output formats that support
14294 collapsing sub-entries).
14295 content is a sequence of (letter, entries) tuples, where
14297 letter is the “heading” for the given entries, usually
14298 the starting letter.
14299 entries is a sequence of single entries, where a single
14301 entry is a sequence [name, subtype, docname, anchor,
14302 extra, qualifier, descr]. The items in this sequence
14303 have the following meaning:
14304 · name – the name of the index entry to be displayed
14306 · subtype – sub-entry related type: 0 – normal entry 1 –
14308 entry with sub-entries 2 – sub-entry
14309 · docname – docname where the entry is located
14311 · anchor – anchor for the entry within docname
14313 · extra – extra info for the entry
14315 · qualifier – qualifier for the description
14317 · descr – description for the entry
14319 Qualifier and description are not rendered e.g. in LaTeX
14321 output.
14322 Parser API
14324 The docutils documentation describes parsers as follows:
14325 The Parser analyzes the input document and creates a node tree rep‐
14326 resentation.
14327 In Sphinx, the parser modules works as same as docutils. The parsers
14329 are registered to Sphinx by extensions using Application APIs;
14330 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
14331 The source suffix is a mapping from file suffix to file type. For
14333 example, .rst file is mapped to 'restructuredtext' type. Sphinx uses
14334 the file type to looking for parsers from registered list. On search‐
14335 ing, Sphinx refers to the Parser.supported attribute and picks up a
14336 parser which contains the file type in the attribute.
14337 The users can override the source suffix mappings using source_suffix
14339 like following:
14340 # a mapping from file suffix to file types
14342 source_suffix = {
14343 '.rst': 'restructuredtext',
14344 '.md': 'markdown',
14345 }
14346 You should indicate file types your parser supports. This will allow
14348 users to configure their settings appropriately.
14349 class sphinx.parsers.Parser
14351 A base class of source parsers. The additional parsers should
14352 inherit this class instead of docutils.parsers.Parser. Compared
14353 with docutils.parsers.Parser, this class improves accessibility
14354 to Sphinx APIs.
14355 The subclasses can access following objects and functions:
14357 self.app
14359 The application object (sphinx.application.Sphinx)
14360 self.config
14362 The config object (sphinx.config.Config)
14363 self.env
14365 The environment object (sphinx.environment.BuildEnviron‐
14366 ment)
14367 self.warn()
14369 Emit a warning. (Same as sphinx.applica‐
14370 tion.Sphinx.warn())
14371 self.info()
14373 Emit a informational message. (Same as sphinx.applica‐
14374 tion.Sphinx.info())
14375 Deprecated since version 1.6: warn() and info() is deprecated.
14377 Use sphinx.util.logging instead.
14378 Doctree node classes added by Sphinx
14381 Nodes for domain-specific object descriptions
14382 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
14383 Node for object descriptions.
14384 This node is similar to a “definition list” with one definition.
14386 It contains one or more desc_signature and a desc_content.
14387 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
14389 **attributes)
14390 Node for object signatures.
14391 The “term” part of the custom Sphinx definition list.
14393 As default the signature is a single line signature, but set
14395 is_multiline = True to describe a multi-line signature. In that
14396 case all child nodes must be desc_signature_line nodes.
14397 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
14399 dren, **attributes)
14400 Node for a line in a multi-line object signatures.
14401 It should only be used in a desc_signature with is_multiline
14403 set. Set add_permalink = True for the line that should get the
14404 permalink.
14405 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
14407 **attributes)
14408 Node for additional name parts (module name, class name).
14409 class sphinx.addnodes.desc_type(rawsource='', text='', *children,
14411 **attributes)
14412 Node for return types or object type names.
14413 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
14415 **attributes)
14416 Node for a “returns” annotation (a la -> in Python).
14417 class sphinx.addnodes.desc_name(rawsource='', text='', *children,
14419 **attributes)
14420 Node for the main object name.
14421 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
14423 dren, **attributes)
14424 Node for a general parameter list.
14425 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
14427 **attributes)
14428 Node for a single parameter.
14429 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
14431 **attributes)
14432 Node for marking optional parts of the parameter list.
14433 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
14435 **attributes)
14436 Node for signature annotations (not Python 3-style annotations).
14437 class sphinx.addnodes.desc_content(rawsource='', *children,
14439 **attributes)
14440 Node for object description content.
14441 This is the “definition” part of the custom Sphinx definition
14443 list.
14444 New admonition-like constructs
14446 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
14447 **attributes)
14448 Node for version change entries.
14449 Currently used for “versionadded”, “versionchanged” and “depre‐
14451 cated” directives.
14452 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
14454 Custom “see also” admonition.
14455 Other paragraph-level nodes
14457 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
14458 dren, **attributes)
14459 Node for a compact paragraph (which never makes a <p> node).
14460 New inline nodes
14462 class sphinx.addnodes.index(rawsource='', text='', *children,
14463 **attributes)
14464 Node for index entries.
14465 This node is created by the index directive and has one
14467 attribute, entries. Its value is a list of 5-tuples of (entry‐
14468 type, entryname, target, ignored, key).
14469 entrytype is one of “single”, “pair”, “double”, “triple”.
14471 key is categorization characters (usually a single character)
14473 for general index page. For the details of this, please see
14474 also: glossary and issue #2320.
14475 class sphinx.addnodes.pending_xref(rawsource='', *children,
14477 **attributes)
14478 Node for cross-references that cannot be resolved without com‐
14479 plete information about all documents.
14480 These nodes are resolved before writing output, in BuildEnviron‐
14482 ment.resolve_references.
14483 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
14485 dren, **attributes)
14486 Node that behaves like emphasis, but further text processors are
14487 not applied (e.g. smartypants for HTML output).
14488 class sphinx.addnodes.abbreviation(rawsource='', text='', *children,
14490 **attributes)
14491 Node for abbreviations with explanations.
14492 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
14494 dren, **attributes)
14495 Node for download references, similar to pending_xref.
14496 Special nodes
14498 class sphinx.addnodes.only(rawsource='', *children, **attributes)
14499 Node for “only” directives (conditional inclusion based on
14500 tags).
14501 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
14503 Node for meta directive – same as docutils’ standard meta node,
14504 but pickleable.
14505 class sphinx.addnodes.highlightlang(rawsource='', *children,
14507 **attributes)
14508 Inserted to set the highlight language and line number options
14509 for subsequent code blocks.
14510 You should not need to generate the nodes below in extensions.
14512 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
14514 Node to insert a glossary.
14515 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
14517 Node for inserting a “TOC tree”.
14518 class sphinx.addnodes.start_of_file(rawsource='', *children,
14520 **attributes)
14521 Node to mark start of a new file, used in the LaTeX builder
14522 only.
14523 class sphinx.addnodes.productionlist(rawsource='', *children,
14525 **attributes)
14526 Node for grammar production lists.
14527 Contains production nodes.
14529 class sphinx.addnodes.production(rawsource='', text='', *children,
14531 **attributes)
14532 Node for a single grammar production rule.
14533 Logging API
14535 sphinx.util.logging.getLogger(name)
14536 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
14537 Sphinx logger always uses sphinx.* namespace to be independent
14539 from settings of root logger. It ensures logging is consistent
14540 even if a third-party extension or imported application resets
14541 logger settings.
14542 Example usage:
14544 >>> from sphinx.util import logging
14546 >>> logger = logging.getLogger(__name__)
14547 >>> logger.info('Hello, this is an extension!')
14548 Hello, this is an extension!
14549 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
14551 LoggerAdapter allowing type and subtype keywords.
14552 error(msg, *args, **kwargs)
14554 critical(msg, *args, **kwargs)
14556 warning(msg, *args, **kwargs)
14558 Logs a message on this logger with the specified level.
14559 Basically, the arguments are as with python’s logging
14560 module.
14561 In addition, Sphinx logger supports following keyword
14563 arguments:
14564 type, *subtype*
14566 Categories of warning logs. It is used to sup‐
14567 press warnings by suppress_warnings setting.
14568 location
14570 Where the warning happened. It is used to include
14571 the path and line number in each log. It allows
14572 docname, tuple of docname and line number and
14573 nodes:
14574 logger = sphinx.util.logging.getLogger(__name__)
14576 logger.warning('Warning happened!', location='index')
14577 logger.warning('Warning happened!', location=('chapter1/index', 10))
14578 logger.warning('Warning happened!', location=some_node)
14579 color The color of logs. By default, error level logs
14581 are colored as "darkred", critical level ones is
14582 not colored, and warning level ones are colored as
14583 "red".
14584 log(level, msg, *args, **kwargs)
14586 info(msg, *args, **kwargs)
14588 verbose(msg, *args, **kwargs)
14590 debug(msg, *args, **kwargs)
14592 Logs a message to this logger with the specified level.
14593 Basically, the arguments are as with python’s logging
14594 module.
14595 In addition, Sphinx logger supports following keyword
14597 arguments:
14598 nonl If true, the logger does not fold lines at the end
14600 of the log message. The default is False.
14601 location
14603 Where the message emitted. For more detail, see
14604 SphinxLoggerAdapter.warning().
14605 color The color of logs. By default, info and verbose
14607 level logs are not colored, and debug level ones
14608 are colored as "darkgray".
14609 sphinx.util.logging.pending_logging()
14611 Contextmanager to pend logging all logs temporary.
14612 For example:
14614 >>> with pending_logging():
14616 >>> logger.warning('Warning message!') # not flushed yet
14617 >>> some_long_process()
14618 >>>
14619 Warning message! # the warning is flushed here
14620 sphinx.util.logging.pending_warnings()
14622 Contextmanager to pend logging warnings temporary.
14623 Similar to pending_logging().
14625 i18n API
14627 sphinx.locale.init(locale_dirs, language, catalog='sphinx', names‐
14628 pace='general')
14629 Look for message catalogs in locale_dirs and ensure that there
14630 is at least a NullTranslations catalog set in translators. If
14631 called multiple times or if several .mo files are found, their
14632 contents are merged together (thus making init reentrant).
14633 sphinx.locale.init_console(locale_dir, catalog)
14635 Initialize locale for console.
14636 New in version 1.8.
14638 sphinx.locale.get_translation(catalog, namespace='general')
14641 Get a translation function based on the catalog and namespace.
14642 The extension can use this API to translate the messages on the
14644 extension:
14645 import os
14647 from sphinx.locale import get_translation
14648 _ = get_translation(__name__)
14650 text = _('Hello Sphinx!')
14651 def setup(app):
14654 package_dir = path.abspath(path.dirname(__file__))
14655 locale_dir = os.path.join(package_dir, 'locales')
14656 app.add_message_catalog(__name__, locale_dir)
14657 With this code, sphinx searches a message catalog from ${pack‐
14659 age_dir}/locales/${language}/LC_MESSAGES/${__name__}.mo The lan‐
14660 guage is used for the searching.
14661 New in version 1.8.
14663 sphinx.locale._(message, *args)
14666 Translation function for messages on documentation (menu,
14667 labels, themes and so on). This function follows language set‐
14668 ting.
14669 sphinx.locale.__(message, *args)
14671 Translation function for console messages This function follows
14672 locale setting (LC_ALL, LC_MESSAGES and so on).
14673 Utilities
14675 Sphinx provides utility classes and functions to develop extensions.
14676 Base classes for components
14678 These base classes are useful to allow your extensions to obtain Sphinx
14679 components (e.g. Config, BuildEnvironment and so on) easily.
14680 NOTE:
14682 The subclasses of them might not work with bare docutils because
14683 they are strongly coupled with Sphinx.
14684 class sphinx.transforms.SphinxTransform(document, startnode=None)
14686 A base class of Transforms.
14687 Compared with docutils.transforms.Transform, this class improves
14689 accessibility to Sphinx APIs.
14690 app Reference to the Sphinx object.
14692 config Reference to the Config object.
14694 env Reference to the BuildEnvironment object.
14696 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
14698 content, lineno, content_offset, block_text, state, state_machine)
14699 A base class for Sphinx directives.
14700 This class provides helper methods for Sphinx directives.
14702 NOTE:
14704 The subclasses of this class might not work with docutils.
14705 This class is strongly coupled with Sphinx.
14706 config Reference to the Config object.
14708 env Reference to the BuildEnvironment object.
14710 class sphinx.transforms.post_transforms.images.ImageConverter(*args,
14712 **kwargs)
14713 A base class for image converters.
14714 An image converter is kind of Docutils transform module. It is
14716 used to convert image files which does not supported by builder
14717 to appropriate format for that builder.
14718 For example, LaTeX builder supports PDF, PNG and JPEG as image
14720 formats. However it does not support SVG images. For such
14721 case, to use image converters allows to embed these unsupported
14722 images into the document. One of image converters;
14723 sphinx.ext.imgconverter can convert a SVG image to PNG format
14724 using Imagemagick internally.
14725 There are three steps to make your custom image converter:
14727 1. Make a subclass of ImageConverter class
14729 2. Override conversion_rules, is_available() and convert()
14731 3. Register your image converter to Sphinx using
14733 Sphinx.add_post_transform()
14734 convert(_from, _to)
14736 Convert a image file to expected format.
14737 _from is a path for source image file, and _to is a path
14739 for destination file.
14740 is_available()
14742 Return the image converter is available or not.
14743 conversion_rules = []
14745 A conversion rules the image converter supports. It is
14746 represented as a list of pair of source image format
14747 (mimetype) and destination one:
14748 conversion_rules = [
14750 ('image/svg+xml', 'image/png'),
14751 ('image/gif', 'image/png'),
14752 ('application/pdf', 'image/png'),
14753 ]
14754 Deprecated APIs
14756 On developing Sphinx, we are always careful to the compatibility of our
14757 APIs. But, sometimes, the change of interface are needed for some rea‐
14758 sons. In such cases, we’ve marked them as deprecated. And they are
14759 kept during the two major versions (for more details, please see depre‐
14760 cation-policy).
14761 The following is a list of deprecated interfaces.
14763 deprecated APIs
14765┌─────────────────────────────────────────────────────┬────────────┬───────────┬───────────────────────────────────────┐
14766│Target │ Deprecated │ (will be) │ Alternatives │
14767│ │ │ Removed │ │
14768├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14769│highlightlang │ 1.8 │ 4.0 │ highlight │
14770├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14771│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
14772├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14773│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
14774├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14775│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
14776├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14777│content arguments of │ 1.8 │ 3.0 │ N/A │
14778│sphinx.util.image.guess_mime‐ │ │ │ │
14779│type() │ │ │ │
14780├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14781│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
14782│sphinx.util.i18n.find_cata‐ │ │ │ │
14783│log_source_files() │ │ │ │
14784├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14785│sphinx.io.SphinxI18nReader.set_lineno_for_reporter() │ 1.8 │ 3.0 │ N/A │
14786└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
14787│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
14789├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14790│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.change‐ │
14791│ │ │ │ set.VersionChanges │
14792├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14793│sphinx.highlighting.PygmentsBridge.unhighlight() │ 1.8 │ 3.0 │ N/A │
14794├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14795│trim_doctest_flags arguments of sphinx.highlight‐ │ 1.8 │ 3.0 │ N/A │
14796│ing.PygmentsBridge │ │ │ │
14797├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14798│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
14799├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14800│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.Math‐ │
14801│ │ │ │ Domain │
14802├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14803│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.direc‐ │
14804│ │ │ │ tives.patches.MathDirec‐ │
14805│ │ │ │ tive │
14806├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14807│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
14808│ │ │ │ tils.parsers.rst.roles.math_role() │
14809├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14810│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
14811├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14812│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
14813├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14814│sphinx.ext.mathbase.get_node_equation_number() │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
14815│ │ │ │ tion_number() │
14816├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14817│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
14818│ │ │ │ math() │
14819├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14820│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
14821├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14822│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
14823├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14824│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.latex.nodes.math_ref‐ │
14825│ │ │ │ erence │
14826├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14827│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
14828├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14829│sphinx.writers.latex.Table.caption_footnotetexts │ 1.8 │ 3.0 │ N/A │
14830├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14831│sphinx.writers.latex.Table.header_footnotetexts │ 1.8 │ 3.0 │ N/A │
14832├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14833│sphinx.writers.latex.LaTeXTranslator.footnotestack │ 1.8 │ 3.0 │ N/A │
14834├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14835│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
14836│tainer_literal_block │ │ │ │
14837├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14838│sphinx.writers.latex.LaTeXTranslator.next_sec‐ │ 1.8 │ 3.0 │ N/A │
14839│tion_ids │ │ │ │
14840├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14841│sphinx.writers.latex.LaTeXTranslator.next_hyper‐ │ 1.8 │ 3.0 │ N/A │
14842│link_ids │ │ │ │
14843├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14844│sphinx.writers.latex.LaTeXTranslator.restrict_foot‐ │ 1.8 │ 3.0 │ N/A │
14845│note() │ │ │ │
14846├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14847│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
14848│strict_footnote() │ │ │ │
14849├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14850│sphinx.writers.latex.LaTeXTranslator.push_hyper‐ │ 1.8 │ 3.0 │ N/A │
14851│link_ids() │ │ │ │
14852├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14853│sphinx.writers.latex.LaTeXTranslator.pop_hyper‐ │ 1.8 │ 3.0 │ N/A │
14854│link_ids() │ │ │ │
14855├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14856│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
14857├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14858│sphinx.writers.latex.LaTeXTranslator.hlsettingstack │ 1.8 │ 3.0 │ N/A │
14859├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14860│sphinx.writers.latex.ExtBabel.get_shorthandoff() │ 1.8 │ 3.0 │ N/A │
14861├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14862│sphinx.writers.html.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
14863├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14864│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
14865│lang_base() │ │ │ │
14866├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14867│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
14868│langopts() │ │ │ │
14869├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14870│sphinx.writers.html.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
14871│nenothreshold() │ │ │ │
14872├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14873│sphinx.writers.html5.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
14874├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14875│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
14876│lang_base() │ │ │ │
14877├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14878│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
14879│langopts() │ │ │ │
14880├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14881│sphinx.writers.html5.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
14882│nenothreshold() │ │ │ │
14883├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14884│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
14885│tor.check_latex_elements() │ │ │ │
14886├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14887│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
14888├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14889│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
14890├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14891│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_confval_types() │
14892├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14893│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
14894│fig.__init__() │ │ │ │
14895├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14896│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
14897├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14898│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
14899├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14900│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
14901├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14902│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
14903├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14904│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
14905├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14906│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
14907├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14908│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
14909├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14910│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
14911├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14912│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
14913├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14914│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
14915├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14916│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
14917├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14918│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
14919├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14920│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
14921└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
14922│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
14925├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14926│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
14927├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14928│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
14929├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14930│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
14931├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14932│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
14933├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14934│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
14935├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14936│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
14937├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14938│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
14939├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14940│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
14941├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14942│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
14943├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14944│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
14945├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14946│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
14947├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14948│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
14949├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14950│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
14951├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14952│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
14953├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14954│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
14955├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14956│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.inspect_main() │
14957├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14958│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
14959├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14960│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
14961├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14962│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
14963│ │ │ │ tils.switch_source_input() │
14964├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14965│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
14966├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14967│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
14968├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14969│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
14970├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14971│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
14972├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14973│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
14974├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14975│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
14976│ │ │ │ ment.adapters.toctree) │
14977├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14978│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
14979│ │ │ │ sphinx.environment.adapters.toctree) │
14980├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14981│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
14982│ │ │ │ sphinx.environment.adapters.toctree) │
14983├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14984│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
14985│ │ │ │ sphinx.environment.adapters.indexen‐ │
14986│ │ │ │ tries) │
14987├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14988│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
14989├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14990│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
14991├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14992│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
14993├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14994│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
14995├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14996│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
14997├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
14998│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
14999│ │ │ │ tive_helper() │
15000├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
15001│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
15002├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
15003│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__version_info__ │
15004└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
15005 NOTE:
15007 On deprecating on public APIs (internal functions and classes), we
15008 also follow the policy as much as possible.
15009
15011 New in version 1.1.
15012 Sphinx provides a Python API to easily integrate Sphinx documentation
15015 into your web application. To learn more read the websupportquick‐
15016 start.
15017 Web Support Quick Start
15019 Building Documentation Data
15020 To make use of the web support package in your application you’ll need
15021 to build the data it uses. This data includes pickle files represent‐
15022 ing documents, search indices, and node data that is used to track
15023 where comments and other things are in a document. To do this you will
15024 need to create an instance of the WebSupport class and call its build()
15025 method:
15026 from sphinxcontrib.websupport import WebSupport
15028 support = WebSupport(srcdir='/path/to/rst/sources/',
15030 builddir='/path/to/build/outdir',
15031 search='xapian')
15032 support.build()
15034 This will read reStructuredText sources from srcdir and place the nec‐
15036 essary data in builddir. The builddir will contain two sub-directo‐
15037 ries: one named “data” that contains all the data needed to display
15038 documents, search through documents, and add comments to documents.
15039 The other directory will be called “static” and contains static files
15040 that should be served from “/static”.
15041 NOTE:
15043 If you wish to serve static files from a path other than “/static”,
15044 you can do so by providing the staticdir keyword argument when cre‐
15045 ating the WebSupport object.
15046 Integrating Sphinx Documents Into Your Webapp
15048 Now that the data is built, it’s time to do something useful with it.
15049 Start off by creating a WebSupport object for your application:
15050 from sphinxcontrib.websupport import WebSupport
15052 support = WebSupport(datadir='/path/to/the/data',
15054 search='xapian')
15055 You’ll only need one of these for each set of documentation you will be
15057 working with. You can then call its get_document() method to access
15058 individual documents:
15059 contents = support.get_document('contents')
15061 This will return a dictionary containing the following items:
15063 · body: The main body of the document as HTML
15065 · sidebar: The sidebar of the document as HTML
15067 · relbar: A div containing links to related documents
15069 · title: The title of the document
15071 · css: Links to CSS files used by Sphinx
15073 · script: JavaScript containing comment options
15075 This dict can then be used as context for templates. The goal is to be
15077 easy to integrate with your existing templating system. An example
15078 using Jinja2 is:
15079 {%- extends "layout.html" %}
15081 {%- block title %}
15083 {{ document.title }}
15084 {%- endblock %}
15085 {% block css %}
15087 {{ super() }}
15088 {{ document.css|safe }}
15089 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
15090 {% endblock %}
15091 {%- block script %}
15093 {{ super() }}
15094 {{ document.script|safe }}
15095 {%- endblock %}
15096 {%- block relbar %}
15098 {{ document.relbar|safe }}
15099 {%- endblock %}
15100 {%- block body %}
15102 {{ document.body|safe }}
15103 {%- endblock %}
15104 {%- block sidebar %}
15106 {{ document.sidebar|safe }}
15107 {%- endblock %}
15108 Authentication
15110 To use certain features such as voting, it must be possible to authen‐
15111 ticate users. The details of the authentication are left to your
15112 application. Once a user has been authenticated you can pass the
15113 user’s details to certain WebSupport methods using the username and
15114 moderator keyword arguments. The web support package will store the
15115 username with comments and votes. The only caveat is that if you allow
15116 users to change their username you must update the websupport package’s
15117 data:
15118 support.update_username(old_username, new_username)
15120 username should be a unique string which identifies a user, and modera‐
15122 tor should be a boolean representing whether the user has moderation
15123 privileges. The default value for moderator is False.
15124 An example Flask function that checks whether a user is logged in and
15126 then retrieves a document is:
15127 from sphinxcontrib.websupport.errors import *
15129 @app.route('/<path:docname>')
15131 def doc(docname):
15132 username = g.user.name if g.user else ''
15133 moderator = g.user.moderator if g.user else False
15134 try:
15135 document = support.get_document(docname, username, moderator)
15136 except DocumentNotFoundError:
15137 abort(404)
15138 return render_template('doc.html', document=document)
15139 The first thing to notice is that the docname is just the request path.
15141 This makes accessing the correct document easy from a single view. If
15142 the user is authenticated, then the username and moderation status are
15143 passed along with the docname to get_document(). The web support pack‐
15144 age will then add this data to the COMMENT_OPTIONS that are used in the
15145 template.
15146 NOTE:
15148 This only works if your documentation is served from your document
15149 root. If it is served from another directory, you will need to pre‐
15150 fix the url route with that directory, and give the docroot keyword
15151 argument when creating the web support object:
15152 support = WebSupport(..., docroot='docs')
15154 @app.route('/docs/<path:docname>')
15156 Performing Searches
15158 To use the search form built-in to the Sphinx sidebar, create a func‐
15159 tion to handle requests to the url ‘search’ relative to the documenta‐
15160 tion root. The user’s search query will be in the GET parameters, with
15161 the key q. Then use the get_search_results() method to retrieve search
15162 results. In Flask that would be like this:
15163 @app.route('/search')
15165 def search():
15166 q = request.args.get('q')
15167 document = support.get_search_results(q)
15168 return render_template('doc.html', document=document)
15169 Note that we used the same template to render our search results as we
15171 did to render our documents. That’s because get_search_results()
15172 returns a context dict in the same format that get_document() does.
15173 Comments & Proposals
15175 Now that this is done it’s time to define the functions that handle the
15176 AJAX calls from the script. You will need three functions. The first
15177 function is used to add a new comment, and will call the web support
15178 method add_comment():
15179 @app.route('/docs/add_comment', methods=['POST'])
15181 def add_comment():
15182 parent_id = request.form.get('parent', '')
15183 node_id = request.form.get('node', '')
15184 text = request.form.get('text', '')
15185 proposal = request.form.get('proposal', '')
15186 username = g.user.name if g.user is not None else 'Anonymous'
15187 comment = support.add_comment(text, node_id='node_id',
15188 parent_id='parent_id',
15189 username=username, proposal=proposal)
15190 return jsonify(comment=comment)
15191 You’ll notice that both a parent_id and node_id are sent with the
15193 request. If the comment is being attached directly to a node, parent_id
15194 will be empty. If the comment is a child of another comment, then
15195 node_id will be empty. Then next function handles the retrieval of com‐
15196 ments for a specific node, and is aptly named get_data():
15197 @app.route('/docs/get_comments')
15199 def get_comments():
15200 username = g.user.name if g.user else None
15201 moderator = g.user.moderator if g.user else False
15202 node_id = request.args.get('node', '')
15203 data = support.get_data(node_id, username, moderator)
15204 return jsonify(**data)
15205 The final function that is needed will call process_vote(), and will
15207 handle user votes on comments:
15208 @app.route('/docs/process_vote', methods=['POST'])
15210 def process_vote():
15211 if g.user is None:
15212 abort(401)
15213 comment_id = request.form.get('comment_id')
15214 value = request.form.get('value')
15215 if value is None or comment_id is None:
15216 abort(400)
15217 support.process_vote(comment_id, g.user.id, value)
15218 return "success"
15219 Comment Moderation
15221 By default, all comments added through add_comment() are automatically
15222 displayed. If you wish to have some form of moderation, you can pass
15223 the displayed keyword argument:
15224 comment = support.add_comment(text, node_id='node_id',
15226 parent_id='parent_id',
15227 username=username, proposal=proposal,
15228 displayed=False)
15229 You can then create a new view to handle the moderation of comments.
15231 It will be called when a moderator decides a comment should be accepted
15232 and displayed:
15233 @app.route('/docs/accept_comment', methods=['POST'])
15235 def accept_comment():
15236 moderator = g.user.moderator if g.user else False
15237 comment_id = request.form.get('id')
15238 support.accept_comment(comment_id, moderator=moderator)
15239 return 'OK'
15240 Rejecting comments happens via comment deletion.
15242 To perform a custom action (such as emailing a moderator) when a new
15244 comment is added but not displayed, you can pass callable to the Web‐
15245 Support class when instantiating your support object:
15246 def moderation_callback(comment):
15248 """Do something..."""
15249 support = WebSupport(..., moderation_callback=moderation_callback)
15251 The moderation callback must take one argument, which will be the same
15253 comment dict that is returned by add_comment().
15254 The WebSupport Class
15256 class sphinxcontrib.websupport.WebSupport
15257 The main API class for the web support package. All interac‐
15258 tions with the web support package should occur through this
15259 class.
15260 The class takes the following keyword arguments:
15262 srcdir The directory containing reStructuredText source files.
15264 builddir
15266 The directory that build data and static files should be
15267 placed in. This should be used when creating a
15268 WebSupport object that will be used to build data.
15269 datadir
15271 The directory that the web support data is in. This
15272 should be used when creating a WebSupport object that
15273 will be used to retrieve data.
15274 search This may contain either a string (e.g. ‘xapian’) refer‐
15276 encing a built-in search adapter to use, or an instance
15277 of a subclass of BaseSearch.
15278 storage
15280 This may contain either a string representing a database
15281 uri, or an instance of a subclass of StorageBackend. If
15282 this is not provided, a new sqlite database will be cre‐
15283 ated.
15284 moderation_callback
15286 A callable to be called when a new comment is added that
15287 is not displayed. It must accept one argument: a dictio‐
15288 nary representing the comment that was added.
15289 staticdir
15291 If the static files should be created in a different
15292 location and not in '/static', this should be a string
15293 with the name of that location (e.g. builddir +
15294 '/static_files').
15295 NOTE:
15297 If you specify staticdir, you will typically want to
15298 adjust staticroot accordingly.
15299 staticroot
15301 If the static files are not served from '/static', this
15302 should be a string with the name of that location (e.g.
15303 '/static_files').
15304 docroot
15306 If the documentation is not served from the base path of
15307 a URL, this should be a string specifying that path (e.g.
15308 'docs').
15309 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
15311 support from sphinx.websupport. Please add sphinxcontrib-websupport
15312 package in your dependency and use moved class instead.
15313 Methods
15316 WebSupport.build()
15317 Build the documentation. Places the data into the outdir direc‐
15318 tory. Use it like this:
15319 support = WebSupport(srcdir, builddir, search='xapian')
15321 support.build()
15322 This will read reStructured text files from srcdir. Then it will
15324 build the pickles and search index, placing them into builddir.
15325 It will also save node data to the database.
15326 WebSupport.get_document(docname, username='', moderator=False)
15328 Load and return a document from a pickle. The document will be a
15329 dict object which can be used to render a template:
15330 support = WebSupport(datadir=datadir)
15332 support.get_document('index', username, moderator)
15333 In most cases docname will be taken from the request path and
15335 passed directly to this function. In Flask, that would be some‐
15336 thing like this:
15337 @app.route('/<path:docname>')
15339 def index(docname):
15340 username = g.user.name if g.user else ''
15341 moderator = g.user.moderator if g.user else False
15342 try:
15343 document = support.get_document(docname, username,
15344 moderator)
15345 except DocumentNotFoundError:
15346 abort(404)
15347 render_template('doc.html', document=document)
15348 The document dict that is returned contains the following items
15350 to be used during template rendering.
15351 · body: The main body of the document as HTML
15353 · sidebar: The sidebar of the document as HTML
15355 · relbar: A div containing links to related documents
15357 · title: The title of the document
15359 · css: Links to css files used by Sphinx
15361 · script: Javascript containing comment options
15363 This raises DocumentNotFoundError if a document matching docname
15365 is not found.
15366 Parameters
15368 docname – the name of the document to load.
15369 WebSupport.get_data(node_id, username=None, moderator=False)
15371 Get the comments and source associated with node_id. If username
15372 is given vote information will be included with the returned
15373 comments. The default CommentBackend returns a dict with two
15374 keys, source, and comments. source is raw source of the node and
15375 is used as the starting point for proposals a user can add. com‐
15376 ments is a list of dicts that represent a comment, each having
15377 the following items:
15378 ┌──────────────┬────────────────────────────┐
15380 │Key │ Contents │
15381 ├──────────────┼────────────────────────────┤
15382 │text │ The comment text. │
15383 ├──────────────┼────────────────────────────┤
15384 │username │ The username that was │
15385 │ │ stored with the comment. │
15386 ├──────────────┼────────────────────────────┤
15387 │id │ The comment’s unique iden‐ │
15388 │ │ tifier. │
15389 ├──────────────┼────────────────────────────┤
15390 │rating │ The comment’s current rat‐ │
15391 │ │ ing. │
15392 ├──────────────┼────────────────────────────┤
15393 │age │ The time in seconds since │
15394 │ │ the comment was added. │
15395 ├──────────────┼────────────────────────────┤
15396 │time │ A dict containing time │
15397 │ │ information. It contains │
15398 │ │ the following keys: year, │
15399 │ │ month, day, hour, minute, │
15400 │ │ second, iso, and delta. │
15401 │ │ iso is the time formatted │
15402 │ │ in ISO 8601 format. delta │
15403 │ │ is a printable form of how │
15404 │ │ old the comment is (e.g. │
15405 │ │ “3 hours ago”). │
15406 ├──────────────┼────────────────────────────┤
15407 │vote │ If user_id was given, this │
15408 │ │ will be an integer repre‐ │
15409 │ │ senting the vote. 1 for an │
15410 │ │ upvote, -1 for a downvote, │
15411 │ │ or 0 if unvoted. │
15412 ├──────────────┼────────────────────────────┤
15413 │node │ The id of the node that │
15414 │ │ the comment is attached │
15415 │ │ to. If the comment’s par‐ │
15416 │ │ ent is another comment │
15417 │ │ rather than a node, this │
15418 │ │ will be null. │
15419 ├──────────────┼────────────────────────────┤
15420 │parent │ The id of the comment that │
15421 │ │ this comment is attached │
15422 │ │ to if it is not attached │
15423 │ │ to a node. │
15424 ├──────────────┼────────────────────────────┤
15425 │children │ A list of all children, in │
15426 │ │ this format. │
15427 ├──────────────┼────────────────────────────┤
15428 │proposal_diff │ An HTML representation of │
15429 │ │ the differences between │
15430 │ │ the the current source and │
15431 │ │ the user’s proposed │
15432 │ │ source. │
15433 └──────────────┴────────────────────────────┘
15434 Parameters
15436 · node_id – the id of the node to get comments for.
15438 · username – the username of the user viewing the com‐
15440 ments.
15441 · moderator – whether the user is a moderator.
15443 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
15445 username=None, time=None, proposal=None, moderator=False)
15446 Add a comment to a node or another comment. Returns the comment
15447 in the same format as get_comments(). If the comment is being
15448 attached to a node, pass in the node’s id (as a string) with the
15449 node keyword argument:
15450 comment = support.add_comment(text, node_id=node_id)
15452 If the comment is the child of another comment, provide the par‐
15454 ent’s id (as a string) with the parent keyword argument:
15455 comment = support.add_comment(text, parent_id=parent_id)
15457 If you would like to store a username with the comment, pass in
15459 the optional username keyword argument:
15460 comment = support.add_comment(text, node=node_id,
15462 username=username)
15463 Parameters
15465 · parent_id – the prefixed id of the comment’s parent.
15467 · text – the text of the comment.
15469 · displayed – for moderation purposes
15471 · username – the username of the user making the comment.
15473 · time – the time the comment was created, defaults to
15475 now.
15476 WebSupport.process_vote(comment_id, username, value)
15478 Process a user’s vote. The web support package relies on the API
15479 user to perform authentication. The API user will typically
15480 receive a comment_id and value from a form, and then make sure
15481 the user is authenticated. A unique username must be passed in,
15482 which will also be used to retrieve the user’s past voting data.
15483 An example, once again in Flask:
15484 @app.route('/docs/process_vote', methods=['POST'])
15486 def process_vote():
15487 if g.user is None:
15488 abort(401)
15489 comment_id = request.form.get('comment_id')
15490 value = request.form.get('value')
15491 if value is None or comment_id is None:
15492 abort(400)
15493 support.process_vote(comment_id, g.user.name, value)
15494 return "success"
15495 Parameters
15497 · comment_id – the comment being voted on
15499 · username – the unique username of the user voting
15501 · value – 1 for an upvote, -1 for a downvote, 0 for an
15503 unvote.
15504 WebSupport.get_search_results(q)
15506 Perform a search for the query q, and create a set of search
15507 results. Then render the search results as html and return a
15508 context dict like the one created by get_document():
15509 document = support.get_search_results(q)
15511 Parameters
15513 q – the search query
15514 Search Adapters
15516 To create a custom search adapter you will need to subclass the
15517 BaseSearch class. Then create an instance of the new class and pass
15518 that as the search keyword argument when you create the WebSupport
15519 object:
15520 support = WebSupport(srcdir=srcdir,
15522 builddir=builddir,
15523 search=MySearch())
15524 For more information about creating a custom search adapter, please see
15526 the documentation of the BaseSearch class below.
15527 class sphinxcontrib.websupport.search.BaseSearch
15529 Defines an interface for search adapters.
15530 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
15532 support.search from sphinx.websupport.search.
15533 BaseSearch Methods
15536 The following methods are defined in the BaseSearch class. Some
15537 methods do not need to be overridden, but some (add_document() and
15538 handle_query()) must be overridden in your subclass. For a working
15539 example, look at the built-in adapter for whoosh.
15540 BaseSearch.init_indexing(changed=[])
15542 Called by the builder to initialize the search indexer. changed
15543 is a list of pagenames that will be reindexed. You may want to
15544 remove these from the search index before indexing begins.
15545 Parameters
15547 changed – a list of pagenames that will be re-indexed
15548 BaseSearch.finish_indexing()
15550 Called by the builder when writing has been completed. Use this
15551 to perform any finalization or cleanup actions after indexing is
15552 complete.
15553 BaseSearch.feed(pagename, filename, title, doctree)
15555 Called by the builder to add a doctree to the index. Converts
15556 the doctree to text and passes it to add_document(). You proba‐
15557 bly won’t want to override this unless you need access to the
15558 doctree. Override add_document() instead.
15559 Parameters
15561 · pagename – the name of the page to be indexed
15563 · filename – the name of the original source file
15565 · title – the title of the page to be indexed
15567 · doctree – is the docutils doctree representation of the
15569 page
15570 BaseSearch.add_document(pagename, filename, title, text)
15572 Called by feed() to add a document to the search index. This
15573 method should should do everything necessary to add a single
15574 document to the search index.
15575 pagename is name of the page being indexed. It is the combina‐
15577 tion of the source files relative path and filename, minus the
15578 extension. For example, if the source file is
15579 “ext/builders.rst”, the pagename would be “ext/builders”. This
15580 will need to be returned with search results when processing a
15581 query.
15582 Parameters
15584 · pagename – the name of the page being indexed
15586 · filename – the name of the original source file
15588 · title – the page’s title
15590 · text – the full text of the page
15592 BaseSearch.query(q)
15594 Called by the web support api to get search results. This method
15595 compiles the regular expression to be used when extracting con‐
15596 text, then calls handle_query(). You won’t want to override
15597 this unless you don’t want to use the included extract_context()
15598 method. Override handle_query() instead.
15599 Parameters
15601 q – the search query string.
15602 BaseSearch.handle_query(q)
15604 Called by query() to retrieve search results for a search query
15605 q. This should return an iterable containing tuples of the fol‐
15606 lowing format:
15607 (<path>, <title>, <context>)
15609 path and title are the same values that were passed to
15611 add_document(), and context should be a short text snippet of
15612 the text surrounding the search query in the document.
15613 The extract_context() method is provided as a simple way to cre‐
15615 ate the context.
15616 Parameters
15618 q – the search query
15619 BaseSearch.extract_context(text, length=240)
15621 Extract the context for the search query from the document’s
15622 full text.
15623 Parameters
15625 · text – the full text of the document to create the con‐
15627 text for
15628 · length – the length of the context snippet to return.
15630 Storage Backends
15632 To create a custom storage backend you will need to subclass the
15633 StorageBackend class. Then create an instance of the new class and
15634 pass that as the storage keyword argument when you create the WebSup‐
15635 port object:
15636 support = WebSupport(srcdir=srcdir,
15638 builddir=builddir,
15639 storage=MyStorage())
15640 For more information about creating a custom storage backend, please
15642 see the documentation of the StorageBackend class below.
15643 class sphinxcontrib.websupport.storage.StorageBackend
15645 Defines an interface for storage backends.
15646 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
15648 trib.websupport.storage from sphinx.websupport.storage.
15649 StorageBackend Methods
15652 StorageBackend.pre_build()
15653 Called immediately before the build process begins. Use this to
15654 prepare the StorageBackend for the addition of nodes.
15655 StorageBackend.add_node(id, document, source)
15657 Add a node to the StorageBackend.
15658 Parameters
15660 · id – a unique id for the comment.
15662 · document – the name of the document the node belongs
15664 to.
15665 · source – the source files name.
15667 StorageBackend.post_build()
15669 Called after a build has completed. Use this to finalize the
15670 addition of nodes if needed.
15671 StorageBackend.add_comment(text, displayed, username, time, proposal,
15673 node_id, parent_id, moderator)
15674 Called when a comment is being added.
15675 Parameters
15677 · text – the text of the comment
15679 · displayed – whether the comment should be displayed
15681 · username – the name of the user adding the comment
15683 · time – a date object with the time the comment was
15685 added
15686 · proposal – the text of the proposal the user made
15688 · node_id – the id of the node that the comment is being
15690 added to
15691 · parent_id – the id of the comment’s parent comment.
15693 · moderator – whether the user adding the comment is a
15695 moderator
15696 StorageBackend.delete_comment(comment_id, username, moderator)
15698 Delete a comment.
15699 Raises UserNotAuthorizedError if moderator is False and username
15701 doesn’t match the username on the comment.
15702 Parameters
15704 · comment_id – The id of the comment being deleted.
15706 · username – The username of the user requesting the
15708 deletion.
15709 · moderator – Whether the user is a moderator.
15711 StorageBackend.get_data(node_id, username, moderator)
15713 Called to retrieve all data for a node. This should return a
15714 dict with two keys, source and comments as described by WebSup‐
15715 port’s get_data() method.
15716 Parameters
15718 · node_id – The id of the node to get data for.
15720 · username – The name of the user requesting the data.
15722 · moderator – Whether the requestor is a moderator.
15724 StorageBackend.process_vote(comment_id, username, value)
15726 Process a vote that is being cast. value will be either -1, 0,
15727 or 1.
15728 Parameters
15730 · comment_id – The id of the comment being voted on.
15732 · username – The username of the user casting the vote.
15734 · value – The value of the vote being cast.
15736 StorageBackend.update_username(old_username, new_username)
15738 If a user is allowed to change their username this method should
15739 be called so that there is not stagnate data in the storage sys‐
15740 tem.
15741 Parameters
15743 · old_username – The username being changed.
15745 · new_username – What the username is being changed to.
15747 StorageBackend.accept_comment(comment_id)
15749 Called when a moderator accepts a comment. After the method is
15750 called the comment should be displayed to all users.
15751 Parameters
15753 comment_id – The id of the comment being accepted.
15754
15756 This is a list of Frequently Asked Questions about Sphinx. Feel free
15757 to suggest new entries!
15758 How do I…
15760 … create PDF files without LaTeX?
15761 rinohtype provides a PDF builder that can be used as a drop-in
15762 replacement for the LaTeX builder.
15763 … get section numbers?
15765 They are automatic in LaTeX output; for HTML, give a :numbered:
15766 option to the toctree directive where you want to start number‐
15767 ing.
15768 … customize the look of the built HTML files?
15770 Use themes, see theming.
15771 … add global substitutions or includes?
15773 Add them in the rst_prolog or rst_epilog config value.
15774 … display the whole TOC tree in the sidebar?
15776 Use the toctree callable in a custom layout template, probably
15777 in the sidebartoc block.
15778 … write my own extension?
15780 See the extension tutorial.
15781 … convert from my existing docs using MoinMoin markup?
15783 The easiest way is to convert to xhtml, then convert xhtml to
15784 reST. You’ll still need to mark up classes and such, but the
15785 headings and code examples come through cleanly.
15786 … create HTML slides from Sphinx documents?
15788 See the “Hieroglyph” package at
15789 https://github.com/nyergler/hieroglyph.
15790 For many more extensions and other contributed stuff, see the
15792 sphinx-contrib repository.
15793 Using Sphinx with…
15795 Read the Docs
15796 https://readthedocs.org is a documentation hosting service based
15797 around Sphinx. They will host sphinx documentation, along with
15798 supporting a number of other features including version support,
15799 PDF generation, and more. The Getting Started guide is a good
15800 place to start.
15801 Epydoc There’s a third-party extension providing an api role which
15803 refers to Epydoc’s API docs for a given identifier.
15804 Doxygen
15806 Michael Jones is developing a reST/Sphinx bridge to doxygen
15807 called breathe.
15808 SCons Glenn Hutchings has written a SCons build script to build Sphinx
15810 documentation; it is hosted here:
15811 https://bitbucket.org/zondo/sphinx-scons
15812 PyPI Jannis Leidel wrote a setuptools command that automatically
15814 uploads Sphinx documentation to the PyPI package documentation
15815 area at https://pythonhosted.org/.
15816 GitHub Pages
15818 Directories starting with underscores are ignored by default
15819 which breaks static files in Sphinx. GitHub’s preprocessor can
15820 be disabled to support Sphinx HTML output properly.
15821 MediaWiki
15823 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
15824 project by Kevin Dunn.
15825 Google Analytics
15827 You can use a custom layout.html template, like this:
15828 {% extends "!layout.html" %}
15830 {%- block extrahead %}
15832 {{ super() }}
15833 <script type="text/javascript">
15834 var _gaq = _gaq || [];
15835 _gaq.push(['_setAccount', 'XXX account number XXX']);
15836 _gaq.push(['_trackPageview']);
15837 </script>
15838 {% endblock %}
15839 {% block footer %}
15841 {{ super() }}
15842 <div class="footer">This page uses <a href="https://analytics.google.com/">
15843 Google Analytics</a> to collect statistics. You can disable it by blocking
15844 the JavaScript coming from www.google-analytics.com.
15845 <script type="text/javascript">
15846 (function() {
15847 var ga = document.createElement('script');
15848 ga.src = ('https:' == document.location.protocol ?
15849 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
15850 ga.setAttribute('async', 'true');
15851 document.documentElement.firstChild.appendChild(ga);
15852 })();
15853 </script>
15854 </div>
15855 {% endblock %}
15856 Epub info
15858 The following list gives some hints for the creation of epub files:
15859 · Split the text into several files. The longer the individual HTML
15861 files are, the longer it takes the ebook reader to render them. In
15862 extreme cases, the rendering can take up to one minute.
15863 · Try to minimize the markup. This also pays in rendering time.
15865 · For some readers you can use embedded or external fonts using the CSS
15867 @font-face directive. This is extremely useful for code listings
15868 which are often cut at the right margin. The default Courier font
15869 (or variant) is quite wide and you can only display up to 60 charac‐
15870 ters on a line. If you replace it with a narrower font, you can get
15871 more characters on a line. You may even use FontForge and create
15872 narrow variants of some free font. In my case I get up to 70 charac‐
15873 ters on a line.
15874 You may have to experiment a little until you get reasonable results.
15876 · Test the created epubs. You can use several alternatives. The ones I
15878 am aware of are Epubcheck, Calibre, FBreader (although it does not
15879 render the CSS), and Bookworm. For Bookworm, you can download the
15880 source from https://code.google.com/archive/p/threepress and run your
15881 own local server.
15882 · Large floating divs are not displayed properly. If they cover more
15884 than one page, the div is only shown on the first page. In that case
15885 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
15886 tory to your local _static/ directory and remove the float settings.
15887 · Files that are inserted outside of the toctree directive must be man‐
15889 ually included. This sometimes applies to appendixes, e.g. the glos‐
15890 sary or the indices. You can add them with the epub_post_files
15891 option.
15892 · The handling of the epub cover page differs from the reStructuredText
15894 procedure which automatically resolves image paths and puts the
15895 images into the _images directory. For the epub cover page put the
15896 image in the html_static_path directory and reference it with its
15897 full path in the epub_cover config option.
15898 · kindlegen command can convert from epub3 resulting file to .mobi file
15900 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
15901 lowing command:
15902 $ make epub
15904 $ kindlegen _build/epub/yourdoc.epub
15905 The kindlegen command doesn’t accept documents that have section
15907 titles surrounding toctree directive:
15908 Section Title
15910 =============
15911 .. toctree::
15913 subdocument
15915 Section After Toc Tree
15917 ======================
15918 kindlegen assumes all documents order in line, but the resulting doc‐
15920 ument has complicated order for kindlegen:
15921 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
15923 If you get the following error, fix your document structure:
15925 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
15927 Error(prcgen):E24001: The table of content could not be built.
15928 Texinfo info
15930 There are two main programs for reading Info files, info and GNU Emacs.
15931 The info program has less features but is available in most Unix envi‐
15932 ronments and can be quickly accessed from the terminal. Emacs provides
15933 better font and color display and supports extensive customization (of
15934 course).
15935 Displaying Links
15937 One noticeable problem you may encounter with the generated Info files
15938 is how references are displayed. If you read the source of an Info
15939 file, a reference to this section would look like:
15940 * note Displaying Links: target-id
15942 In the stand-alone reader, info, references are displayed just as they
15944 appear in the source. Emacs, on the other-hand, will by default
15945 replace *note: with see and hide the target-id. For example:
15946 Displaying Links
15947 The exact behavior of how Emacs displays references is dependent on the
15949 variable Info-hide-note-references. If set to the value of hide, Emacs
15950 will hide both the *note: part and the target-id. This is generally
15951 the best way to view Sphinx-based documents since they often make fre‐
15952 quent use of links and do not take this limitation into account. How‐
15953 ever, changing this variable affects how all Info documents are dis‐
15954 played and most do take this behavior into account.
15955 If you want Emacs to display Info files produced by Sphinx using the
15957 value hide for Info-hide-note-references and the default value for all
15958 other Info files, try adding the following Emacs Lisp code to your
15959 start-up file, ~/.emacs.d/init.el.
15960 (defadvice info-insert-file-contents (after
15962 sphinx-info-insert-file-contents
15963 activate)
15964 "Hack to make `Info-hide-note-references' buffer-local and
15965 automatically set to `hide' iff it can be determined that this file
15966 was created from a Texinfo file generated by Docutils or Sphinx."
15967 (set (make-local-variable 'Info-hide-note-references)
15968 (default-value 'Info-hide-note-references))
15969 (save-excursion
15970 (save-restriction
15971 (widen) (goto-char (point-min))
15972 (when (re-search-forward
15973 "^Generated by \\(Sphinx\\|Docutils\\)"
15974 (save-excursion (search-forward "\x1f" nil t)) t)
15975 (set (make-local-variable 'Info-hide-note-references)
15976 'hide)))))
15977 Notes
15979 The following notes may be helpful if you want to create Texinfo files:
15980 · Each section corresponds to a different node in the Info file.
15982 · Colons (:) cannot be properly escaped in menu entries and xrefs.
15984 They will be replaced with semicolons (;).
15985 · Links to external Info files can be created using the somewhat offi‐
15987 cial URI scheme info. For example:
15988 info:Texinfo#makeinfo_options
15990 · Inline markup
15992 The standard formatting for *strong* and _emphasis_ can result in
15994 ambiguous output when used to markup parameter names and other val‐
15995 ues. Since this is a fairly common practice, the default formatting
15996 has been changed so that emphasis and strong are now displayed like
15997 `literal's.
15998 The standard formatting can be re-enabled by adding the following to
16000 your conf.py:
16001 texinfo_elements = {'preamble': """
16003 @definfoenclose strong,*,*
16004 @definfoenclose emph,_,_
16005 """}
16006
16008 builder
16009 A class (inheriting from Builder) that takes parsed documents
16010 and performs an action on them. Normally, builders translate
16011 the documents to an output format, but it is also possible to
16012 use the builder builders that e.g. check for broken links in the
16013 documentation, or build coverage information.
16014 See /usage/builders/index for an overview over Sphinx’s built-in
16016 builders.
16017 configuration directory
16019 The directory containing conf.py. By default, this is the same
16020 as the source directory, but can be set differently with the -c
16021 command-line option.
16022 directive
16024 A reStructuredText markup element that allows marking a block of
16025 content with special meaning. Directives are supplied not only
16026 by docutils, but Sphinx and custom extensions can add their own.
16027 The basic directive syntax looks like this:
16028 .. directivename:: argument ...
16030 :option: value
16031 Content of the directive.
16033 See rst-directives for more information.
16035 document name
16037 Since reST source files can have different extensions (some peo‐
16038 ple like .txt, some like .rst – the extension can be configured
16039 with source_suffix) and different OSes have different path sepa‐
16040 rators, Sphinx abstracts them: document names are always rela‐
16041 tive to the source directory, the extension is stripped, and
16042 path separators are converted to slashes. All values, parame‐
16043 ters and such referring to “documents” expect such document
16044 names.
16045 Examples for document names are index, library/zipfile, or ref‐
16047 erence/datamodel/types. Note that there is no leading or trail‐
16048 ing slash.
16049 domain A domain is a collection of markup (reStructuredText directives
16051 and roles) to describe and link to objects belonging together,
16052 e.g. elements of a programming language. Directive and role
16053 names in a domain have names like domain:name, e.g. py:function.
16054 Having domains means that there are no naming problems when one
16056 set of documentation wants to refer to e.g. C++ and Python
16057 classes. It also means that extensions that support the docu‐
16058 mentation of whole new languages are much easier to write.
16059 For more information, refer to /usage/restructuredtext/domains.
16061 environment
16063 A structure where information about all documents under the root
16064 is saved, and used for cross-referencing. The environment is
16065 pickled after the parsing stage, so that successive runs only
16066 need to read and parse new and changed documents.
16067 extension
16069 A custom role, directive or other aspect of Sphinx that allows
16070 users to modify any aspect of the build process within Sphinx.
16071 For more information, refer to /usage/extensions/index.
16073 master document
16075 The document that contains the root toctree directive.
16076 object The basic building block of Sphinx documentation. Every “object
16078 directive” (e.g. function or object) creates such a block; and
16079 most objects can be cross-referenced to.
16080 RemoveInSphinxXXXWarning
16082 The feature which is warned will be removed in Sphinx-XXX ver‐
16083 sion. It usually caused from Sphinx extensions which is using
16084 deprecated. See also when-deprecation-warnings-are-displayed.
16085 role A reStructuredText markup element that allows marking a piece of
16087 text. Like directives, roles are extensible. The basic syntax
16088 looks like this: :rolename:`content`. See rst-inline-markup for
16089 details.
16090 source directory
16092 The directory which, including its subdirectories, contains all
16093 source files for one Sphinx project.
16094 reStructuredText
16096 An easy-to-read, what-you-see-is-what-you-get plaintext markup
16097 syntax and parser system.
16098
16100 Abstract
16101 This document describes the development process of Sphinx, a documenta‐
16102 tion system used by developers to document systems used by other devel‐
16103 opers to develop other systems that may also be documented using
16104 Sphinx.
16105 · Bug Reports and Feature Requests
16107 · Contributing to Sphinx
16109 · Getting Started
16111 · Core Developers
16113 · Locale updates
16115 · Coding Guide
16117 · Debugging Tips
16119 · Branch Model
16121 · Deprecating a feature
16123 · Deprecation policy
16125 · Unit Testing
16127 The Sphinx source code is managed using Git and is hosted on GitHub.
16129 git clone git://github.com/sphinx-doc/sphinx
16130 Community.INDENT 0.0
16131 sphinx-users <sphinx-users@googlegroups.com>
16133 Mailing list for user support.
16134 sphinx-dev <sphinx-dev@googlegroups.com>
16136 Mailing list for development related discussions.
16137 #sphinx-doc on irc.freenode.net
16139 IRC channel for development questions and user support.
16140 Bug Reports and Feature Requests
16142 If you have encountered a problem with Sphinx or have an idea for a new
16143 feature, please submit it to the issue tracker on GitHub or discuss it
16144 on the sphinx-dev mailing list.
16145 For bug reports, please include the output produced during the build
16147 process and also the log file Sphinx creates after it encounters an
16148 unhandled exception. The location of this file should be shown towards
16149 the end of the error message.
16150 Including or providing a link to the source files involved may help us
16152 fix the issue. If possible, try to create a minimal project that pro‐
16153 duces the error and post that instead.
16154 Contributing to Sphinx
16156 The recommended way for new contributors to submit code to Sphinx is to
16157 fork the repository on GitHub and then submit a pull request after com‐
16158 mitting the changes. The pull request will then need to be approved by
16159 one of the core developers before it is merged into the main reposi‐
16160 tory.
16161 1. Check for open issues or open a fresh issue to start a discussion
16163 around a feature idea or a bug.
16164 2. If you feel uncomfortable or uncertain about an issue or your
16166 changes, feel free to email the sphinx-dev mailing list.
16167 3. Fork the repository on GitHub to start making your changes to the
16169 master branch for next major version, or X.Y branch for next minor
16170 version (see Branch Model).
16171 4. Write a test which shows that the bug was fixed or that the feature
16173 works as expected.
16174 5. Send a pull request and bug the maintainer until it gets merged and
16176 published. Make sure to add yourself to AUTHORS and the change to
16177 CHANGES.
16178 Getting Started
16180 These are the basic steps needed to start developing on Sphinx.
16181 1. Create an account on GitHub.
16183 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
16185 GitHub interface.
16186 3. Clone the forked repository to your machine.
16188 git clone https://github.com/USERNAME/sphinx
16190 cd sphinx
16191 4. Checkout the appropriate branch.
16193 For changes that should be included in the next minor release
16195 (namely bug fixes), use the X.Y branch.
16196 git checkout X.Y
16198 For new features or other substantial changes that should wait
16200 until the next major release, use the master branch (see Branch
16201 Model for detail).
16202 5. Setup a virtual environment.
16204 This is not necessary for unit testing, thanks to tox, but it is
16206 necessary if you wish to run sphinx-build locally or run unit tests
16207 without the help of tox.
16208 virtualenv ~/.venv
16210 . ~/.venv/bin/activate
16211 pip install -e .
16212 6. Create a new working branch. Choose any name you like.
16214 git checkout -b feature-xyz
16216 7. Hack, hack, hack.
16218 For tips on working with the code, see the Coding Guide.
16220 8. Test, test, test.
16222 Testing is best done through tox, which provides a number of tar‐
16224 gets and allows testing against multiple different Python environ‐
16225 ments:
16226 · To list all possible targets:
16228 tox -av
16230 · To run unit tests for a specific Python version, such as 3.6:
16232 tox -e py36
16234 · To run unit tests for a specific Python version and turn on dep‐
16236 recation warnings on so they’re shown in the test output:
16237 PYTHONWARNINGS=all tox -e py36
16239 · To run code style and type checks:
16241 tox -e mypy
16243 tox -e flake8
16244 · Arguments to pytest can be passed via tox, e.g. in order to run a
16246 particular test:
16247 tox -e py36 tests/test_module.py::test_new_feature
16249 · To build the documentation:
16251 tox -e docs
16253 · To build the documentation in multiple formats:
16255 tox -e docs -- -b html,latexpdf
16257 · To run JavaScript tests with Karma, execute the following com‐
16259 mands (requires Node.js):
16260 npm install
16262 npm run test
16263 You can also test by installing dependencies in your local environ‐
16265 ment.
16266 pip install .[test]
16268 New unit tests should be included in the tests directory where nec‐
16270 essary:
16271 · For bug fixes, first add a test that fails without your changes
16273 and passes after they are applied.
16274 · Tests that need a sphinx-build run should be integrated in one of
16276 the existing test modules if possible. New tests that to
16277 @with_app and then build_all for a few assertions are not good
16278 since the test suite should not take more than a minute to run.
16279 9. Please add a bullet point to CHANGES if the fix or feature is not
16281 trivial (small doc updates, typo fixes). Then commit:
16282 git commit -m '#42: Add useful new feature that does this.'
16284 GitHub recognizes certain phrases that can be used to automatically
16286 update the issue tracker.
16287 For example:
16289 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
16291 would close issue #42.
16293 10. Push changes in the branch to your forked repository on GitHub.
16295 git push origin feature-xyz
16297 11. Submit a pull request from your branch to the respective branch
16299 (master or X.Y).
16300 12. Wait for a core developer to review your changes.
16302 Core Developers
16304 The core developers of Sphinx have write access to the main repository.
16305 They can commit changes, accept/reject pull requests, and manage items
16306 on the issue tracker.
16307 You do not need to be a core developer or have write access to be
16309 involved in the development of Sphinx. You can submit patches or cre‐
16310 ate pull requests from forked repositories and have a core developer
16311 add the changes for you.
16312 The following are some general guidelines for core developers:
16314 · Questionable or extensive changes should be submitted as a pull
16316 request instead of being committed directly to the main repository.
16317 The pull request should be reviewed by another core developer before
16318 it is merged.
16319 · Trivial changes can be committed directly but be sure to keep the
16321 repository in a good working state and that all tests pass before
16322 pushing your changes.
16323 · When committing code written by someone else, please attribute the
16325 original author in the commit message and any relevant CHANGES entry.
16326 Locale updates
16328 The parts of messages in Sphinx that go into builds are translated into
16329 several locales. The translations are kept as gettext .po files trans‐
16330 lated from the master template sphinx/locale/sphinx.pot.
16331 Sphinx uses Babel to extract messages and maintain the catalog files.
16333 It is integrated in setup.py:
16334 · Use python setup.py extract_messages to update the .pot template.
16336 · Use python setup.py update_catalog to update all existing language
16338 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
16339 the template file.
16340 · Use python setup.py compile_catalog to compile the .po files to
16342 binary .mo files and .js files.
16343 When an updated .po file is submitted, run compile_catalog to commit
16345 both the source and the compiled catalogs.
16346 When a new locale is submitted, add a new directory with the ISO 639-1
16348 language identifier and put sphinx.po in there. Don’t forget to update
16349 the possible values for language in doc/config.rst.
16350 The Sphinx core messages can also be translated on Transifex. There
16352 exists a client tool named tx in the Python package “transifex_client”,
16353 which can be used to pull translations in .po format from Transifex.
16354 To do this, go to sphinx/locale and then run tx pull -f -l LANG where
16355 LANG is an existing language identifier. It is good practice to run
16356 python setup.py update_catalog afterwards to make sure the .po file has
16357 the canonical Babel formatting.
16358 Coding Guide
16360 · Try to use the same code style as used in the rest of the project.
16361 See the Pocoo Styleguide for more information.
16362 · For non-trivial changes, please update the CHANGES file. If your
16364 changes alter existing behavior, please document this.
16365 · New features should be documented. Include examples and use cases
16367 where appropriate. If possible, include a sample that is displayed
16368 in the generated output.
16369 · When adding a new configuration variable, be sure to document it and
16371 update sphinx/quickstart.py if it’s important enough.
16372 · Use the included utils/check_sources.py script to check for common
16374 formatting issues (trailing whitespace, lengthy lines, etc).
16375 · Add appropriate unit tests.
16377 Debugging Tips
16379 · Delete the build cache before building documents if you make changes
16380 in the code by running the command make clean or using the
16381 sphinx-build -E option.
16382 · Use the sphinx-build -P option to run pdb on exceptions.
16384 · Use node.pformat() and node.asdom().toxml() to generate a printable
16386 representation of the document structure.
16387 · Set the configuration variable keep_warnings to True so warnings will
16389 be displayed in the generated output.
16390 · Set the configuration variable nitpicky to True so that Sphinx will
16392 complain about references without a known target.
16393 · Set the debugging options in the Docutils configuration file.
16395 · JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
16397 are generated by this modified snowballcode generator. Generated JSX
16398 files are in this repository. You can get the resulting JavaScript
16399 files using the following command:
16400 npm install
16402 node_modules/.bin/grunt build # -> dest/*.global.js
16403 Branch Model
16405 Sphinx project uses following branches for developing.
16406 master Used for main development. All improvement and refactoring, bug
16408 fixes are allowed.
16409 X.Y Where X.Y is the MAJOR.MINOR release. Used to maintain current
16411 stable release. Only bug fixes and stable changes are allowed.
16412 Only the most recent stable release is currently retained. When
16413 a new version is released, the old release branch will be
16414 deleted and replaced by an equivalent tag.
16415 Deprecating a feature
16417 There are a couple reasons that code in Sphinx might be deprecated:
16418 · If a feature has been improved or modified in a backwards-incompati‐
16420 ble way, the old feature or behavior will be deprecated.
16421 · Sometimes Sphinx will include a backport of a Python library that’s
16423 not included in a version of Python that Sphinx currently supports.
16424 When Sphinx no longer needs to support the older version of Python
16425 that doesn’t include the library, the library will be deprecated in
16426 Sphinx.
16427 As the Deprecation policy describes, the first release of Sphinx that
16429 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
16430 (where XX is the Sphinx version where the feature will be removed) when
16431 the deprecated feature is invoked. Assuming we have good test coverage,
16432 these warnings are converted to errors when running the test suite with
16433 warnings enabled:
16434 pytest -Wall
16436 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
16438 silence any warnings generated when running the tests.
16439 Deprecation policy
16441 A feature release may deprecate certain features from previous
16442 releases. If a feature is deprecated in feature release 1.A, it will
16443 continue to work in all 1.A.x versions (for all versions of x) but
16444 raise warnings. Deprecated features will be removed in the first 1.B
16445 release, or 1.B.1 for features deprecated in the last 1.A.x feature
16446 release to ensure deprecations are done over at least 2 feature
16447 releases.
16448 So, for example, if we decided to start the deprecation of a function
16450 in Sphinx 1.4:
16451 · Sphinx 1.4.x will contain a backwards-compatible replica of the func‐
16453 tion which will raise a RemovedInSphinx16Warning.
16454 · Sphinx 1.5 (the version that follows 1.4) will still contain the
16456 backwards-compatible replica.
16457 · Sphinx 1.6 will remove the feature outright.
16459 The warnings are displayed by default. You can turn off display of
16461 these warnings with:
16462 · PYTHONWARNINGS= make html (Linux/Mac)
16464 · export PYTHONWARNINGS= and do make html (Linux/Mac)
16466 · set PYTHONWARNINGS= and do make html (Windows)
16468 Unit Testing
16470 Sphinx has been tested with pytest runner. Sphinx developers write unit
16471 tests using pytest notation. Utility functions and pytest fixtures for
16472 testing are provided in sphinx.testing. If you are a developer of
16473 Sphinx extensions, you can write unit tests with using pytest. At this
16474 time, sphinx.testing will help your test implementation.
16475 How to use pytest fixtures that are provided by sphinx.testing? You
16477 can require 'sphinx.testing.fixtures' in your test modules or con‐
16478 ftest.py files like this:
16479 pytest_plugins = 'sphinx.testing.fixtures'
16481 If you want to know more detailed usage, please refer to tests/con‐
16483 ftest.py and other test_*.py files under tests directory.
16484 NOTE:
16486 Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
16487 New in version 1.6: sphinx.testing as a experimental.
16489 New in version 1.8: Sphinx also runs JavaScript tests.
16492
16495 Release 1.8.4 (released Feb 03, 2019)
16496 Bugs fixed
16497 · #3707: latex: no bold checkmark (✔) available.
16498 · #5605: with the documentation language set to Chinese, English words
16500 could not be searched.
16501 · #5889: LaTeX: user numfig_format is stripped of spaces and may cause
16503 build failure
16504 · C++, fix hyperlinks for declarations involving east cv-qualifiers.
16506 · #5755: C++, fix duplicate declaration error on function templates
16508 with constraints in the return type.
16509 · C++, parse unary right fold expressions and binary fold expressions.
16511 · pycode could not handle egg files on windows
16513 · #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
16515 · #5936: LaTeX: PDF build broken by inclusion of image taller than page
16517 height in an admonition
16518 · #5231: “make html” does not read and build “po” files in “locale” dir
16520 · #5954: :scale: image option may break PDF build if image in an admo‐
16522 nition
16523 · #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
16525 of parskip.sty
16526 · #5948: LaTeX: duplicated labels are generated for sections
16528 · #5958: versionadded directive causes crash with Python 3.5.0
16530 · #5995: autodoc: autodoc_mock_imports conflict with metaclass on
16532 Python 3.7
16533 · #5871: texinfo: a section title . is not allowed
16535 Release 1.8.3 (released Dec 26, 2018)
16537 Features added
16538 · LaTeX: it is possible to insert custom material to appear on back of
16539 title page, see discussion of 'maketitle' key of latex_elements
16540 ('manual' docclass only)
16541 Bugs fixed
16543 · #5725: mathjax: Use CDN URL for “latest” version by default
16544 · #5460: html search does not work with some 3rd party themes
16546 · #5520: LaTeX, caption package incompatibility since Sphinx 1.6
16548 · #5614: autodoc: incremental build is broken when builtin modules are
16550 imported
16551 · #5627: qthelp: index.html missing in QtHelp
16553 · #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
16555 acter
16556 · #5754: DOC: Fix some mistakes in /latex
16558 · #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
16560 1.6.6 (refs: #1238)
16561 · #5636: C++, fix parsing of floating point literals.
16563 · #5496 (again): C++, fix assertion in partial builds with duplicates.
16565 · #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
16567 · #1956: Default conf.py is not PEP8-compliant
16569 · #5849: LaTeX: document class \maketitle is overwritten with no possi‐
16571 bility to use original meaning in place of Sphinx custom one
16572 · #5834: apidoc: wrong help for --tocfile
16574 · #5800: todo: crashed if todo is defined in TextElement
16576 · #5846: htmlhelp: convert hex escaping to decimal escaping in
16578 .hhc/.hhk files
16579 · htmlhelp: broken .hhk file generated when title contains a double
16581 quote
16582 Release 1.8.2 (released Nov 11, 2018)
16584 Incompatible changes
16585 · #5497: Do not include MathJax.js and jsmath.js unless it is really
16586 needed
16587 Features added
16589 · #5471: Show appropriate deprecation warnings
16590 Bugs fixed
16592 · #5490: latex: enumerated list causes a crash with recommonmark
16593 · #5492: sphinx-build fails to build docs w/ Python < 3.5.2
16595 · #3704: latex: wrong \label positioning for figures with a legend
16597 · #5496: C++, fix assertion when a symbol is declared more than twice.
16599 · #5493: gettext: crashed with broken template
16601 · #5495: csv-table directive with file option in included file is bro‐
16603 ken (refs: #4821)
16604 · #5498: autodoc: unable to find type hints for a functools.partial
16606 · #5480: autodoc: unable to find type hints for unresolvable Forward
16608 references
16609 · #5419: incompatible math_block node has been generated
16611 · #5548: Fix ensuredir() in case of pre-existing file
16613 · #5549: graphviz Correctly deal with non-existing static dir
16615 · #3002: i18n: multiple footnote_references referring same footnote
16617 cause duplicated node_ids
16618 · #5563: latex: footnote_references generated by extension causes a
16620 LaTeX builder crash
16621 · #5561: make all-pdf fails with old xindy version
16623 · #5557: quickstart: –no-batchfile isn’t honored
16625 · #3080: texinfo: multiline rubrics are broken
16627 · #3080: texinfo: multiline citations are broken
16629 Release 1.8.1 (released Sep 22, 2018)
16631 Incompatible changes
16632 · LaTeX \pagestyle commands have been moved to the LaTeX template. No
16633 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
16634 tained them, had been customized in conf.py. (refs: #5455)
16635 Bugs fixed
16637 · #5418: Incorrect default path for sphinx-build -d/doctrees files
16638 · #5421: autodoc emits deprecation warning for autodoc_default_flags
16640 · #5422: lambda object causes PicklingError on storing environment
16642 · #5417: Sphinx fails to build with syntax error in Python 2.7.5
16644 · #4911: add latexpdf to make.bat for non make-mode
16646 · #5436: Autodoc does not work with enum subclasses with proper‐
16648 ties/methods
16649 · #5437: autodoc: crashed on modules importing eggs
16651 · #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
16653 · #5431: autodoc: autofunction emits a warning for callable objects
16655 · #5457: Fix TypeError in error message when override is prohibited
16657 · #5453: PDF builds of ‘howto’ documents have no page numbers
16659 · #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
16661 · #5454: latex: Index has disappeared from PDF for Japanese documents
16663 · #5432: py domain: :type: field can’t process :term: references
16665 · #5426: py domain: TypeError has been raised for class attribute
16667 Release 1.8.0 (released Sep 13, 2018)
16669 Dependencies
16670 1.8.0b1
16671 · LaTeX: latex_use_xindy, if True (default for xelatex/lualatex),
16673 instructs make latexpdf to use xindy for general index. Make sure
16674 your LaTeX distribution includes it. (refs: #5134)
16675 · LaTeX: latexmk is required for make latexpdf on Windows
16677 Incompatible changes
16679 1.8.0b2
16680 · #5282: html theme: refer pygments_style settings of HTML themes pref‐
16682 erentially
16683 · The URL of download files are changed
16685 · #5127: quickstart: Makefile and make.bat are not overwritten if
16687 exists
16688 1.8.0b1
16690 · #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
16692 of the document being built instead of in the root directory of the
16693 documentation.
16694 · #4460: extensions which stores any data to environment should return
16696 the version of its env data structure as metadata. In detail, please
16697 see ext-metadata.
16698 · Sphinx expects source parser modules to have supported file formats
16700 as Parser.supported attribute
16701 · The default value of epub_author and epub_publisher are changed from
16703 'unknown' to the value of author. This is same as a conf.py file
16704 sphinx-build generates.
16705 · The gettext_compact attribute is removed from document.settings
16707 object. Please use config.gettext_compact instead.
16708 · The processing order on reading phase is changed. smart_quotes,
16710 sphinx domains, doctree-read event and versioning doctrees are
16711 invoked earlier than so far. For more details, please read a
16712 description of Sphinx.add_transform()
16713 · #4827: All substitution_definition nodes are removed from doctree on
16715 reading phase
16716 · docutils.conf in $HOME or /etc directories are ignored. Only docu‐
16718 tils.conf from confdir is obeyed.
16719 · #789: :samp: role supports to escape curly braces with backslash
16721 · #4811: The files under html_static_path are excluded from source
16723 files.
16724 · latex: Use \sphinxcite for citation references instead \hyperref
16726 · The config value viewcode_import is renamed to viewcode_fol‐
16728 low_imported_members (refs: #4035)
16729 · #1857: latex: latex_show_pagerefs does not add pagerefs for citations
16731 · #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
16733 tion title
16734 · #4983: html: The anchor for productionlist tokens has been changed
16736 · Modifying a template variable script_files in templates is allowed
16738 now. Please use app.add_js_file() instead.
16739 · #5072: Save environment object also with only new documents
16741 · #5035: qthelp builder allows dashes in qthelp_namespace
16743 · LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
16745 replacement of makeindex (refs: #5134). After upgrading Sphinx,
16746 please clean latex build repertory of existing project before new
16747 build.
16748 · #5163: html: hlist items are now aligned to top
16750 · highlightlang directive is processed on resolving phase
16752 · #4000: LaTeX: template changed. Following elements moved to it:
16754 · \begin{document}
16756 · shorthandoff variable
16758 · maketitle variable
16760 · tableofcontents variable
16762 Deprecated
16764 1.8.0b2
16765 · sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
16767 · sphinx.io.SphinxI18nReader.line is deprecated
16769 · sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
16771 text_compact argument has been deprecated
16772 · #5403: sphinx.util.images.guess_mimetype() has changed; the content
16774 argument has been deprecated
16775 1.8.0b1
16777 · source_parsers is deprecated
16779 · autodoc_default_flags is deprecated
16781 · quickstart: --epub option becomes default, so it is deprecated
16783 · Drop function based directive support. For now, Sphinx only supports
16785 class based directives (see Directive)
16786 · sphinx.util.docutils.directive_helper() is deprecated
16788 · sphinx.cmdline is deprecated
16790 · sphinx.make_mode is deprecated
16792 · sphinx.locale.l_() is deprecated
16794 · #2157: helper function warn() for HTML themes is deprecated
16796 · app.override_domain() is deprecated
16798 · app.add_stylesheet() is deprecated
16800 · app.add_javascript() is deprecated
16802 · app.import_object() is deprecated
16804 · app.add_source_parser() has changed; the suffix argument has been
16806 deprecated
16807 · sphinx.versioning.prepare() is deprecated
16809 · Config.__init__() has changed; the dirname, filename and tags argu‐
16811 ment has been deprecated
16812 · Config.check_types() is deprecated
16814 · Config.check_unicode() is deprecated
16816 · sphinx.application.CONFIG_FILENAME is deprecated
16818 · highlightlang directive is deprecated
16820 · BuildEnvironment.load() is deprecated
16822 · BuildEnvironment.loads() is deprecated
16824 · BuildEnvironment.frompickle() is deprecated
16826 · env.read_doc() is deprecated
16828 · env.update() is deprecated
16830 · env._read_serial() is deprecated
16832 · env._read_parallel() is deprecated
16834 · env.write_doctree() is deprecated
16836 · env._nitpick_ignore is deprecated
16838 · env.versionchanges is deprecated
16840 · env.dump() is deprecated
16842 · env.dumps() is deprecated
16844 · env.topickle() is deprecated
16846 · env.note_versionchange() is deprecated
16848 · sphinx.writers.latex.Table.caption_footnotetexts is deprecated
16850 · sphinx.writers.latex.Table.header_footnotetexts is deprecated
16852 · sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
16854 · sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
16856 deprecated
16857 · sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
16859 · sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
16861 · sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
16863 cated
16864 · sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
16866 cated
16867 · sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
16869 cated
16870 · sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
16872 cated
16873 · sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
16875 cated
16876 · sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
16878 · sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
16880 · sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
16882 · sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
16884 · sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
16886 · sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
16888 · sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
16890 cated
16891 · sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
16893 · sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
16895 · sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
16897 · sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
16899 recated
16900 · sphinx.ext.mathbase extension is deprecated
16902 · sphinx.ext.mathbase.math node is deprecated
16904 · sphinx.ext.mathbase.displaymath node is deprecated
16906 · sphinx.ext.mathbase.eqref node is deprecated
16908 · sphinx.ext.mathbase.is_in_section_title() is deprecated
16910 · sphinx.ext.mathbase.MathDomain is deprecated
16912 · sphinx.ext.mathbase.MathDirective is deprecated
16914 · sphinx.ext.mathbase.math_role is deprecated
16916 · sphinx.ext.mathbase.setup_math() is deprecated
16918 · sphinx.directives.other.VersionChanges is deprecated
16920 · sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
16922 · sphinx.ext.mathbase.get_node_equation_number() is deprecated
16924 · sphinx.ext.mathbase.wrap_displaymath() is deprecated
16926 · The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
16928 is deprecated
16929 For more details, see deprecation APIs list
16931 Features added
16933 1.8.0b2
16934 · #5388: Ensure frozen object descriptions are reproducible
16936 · #5362: apidoc: Add --tocfile option to change the filename of ToC
16938 1.8.0b1
16940 · Add config-inited event
16942 · Add sphinx.config.Any to represent the config value accepts any type
16944 of value
16945 · source_suffix allows a mapping fileext to file types
16947 · Add author as a configuration value
16949 · #2852: imgconverter: Support to convert GIF to PNG
16951 · sphinx-build command supports i18n console output
16953 · Add app.add_message_catalog() and sphinx.locale.get_translations() to
16955 support translation for 3rd party extensions
16956 · helper function warning() for HTML themes is added
16958 · Add Domain.enumerable_nodes to manage own enumerable nodes for
16960 domains (experimental)
16961 · Add a new keyword argument override to Application APIs
16963 · LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
16965 default sets fanvyvrb to use normal, not small, fontsize in
16966 code-blocks (refs: #4793)
16967 · Add html_css_files and epub_css_files for adding CSS files from con‐
16969 figuration
16970 · Add html_js_files for adding JS files from configuration
16972 · #4834: Ensure set object descriptions are reproducible.
16974 · #4828: Allow to override numfig_format partially. Full definition is
16976 not needed.
16977 · Improve warning messages during including (refs: #4818)
16979 · LaTeX: separate customizability of guilabel and menuselection (refs:
16981 #4830)
16982 · Add Config.read() classmethod to create a new config object from con‐
16984 figuration file
16985 · #4866: Wrap graphviz diagrams in <div> tag
16987 · viewcode: Add viewcode-find-source and viewcode-follow-imported to
16989 load source code without loading
16990 · #4785: napoleon: Add strings to translation file for localisation
16992 · #4927: Display a warning when invalid values are passed to
16994 linenothreshold option of highlight directive
16995 · C++:
16997 · Add a cpp:texpr role as a sibling to cpp:expr.
16999 · Add support for unions.
17001 · #3593, #2683: add support for anonymous entities using names star‐
17003 ing with @.
17004 · #5147: add support for (most) character literals.
17006 · Cross-referencing entities inside primary templates is supported,
17008 and now properly documented.
17009 · #1552: add new cross-referencing format for cpp:any and cpp:func
17011 roles, for referencing specific function overloads.
17012 · #3606: MathJax should be loaded with async attribute
17014 · html: Output canonical_url metadata if html_baseurl set (refs: #4193)
17016 · #5029: autosummary: expose inherited_members to template
17018 · #3784: mathjax: Add mathjax_options to give options to script tag for
17020 mathjax
17021 · #4362: latex: Don’t overwrite .tex file if document not changed
17023 · #1431: latex: Add alphanumeric enumerated list support
17025 · Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
17027 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
17028 · #4976: SphinxLoggerAdapter.info() now supports location parameter
17030 · #5122: setuptools: support nitpicky option
17032 · #2820: autoclass directive supports nested class
17034 · Add app.add_html_math_renderer() to register a math renderer for HTML
17036 · Apply trim_doctest_flags to all builders (cf. text, manpages)
17038 · #5140: linkcheck: Add better Accept header to HTTP client
17040 · #4614: sphinx-build: Add --keep-going option to show all warnings
17042 · Add math:numref role to refer equations (Same as eq)
17044 · quickstart: epub builder is enabled by default
17046 · #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
17048 builder
17049 · #5273: doctest: Skip doctest conditionally
17051 · #5306: autodoc: emit a warning for invalid typehints
17053 · #4075, #5215: autodoc: Add autodoc_default_options which accepts
17055 option values as dict
17056 Bugs fixed
17058 1.8.0b2
17059 · html: search box overrides to other elements if scrolled
17061 · i18n: warnings for translation catalogs have wrong line numbers
17063 (refs: #5321)
17064 · #5325: latex: cross references has been broken by multiply labeled
17066 objects
17067 · C++, fixes for symbol addition and lookup. Lookup should no longer
17069 break in partial builds. See also #5337.
17070 · #5348: download reference to remote file is not displayed
17072 · #5282: html theme: pygments_style of theme was overridden by conf.py
17074 by default
17075 · #4379: toctree shows confusing warning when document is excluded
17077 · #2401: autodoc: :members: causes :special-members: not to be shown
17079 · autodoc: ImportError is replaced by AttributeError for deeper module
17081 · #2720, #4034: Incorrect links with :download:, duplicate names, and
17083 parallel builds
17084 · #5290: autodoc: failed to analyze source code in egg package
17086 · #5399: Sphinx crashes if unknown po file exists
17088 1.8.0b1
17090 · i18n: message catalogs were reset on each initialization
17092 · #4850: latex: footnote inside footnote was not rendered
17094 · #4945: i18n: fix lang_COUNTRY not fallback correctly for
17096 IndexBuilder. Thanks to Shengjing Zhu.
17097 · #4983: productionlist directive generates invalid IDs for the tokens
17099 · #5132: (lualatex) PDF build fails if indexed word starts with Unicode
17101 character
17102 · #5133: latex: index headings “Symbols” and “Numbers” not internation‐
17104 alized
17105 · #5114: sphinx-build: Handle errors on scanning documents
17107 · epub: spine has been broken when “self” is listed on toctree (refs:
17109 #4611)
17110 · #344: autosummary does not understand docstring of module level
17112 attributes
17113 · #5191: C++, prevent nested declarations in functions to avoid lookup
17115 problems.
17116 · #5126: C++, add missing isPack method for certain template parameter
17118 types.
17119 · #5187: C++, parse attributes on declarators as well.
17121 · C++, parse delete expressions and basic new expressions as well.
17123 · #5002: graphviz: SVGs do not adapt to the column width
17125 Features removed
17127 1.8.0b1
17128 · sphinx.ext.pngmath extension
17130 Documentation
17132 1.8.0b1
17133 · #5083: Fix wrong make.bat option for internationalization.
17135 · #5115: napoleon: add admonitions added by #4613 to the docs.
17137 Release 1.7.9 (released Sep 05, 2018)
17139 Features added
17140 · #5359: Make generated texinfo files reproducible by sorting the
17141 anchors
17142 Bugs fixed
17144 · #5361: crashed on incremental build if document uses include direc‐
17145 tive
17146 Release 1.7.8 (released Aug 29, 2018)
17148 Incompatible changes
17149 · The type of env.included has been changed to dict of set
17150 Bugs fixed
17152 · #5320: intersphinx: crashed if invalid url given
17153 · #5326: manpage: crashed when invalid docname is specified as
17155 man_pages
17156 · #5322: autodoc: Any typehint causes formatting error
17158 · #5327: “document isn’t included in any toctree” warning on rebuild
17160 with generated files
17161 · #5335: quickstart: escape sequence has been displayed with MacPorts’
17163 python
17164 Release 1.7.7 (released Aug 19, 2018)
17166 Bugs fixed
17167 · #5198: document not in toctree warning when including files only for
17168 parallel builds
17169 · LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
17171 in latex console output (refs: #5236)
17172 · LaTeX: suppress “remreset Warning: The remreset package is obsolete”
17174 in latex console output with recent LaTeX (refs: #5237)
17175 · #5234: PDF output: usage of PAPER environment variable is broken
17177 since Sphinx 1.5
17178 · LaTeX: fix the latex_engine documentation regarding Latin Modern font
17180 with XeLaTeX/LuaLateX (refs: #5251)
17181 · #5280: autodoc: Fix wrong type annotations for complex typing
17183 · autodoc: Optional types are wrongly rendered
17185 · #5291: autodoc crashed by ForwardRef types
17187 · #5211: autodoc: No docs generated for functools.partial functions
17189 · #5306: autodoc: getargspec() raises NameError for invalid typehints
17191 · #5298: imgmath: math_number_all causes equations to have two numbers
17193 in html
17194 · #5294: sphinx-quickstart blank prompts in PowerShell
17196 Release 1.7.6 (released Jul 17, 2018)
17198 Bugs fixed
17199 · #5037: LaTeX \sphinxupquote{} breaks in Russian
17200 · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
17202 · #5016: crashed when recommonmark.AutoStrictify is enabled
17204 · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
17206 · #5009: latex: a label for table is vanished if table does not have a
17208 caption
17209 · #5048: crashed with numbered toctree
17211 · #2410: C, render empty argument lists for macros.
17213 · C++, fix lookup of full template specializations with no template
17215 arguments.
17216 · #4667: C++, fix assertion on missing references in global scope when
17218 using intersphinx. Thanks to Alan M. Carroll.
17219 · #5019: autodoc: crashed by Form Feed Character
17221 · #5032: autodoc: loses the first staticmethod parameter for old styled
17223 classes
17224 · #5036: quickstart: Typing Ctrl-U clears the whole of line
17226 · #5066: html: “relations” sidebar is not shown by default
17228 · #5091: latex: curly braces in index entries are not handled correctly
17230 · #5070: epub: Wrong internal href fragment links
17232 · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
17234 · #4272: PDF builds of French projects have issues with XeTeX
17236 · #5076: napoleon raises RuntimeError with python 3.7
17238 · #5125: sphinx-build: Interface of sphinx:main() has changed
17240 · sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
17242 given argument
17243 · #5146: autosummary: warning is emitted when the first line of doc‐
17245 string ends with literal notation
17246 · autosummary: warnings of autosummary indicates wrong location (refs:
17248 #5146)
17249 · #5143: autodoc: crashed on inspecting dict like object which does not
17251 support sorting
17252 · #5139: autodoc: Enum argument missing if it shares value with another
17254 · #4946: py domain: rtype field could not handle “None” as a type
17256 · #5176: LaTeX: indexing of terms containing @, !, or " fails
17258 · #5161: html: crashes if copying static files are failed
17260 · #5167: autodoc: Fix formatting type annotations for tuples with more
17262 than two arguments
17263 · #3329: i18n: crashed by auto-symbol footnote references
17265 · #5158: autosummary: module summary has been broken when it starts
17267 with heading
17268 Release 1.7.5 (released May 29, 2018)
17270 Bugs fixed
17271 · #4924: html search: Upper characters problem in any other languages
17272 · #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
17274 tains a module starting with underscore
17275 · #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
17277 for contents, topic, admonition, table and section.
17278 · #4913: i18n: literal blocks in bullet list are not translated
17280 · #4962: C++, raised TypeError on duplicate declaration.
17282 · #4825: C++, properly parse expr roles and give better error messages
17284 when (escaped) line breaks are present.
17285 · C++, properly use desc_addname nodes for prefixes of names.
17287 · C++, parse pack expansions in function calls.
17289 · #4915, #4916: links on search page are broken when using dirhtml
17291 builder
17292 · #4969: autodoc: constructor method should not have return annotation
17294 · latex: deeply nested enumerated list which is beginning with non-1
17296 causes LaTeX engine crashed
17297 · #4978: latex: shorthandoff is not set up for Brazil locale
17299 · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
17301 · #4946: py domain: type field could not handle “None” as a type
17303 · #4979: latex: Incorrect escaping of curly braces in index entries
17305 · #4956: autodoc: Failed to extract document from a subclass of the
17307 class on mocked module
17308 · #4973: latex: glossary directive adds whitespace to each item
17310 · #4980: latex: Explicit labels on code blocks are duplicated
17312 · #4919: node.asdom() crashes if toctree has :numbered: option
17314 · #4914: autodoc: Parsing error when using dataclasses without default
17316 values
17317 · #4931: autodoc: crashed when handler for autodoc-skip-member raises
17319 an error
17320 · #4931: autodoc: crashed when subclass of mocked class are processed
17322 by napoleon module
17323 · #5007: sphinx-build crashes when error log contains a “%” character
17325 Release 1.7.4 (released Apr 25, 2018)
17327 Bugs fixed
17328 · #4885, #4887: domains: Crashed with duplicated objects
17329 · #4889: latex: sphinx.writers.latex causes recursive import
17331 Release 1.7.3 (released Apr 23, 2018)
17333 Bugs fixed
17334 · #4769: autodoc loses the first staticmethod parameter
17335 · #4790: autosummary: too wide two column tables in PDF builds
17337 · #4795: Latex customization via _templates/longtable.tex_t is broken
17339 · #4789: imgconverter: confused by convert.exe of Windows
17341 · #4783: On windows, Sphinx crashed when drives of srcdir and outdir
17343 are different
17344 · #4812: autodoc ignores type annotated variables
17346 · #4817: wrong URLs on warning messages
17348 · #4784: latex: latex_show_urls assigns incorrect footnote numbers if
17350 hyperlinks exists inside substitutions
17351 · #4837: latex with class memoir Error: Font command \sf is not sup‐
17353 ported
17354 · #4803: latex: too slow in proportion to number of auto numbered foot‐
17356 notes
17357 · #4838: htmlhelp: The entries in .hhp file is not ordered
17359 · toctree directive tries to glob for URL having query_string
17361 · #4871: html search: Upper characters problem in German
17363 · #4717: latex: Compilation for German docs failed with LuaLaTeX and
17365 XeLaTeX
17366 · #4459: duplicated labels detector does not work well in parallel
17368 build
17369 · #4878: Crashed with extension which returns invalid metadata
17371 Release 1.7.2 (released Mar 21, 2018)
17373 Incompatible changes
17374 · #4520: apidoc: folders with an empty __init__.py are no longer
17375 excluded from TOC
17376 Bugs fixed
17378 · #4669: sphinx.build_main and sphinx.make_main throw NameError
17379 · #4685: autosummary emits meaningless warnings
17381 · autodoc: crashed when invalid options given
17383 · pydomain: always strip parenthesis if empty (refs: #1042)
17385 · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
17387 · #4701: viewcode: Misplaced <div> in viewcode html output
17389 · #4444: Don’t require numfig to use :numref: on sections
17391 · #4727: Option clash for package textcomp
17393 · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
17395 · #4716: Generation PDF file with TexLive on Windows, file not found
17397 error
17398 · #4574: vertical space before equation in latex
17400 · #4720: message when an image is mismatched for builder is not clear
17402 · #4655, #4684: Incomplete localization strings in Polish and Chinese
17404 · #2286: Sphinx crashes when error is happens in rendering HTML pages
17406 · #4688: Error to download remote images having long URL
17408 · #4754: sphinx/pycode/__init__.py raises AttributeError
17410 · #1435: qthelp builder should htmlescape keywords
17412 · epub: Fix docTitle elements of toc.ncx is not escaped
17414 · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
17416 · #4767: html: search highlighting breaks mathjax equations
17418 Release 1.7.1 (released Feb 23, 2018)
17420 Deprecated
17421 · #4623: sphinx.build_main() is deprecated.
17422 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
17424 has been changed (Since 1.7.0)
17425 · #4664: sphinx.ext.intersphinx.debug() is deprecated.
17427 For more details, see deprecation APIs list
17429 Bugs fixed
17431 · #4608: epub: Invalid meta tag is generated
17432 · #4260: autodoc: keyword only argument separator is not disappeared if
17434 it is appeared at top of the argument list
17435 · #4622: epub: epub_scheme does not effect to content.opf
17437 · #4627: graphviz: Fit graphviz images to page
17439 · #4617: quickstart: PROJECT_DIR argument is required
17441 · #4623: sphinx.build_main no longer exists in 1.7.0
17443 · #4615: The argument of sphinx.build has been changed in 1.7.0
17445 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
17447 has been changed
17448 · #4630: Have order on msgids in sphinx.pot deterministic
17450 · #4563: autosummary: Incorrect end of line punctuation detection
17452 · #4577: Enumerated sublists with explicit start with wrong number
17454 · #4641: A external link in TOC cannot contain “?” with :glob: option
17456 · C++, add missing parsing of explicit casts and typeid in expression
17458 parsing.
17459 · C++, add missing parsing of this in expression parsing.
17461 · #4655: Fix incomplete localization strings in Polish
17463 · #4653: Fix error reporting for parameterless ImportErrors
17465 · #4664: Reading objects.inv fails again
17467 · #4662: any refs with term targets crash when an ambiguity is encoun‐
17469 tered
17470 Release 1.7.0 (released Feb 12, 2018)
17472 Dependencies
17473 1.7.0b1
17474 · Add packaging package
17476 Incompatible changes
17478 1.7.0b1
17479 · #3668: The arguments has changed of main functions for each command
17481 · #3893: Unknown html_theme_options throw warnings instead of errors
17483 · #3927: Python parameter/variable types should match classes, not all
17485 objects
17486 · #3962: sphinx-apidoc now recognizes given directory as an implicit
17488 namespace package when --implicit-namespaces option given, not subdi‐
17489 rectories of given directory.
17490 · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
17492 · #4226: apidoc: Generate new style makefile (make-mode)
17494 · #4274: sphinx-build returns 2 as an exit code on argument error
17496 · #4389: output directory will be created after loading extensions
17498 · autodoc does not generate warnings messages to the generated document
17500 even if keep_warnings is True. They are only emitted to stderr.
17501 · shebang line is removed from generated conf.py
17503 · #2557: autodoc: autodoc_mock_imports only mocks specified modules
17505 with their descendants. It does not mock their ancestors. If you
17506 want to mock them, please specify the name of ancestors explicitly.
17507 · #3620: html theme: move DOCUMENTATION_OPTIONS to independent
17509 JavaScript file (refs: #4295)
17510 · #4246: Limit width of text body for all themes. Configurable via
17512 theme options body_min_width and body_max_width.
17513 · #4771: apidoc: The exclude_patterns arguments are ignored if they are
17515 placed just after command line options
17516 1.7.0b2
17518 · #4467: html theme: Rename csss block to css
17520 Deprecated
17522 1.7.0b1
17523 · using a string value for html_sidebars is deprecated and only list
17525 values will be accepted at 2.0.
17526 · format_annotation() and formatargspec() is deprecated. Please use
17528 sphinx.util.inspect.Signature instead.
17529 · sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
17531 tils. switch_source_input() and now deprecated. It will be removed
17532 in Sphinx-2.0.
17533 · sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
17535 now deprecated. Please use app.add_autodocumenter() instead.
17536 · AutoDirective._special_attrgetters is now deprecated. Please use
17538 app.add_autodoc_attrgetter() instead.
17539 Features added
17541 1.7.0b1
17542 · C++, handle decltype(auto).
17544 · #2406: C++, add proper parsing of expressions, including linking of
17546 identifiers.
17547 · C++, add a cpp:expr role for inserting inline C++ expressions or
17549 types.
17550 · C++, support explicit member instantiations with shorthand template
17552 prefix.
17553 · C++, make function parameters linkable, like template params.
17555 · #3638: Allow to change a label of reference to equation using
17557 math_eqref_format
17558 · Now suppress_warnings accepts following configurations:
17560 · ref.python (ref: #3866)
17562 · #3872: Add latex key to configure literal blocks caption position in
17564 PDF output (refs #3792, #1723)
17565 · In case of missing docstring try to retrieve doc from base classes
17567 (ref: #3140)
17568 · #4023: Clarify error message when any role has more than one target.
17570 · #3973: epub: allow to override build date
17572 · #3972: epub: Sort manifest entries by filename
17574 · #4052: viewcode: Sort before highlighting module code
17576 · #1448: qthelp: Add new config value; qthelp_namespace
17578 · #4140: html themes: Make body tag inheritable
17580 · #4168: improve zh search with jieba
17582 · HTML themes can set up default sidebars through theme.conf
17584 · #3160: html: Use <kdb> to represent :kbd: role
17586 · #4212: autosummary: catch all exceptions when importing modules
17588 · #4166: Add math_numfig for equation numbering by section (refs:
17590 #3991, #4080). Thanks to Oliver Jahn.
17591 · #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
17593 code-blocks
17594 · #947: autodoc now supports ignore-module-all to ignore a module’s
17596 __all__
17597 · #4332: Let LaTeX obey math_numfig for equation numbering
17599 · #4093: sphinx-build creates empty directories for unknown tar‐
17601 gets/builders
17602 · Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
17604 sion to limit the scope of inheritance graphs.
17605 · #4183: doctest: :pyversion: option also follows PEP-440 specification
17607 · #4235: html: Add manpages_url to make manpage roles to hyperlinks
17609 · #3570: autodoc: Do not display ‘typing.’ module for type hints
17611 · #4354: sphinx-build now emits finish message. Builders can modify it
17613 through Builder.epilog attribute
17614 · #4245: html themes: Add language to javascript vars list
17616 · #4079: html: Add notranslate class to each code-blocks, literals and
17618 maths to let Google Translate know they are not translatable
17619 · #4137: doctest: doctest block is always highlighted as python console
17621 (pycon)
17622 · #4137: doctest: testcode block is always highlighted as python
17624 · #3998: text: Assign section numbers by default. You can control it
17626 using text_add_secnumbers and text_secnumber_suffix
17627 1.7.0b2
17629 · #4271: sphinx-build supports an option called -j auto to adjust num‐
17631 bers of processes automatically.
17632 · Napoleon: added option to specify custom section tags.
17634 Features removed
17636 1.7.0b1
17637 · Configuration variables
17639 · html_use_smartypants
17641 · latex_keep_old_macro_names
17643 · latex_elements[‘footer’]
17645 · utility methods of sphinx.application.Sphinx class
17647 · buildername (property)
17649 · _display_chunk()
17651 · old_status_iterator()
17653 · status_iterator()
17655 · _directive_helper()
17657 · utility methods of sphinx.environment.BuildEnvironment class
17659 · currmodule (property)
17661 · currclass (property)
17663 · epub2 builder
17665 · prefix and colorfunc parameter for warn()
17667 · sphinx.util.compat module
17669 · sphinx.util.nodes.process_only_nodes()
17671 · LaTeX environment notice, use sphinxadmonition instead
17673 · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
17675 · C++, support of function concepts. Thanks to mickk-on-cpp.
17677 · Not used and previously not documented LaTeX macros \shortversion and
17679 \setshortversion
17680 Bugs fixed
17682 1.7.0b1
17683 · #3882: Update the order of files for HTMLHelp and QTHelp
17685 · #3962: sphinx-apidoc does not recognize implicit namespace packages
17687 correctly
17688 · #4094: C++, allow empty template argument lists.
17690 · C++, also hyperlink types in the name of declarations with qualified
17692 names.
17693 · C++, do not add index entries for declarations inside concepts.
17695 · C++, support the template disambiguator for dependent names.
17697 · #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
17699 from the one of figures and tables
17700 · #4330: PDF ‘howto’ documents have an incoherent default LaTeX
17702 tocdepth counter setting
17703 · #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
17705 Thanks to Joel Nothman.
17706 · #4081: Warnings and errors colored the same when building
17708 · latex: Do not display ‘Release’ label if release is not set
17710 1.7.0b2
17712 · #4415: autodoc classifies inherited classmethods as regular methods
17714 · #4415: autodoc classifies inherited staticmethods as regular methods
17716 · #4472: DOCUMENTATION_OPTIONS is not defined
17718 · #4491: autodoc: prefer _MockImporter over other importers in
17720 sys.meta_path
17721 · #4490: autodoc: type annotation is broken with python 3.7.0a4+
17723 · utils package is no longer installed
17725 · #3952: apidoc: module header is too escaped
17727 · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
17729 · #4493: recommonmark raises AttributeError if AutoStructify enabled
17731 · #4209: intersphinx: In link title, “v” should be optional if target
17733 has no version
17734 · #4230: slowdown in writing pages with sphinx 1.6
17736 · #4522: epub: document is not rebuilt even if config changed
17738 1.7.0b3
17740 · #4019: inheritance_diagram AttributeError stopping make process
17742 · #4531: autosummary: methods are not treated as attributes
17744 · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
17746 · #4539: autodoc emits warnings for partialmethods
17748 · #4223: doctest: failing tests reported in wrong file, at wrong line
17750 · i18n: message catalogs are not compiled if specific filenames are
17752 given for sphinx-build as arguments (refs: #4560)
17753 · #4027: sphinx.ext.autosectionlabel now expects labels to be the same
17755 as they are in the raw source; no smart quotes, nothig fancy.
17756 · #4581: apidoc: Excluded modules still included
17758 Testing
17760 1.7.0b1
17761 · Add support for docutils 0.14
17763 · Add tests for the sphinx.ext.inheritance_diagram extension.
17765 Release 1.6.7 (released Feb 04, 2018)
17767 Bugs fixed
17768 · #1922: html search: Upper characters problem in French
17769 · #4412: Updated jQuery version from 3.1.0 to 3.2.1
17771 · #4438: math: math with labels with whitespace cause html error
17773 · #2437: make full reference for classes, aliased with “alias of”
17775 · #4434: pure numbers as link targets produce warning
17777 · #4477: Build fails after building specific files
17779 · #4449: apidoc: include “empty” packages that contain modules
17781 · #3917: citation labels are transformed to ellipsis
17783 · #4501: graphviz: epub3 validation error caused if graph is not click‐
17785 able
17786 · #4514: graphviz: workaround for wrong map ID which graphviz generates
17788 · #4525: autosectionlabel does not support parallel build
17790 · #3953: Do not raise warning when there is a working intersphinx
17792 inventory
17793 · #4487: math: ValueError is raised on parallel build. Thanks to
17795 jschueller.
17796 · #2372: autosummary: invalid signatures are shown for type annotated
17798 functions
17799 · #3942: html: table is not aligned to center even if :align: center
17801 Release 1.6.6 (released Jan 08, 2018)
17803 Features added
17804 · #4181: autodoc: Sort dictionary keys when possible
17805 · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
17807 · Easier customizability of LaTeX macros involved in rendering of
17809 code-blocks
17810 · Show traceback if conf.py raises an exception (refs: #4369)
17812 · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
17814 · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
17816 Bugs fixed
17818 · #4334: sphinx-apidoc: Don’t generate references to non-existing files
17819 in TOC
17820 · #4206: latex: reST label between paragraphs loses paragraph break
17822 · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
17824 · #4221: napoleon depends on autodoc, but users need to load it manu‐
17826 ally
17827 · #2298: automodule fails to document a class attribute
17829 · #4099: C++: properly link class reference to class from inside con‐
17831 structor
17832 · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
17834 · #4249: PDF output: Pygments error highlighting increases line spacing
17836 in code blocks
17837 · #1238: Support :emphasize-lines: in PDF output
17839 · #4279: Sphinx crashes with pickling error when run with multiple pro‐
17841 cesses and remote image
17842 · #1421: Respect the quiet flag in sphinx-quickstart
17844 · #4281: Race conditions when creating output directory
17846 · #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
17848 generates \chapter commands
17849 · #4214: Two todolist directives break sphinx-1.6.5
17851 · Fix links to external option docs with intersphinx (refs: #3769)
17853 · #4091: Private members not documented without :undoc-members:
17855 Release 1.6.5 (released Oct 23, 2017)
17857 Features added
17858 · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
17859 · #4112: Don’t override the smart_quotes setting if it was already set
17861 · #4125: Display reference texts of original and translated passages on
17863 i18n warning message
17864 · #4147: Include the exception when logging PO/MO file read/write
17866 Bugs fixed
17868 · #4085: Failed PDF build from image in parsed-literal using :align:
17869 option
17870 · #4100: Remove debug print from autodoc extension
17872 · #3987: Changing theme from alabaster causes HTML build to fail
17874 · #4096: C++, don’t crash when using the wrong role type. Thanks to
17876 mitya57.
17877 · #4070, #4111: crashes when the warning message contains format
17879 strings (again)
17880 · #4108: Search word highlighting breaks SVG images
17882 · #3692: Unable to build HTML if writing .buildinfo failed
17884 · #4152: HTML writer crashes if a field list is placed on top of the
17886 document
17887 · #4063: Sphinx crashes when labeling directive .. todolist::
17889 · #4134: [doc] docutils.conf is not documented explicitly
17891 · #4169: Chinese language doesn’t trigger Chinese search automatically
17893 · #1020: ext.todo todolist not linking to the page in pdflatex
17895 · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
17897 · #3739: :module: option is ignored at content of pyobjects
17899 · #4149: Documentation: Help choosing latex_engine
17901 · #4090: [doc] latex_additional_files with extra LaTeX macros should
17903 not use .tex extension
17904 · Failed to convert reST parser error to warning (refs: #4132)
17906 Release 1.6.4 (released Sep 26, 2017)
17908 Features added
17909 · #3926: Add autodoc_warningiserror to suppress the behavior of -W
17910 option during importing target modules on autodoc
17911 Bugs fixed
17913 · #3924: docname lost after dynamically parsing RST in extension
17914 · #3946: Typo in sphinx.sty (this was a bug with no effect in default
17916 context)
17917 ·
17919 pep and :rfc: does not supports default-role directive (refs:
17921 #3960)
17922 · #3960: default_role = ‘guilabel’ not functioning
17924 · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
17926 dows.
17927 · #4026: nature: Fix macOS Safari scrollbar color
17929 · #3877: Fix for C++ multiline signatures.
17931 · #4006: Fix crash on parallel build
17933 · #3969: private instance attributes causes AttributeError
17935 · #4041: C++, remove extra name linking in function pointers.
17937 · #4038: C, add missing documentation of member role.
17939 · #4044: An empty multicolumn cell causes extra row height in PDF out‐
17941 put
17942 · #4049: Fix typo in output of sphinx-build -h
17944 · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
17946 · Avoid indent after index entries in latex (refs: #4066)
17948 · #4070: crashes when the warning message contains format strings
17950 · #4067: Return non-zero exit status when make subprocess fails
17952 · #4055: graphviz: the :align: option does not work for SVG output
17954 · #4055: graphviz: the :align: center option does not work for latex
17956 output
17957 · #4051: warn() function for HTML theme outputs ‘None’ string
17959 Release 1.6.3 (released Jul 02, 2017)
17961 Features added
17962 · latex: hint that code-block continues on next page (refs: #3764,
17963 #3792)
17964 Bugs fixed
17966 · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
17967 · #3829: sphinx-quickstart template is incomplete regarding use of
17969 alabaster
17970 · #3772: ‘str object’ has no attribute ‘filename’
17972 · Emit wrong warnings if citation label includes hyphens (refs: #3565)
17974 · #3858: Some warnings are not colored when using –color option
17976 · #3775: Remove unwanted whitespace in default template
17978 · #3835: sphinx.ext.imgmath fails to convert SVG images if project
17980 directory name contains spaces
17981 · #3850: Fix color handling in make mode’s help command
17983 · #3865: use of self.env.warn in sphinx extension fails
17985 · #3824: production lists apply smart quotes transform since Sphinx
17987 1.6.1
17988 · latex: fix \sphinxbfcode swallows initial space of argument
17990 · #3878: Quotes in auto-documented class attributes should be straight
17992 quotes in PDF output
17993 · #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
17995 tical whitespace
17996 · #3885: duplicated footnotes raises IndexError
17998 · #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
18000 pat.Directive
18001 · #3874: Bogus warnings for “citation not referenced” for cross-file
18003 citations
18004 · #3860: Don’t download images when builders not supported images
18006 · #3860: Remote image URIs without filename break builders not sup‐
18008 ported remote images
18009 · #3833: command line messages are translated unintentionally with lan‐
18011 guage setting.
18012 · #3840: make checking epub_uid strict
18014 · #3851, #3706: Fix about box drawing characters for PDF output
18016 · #3900: autosummary could not find methods
18018 · #3902: Emit error if latex_documents contains non-unicode string in
18020 py2
18021 Release 1.6.2 (released May 28, 2017)
18023 Incompatible changes
18024 · #3789: Do not require typing module for python>=3.5
18025 Bugs fixed
18027 · #3754: HTML builder crashes if HTML theme appends own stylesheets
18028 · #3756: epub: Entity ‘mdash’ not defined
18030 · #3758: Sphinx crashed if logs are emitted in conf.py
18032 · #3755: incorrectly warns about dedent with literalinclude
18034 · #3742: RTD PDF builds of Sphinx own docs are missing an index entry
18036 in the bookmarks and table of contents. This is
18037 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
18038 extra LaTeX code in Sphinx’s own conf.py
18039 · #3770: Build fails when a “code-block” has the option emphasize-lines
18041 and the number indicated is higher than the number of lines
18042 · #3774: Incremental HTML building broken when using citations
18044 · #3763: got epubcheck validations error if epub_cover is set
18046 · #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
18048 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
18049 · #3796: env.resolve_references() crashes when non-document node given
18051 · #3803: Sphinx crashes with invalid PO files
18053 · #3791: PDF “continued on next page” for long tables isn’t interna‐
18055 tionalized
18056 · #3788: smartquotes emits warnings for unsupported languages
18058 · #3807: latex Makefile for make latexpdf is only for unixen
18060 · #3781: double hyphens in option directive are compiled as endashes
18062 · #3817: latex builder raises AttributeError
18064 Release 1.6.1 (released May 16, 2017)
18066 Dependencies
18067 1.6b1
18068 · (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
18070 ages (Feb. 2014) and earlier tex installations may not be fully com‐
18071 pliant, particularly regarding Unicode engines xelatex and lualatex
18072 · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
18074 X (refs: #3082)
18075 Incompatible changes
18077 1.6b1
18078 · #1061, #2336, #3235: Now generation of autosummary doesn’t contain
18080 imported members by default. Thanks to Luc Saffre.
18081 · LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
18083 graphics has the custom code to fit image to available width if over‐
18084 sized.
18085 · The subclasses of sphinx.domains.Index should override generate()
18087 method. The default implementation raises NotImplementedError
18088 · LaTeX positioned long tables horizontally centered, and short ones
18090 flushed left (no text flow around table.) The position now defaults
18091 to center in both cases, and it will obey Docutils 0.13 :align:
18092 option (refs #3415, #3377)
18093 · option directive also allows all punctuations for the option name
18095 (refs: #3366)
18096 · #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
18098 tive (refs #3412)
18099 · literalinclude directive does not allow the combination of :diff:
18101 option and other options (refs: #3416)
18102 · LuaLaTeX engine uses fontspec like XeLaTeX. It is advised
18104 latex_engine = 'lualatex' be used only on up-to-date TeX installs
18105 (refs #3070, #3466)
18106 · latex_keep_old_macro_names default value has been changed from True
18108 to False. This means that some LaTeX macros for styling are by
18109 default defined only with \sphinx.. prefixed names. (refs: #3429)
18110 · Footer “Continued on next page” of LaTeX longtable’s now not framed
18112 (refs: #3497)
18113 · #3529: The arguments of BuildEnvironment.__init__ is changed
18115 · #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
18117 only)
18118 · #3558: Emit warnings if footnotes and citations are not referenced.
18120 The warnings can be suppressed by suppress_warnings.
18121 · latex made available (non documented) colour macros from a file dis‐
18123 tributed with pdftex engine for Plain TeX. This is removed in order
18124 to provide better support for multiple TeX engines. Only interface
18125 from color or xcolor packages should be used by extensions of Sphinx
18126 latex writer. (refs #3550)
18127 · Builder.env is not filled at instantiation
18129 · #3594: LaTeX: single raw directive has been considered as block level
18131 element
18132 · #3639: If html_experimental_html5_writer is available, epub builder
18134 use it by default.
18135 · Sphinx.add_source_parser() raises an error if duplicated
18137 1.6b2
18139 · #3345: Replace the custom smartypants code with Docutils’
18141 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at
18142 Docutils.
18143 1.6b3
18145 · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
18147 · LaTeX package multirow is not used and not loaded by Sphinx anymore
18149 · Add line numbers to citation data in std domain
18151 1.6 final
18153 · LaTeX package threeparttable is not used and not loaded by Sphinx
18155 anymore (refs #3686, #3532, #3377)
18156 Features removed
18158 · Configuration variables
18159 · epub3_contributor
18161 · epub3_description
18163 · epub3_page_progression_direction
18165 · html_translator_class
18167 · html_use_modindex
18169 · latex_font_size
18171 · latex_paper_size
18173 · latex_preamble
18175 · latex_use_modindex
18177 · latex_use_parts
18179 · termsep node
18181 · defindex.html template
18183 · LDML format support in today, today_fmt and html_last_updated_fmt
18185 · :inline: option for the directives of sphinx.ext.graphviz extension
18187 · sphinx.ext.pngmath extension
18189 · sphinx.util.compat.make_admonition()
18191 Features added
18193 1.6b1
18194 · #3136: Add :name: option to the directives in sphinx.ext.graphviz
18196 · #2336: Add imported_members option to sphinx-autogen command to docu‐
18198 ment imported members.
18199 · C++, add :tparam-line-spec: option to templated declarations. When
18201 specified, each template parameter will be rendered on a separate
18202 line.
18203 · #3359: Allow sphinx.js in a user locale dir to override sphinx.js
18205 from Sphinx
18206 · #3303: Add :pyversion: option to the doctest directive.
18208 · #3378: (latex) support for :widths: option of table directives (refs:
18210 #3379, #3381)
18211 · #3402: Allow to suppress “download file not readable” warnings using
18213 suppress_warnings.
18214 · #3377: latex: Add support for Docutils 0.13 :align: option for tables
18216 (but does not implement text flow around table).
18217 · latex: footnotes from inside tables are hyperlinked (except from cap‐
18219 tions or headers) (refs: #3422)
18220 · Emit warning if over dedent has detected on literalinclude directive
18222 (refs: #3416)
18223 · Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
18225 and polyglossia). (refs: #3070, #3466)
18226 · Make 'extraclassoptions' key of latex_elements public (refs #3480)
18228 · #3463: Add warning messages for required EPUB3 metadata. Add default
18230 value to epub_description to avoid warning like other settings.
18231 · #3476: setuptools: Support multiple builders
18233 · latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
18235 quotes… as do normal cells (refs: #3435)
18236 · HTML builder uses experimental HTML5 writer if html_experimen‐
18238 tal_html5_writer is True and docutils 0.13 or later is installed.
18239 · LaTeX macros to customize space before and after tables in PDF output
18241 (refs #3504)
18242 · #3348: Show decorators in literalinclude and viewcode directives
18244 · #3108: Show warning if :start-at: and other literalinclude options
18246 does not match to the text
18247 · #3609: Allow to suppress “duplicate citation” warnings using sup‐
18249 press_warnings
18250 · #2803: Discovery of builders by entry point
18252 · #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
18254 stylesheets
18255 · #3589: Support remote images on non-HTML builders
18257 · #3589: Support images in Data URI on non-HTML builders
18259 · #2961: improve autodoc_mock_imports. Now the config value only
18261 requires to declare the top-level modules that should be mocked.
18262 Thanks to Robin Jarry.
18263 · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
18265 ture calculation. Thanks to Nathaniel J. Smith.
18266 · #3641: Epub theme supports HTML structures that are generated by
18268 HTML5 writer.
18269 · #3644 autodoc uses inspect instead of checking types. Thanks to
18271 Jeroen Demeyer.
18272 · Add a new extension; sphinx.ext.imgconverter. It converts images in
18274 the document to appropriate format for builders
18275 · latex: Use templates to render tables (refs #3389, 2a37b0e)
18277 1.6b2
18279 · LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass
18281 options to latexmk when executing make latexpdf (refs #3695, #3720)
18282 · Add a new event env-check-consistency to check consistency to exten‐
18284 sions
18285 · Add Domain.check_consistency() to check consistency
18287 Bugs fixed
18289 1.6b1
18290 · literalinclude directive expands tabs after dedent-ing (refs: #3416)
18292 · #1574: Paragraphs in table cell doesn’t work in Latex output
18294 · #3288: Table with merged headers not wrapping text
18296 · #3491: Inconsistent vertical space around table and longtable in PDF
18298 · #3506: Depart functions for all admonitions in HTML writer now prop‐
18300 erly pass node to depart_admonition.
18301 · #2693: Sphinx latex style file wrongly inhibits colours for section
18303 headings for latex+dvi(ps,pdf,pdfmx)
18304 · C++, properly look up any references.
18306 · #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
18308 with gzip
18309 · #3551: PDF information dictionary is lacking author and title data
18311 · #3351: intersphinx does not refers context like py:module, py:class
18313 and so on.
18314 · Fail to load template file if the parent template is archived
18316 1.6b2
18318 · #3661: sphinx-build crashes on parallel build
18320 · #3669: gettext builder fails with “ValueError: substring not found”
18322 · #3660: Sphinx always depends on sphinxcontrib-websupport and its
18324 dependencies
18325 · #3472: smart quotes getting wrong in latex (at least with list of
18327 strings via autoattribute) (refs: #3345, #3666)
18328 1.6b3
18330 · #3588: No compact (p tag) html output in the i18n document build even
18332 when html_compact_lists is True.
18333 · The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using
18335 latexmk) aborted earlier in case of LaTeX errors than was the case
18336 with 1.5 series, due to hard-coded usage of --halt-on-error option.
18337 (refs #3695)
18338 · #3683: sphinx.websupport module is not provided by default
18340 · #3683: Failed to build document if builder.css_file.insert() is
18342 called
18343 · #3714: viewcode extension not taking highlight_code='none' in account
18345 · #3698: Moving :doc: to std domain broke backwards compatibility
18347 · #3633: misdetect unreferenced citations
18349 1.6 final
18351 · LaTeX tables do not allow multiple paragraphs in a header cell
18353 · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
18355 · #3532: Figure or literal block captions in cells of short tables
18357 cause havoc in PDF output
18358 · Fix: in PDF captions of tables are rendered differently whether table
18360 is of longtable class or not (refs #3686)
18361 · #3725: Todo looks different from note in LaTeX output
18363 · #3479: stub-columns have no effect in LaTeX output
18365 · #3738: Nonsensical code in theming.py
18367 · #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
18369 options -pdfxe and -pdflua
18370 Deprecated
18372 1.6b1
18373 · sphinx.util.compat.Directive class is now deprecated. Please use
18375 instead docutils.parsers.rst.Directive
18376 · sphinx.util.compat.docutils_version is now deprecated
18378 · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
18380 deprecated. Please use sphinx.util.logging (logging-api) instead.
18381 · #3318: notice is now deprecated as LaTeX environment name and will be
18383 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
18384 instead (as Sphinx does since 1.5.)
18385 · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
18387 recated. Please use sphinx.util:status_iterator() instead.
18388 · Sphinx._directive_helper() is deprecated. Please use
18390 sphinx.util.docutils.directive_helper() instead.
18391 · BuildEnvironment.set_warnfunc() is now deprecated
18393 · Following methods of BuildEnvironment is now deprecated.
18395 · BuildEnvironment.note_toctree()
18397 · BuildEnvironment.get_toc_for()
18399 · BuildEnvironment.get_toctree_for()
18401 · BuildEnvironment.create_index()
18403 Please use sphinx.environment.adapters modules instead.
18405 · latex package footnote is not loaded anymore by its bundled replace‐
18407 ment footnotehyper-sphinx. The redefined macros keep the same names
18408 as in the original package.
18409 · #3429: deprecate config setting latex_keep_old_macro_names. It will
18411 be removed at 1.7, and already its default value has changed from
18412 True to False.
18413 · #3221: epub2 builder is deprecated
18415 · #3254: sphinx.websupport is now separated into independent package;
18417 sphinxcontrib-websupport. sphinx.websupport will be removed in
18418 Sphinx-2.0.
18419 · #3628: sphinx_themes entry_point is deprecated. Please use
18421 sphinx.html_themes instead.
18422 1.6b2
18424 · #3662: builder.css_files is deprecated. Please use add_stylesheet()
18426 API instead.
18427 1.6 final
18429 · LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
18431 1.7. Please move customization into new macro \sphinxstyletheadfam‐
18432 ily.
18433 Testing
18435 1.6 final
18436 · #3458: Add sphinx.testing (experimental)
18438 Release 1.6 (unreleased)
18440 · not released (because of package script error)
18441 Release 1.5.6 (released May 15, 2017)
18443 Bugs fixed
18444 · #3614: Sphinx crashes with requests-2.5.0
18445 · #3618: autodoc crashes with tupled arguments
18447 · #3664: No space after the bullet in items of a latex list produced by
18449 Sphinx
18450 · #3657: EPUB builder crashes if a document starting with genindex
18452 exists
18453 · #3588: No compact (p tag) html output in the i18n document build even
18455 when html_compact_lists is True.
18456 · #3685: AttributeError when using 3rd party domains
18458 · #3702: LaTeX writer styles figure legends with a hard-coded \small
18460 · #3708: LaTeX writer allows irc scheme
18462 · #3717: Stop enforcing that favicon’s must be .ico
18464 · #3731, #3732: Protect isenumclass predicate against non-class argu‐
18466 ments
18467 · #3320: Warning about reference target not being found for container
18469 types
18470 · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
18472 Release 1.5.5 (released Apr 03, 2017)
18474 Bugs fixed
18475 · #3597: python domain raises UnboundLocalError if invalid name given
18476 · #3599: Move to new MathJax CDN
18478 Release 1.5.4 (released Apr 02, 2017)
18480 Features added
18481 · #3470: Make genindex support all kinds of letters, not only Latin
18482 ones
18483 Bugs fixed
18485 · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
18486 to failed PDF build
18487 · EPUB file has duplicated nav.xhtml link in content.opf except first
18489 time build
18490 · #3488: objects.inv has broken when release or version contain return
18492 code
18493 · #2073, #3443, #3490: gettext builder that writes pot files unless the
18495 content are same without creation date. Thanks to Yoshiki Shibukawa.
18496 · #3487: intersphinx: failed to refer options
18498 · #3496: latex longtable’s last column may be much wider than its con‐
18500 tents
18501 · #3507: wrong quotes in latex output for productionlist directive
18503 · #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
18505 links rendered as code
18506 · #2665, #2607: Link names in C++ docfields, and make it possible for
18508 other domains.
18509 · #3542: C++, fix parsing error of non-type template argument with tem‐
18511 plate.
18512 · #3065, #3520: python domain fails to recognize nested class
18514 · #3575: Problems with pdflatex in a Turkish document built with sphinx
18516 has reappeared (refs #2997, #2397)
18517 · #3577: Fix intersphinx debug tool
18519 · A LaTeX command such as \\large inserted in the title items of
18521 latex_documents causes failed PDF build (refs #3551, #3567)
18522 Release 1.5.3 (released Feb 26, 2017)
18524 Features added
18525 · Support requests-2.0.0 (experimental) (refs: #3367)
18526 · (latex) PDF page margin dimensions may be customized (refs: #3387)
18528 · literalinclude directive allows combination of :pyobject: and :lines:
18530 options (refs: #3416)
18531 · #3400: make-mode doesn’t use subprocess on building docs
18533 Bugs fixed
18535 · #3370: the caption of code-block is not picked up for translation
18536 · LaTeX: release is not escaped (refs: #3362)
18538 · #3364: sphinx-quickstart prompts overflow on Console with 80 chars
18540 width
18541 · since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
18543 (refs: #3383)
18544 · #3392: 'releasename' in latex_elements is not working
18546 · #3356: Page layout for Japanese 'manual' docclass has a shorter text
18548 area
18549 · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
18551 wrong PDF page dimensions
18552 · #3399: quickstart: conf.py was not overwritten by template
18554 · #3366: option directive does not allow punctuations
18556 · #3410: return code in release breaks html search
18558 · #3427: autodoc: memory addresses are not stripped on Windows
18560 · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
18562 · #3349: Result of IndexBuilder.load() is broken
18564 · #3450:   is appeared in EPUB docs
18566 · #3418: Search button is misaligned in nature and pyramid theme
18568 · #3421: Could not translate a caption of tables
18570 · #3552: linkcheck raises UnboundLocalError
18572 Release 1.5.2 (released Jan 22, 2017)
18574 Incompatible changes
18575 · Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
18576 #3310)
18577 Features added
18579 · #3241: emit latex warning if buggy titlesec (ref #3210)
18580 · #3194: Refer the $MAKE environment variable to determine make command
18582 · Emit warning for nested numbered toctrees (refs: #3142)
18584 · #978: intersphinx_mapping also allows a list as a parameter
18586 · #3340: (LaTeX) long lines in parsed-literal are wrapped like in
18588 code-block, inline math and footnotes are fully functional.
18589 Bugs fixed
18591 · #3246: xapian search adapter crashes
18592 · #3253: In Py2 environment, building another locale with a non-cap‐
18594 tioned toctree produces None captions
18595 · #185: References to section title including raw node has broken
18597 · #3255: In Py3.4 environment, autodoc doesn’t support documentation
18599 for attributes of Enum class correctly.
18600 · #3261: latex_use_parts makes sphinx crash
18602 · The warning type misc.highlighting_failure does not work
18604 · #3294: add_latex_package() make crashes non-LaTeX builders
18606 · The caption of table are rendered as invalid HTML (refs: #3287)
18608 · #3268: Sphinx crashes with requests package from Debian jessie
18610 · #3284: Sphinx crashes on parallel build with an extension which
18612 raises unserializable exception
18613 · #3315: Bibliography crashes on latex build with docclass ‘memoir’
18615 · #3328: Could not refer rubric implicitly
18617 · #3329: emit warnings if po file is invalid and can’t read it. Also
18619 writing mo too
18620 · #3337: Ugly rendering of definition list term’s classifier
18622 · #3335: gettext does not extract field_name of a field in a field_list
18624 · #2952: C++, fix refs to operator() functions.
18626 · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
18628 eral LaTeX output (ref #3342)
18629 · LaTeX writer: leave " character inside parsed-literal as is (ref
18631 #3341)
18632 · #3234: intersphinx failed for encoded inventories
18634 · #3158: too much space after captions in PDF output
18636 · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
18638 if with hyphen
18639 · LaTeX crash if the filename of an image inserted in parsed-literal
18641 via a substitution contains an hyphen (ref #3340)
18642 · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
18644 #3340)
18645 · Inline math in parsed-literal is not rendered well by LaTeX (ref
18647 #3340)
18648 · #3308: Parsed-literals don’t wrap very long lines with pdf builder
18650 (ref #3340)
18651 · #3295: Could not import extension sphinx.builders.linkcheck
18653 · #3285: autosummary: asterisks are escaped twice
18655 · LaTeX, pass dvipdfm option to geometry package for Japanese documents
18657 (ref #3363)
18658 · Fix parselinenos() could not parse left half open range (cf. “-4”)
18660 Release 1.5.1 (released Dec 13, 2016)
18662 Features added
18663 · #3214: Allow to suppress “unknown mimetype” warnings from epub
18664 builder using suppress_warnings.
18665 Bugs fixed
18667 · #3195: Can not build in parallel
18668 · #3198: AttributeError is raised when toctree has ‘self’
18670 · #3211: Remove untranslated sphinx locale catalogs (it was covered by
18672 untranslated it_IT)
18673 · #3212: HTML Builders crashes with docutils-0.13
18675 · #3207: more latex problems with references inside parsed-literal
18677 directive (\DUrole)
18678 · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
18680 · #3220: KeyError when having a duplicate citation
18682 · #3200: LaTeX: xref inside desc_name not allowed
18684 · #3228: build_sphinx command crashes when missing dependency
18686 · #2469: Ignore updates of catalog files for gettext builder. Thanks to
18688 Hiroshi Ohkubo.
18689 · #3183: Randomized jump box order in generated index page.
18691 Release 1.5 (released Dec 5, 2016)
18693 Incompatible changes
18694 1.5a1
18695 · latex, package fancybox is not any longer a dependency of sphinx.sty
18697 · Use 'locales' as a default value of locale_dirs
18699 · latex, package ifthen is not any longer a dependency of sphinx.sty
18701 · latex, style file does not modify fancyvrb’s Verbatim (also available
18703 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
18704 per.
18705 · latex, package newfloat is not used (and not included) anymore (ref
18707 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
18708 · latex, literal blocks in tables do not use OriginalVerbatim but
18710 sphinxVerbatimintable which handles captions and wraps lines (ref
18711 #2704).
18712 · latex, replace pt by TeX equivalent bp if found in width or height
18714 attribute of an image.
18715 · latex, if width or height attribute of an image is given with no
18717 unit, use px rather than ignore it.
18718 · latex: Separate stylesheets of pygments to independent .sty file
18720 · #2454: The filename of sourcelink is now changed. The value of
18722 html_sourcelink_suffix will be appended to the original filename
18723 (like index.rst.txt).
18724 · sphinx.util.copy_static_entry() is now deprecated. Use
18726 sphinx.util.fileutil.copy_asset() instead.
18727 · sphinx.util.osutil.filecopy() skips copying if the file has not been
18729 changed (ref: #2510, #2753)
18730 · Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
18732 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
18733 #2773)
18734 · QtHelpBuilder doesn’t generate search page (ref: #2352)
18736 · QtHelpBuilder uses nonav theme instead of default one to improve
18738 readability.
18739 · latex: To provide good default settings to Japanese documents, Sphinx
18741 uses jreport and jsbook as docclass if language is ja.
18742 · sphinx-quickstart now allows a project version is empty
18744 · Fix :download: role on epub/qthelp builder. They ignore the role
18746 because they don’t support it.
18747 · sphinx.ext.viewcode doesn’t work on epub building by default. view‐
18749 code_enable_epub option
18750 · sphinx.ext.viewcode disabled on singlehtml builder.
18752 · Use make-mode of sphinx-quickstart by default. To disable this, use
18754 -M option
18755 · Fix genindex.html, Sphinx’s document template, link address to itself
18757 to satisfy xhtml standard.
18758 · Use epub3 builder by default. And the old epub builder is renamed to
18760 epub2.
18761 · Fix epub and epub3 builders that contained links to genindex even if
18763 epub_use_index = False.
18764 · html_translator_class is now deprecated. Use Sphinx.set_translator()
18766 API instead.
18767 · Drop python 2.6 and 3.3 support
18769 · Drop epub3 builder’s epub3_page_progression_direction option (use
18771 epub3_writing_mode).
18772 · #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
18774 body']
18775 1.5a2
18777 · #2983: Rename epub3_description and epub3_contributor to
18779 epub_description and epub_contributor.
18780 · Remove themes/basic/defindex.html; no longer used
18782 · Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
18784 chap
18785 · #2435: Slim down quickstarted conf.py
18787 · The sphinx.sty latex package does not load itself “hyperref”, as this
18789 is done later in the preamble of the latex output via 'hyperref' key.
18790 · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
18792 lary. The non-modified package is used.
18793 · #3057: By default, footnote marks in latex PDF output are not pre‐
18795 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
18796 tomization if needed.
18797 · LaTeX target requires that option hyperfootnotes of package hyperref
18799 be left unchanged to its default (i.e. true) (refs: #3022)
18800 1.5 final
18802 · #2986: themes/basic/defindex.html is now deprecated
18804 · Emit warnings that will be deprecated in Sphinx 1.6 by default.
18806 Users can change the behavior by setting the environment variable
18807 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
18808 · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
18810 Deprecated
18812 These features are removed in Sphinx-1.6:
18813 · LDML format support in i18n feature
18815 · sphinx.addnodes.termsep
18817 · Some functions and classes in sphinx.util.pycompat: zip_longest,
18819 product, all, any, next, open, class_types, base_exception, relpath,
18820 StringIO, BytesIO. Please use the standard library version instead;
18821 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
18823 played, please refer when-deprecation-warnings-are-displayed.
18824 Features added
18826 1.5a1
18827 · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
18829 · Add :caption: option for sphinx.ext.inheritance_diagram.
18831 · #2471: Add config variable for default doctest flags.
18833 · Convert linkcheck builder to requests for better encoding handling
18835 · #2463, #2516: Add keywords of “meta” directive to search index
18837 · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
18839 · #2575: Now sphinx.ext.graphviz allows :align: option
18841 · Show warnings if unknown key is specified to latex_elements
18843 · Show warnings if no domains match with primary_domain (ref: #2001)
18845 · C++, show warnings when the kind of role is misleading for the kind
18847 of target it refers to (e.g., using the class role for a function).
18848 · latex, writer abstracts more of text styling into customizable
18850 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
18851 rather than \emph (which may be in use elsewhere or in an added LaTeX
18852 package). See list at end of sphinx.sty (ref: #2686)
18853 · latex, public names for environments and parameters used by note,
18855 warning, and other admonition types, allowing full customizability
18856 from the 'preamble' key or an input file (ref: feature request #2674,
18857 #2685)
18858 · latex, better computes column widths of some tables (as a result,
18860 there will be slight changes as tables now correctly fill the line
18861 width; ref: #2708)
18862 · latex, sphinxVerbatim environment is more easily customizable (ref:
18864 #2704). In addition to already existing VerbatimColor and Verbatim‐
18865 BorderColor:
18866 · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
18868 · booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
18870 slines.
18871 · latex, captions for literal blocks inside tables are handled, and
18873 long code lines wrapped to fit table cell (ref: #2704)
18874 · #2597: Show warning messages as darkred
18876 · latex, allow image dimensions using px unit (default is 96px=1in)
18878 · Show warnings if invalid dimension units found
18880 · #2650: Add --pdb option to setup.py command
18882 · latex, make the use of \small for code listings customizable (ref
18884 #2721)
18885 · #2663: Add --warning-is-error option to setup.py command
18887 · Show warnings if deprecated latex options are used
18889 · Add sphinx.config.ENUM to check the config values is in candidates
18891 · math: Add hyperlink marker to each equations in HTML output
18893 · Add new theme nonav that doesn’t include any navigation links. This
18895 is for any help generator like qthelp.
18896 · #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings
18898 enabled. Also, it emits an additional event named todo-defined to
18899 handle the TODO entries in 3rd party extensions.
18900 · Python domain signature parser now uses the xref mixin for ‘excep‐
18902 tions’, allowing exception classes to be autolinked.
18903 · #2513: Add latex_engine to switch the LaTeX engine by conf.py
18905 · #2682: C++, basic support for attributes (C++11 style and GNU style).
18907 The new configuration variables ‘cpp_id_attributes’ and
18908 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
18909 · #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
18911 removing prefixes from the index text of C++ objects.
18912 · C++, added concept directive. Thanks to mickk-on-cpp.
18914 · C++, added support for template introduction syntax. Thanks to
18916 mickk-on-cpp.
18917 · #2725: latex builder: allow to use user-defined template file (exper‐
18919 imental)
18920 · apidoc now avoids invalidating cached files by not writing to files
18922 whose content doesn’t change. This can lead to significant perfor‐
18923 mance wins if apidoc is run frequently.
18924 · #2851: sphinx.ext.math emits missing-reference event if equation not
18926 found
18927 · #1210: eqref role now supports cross reference
18929 · #2892: Added -a (--append-syspath) option to sphinx-apidoc
18931 · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
18933 · #646: option directive support ‘.’ character as a part of options
18935 · Add document about kindlegen and fix document structure for it.
18937 · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
18939 · #2926: EPUB3 builder supports vertical mode (epub3_writing_mode
18941 option)
18942 · #2695: build_sphinx subcommand for setuptools handles exceptions as
18944 same as sphinx-build does
18945 · #326: numref role can also refer sections
18947 · #2916: numref role can also refer caption as an its linktext
18949 1.5a2
18951 · #3008: linkcheck builder ignores self-signed certificate URL
18953 · #3020: new 'geometry' key to latex_elements whose default uses LaTeX
18955 style file geometry.sty to set page layout
18956 · #2843: Add :start-at: and :end-at: options to literalinclude direc‐
18958 tive
18959 · #2527: Add :reversed: option to toctree directive
18961 · Add -t and -d option to sphinx-quickstart to support templating gen‐
18963 erated sphinx project.
18964 · #3028: Add {path} and {basename} to the format of figure_lan‐
18966 guage_filename
18967 · new 'hyperref' key in the latex_elements dictionary (ref #3030)
18969 · #3022: Allow code-blocks in footnotes for LaTeX PDF output
18971 1.5b1
18973 · #2513: A better default settings for XeLaTeX
18975 · #3096: 'maxlistdepth' key to work around LaTeX list limitations
18977 · #3060: autodoc supports documentation for attributes of Enum class.
18979 Now autodoc render just the value of Enum attributes instead of Enum
18980 attribute representation.
18981 · Add --extensions to sphinx-quickstart to support enable arbitrary
18983 extensions from command line (ref: #2904)
18984 · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
18986 · #3071: Autodoc: Allow mocked module decorators to pass-through func‐
18988 tions unchanged
18989 · #2495: linkcheck: Allow skipping anchor checking using
18991 linkcheck_anchors_ignore
18992 · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
18994 · #3116: allow word wrap in PDF output for inline literals (ref #3110)
18996 · #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
18998 Nick Coghlan.
18999 · #3121: add inlineliteralwraps option to control if inline literal
19001 word-wraps in latex
19002 1.5 final
19004 · #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
19006 servers in linkcheck and intersphinx
19007 · #2215: make.bat generated by sphinx-quickstart can be called from
19009 another dir. Thanks to Timotheus Kampik.
19010 · #3185: Add new warning type misc.highlighting_failure
19012 Bugs fixed
19014 1.5a1
19015 · #2707: (latex) the column width is badly computed for tabular
19017 · #2799: Sphinx installs roles and directives automatically on import‐
19019 ing sphinx module. Now Sphinx installs them on running application.
19020 · sphinx.ext.autodoc crashes if target code imports * from mock modules
19022 by autodoc_mock_imports.
19023 · #1953: Sphinx.add_node does not add handlers the translator installed
19025 by html_translator_class
19026 · #1797: text builder inserts blank line on top
19028 · #2894: quickstart main() doesn’t use argv argument
19030 · #2874: gettext builder could not extract all text under the only
19032 directives
19033 · #2485: autosummary crashes with multiple source_suffix values
19035 · #1734: Could not translate the caption of toctree directive
19037 · Could not translate the content of meta directive (ref: #1734)
19039 · #2550: external links are opened in help viewer
19041 · #2687: Running Sphinx multiple times produces ‘already registered’
19043 warnings
19044 1.5a2
19046 · #2810: Problems with pdflatex in an Italian document
19048 · Use latex_elements.papersize to specify papersize of LaTeX in Make‐
19050 file
19051 · #2988: linkcheck: retry with GET request if denied HEAD request
19053 · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
19055 itly” error if linkcheck_anchors enabled
19056 · #3004: Invalid link types “top” and “up” are used
19058 · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
19060 · #3000: option directive generates invalid HTML anchors
19062 · #2984: Invalid HTML has been generated if html_split_index enabled
19064 · #2986: themes/basic/defindex.html should be changed for html5
19066 friendly
19067 · #2987: Invalid HTML has been generated if multiple IDs are assigned
19069 to a list
19070 · #2891: HTML search does not provide all the results
19072 · #1986: Title in PDF Output
19074 · #147: Problem with latex chapter style
19076 · #3018: LaTeX problem with page layout dimensions and chapter titles
19078 · Fix an issue with \pysigline in LaTeX style file (ref #3023)
19080 · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
19082 · #3031: incompatibility with LaTeX package tocloft
19084 · #3003: literal blocks in footnotes are not supported by Latex
19086 · #3047: spacing before footnote in pdf output is not coherent and
19088 allows breaks
19089 · #3045: HTML search index creator should ignore “raw” content if now
19091 html
19092 · #3039: English stemmer returns wrong word if the word is capitalized
19094 · Fix make-mode Makefile template (ref #3056, #2936)
19096 1.5b1
19098 · #2432: Fix unwanted * between varargs and keyword only args. Thanks
19100 to Alex Grönholm.
19101 · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
19103 panese documents since PR#3030)
19104 · Better rendering of multiline signatures in html.
19106 · #777: LaTeX output “too deeply nested” (ref #3096)
19108 · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
19110 #3059)
19111 · #3019: LaTeX fails on description of C function with arguments (ref
19113 #3083)
19114 · fix latex inline literals where < > - gobbled a space
19116 1.5 final
19118 · #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
19120 tains one \addto\captions...
19121 · #3123: user 'babel' key setting is not obeyed anymore
19123 · #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
19125 Opera
19126 · #3085: keep current directory after breaking build documentation.
19128 Thanks to Timotheus Kampik.
19129 · #3181: pLaTeX crashes with a section contains endash
19131 · #3180: latex: add stretch/shrink between successive singleline or
19133 multipleline cpp signatures (ref #3072)
19134 · #3128: globing images does not support .svgz file
19136 · #3015: fix a broken test on Windows.
19138 · #1843: Fix documentation of descriptor classes that have a custom
19140 metaclass. Thanks to Erik Bray.
19141 · #3190: util.split_docinfo fails to parse multi-line field bodies
19143 · #3024, #3037: In Python3, application.Sphinx._log crushed when the
19145 log message cannot be encoded into console encoding.
19146 Testing
19148 · To simplify, sphinx uses external mock package even if unittest.mock
19149 exists.
19150 Release 1.4.9 (released Nov 23, 2016)
19152 Bugs fixed
19153 · #2936: Fix doc/Makefile that can’t build man because doc/man exists
19154 · #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
19156 directives results in warning / error
19157 · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
19159 · #3074: add_source_parser() crashes in debug mode
19161 · #3135: sphinx.ext.autodoc crashes with plain Callable
19163 · #3150: Fix query word splitter in JavaScript. It behaves as same as
19165 Python’s regular expression.
19166 · #3093: gettext build broken on substituted images.
19168 · #3093: gettext build broken on image node under note directive.
19170 · imgmath: crashes on showing error messages if image generation failed
19172 · #3117: LaTeX writer crashes if admonition is placed before first sec‐
19174 tion title
19175 · #3164: Change search order of sphinx.ext.inheritance_diagram
19177 Release 1.4.8 (released Oct 1, 2016)
19179 Bugs fixed
19180 · #2996: The wheel package of Sphinx got crash with ImportError
19181 Release 1.4.7 (released Oct 1, 2016)
19183 Bugs fixed
19184 · #2890: Quickstart should return an error consistently on all error
19185 conditions
19186 · #2870: flatten genindex columns’ heights.
19188 · #2856: Search on generated HTML site doesn’t find some symbols
19190 · #2882: Fall back to a GET request on 403 status in linkcheck
19192 · #2902: jsdump.loads fails to load search index if keywords starts
19194 with underscore
19195 · #2900: Fix epub content.opf: add auto generated orphan files to
19197 spine.
19198 · #2899: Fix hasdoc() function in Jinja2 template. It will detect
19200 genindex, search also.
19201 · #2901: Fix epub result: skip creating links from image tags to origi‐
19203 nal image files.
19204 · #2917: inline code is hyphenated on HTML
19206 · #1462: autosummary warns for namedtuple with attribute with trailing
19208 underscore
19209 · Could not reference equations if :nowrap: option specified
19211 · #2873: code-block overflow in latex (due to commas)
19213 · #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
19215 relative paths are used in intersphinx_mapping
19216 · #2931: code-block directive with same :caption: causes warning of
19218 duplicate target. Now code-block and literalinclude does not define
19219 hyperlink target using its caption automatically.
19220 · #2962: latex: missing label of longtable
19222 · #2968: autodoc: show-inheritance option breaks docstrings
19224 Release 1.4.6 (released Aug 20, 2016)
19226 Incompatible changes
19227 · #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
19228 six-1.5 or later
19229 Bugs fixed
19231 · applehelp: Sphinx crashes if hiutil or codesign commands not found
19232 · Fix make clean abort issue when build dir contains regular files like
19234 DS_Store.
19235 · Reduce epubcheck warnings/errors:
19237 · Fix DOCTYPE to html5
19239 · Change extension from .html to .xhtml.
19241 · Disable search page on epub results
19243 · #2778: Fix autodoc crashes if obj.__dict__ is a property method and
19245 raises exception
19246 · Fix duplicated toc in epub3 output.
19248 · #2775: Fix failing linkcheck with servers not supporting identity
19250 encoding
19251 · #2833: Fix formatting instance annotations in ext.autodoc.
19253 · #1911: -D option of sphinx-build does not override the extensions
19255 variable
19256 · #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the
19258 inventory is given
19259 · parsing errors for caption of code-blocks are displayed in document
19261 (ref: #2845)
19262 · #2846: singlehtml builder does not include figure numbers
19264 · #2816: Fix data from builds cluttering the Domain.initial_data class
19266 attributes
19267 Release 1.4.5 (released Jul 13, 2016)
19269 Incompatible changes
19270 · latex, inclusion of non-inline images from image directive resulted
19271 in non-coherent whitespaces depending on original image width; new
19272 behaviour by necessity differs from earlier one in some cases. (ref:
19273 #2672)
19274 · latex, use of \includegraphics to refer to Sphinx custom variant is
19276 deprecated; in future it will revert to original LaTeX macro, custom
19277 one already has alternative name \sphinxincludegraphics.
19278 Features added
19280 · new config option latex_keep_old_macro_names, defaults to True. If
19281 False, lets macros (for text styling) be defined only with
19282 \sphinx-prefixed names.
19283 · latex writer allows user customization of “shadowed” boxes (topics),
19285 via three length variables.
19286 · woff-format web font files now supported by the epub builder.
19288 Bugs fixed
19290 · jsdump fix for python 3: fixes the HTML search on python > 3
19291 · #2676: (latex) Error with verbatim text in captions since Sphinx
19293 1.4.4
19294 · #2629: memoir class crashes LaTeX. Fixed by
19296 latex_keep_old_macro_names=False (ref 2675)
19297 · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
19299 · #2679: float package needed for 'figure_align': 'H' latex option
19301 · #2671: image directive may lead to inconsistent spacing in pdf
19303 · #2705: toctree generates empty bullet_list if :titlesonly: specified
19305 · #2479: sphinx.ext.viewcode uses python2 highlighter by default
19307 · #2700: HtmlHelp builder has hard coded index.html
19309 · latex, since 1.4.4 inline literal text is followed by spurious space
19311 · #2722: C++, fix id generation for var/member declarations to include
19313 namespaces.
19314 · latex, images (from image directive) in lists or quoted blocks did
19316 not obey indentation (fixed together with #2671)
19317 · #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
19319 warnings
19320 · #2731: sphinx.ext.autodoc does not access propertymethods which
19322 raises any exceptions
19323 · #2666: C++, properly look up nested names involving constructors.
19325 · #2579: Could not refer a label including both spaces and colons via
19327 sphinx.ext.intersphinx
19328 · #2718: Sphinx crashes if the document file is not readable
19330 · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
19332 · #2723: extra spaces in latex pdf output from multirow cell
19334 · #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
19336 page
19337 · #2667: latex crashes if resized images appeared in section title
19339 · #2763: (html) Provide default value for required alt attribute for
19341 image tags of SVG source, required to validate and now consistent w/
19342 other formats.
19343 Release 1.4.4 (released Jun 12, 2016)
19345 Bugs fixed
19346 · #2630: latex: sphinx.sty notice environment formatting problem
19347 · #2632: Warning directives fail in quote environment latex build
19349 · #2633: Sphinx crashes with old styled indices
19351 · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
19353 · #2622: Latex produces empty pages after title and table of contents
19355 · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
19357 · Let LaTeX use straight quotes also in inline code (ref #2627)
19359 · #2351: latex crashes if enumerated lists are placed on footnotes
19361 · #2646: latex crashes if math contains twice empty lines
19363 · #2480: sphinx.ext.autodoc: memory addresses were shown
19365 · latex: allow code-blocks appearing inside lists and quotes at maximal
19367 nesting depth (ref #777, #2624, #2651)
19368 · #2635: Latex code directives produce inconsistent frames based on
19370 viewing resolution
19371 · #2639: Sphinx now bundles iftex.sty
19373 · Failed to build PDF with framed.sty 0.95
19375 · Sphinx now bundles needspace.sty
19377 Release 1.4.3 (released Jun 5, 2016)
19379 Bugs fixed
19380 · #2530: got “Counter too large” error on building PDF if large num‐
19381 bered footnotes existed in admonitions
19382 · width option of figure directive does not work if align option speci‐
19384 fied at same time (ref: #2595)
19385 · #2590: The inputenc package breaks compiling under lualatex and xela‐
19387 tex
19388 · #2540: date on latex front page use different font
19390 · Suppress “document isn’t included in any toctree” warning if the doc‐
19392 ument is included (ref: #2603)
19393 · #2614: Some tables in PDF output will end up shifted if user sets non
19395 zero parindent in preamble
19396 · #2602: URL redirection breaks the hyperlinks generated by
19398 sphinx.ext.intersphinx
19399 · #2613: Show warnings if merged extensions are loaded
19401 · #2619: make sure amstext LaTeX package always loaded (ref: d657225,
19403 488ee52, 9d82cad and #2615)
19404 · #2593: latex crashes if any figures in the table
19406 Release 1.4.2 (released May 29, 2016)
19408 Features added
19409 · Now suppress_warnings accepts following configurations (ref: #2451,
19410 #2466):
19411 · app.add_node
19413 · app.add_directive
19415 · app.add_role
19417 · app.add_generic_role
19419 · app.add_source_parser
19421 · image.data_uri
19423 · image.nonlocal_uri
19425 · #2453: LaTeX writer allows page breaks in topic contents; and their
19427 horizontal extent now fits in the line width (with shadow in margin).
19428 Also warning-type admonitions allow page breaks and their vertical
19429 spacing has been made more coherent with the one for hint-type
19430 notices (ref #2446).
19431 · #2459: the framing of literal code-blocks in LaTeX output (and not
19433 only the code lines themselves) obey the indentation in lists or
19434 quoted blocks.
19435 · #2343: the long source lines in code-blocks are wrapped (without mod‐
19437 ifying the line numbering) in LaTeX output (ref #1534, #2304).
19438 Bugs fixed
19440 · #2370: the equations are slightly misaligned in LaTeX writer
19441 · #1817, #2077: suppress pep8 warnings on conf.py generated by
19443 sphinx-quickstart
19444 · #2407: building docs crash if document includes large data image URIs
19446 · #2436: Sphinx does not check version by needs_sphinx if loading
19448 extensions failed
19449 · #2397: Setup shorthandoff for Turkish documents
19451 · #2447: VerbatimBorderColor wrongly used also for captions of PDF
19453 · #2456: C++, fix crash related to document merging (e.g., singlehtml
19455 and Latex builders).
19456 · #2446: latex(pdf) sets local tables of contents (or more generally
19458 topic nodes) in unbreakable boxes, causes overflow at bottom
19459 · #2476: Omit MathJax markers if :nowrap: is given
19461 · #2465: latex builder fails in case no caption option is provided to
19463 toctree directive
19464 · Sphinx crashes if self referenced toctree found
19466 · #2481: spelling mistake for mecab search splitter. Thanks to Naoki
19468 Sato.
19469 · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
19471 · intersphinx fails if mapping URL contains any port
19473 · #2088: intersphinx crashes if the mapping URL requires basic auth
19475 · #2304: auto line breaks in latexpdf codeblocks
19477 · #1534: Word wrap long lines in Latex verbatim blocks
19479 · #2460: too much white space on top of captioned literal blocks in PDF
19481 output
19482 · Show error reason when multiple math extensions are loaded (ref:
19484 #2499)
19485 · #2483: any figure number was not assigned if figure title contains
19487 only non text objects
19488 · #2501: Unicode subscript numbers are normalized in LaTeX
19490 · #2492: Figure directive with :figwidth: generates incorrect
19492 Latex-code
19493 · The caption of figure is always put on center even if :align: was
19495 specified
19496 · #2526: LaTeX writer crashes if the section having only images
19498 · #2522: Sphinx touches mo files under installed directory that caused
19500 permission error.
19501 · #2536: C++, fix crash when an immediately nested scope has the same
19503 name as the current scope.
19504 · #2555: Fix crash on any-references with unicode.
19506 · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
19508 · #2521: generated Makefile causes BSD make crashed if sphinx-build not
19510 found
19511 · #2470: typing backport package causes autodoc errors with python 2.7
19513 · sphinx.ext.intersphinx crashes if non-string value is used for key of
19515 intersphinx_mapping
19516 · #2518: intersphinx_mapping disallows non alphanumeric keys
19518 · #2558: unpack error on devhelp builder
19520 · #2561: Info builder crashes when a footnote contains a link
19522 · #2565: The descriptions of objects generated by sphinx.ext.autosum‐
19524 mary overflow lines at LaTeX writer
19525 · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
19527 · #2445: rst_prolog and rst_epilog affect to non reST sources
19529 · #2576: sphinx.ext.imgmath crashes if subprocess raises error
19531 · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
19533 · #2556: Xapian search does not work with Python 3
19535 · #2581: The search doesn’t work if language=”es” (Spanish)
19537 · #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
19539 writer
19540 · #2383: The generated footnote by latex_show_urls overflows lines
19542 · #2497, #2552: The label of search button does not fit for the button
19544 itself
19545 Release 1.4.1 (released Apr 12, 2016)
19547 Incompatible changes
19548 · The default format of today_fmt and html_last_updated_fmt is back to
19549 strftime format again. Locale Date Markup Language is also supported
19550 for backward compatibility until Sphinx-1.5.
19551 Translations
19553 · Added Welsh translation, thanks to Geraint Palmer.
19554 · Added Greek translation, thanks to Stelios Vitalis.
19556 · Added Esperanto translation, thanks to Dinu Gherman.
19558 · Added Hindi translation, thanks to Purnank H. Ghumalia.
19560 · Added Romanian translation, thanks to Razvan Stefanescu.
19562 Bugs fixed
19564 · C++, added support for extern and thread_local.
19565 · C++, type declarations are now using the prefixes typedef, using, and
19567 type, depending on the style of declaration.
19568 · #2413: C++, fix crash on duplicate declarations
19570 · #2394: Sphinx crashes when html_last_updated_fmt is invalid
19572 · #2408: dummy builder not available in Makefile and make.bat
19574 · #2412: hyperlink targets are broken in LaTeX builder
19576 · figure directive crashes if non paragraph item is given as caption
19578 · #2418: time formats no longer allowed in today_fmt
19580 · #2395: Sphinx crashes if unicode character in image filename
19582 · #2396: “too many values to unpack” in genindex-single
19584 · #2405: numref link in PDF jumps to the wrong location
19586 · #2414: missing number in PDF hyperlinks to code listings
19588 · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
19590 Release 1.4 (released Mar 28, 2016)
19592 Incompatible changes
19593 · Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
19594 Stemmer to accelerate stemming.
19595 · sphinx_rtd_theme has become optional. Please install it manually.
19597 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
19598 · #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
19600 It enables to take title of roles as an argument of custom macros.
19601 · #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns
19603 default values in conf.py that will be provided on sphinx-quickstart.
19604 · #2027, #2208: The html_title accepts string values only. And The None
19606 value cannot be accepted.
19607 · sphinx.ext.graphviz: show graph image in inline by default
19609 · #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
19611 node instead of sphinx.addnodes.literal_emphasis node.
19612 · #2022: html_extra_path also copies dotfiles in the extra directory,
19614 and refers to exclude_patterns to exclude extra files and directo‐
19615 ries.
19616 · #2300: enhance autoclass:: to use the docstring of __new__ if
19618 __init__ method’s is missing of empty
19619 · #2251: Previously, under glossary directives, multiple terms for one
19621 definition are converted into single term node and the each terms in
19622 the term node are separated by termsep node. In new implementation,
19623 each terms are converted into individual term nodes and termsep node
19624 is removed. By this change, output layout of every builders are
19625 changed a bit.
19626 · The default highlight language is now Python 3. This means that
19628 source code is highlighted as Python 3 (which is mostly a superset of
19629 Python 2), and no parsing is attempted to distinguish valid code. To
19630 get the old behavior back, add highlight_language = "python" to
19631 conf.py.
19632 · Locale Date Markup Language like "MMMM dd, YYYY" is default format
19634 for today_fmt and html_last_updated_fmt. However strftime format
19635 like "%B %d, %Y" is also supported for backward compatibility until
19636 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
19637 · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
19639 ing instead.
19640 · #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
19642 writer.
19643 · #1498: manpage writer: don’t make whole of item in definition list
19645 bold if it includes strong node.
19646 · #582: Remove hint message from quick search box for html output.
19648 · #2378: Sphinx now bundles newfloat.sty
19650 Features added
19652 · #2092: add todo directive support in napoleon package.
19653 · #1962: when adding directives, roles or nodes from an extension, warn
19655 if such an element is already present (built-in or added by another
19656 extension).
19657 · #1909: Add “doc” references to Intersphinx inventories.
19659 · C++ type alias support (e.g., .. type:: T = int).
19661 · C++ template support for classes, functions, type aliases, and vari‐
19663 ables (#1729, #1314).
19664 · C++, added new scope management directives namespace-push and names‐
19666 pace-pop.
19667 · #1970: Keyboard shortcuts to navigate Next and Previous topics
19669 · Intersphinx: Added support for fetching Intersphinx inventories with
19671 URLs using HTTP basic auth.
19672 · C++, added support for template parameter in function info field
19674 lists.
19675 · C++, added support for pointers to member (function).
19677 · #2113: Allow :class: option to code-block directive.
19679 · #2192: Imgmath (pngmath with svg support).
19681 · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
19683 · #1906: Use xcolor over color for fcolorbox where available for LaTeX
19685 output.
19686 · #2216: Texinputs makefile improvements.
19688 · #2170: Support for Chinese language search index.
19690 · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
19692 · #1030: Make page reference names for latex_show_pagerefs translatable
19694 · #2162: Add Sphinx.add_source_parser() to add source_suffix and
19696 source_parsers from extension
19697 · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
19699 · #656: Add graphviz_dot option to graphviz directives to switch the
19701 dot command
19702 · #1939: Added the dummy builder: syntax check without output.
19704 · #2230: Add math_number_all option to number all displayed math in
19706 math extensions
19707 · #2235: needs_sphinx supports micro version comparison
19709 · #2282: Add “language” attribute to html tag in the “basic” theme
19711 · #1779: Add EPUB 3 builder
19713 · #1751: Add todo_link_only to avoid file path and line indication on
19715 todolist. Thanks to Francesco Montesano.
19716 · #2199: Use imagesize package to obtain size of images.
19718 · #1099: Add configurable retries to the linkcheck builder. Thanks to
19720 Alex Gaynor. Also don’t check anchors starting with !.
19721 · #2300: enhance autoclass:: to use the docstring of __new__ if
19723 __init__ method’s is missing of empty
19724 · #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
19726 numfig feature
19727 · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
19729 erence sections using its title. Thanks to Tadhg O’Higgins.
19730 · #1854: Allow to choose Janome for Japanese splitter.
19732 · #1853: support custom text splitter on html search with lan‐
19734 guage='ja'.
19735 · #2320: classifier of glossary terms can be used for index entries
19737 grouping key. The classifier also be used for translation. See also
19738 glossary-directive.
19739 · #2308: Define \tablecontinued macro to redefine the style of contin‐
19741 ued label for longtables.
19742 · Select an image by similarity if multiple images are globbed by ..
19744 image:: filename.*
19745 · #1921: Support figure substitutions by language and figure_lan‐
19747 guage_filename
19748 · #2245: Add latex_elements["passoptionstopackages"] option to call
19750 PassOptionsToPackages in early stage of preambles.
19751 · #2340: Math extension: support alignment of multiple equations for
19753 MathJax.
19754 · #2338: Define \titleref macro to redefine the style of title-refer‐
19756 ence roles.
19757 · Define \menuselection and \accelerator macros to redefine the style
19759 of menuselection roles.
19760 · Define \crossref macro to redefine the style of references
19762 · #2301: Texts in the classic html theme should be hyphenated.
19764 · #2355: Define \termref macro to redefine the style of term roles.
19766 · Add suppress_warnings to suppress arbitrary warning message (experi‐
19768 mental)
19769 · #2229: Fix no warning is given for unknown options
19771 · #2327: Add latex_toplevel_sectioning to switch the top level section‐
19773 ing of LaTeX document.
19774 Bugs fixed
19776 · #1913: C++, fix assert bug for enumerators in next-to-global and
19777 global scope.
19778 · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
19780 · C++, add missing support for ‘friend’ functions.
19782 · C++, add missing support for virtual base classes (thanks to Rapptz).
19784 · C++, add support for final classes.
19786 · C++, fix parsing of types prefixed with ‘enum’.
19788 · #2023: Dutch search support uses Danish stemming info.
19790 · C++, add support for user-defined literals.
19792 · #1804: Now html output wraps overflowed long-line-text in the side‐
19794 bar. Thanks to Hassen ben tanfous.
19795 · #2183: Fix porterstemmer causes make json to fail.
19797 · #1899: Ensure list is sent to OptParse.
19799 · #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
19801 package option).
19802 · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
19804 · Fix broken LaTeX code is generated if unknown language is given
19806 · #1944: Fix rst_prolog breaks file-wide metadata
19808 · #2074: make gettext should use canonical relative paths for .pot.
19810 Thanks to anatoly techtonik.
19811 · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
19813 · #2251: Line breaks in .rst files are transferred to .pot files in a
19815 wrong way.
19816 · #794: Fix date formatting in latex output is not localized
19818 · Remove image/gif from supported_image_types of LaTeX writer (#2272)
19820 · Fix ValueError is raised if LANGUAGE is empty string
19822 · Fix unpack warning is shown when the directives generated from
19824 Sphinx.add_crossref_type is used
19825 · The default highlight language is now default. This means that
19827 source code is highlighted as Python 3 (which is mostly a superset of
19828 Python 2) if possible. To get the old behavior back, add high‐
19829 light_language = "python" to conf.py.
19830 · #2329: Refresh environment forcedly if source directory has changed.
19832 · #2331: Fix code-blocks are filled by block in dvi; remove xcdraw
19834 option from xcolor package
19835 · Fix the confval type checker emits warnings if unicode is given to
19837 confvals which expects string value
19838 · #2360: Fix numref in LaTeX output is broken
19840 · #2361: Fix additional paragraphs inside the “compound” directive are
19842 indented
19843 · #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
19845 sion.
19846 · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
19848 · #2368: Ignore emacs lock files like .#foo.rst by default.
19850 · #2262: literal_block and its caption has been separated by pagebreak
19852 in LaTeX output.
19853 · #2319: Fix table counter is overridden by code-block’s in LaTeX.
19855 Thanks to jfbu.
19856 · Fix unpack warning if combined with 3rd party domain extensions.
19858 · #1153: Fix figures in sidebar causes latex build error.
19860 · #2358: Fix user-preamble could not override the tocdepth definition.
19862 · #2358: Reduce tocdepth if part or chapter is used for top_section‐
19864 level.
19865 · #2351: Fix footnote spacing
19867 · #2363: Fix toctree() in templates generates broken links in Single‐
19869 HTMLBuilder.
19870 · #2366: Fix empty hyperref is generated on toctree in HTML builder.
19872 Documentation
19874 · #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
19875 mecke.
19876 Release 1.3.6 (released Feb 29, 2016)
19878 Features added
19879 · #1873, #1876, #2278: Add page_source_suffix html context variable.
19880 This should be introduced with source_parsers feature. Thanks for
19881 Eric Holscher.
19882 Bugs fixed
19884 · #2265: Fix babel is used in spite of disabling it on latex_elements
19885 · #2295: Avoid mutating dictionary errors while enumerating members in
19887 autodoc with Python 3
19888 · #2291: Fix pdflatex “Counter too large” error from footnotes inside
19890 tables of contents
19891 · #2292: Fix some footnotes disappear from LaTeX output
19893 · #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
19895 feature should support parsers that specified source_parsers.
19896 · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
19898 of math fonts
19899 · #2324: Print a hint how to increase the recursion limit when it is
19901 hit.
19902 · #1565, #2229: Revert new warning; the new warning will be triggered
19904 from version 1.4 on.
19905 · #2329: Refresh environment forcedly if source directory has changed.
19907 · #2019: Fix the domain objects in search result are not escaped
19909 Release 1.3.5 (released Jan 24, 2016)
19911 Bugs fixed
19912 · Fix line numbers was not shown on warnings in LaTeX and texinfo
19913 builders
19914 · Fix filenames were not shown on warnings of citations
19916 · Fix line numbers was not shown on warnings in LaTeX and texinfo
19918 builders
19919 · Fix line numbers was not shown on warnings of indices
19921 · #2026: Fix LaTeX builder raises error if parsed-literal includes
19923 links
19924 · #2243: Ignore strange docstring types for classes, do not crash
19926 · #2247: Fix #2205 breaks make html for definition list with classi‐
19928 fiers that contains regular-expression like string
19929 · #1565: Sphinx will now emit a warning that highlighting was skipped
19931 if the syntax is incorrect for code-block, literalinclude and so on.
19932 · #2211: Fix paragraphs in table cell doesn’t work in Latex output
19934 · #2253: :pyobject: option of literalinclude directive can’t detect
19936 indented body block when the block starts with blank or comment
19937 lines.
19938 · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
19940 · Fix warning message for :numref: if target is in orphaned doc (ref:
19942 #2244)
19943 Release 1.3.4 (released Jan 12, 2016)
19945 Bugs fixed
19946 · #2134: Fix figure caption with reference causes latex build error
19947 · #2094: Fix rubric with reference not working in Latex
19949 · #2147: Fix literalinclude code in latex does not break in pages
19951 · #1833: Fix email addresses is showed again if latex_show_urls is not
19953 None
19954 · #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
19956 svg
19957 · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
19959 · #1237: Fix footnotes not working in definition list in LaTeX
19961 · #2168: Fix raw directive does not work for text writer
19963 · #2171: Fix cannot linkcheck url with unicode
19965 · #2182: LaTeX: support image file names with more than 1 dots
19967 · #2189: Fix previous sibling link for first file in subdirectory uses
19969 last file, not intended previous from root toctree
19970 · #2003: Fix decode error under python2 (only) when make linkcheck is
19972 run
19973 · #2186: Fix LaTeX output of mathbb in math
19975 · #1480, #2188: LaTeX: Support math in section titles
19977 · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
19979 Bug
19980 · #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
19982 non-ascii characters
19983 · #2193: Fix shutil.SameFileError if source directory and destination
19985 directory are same
19986 · #2178: Fix unparsable C++ cross-reference when referencing a function
19988 with :cpp:any:
19989 · #2206: Fix Sphinx latex doc build failed due to a footnotes
19991 · #2201: Fix wrong table caption for tables with over 30 rows
19993 · #2213: Set <blockquote> in the classic theme to fit with <p>
19995 · #1815: Fix linkcheck does not raise an exception if warniserror set
19997 to true and link is broken
19998 · #2197: Fix slightly cryptic error message for missing index.rst file
20000 · #1894: Unlisted phony targets in quickstart Makefile
20002 · #2125: Fix unifies behavior of collapsed fields (GroupedField and
20004 TypedField)
20005 · #1408: Check latex_logo validity before copying
20007 · #771: Fix latex output doesn’t set tocdepth
20009 · #1820: On Windows, console coloring is broken with colorama version
20011 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
20012 · #2072: Fix footnotes in chapter-titles do not appear in PDF output
20014 · #1580: Fix paragraphs in longtable don’t work in Latex output
20016 · #1366: Fix centered image not centered in latex
20018 · #1860: Fix man page using :samp: with braces - font doesn’t reset
20020 · #1610: Sphinx crashes in Japanese indexing in some systems
20022 · Fix Sphinx crashes if mecab initialization failed
20024 · #2160: Fix broken TOC of PDFs if section includes an image
20026 · #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
20028 Thanks to jfbu.
20029 · #2198,#2205: make gettext generate broken msgid for definition lists.
20031 · #2062: Escape characters in doctests are treated incorrectly with
20033 Python 2.
20034 · #2225: Fix if the option does not begin with dash, linking is not
20036 performed
20037 · #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
20039 mathjax)
20040 · #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
20042 extensions doesn’t support resolve_any_xref and resolve_xref returns
20043 problematic node instead of None. sphinxcontrib-httpdomain is one of
20044 them.
20045 · #2229: Fix no warning is given for unknown options
20047 Release 1.3.3 (released Dec 2, 2015)
20049 Bugs fixed
20050 · #2177: Fix parallel hangs
20051 · #2012: Fix exception occurred if numfig_format is invalid
20053 · #2142: Provide non-minified JS code in sphinx/search/non-mini‐
20055 fied-js/*.js for source distribution on PyPI.
20056 · #2148: Error while building devhelp target with non-ASCII document.
20058 Release 1.3.2 (released Nov 29, 2015)
20060 Features added
20061 · #1935: Make “numfig_format” overridable in latex_elements.
20062 Bugs fixed
20064 · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
20065 dows environment.
20066 · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
20068 patibility.
20069 · #1788: graphviz extension raises exception when caption option is
20071 present.
20072 · #1789: :pyobject: option of literalinclude directive includes follow‐
20074 ing lines after class definitions
20075 · #1790: literalinclude strips empty lines at the head and tail
20077 · #1802: load plugin themes automatically when theme.conf use it as
20079 ‘inherit’. Thanks to Takayuki Hirai.
20080 · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
20082 find base theme.
20083 · #1834: compatibility for docutils-0.13: handle_io_errors keyword
20085 argument for docutils.io.FileInput cause TypeError.
20086 · #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
20088 error. Now ‘.’ is converted to absolute path automatically.
20089 · Fix a crash when setting up extensions which do not support metadata.
20091 · #1784: Provide non-minified JS code in sphinx/search/non-mini‐
20093 fied-js/*.js
20094 · #1822, #1892: Fix regression for #1061. autosummary can’t generate
20096 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
20097 · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
20099 Takayuki Hirai.
20100 · #1780, #1866: “make text” shows “class” keyword twice. Thanks to
20102 Takayuki Hirai.
20103 · #1871: Fix for LaTeX output of tables with one column and multirows.
20105 · Work around the lack of the HTMLParserError exception in Python 3.5.
20107 · #1949: Use safe_getattr in the coverage builder to avoid aborting
20109 with descriptors that have custom behavior.
20110 · #1915: Do not generate smart quotes in doc field type annotations.
20112 · #1796: On py3, automated .mo building caused UnicodeDecodeError.
20114 · #1923: Use babel features only if the babel latex element is
20116 nonempty.
20117 · #1942: Fix a KeyError in websupport.
20119 · #1903: Fix strange id generation for glossary terms.
20121 · make text will crush if a definition list item has more than 1 clas‐
20123 sifiers as: term : classifier1 : classifier2.
20124 · #1855: make gettext generates broken po file for definition lists
20126 with classifier.
20127 · #1869: Fix problems when dealing with files containing non-ASCII
20129 characters. Thanks to Marvin Schmidt.
20130 · #1798: Fix building LaTeX with references in titles.
20132 · #1725: On py2 environment, doctest with using non-ASCII characters
20134 causes 'ascii' codec can't decode byte exception.
20135 · #1540: Fix RuntimeError with circular referenced toctree
20137 · #1983: i18n translation feature breaks references which uses section
20139 name.
20140 · #1990: Use caption of toctree to title of tableofcontents in LaTeX
20142 · #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
20144 LaTeX builder
20145 · #1994: More supporting non-standard parser (like recommonmark parser)
20147 for Translation and WebSupport feature. Now node.rawsource is fall
20148 backed to node.astext() during docutils transforming.
20149 · #1989: “make blahblah” on Windows indicate help messages for
20151 sphinx-build every time. It was caused by wrong make.bat that gener‐
20152 ated by Sphinx-1.3.0/1.3.1.
20153 · On Py2 environment, conf.py that is generated by sphinx-quickstart
20155 should have u prefixed config value for ‘version’ and ‘release’.
20156 · #2102: On Windows + Py3, using |today| and non-ASCII date format will
20158 raise UnicodeEncodeError.
20159 · #1974: UnboundLocalError: local variable ‘domain’ referenced before
20161 assignment when using any role and sphinx.ext.intersphinx in same
20162 time.
20163 · #2121: multiple words search doesn’t find pages when words across on
20165 the page title and the page content.
20166 · #1884, #1885: plug-in html themes cannot inherit another plug-in
20168 theme. Thanks to Suzumizaki.
20169 · #1818: sphinx.ext.todo directive generates broken html class
20171 attribute as ‘admonition-‘ when language is specified with non-ASCII
20172 linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive
20173 can use :class: option.
20174 · #2140: Fix footnotes in table has broken in LaTeX
20176 · #2127: MecabBinder for html searching feature doesn’t work with
20178 Python 3. Thanks to Tomoko Uchida.
20179 Release 1.3.1 (released Mar 17, 2015)
20181 Bugs fixed
20182 · #1769: allows generating quickstart files/dirs for destination dir
20183 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
20184 rou.
20185 · #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
20187 option argument.
20188 · #1766: the message “least Python 2.6 to run” is at best misleading.
20190 · #1772: cross reference in docstrings like :param .write: breaks
20192 building.
20193 · #1770, #1774: literalinclude with empty file occurs exception. Thanks
20195 to Takayuki Hirai.
20196 · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
20198 · #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
20200 sion.
20201 · #1771: automated .mo building doesn’t work properly.
20203 · #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
20205 Jens Hedegaard Nielsen.
20206 · #1781: Setting html_domain_indices to a list raises a type check
20208 warnings.
20209 Release 1.3 (released Mar 10, 2015)
20211 Incompatible changes
20212 · Roles ref, term and menusel now don’t generate emphasis nodes any‐
20213 more. If you want to keep italic style, adapt your stylesheet.
20214 · Role numref uses %s as special character to indicate position of fig‐
20216 ure numbers instead # symbol.
20217 Features added
20219 · Add convenience directives and roles to the C++ domain: directive
20220 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
20221 ber, and role any for cross-reference to any C++ declaraction. #1577,
20222 #1744
20223 · The source_suffix config value can now be a list of multiple suf‐
20225 fixes.
20226 · Add the ability to specify source parsers by source suffix with the
20228 source_parsers config value.
20229 · #1675: A new builder, AppleHelpBuilder, has been added that builds
20231 Apple Help Books.
20232 Bugs fixed
20234 · 1.3b3 change breaks a previous gettext output that contains dupli‐
20235 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
20236 · #1745: latex builder cause maximum recursion depth exceeded when a
20238 footnote has a footnote mark itself.
20239 · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
20241 · #1658, #1750: No link created (and warning given) if option does not
20243 begin with -, / or +. Thanks to Takayuki Hirai.
20244 · #1753: C++, added missing support for more complex declarations.
20246 · #1700: Add :caption: option for toctree.
20248 · #1742: :name: option is provided for toctree, code-block and literal‐
20250 include directives.
20251 · #1756: Incorrect section titles in search that was introduced from
20253 1.3b3.
20254 · #1746: C++, fixed name lookup procedure, and added missing lookups in
20256 declarations.
20257 · #1765: C++, fix old id generation to use fully qualified names.
20259 Documentation
20261 · #1651: Add vartype field description for python domain.
20262 Release 1.3b3 (released Feb 24, 2015)
20264 Incompatible changes
20265 · Dependency requirement updates: docutils 0.11, Pygments 2.0
20266 · The gettext_enables config value has been renamed to gettext_addi‐
20268 tional_targets.
20269 · #1735: Use https://docs.python.org/ instead of http protocol. It was
20271 used for sphinx.ext.intersphinx and some documentation.
20272 Features added
20274 · #1346: Add new default theme;
20275 · Add ‘alabaster’ theme.
20277 · Add ‘sphinx_rtd_theme’ theme.
20279 · The ‘default’ html theme has been renamed to ‘classic’. ‘default’
20281 is still available, however it will emit notice a recommendation
20282 that using new ‘alabaster’ theme.
20283 · Added highlight_options configuration value.
20285 · The language config value is now available in the HTML templates.
20287 · The env-updated event can now return a value, which is interpreted as
20289 an iterable of additional docnames that need to be rewritten.
20290 · #772: Support for scoped and unscoped enums in C++. Enumerators in
20292 unscoped enums are injected into the parent scope in addition to the
20293 enum scope.
20294 · Add todo_include_todos config option to quickstart conf file, handled
20296 as described in documentation.
20297 · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
20299 nav-item-0, 1, 2…).
20300 · New option sphinx-quickstart --use-make-mode for generating Makefile
20302 that use sphinx-build make-mode.
20303 · #1235: i18n: several node can be translated if it is set to get‐
20305 text_additional_targets in conf.py. Supported nodes are:
20306 · ‘literal-block’
20308 · ‘doctest-block’
20310 · ‘raw’
20312 · ‘image’
20314 · #1227: Add html_scaled_image_link config option to conf.py, to con‐
20316 trol scaled image link.
20317 Bugs fixed
20319 · LaTeX writer now generates correct markup for cells spanning multiple
20320 rows.
20321 · #1674: Do not crash if a module’s __all__ is not a list of strings.
20323 · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
20325 · On windows, make-mode didn’t work on Win32 platform if sphinx was
20327 invoked as python sphinx-build.py.
20328 · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
20330 · #1690: toctrees with glob option now can also contain entries for
20332 single documents with explicit title.
20333 · #1591: html search results for C++ elements now has correct interpage
20335 links.
20336 · bizstyle theme: nested long title pages make long breadcrumb that
20338 breaks page layout.
20339 · bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
20341 browser (iPhone5s safari).
20342 · #1722: restore toctree() template function behavior that was changed
20344 at 1.3b1.
20345 · #1732: i18n: localized table caption raises exception.
20347 · #1718: :numref: does not work with capital letters in the label
20349 · #1630: resolve CSS conflicts, div.container css target for literal
20351 block wrapper now renamed to div.literal-block-wrapper.
20352 · sphinx.util.pycompat has been restored in its backwards-compatibil‐
20354 ity; slated for removal in Sphinx 1.4.
20355 · #1719: LaTeX writer does not respect numref_format option in captions
20357 Release 1.3b2 (released Dec 5, 2014)
20359 Incompatible changes
20360 · update bundled ez_setup.py for setuptools-7.0 that requires Python
20361 2.6 or later.
20362 Features added
20364 · #1597: Added possibility to return a new template name from
20365 html-page-context.
20366 · PR#314, #1150: Configuration values are now checked for their type.
20368 A warning is raised if the configured and the default value do not
20369 have the same type and do not share a common non-trivial base class.
20370 Bugs fixed
20372 · PR#311: sphinx-quickstart does not work on python 3.4.
20373 · Fix autodoc_docstring_signature not working with signatures in class
20375 docstrings.
20376 · Rebuilding cause crash unexpectedly when source files were added.
20378 · #1607: Fix a crash when building latexpdf with “howto” class
20380 · #1251: Fix again. Sections which depth are lower than :tocdepth:
20382 should not be shown on localtoc sidebar.
20383 · make-mode didn’t work on Win32 platform if sphinx was installed by
20385 wheel package.
20386 Release 1.3b1 (released Oct 10, 2014)
20388 Incompatible changes
20389 · Dropped support for Python 2.5, 3.1 and 3.2.
20390 · Dropped support for docutils versions up to 0.9.
20392 · Removed the sphinx.ext.oldcmarkup extension.
20394 · The deprecated config values exclude_trees, exclude_dirnames and
20396 unused_docs have been removed.
20397 · A new node, sphinx.addnodes.literal_strong, has been added, for text
20399 that should appear literally (i.e. no smart quotes) in strong font.
20400 Custom writers will have to be adapted to handle this node.
20401 · PR#269, #1476: replace <tt> tag by <code>. User customized
20403 stylesheets should be updated If the css contain some styles for tt>
20404 tag. Thanks to Takeshi Komiya.
20405 · #1543: templates_path is automatically added to exclude_patterns to
20407 avoid reading autosummary rst templates in the templates directory.
20408 · Custom domains should implement the new Domain.resolve_any_xref
20410 method to make the any role work properly.
20411 · gettext builder: gettext doesn’t emit uuid information to generated
20413 pot files by default. Please set True to gettext_uuid to emit uuid
20414 information. Additionally, if the python-levenshtein 3rd-party pack‐
20415 age is installed, it will improve the calculation time.
20416 · gettext builder: disable extracting/apply ‘index’ node by default.
20418 Please set ‘index’ to gettext_enables to enable extracting index
20419 entries.
20420 · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
20422 Features added
20424 · Add support for Python 3.4.
20425 · Add support for docutils 0.12
20427 · Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
20429 string support.
20430 · Added support for parallel reading (parsing) of source files with the
20432 sphinx-build -j option. Third-party extensions will need to be
20433 checked for compatibility and may need to be adapted if they store
20434 information in the build environment object. See env-merge-info.
20435 · Added the any role that can be used to find a cross-reference of any
20437 type in any domain. Custom domains should implement the new
20438 Domain.resolve_any_xref method to make this work properly.
20439 · Exception logs now contain the last 10 messages emitted by Sphinx.
20441 · Added support for extension versions (a string returned by setup(),
20443 these can be shown in the traceback log files). Version requirements
20444 for extensions can be specified in projects using the new
20445 needs_extensions config value.
20446 · Changing the default role within a document with the default-role
20448 directive is now supported.
20449 · PR#214: Added stemming support for 14 languages, so that the built-in
20451 document search can now handle these. Thanks to Shibukawa Yoshiki.
20452 · PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
20454 tables and code-blocks. This feature is configured with numfig, num‐
20455 fig_secnum_depth and numfig_format. Also numref role is available.
20456 Thanks to Takeshi Komiya.
20457 · PR#202: Allow “.” and “~” prefixed references in :param: doc fields
20459 for Python.
20460 · PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
20462 nal modules that need not be present when autodocumenting.
20463 · #925: Allow list-typed config values to be provided on the command
20465 line, like -D key=val1,val2.
20466 · #668: Allow line numbering of code-block and literalinclude direc‐
20468 tives to start at an arbitrary line number, with a new lineno-start
20469 option.
20470 · PR#172, PR#266: The code-block and literalinclude directives now can
20472 have a caption option that shows a filename before the code in the
20473 output. Thanks to Nasimul Haque, Takeshi Komiya.
20474 · Prompt for the document language in sphinx-quickstart.
20476 · PR#217: Added config values to suppress UUID and location information
20478 in generated gettext catalogs.
20479 · PR#236, #1456: apidoc: Add a -M option to put module documentation
20481 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
20482 · #1434: Provide non-minified JS files for jquery.js and underscore.js
20484 to clarify the source of the minified files.
20485 · PR#252, #1291: Windows color console support. Thanks to meu31.
20487 · PR#255: When generating latex references, also insert latex tar‐
20489 get/anchor for the ids defined on the node. Thanks to Olivier
20490 Heurtier.
20491 · PR#229: Allow registration of other translators. Thanks to Russell
20493 Sim.
20494 · Add app.set_translator() API to register or override a Docutils
20496 translator class like html_translator_class.
20497 · PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
20499 Richard Wall and WAKAYAMA shirou.
20500 · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
20502 · Automatically compile *.mo files from *.po files when get‐
20504 text_auto_build is True (default) and *.po is newer than *.mo file.
20505 · #623: sphinx.ext.viewcode supports imported function/class aliases.
20507 · PR#275: sphinx.ext.intersphinx supports multiple target for the
20509 inventory. Thanks to Brigitta Sipocz.
20510 · PR#261: Added the env-before-read-docs event that can be connected to
20512 modify the order of documents before they are read by the environ‐
20513 ment.
20514 · #1284: Program options documented with option can now start with +.
20516 · PR#291: The caption of code-block is recognized as a title of ref
20518 target. Thanks to Takeshi Komiya.
20519 · PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
20521 · #1344: add gettext_enables to enable extracting ‘index’ to gettext
20523 catalog output / applying translation catalog to generated documenta‐
20524 tion.
20525 · PR#301, #1583: Allow the line numbering of the directive literalin‐
20527 clude to match that of the included file, using a new lineno-match
20528 option. Thanks to Jeppe Pihl.
20529 · PR#299: add various options to sphinx-quickstart. Quiet mode option
20531 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
20532 · #1623: Return types specified with :rtype: are now turned into links
20534 if possible.
20535 Bugs fixed
20537 · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
20538 · #1568: Fix a crash when a “centered” directive contains a reference.
20540 · Now sphinx.ext.autodoc works with python-2.5 again.
20542 · #1563: add_search_language() raises AssertionError for correct type
20544 of argument. Thanks to rikoman.
20545 · #1174: Fix smart quotes being applied inside roles like program or
20547 makevar.
20548 · PR#235: comment db schema of websupport lacked a length of the
20550 node_id field. Thanks to solos.
20551 · #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
20553 “variadic templates” declarations. Thanks to Victor Zverovich.
20554 · #1459,PR#244: Fix default mathjax js path point to http:// that cause
20556 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
20557 · PR#157: autodoc remove spurious signatures from @property decorated
20559 attributes. Thanks to David Ham.
20560 · PR#159: Add coverage targets to quickstart generated Makefile and
20562 make.bat. Thanks to Matthias Troffaes.
20563 · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
20565 data, sub section number that is larger depth than :tocdepth: is
20566 shrunk.
20567 · PR#260: Encode underscore in citation labels for latex export. Thanks
20569 to Lennart Fricke.
20570 · PR#264: Fix could not resolve xref for figure node with :name:
20572 option. Thanks to Takeshi Komiya.
20573 · PR#265: Fix could not capture caption of graphviz node by xref.
20575 Thanks to Takeshi Komiya.
20576 · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
20578 Andersen.
20579 · Hyperlinks to all found nested names and template arguments
20581 (#1103).
20582 · Support for function types everywhere, e.g., in std::func‐
20584 tion<bool(int, int)> (#1013).
20585 · Support for virtual functions.
20587 · Changed interpretation of function arguments to following standard
20589 prototype declarations, i.e., void f(arg) means that arg is the
20590 type of the argument, instead of it being the name.
20591 · Updated tests.
20593 · Updated documentation with elaborate description of what declara‐
20595 tions are supported and how the namespace declarations influence
20596 declaration and cross-reference lookup.
20597 · Index names may be different now. Elements are indexed by their
20599 fully qualified name. It should be rather easy to change this be‐
20600 haviour and potentially index by namespaces/classes as well.
20601 · PR#258, #939: Add dedent option for code-block and literalinclude.
20603 Thanks to Zafar Siddiqui.
20604 · PR#268: Fix numbering section does not work at singlehtml mode. It
20606 still ad-hoc fix because there is a issue that section IDs are con‐
20607 flicted. Thanks to Takeshi Komiya.
20608 · PR#273, #1536: Fix RuntimeError with numbered circular toctree.
20610 Thanks to Takeshi Komiya.
20611 · PR#274: Set its URL as a default title value if URL appears in toc‐
20613 tree. Thanks to Takeshi Komiya.
20614 · PR#276, #1381: rfc and pep roles support custom link text. Thanks to
20616 Takeshi Komiya.
20617 · PR#277, #1513: highlights for function pointers in argument list of
20619 c:function. Thanks to Takeshi Komiya.
20620 · PR#278: Fix section entries were shown twice if toctree has been put
20622 under only directive. Thanks to Takeshi Komiya.
20623 · #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
20625 py3).
20626 · PR#294: On LaTeX builder, wrap float environment on writing lit‐
20628 eral_block to avoid separation of caption and body. Thanks to Takeshi
20629 Komiya.
20630 · PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
20632 directory. Thanks to Peter Suter.
20633 · PR#297, #1571: Add imgpath property to all builders. It make easier
20635 to develop builder extensions. Thanks to Takeshi Komiya.
20636 · #1584: Point to master doc in HTML “top” link.
20638 · #1585: Autosummary of modules broken in Sphinx-1.2.3.
20640 · #1610: Sphinx cause AttributeError when MeCab search option is
20642 enabled and python-mecab is not installed.
20643 · #1674: Do not crash if a module’s __all__ is not a list of strings.
20645 · #1673: Fix crashes with nitpick_ignore and :doc: references.
20647 · #1686: ifconfig directive doesn’t care about default config values.
20649 · #1642: Fix only one search result appearing in Chrome.
20651 Documentation
20653 · Add clarification about the syntax of tags. (doc/markup/misc.rst)
20654 Release 1.2.3 (released Sep 1, 2014)
20656 Features added
20657 · #1518: sphinx-apidoc command now has a --version option to show ver‐
20658 sion information and exit
20659 · New locales: Hebrew, European Portuguese, Vietnamese.
20661 Bugs fixed
20663 · #636: Keep straight single quotes in literal blocks in the LaTeX
20664 build.
20665 · #1419: Generated i18n sphinx.js files are missing message catalog
20667 entries from ‘.js_t’ and ‘.html’. The issue was introduced from
20668 Sphinx-1.1
20669 · #1363: Fix i18n: missing python domain’s cross-references with cur‐
20671 rentmodule directive or currentclass directive.
20672 · #1444: autosummary does not create the description from attributes
20674 docstring.
20675 · #1457: In python3 environment, make linkcheck cause “Can’t convert
20677 ‘bytes’ object to str implicitly” error when link target url has a
20678 hash part. Thanks to Jorge_C.
20679 · #1467: Exception on Python3 if nonexistent method is specified by
20681 automethod
20682 · #1441: autosummary can’t handle nested classes correctly.
20684 · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
20686 user-friendly error message.
20687 · #1502: In autodoc, fix display of parameter defaults containing back‐
20689 slashes.
20690 · #1226: autodoc, autosummary: importing setup.py by automodule will
20692 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
20693 mExit exception and emits warnings without unexpected termination.
20694 · #1503: py:function directive generate incorrectly signature when
20696 specifying a default parameter with an empty list []. Thanks to Geert
20697 Jansen.
20698 · #1508: Non-ASCII filename raise exception on make singlehtml, latex,
20700 man, texinfo and changes.
20701 · #1531: On Python3 environment, docutils.conf with ‘source_link=true’
20703 in the general section cause type error.
20704 · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
20706 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
20707 · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
20709 Thanks to Takeshi Komiya.
20710 · #1477: gettext does not extract nodes.line in a table or list.
20712 · #1544: make text generates wrong table when it has empty table cells.
20714 · #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
20716 lem has been appeared from Sphinx-1.2.1 by #949.
20717 · #508: Sphinx every time exit with zero when is invoked from setup.py
20719 command. ex. python setup.py build_sphinx -b doctest return zero
20720 even if doctest failed.
20721 Release 1.2.2 (released Mar 2, 2014)
20723 Bugs fixed
20724 · PR#211: When checking for existence of the html_logo file, check the
20725 full relative path and not the basename.
20726 · PR#212: Fix traceback with autodoc and __init__ methods without doc‐
20728 string.
20729 · PR#213: Fix a missing import in the setup command.
20731 · #1357: Option names documented by option are now again allowed to not
20733 start with a dash or slash, and referencing them will work correctly.
20734 · #1358: Fix handling of image paths outside of the source directory
20736 when using the “wildcard” style reference.
20737 · #1374: Fix for autosummary generating overly-long summaries if first
20739 line doesn’t end with a period.
20740 · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
20742 · #1391: Actually prevent using “pngmath” and “mathjax” extensions at
20744 the same time in sphinx-quickstart.
20745 · #1386: Fix bug preventing more than one theme being added by the
20747 entry point mechanism.
20748 · #1370: Ignore “toctree” nodes in text writer, instead of raising.
20750 · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
20752 present.
20753 · #1367: Fix a change of PR#96 that break sphinx.util.doc‐
20755 fields.Field.make_field interface/behavior for item argument usage.
20756 Documentation
20758 · Extended the documentation about building extensions.
20759 Release 1.2.1 (released Jan 19, 2014)
20761 Bugs fixed
20762 · #1335: Fix autosummary template overloading with exclamation prefix
20763 like {% extends "!autosummary/class.rst" %} cause infinite recursive
20764 function call. This was caused by PR#181.
20765 · #1337: Fix autodoc with autoclass_content="both" uses useless
20767 object.__init__ docstring when class does not have __init__. This
20768 was caused by a change for #1138.
20769 · #1340: Can’t search alphabetical words on the HTML quick search gen‐
20771 erated with language=’ja’.
20772 · #1319: Do not crash if the html_logo file does not exist.
20774 · #603: Do not use the HTML-ized title for building the search index
20776 (that resulted in “literal” being found on every page with a literal
20777 in the title).
20778 · #751: Allow production lists longer than a page in LaTeX by using
20780 longtable.
20781 · #764: Always look for stopwords lowercased in JS search.
20783 · #814: autodoc: Guard against strange type objects that don’t have
20785 __bases__.
20786 · #932: autodoc: Do not crash if __doc__ is not a string.
20788 · #933: Do not crash if an option value is malformed (contains spaces
20790 but no option name).
20791 · #908: On Python 3, handle error messages from LaTeX correctly in the
20793 pngmath extension.
20794 · #943: In autosummary, recognize “first sentences” to pull from the
20796 docstring if they contain uppercase letters.
20797 · #923: Take the entire LaTeX document into account when caching png‐
20799 math-generated images. This rebuilds them correctly when png‐
20800 math_latex_preamble changes.
20801 · #901: Emit a warning when using docutils’ new “math” markup without a
20803 Sphinx math extension active.
20804 · #845: In code blocks, when the selected lexer fails, display line
20806 numbers nevertheless if configured.
20807 · #929: Support parsed-literal blocks in LaTeX output correctly.
20809 · #949: Update the tabulary.sty packed with Sphinx.
20811 · #1050: Add anonymous labels into objects.inv to be referenced via
20813 intersphinx.
20814 · #1095: Fix print-media stylesheet being included always in the
20816 “scrolls” theme.
20817 · #1085: Fix current classname not getting set if class description has
20819 :noindex: set.
20820 · #1181: Report option errors in autodoc directives more gracefully.
20822 · #1155: Fix autodocumenting C-defined methods as attributes in Python
20824 3.
20825 · #1233: Allow finding both Python classes and exceptions with the
20827 “class” and “exc” roles in intersphinx.
20828 · #1198: Allow “image” for the “figwidth” option of the figure direc‐
20830 tive as documented by docutils.
20831 · #1152: Fix pycode parsing errors of Python 3 code by including two
20833 grammar versions for Python 2 and 3, and loading the appropriate ver‐
20834 sion for the running Python version.
20835 · #1017: Be helpful and tell the user when the argument to option does
20837 not match the required format.
20838 · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
20840 the store environment for changes to have effect.
20841 · #1072: In the JS search, fix issues searching for upper-cased words
20843 by lowercasing words before stemming.
20844 · #1299: Make behavior of the math directive more consistent and avoid
20846 producing empty environments in LaTeX output.
20847 · #1308: Strip HTML tags from the content of “raw” nodes before feeding
20849 it to the search indexer.
20850 · #1249: Fix duplicate LaTeX page numbering for manual documents.
20852 · #1292: In the linkchecker, retry HEAD requests when denied by HTTP
20854 405. Also make the redirect code apparent and tweak the output a bit
20855 to be more obvious.
20856 · #1285: Avoid name clashes between C domain objects and section
20858 titles.
20859 · #848: Always take the newest code in incremental rebuilds with the
20861 sphinx.ext.viewcode extension.
20862 · #979, #1266: Fix exclude handling in sphinx-apidoc.
20864 · #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
20866 menting classes that can’t be pickled.
20867 · #1316: Remove hard-coded font-face resources from epub theme.
20869 · #1329: Fix traceback with empty translation msgstr in .po files.
20871 · #1300: Fix references not working in translated documents in some
20873 instances.
20874 · #1283: Fix a bug in the detection of changed files that would try to
20876 access doctrees of deleted documents.
20877 · #1330: Fix exclude_patterns behavior with subdirectories in the
20879 html_static_path.
20880 · #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
20882 valid HTML.
20883 · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
20885 Documentation
20887 · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
20888 Release 1.2 (released Dec 10, 2013)
20890 Features added
20891 · Added sphinx.version_info tuple for programmatic checking of the
20892 Sphinx version.
20893 Incompatible changes
20895 · Removed the sphinx.ext.refcounting extension – it is very specific to
20896 CPython and has no place in the main distribution.
20897 Bugs fixed
20899 · Restore versionmodified CSS class for versionadded/changed and depre‐
20900 cated directives.
20901 · PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
20903 ments always (This change keeps the current “theme changes cause a
20904 rebuild” feature).
20905 · #1296: Fix invalid charset in HTML help generated HTML files for
20907 default locale.
20908 · PR#190: Fix gettext does not extract figure caption and rubric title
20910 inside other blocks. Thanks to Michael Schlenker.
20911 · PR#176: Make sure setup_command test can always import Sphinx. Thanks
20913 to Dmitry Shachnev.
20914 · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
20916 · #1269: Fix ResourceWarnings with Python 3.2 or later.
20918 · #1138: Fix: When autodoc_docstring_signature = True and auto‐
20920 class_content = 'init' or 'both', __init__ line should be removed
20921 from class documentation.
20922 Release 1.2 beta3 (released Oct 3, 2013)
20924 Features added
20925 · The Sphinx error log files will now include a list of the loaded
20926 extensions for help in debugging.
20927 Incompatible changes
20929 · PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
20930 manual’ and ‘sphinxhowto’. Now you can use your custom document class
20931 without ‘sphinx’ prefix. Thanks to Erik B.
20932 Bugs fixed
20934 · #1265: Fix i18n: crash when translating a section name that is
20935 pointed to from a named target.
20936 · A wrong condition broke the search feature on first page that is usu‐
20938 ally index.rst. This issue was introduced in 1.2b1.
20939 · #703: When Sphinx can’t decode filenames with non-ASCII characters,
20941 Sphinx now catches UnicodeError and will continue if possible instead
20942 of raising the exception.
20943 Release 1.2 beta2 (released Sep 17, 2013)
20945 Features added
20946 · apidoc now ignores “_private” modules by default, and has an option
20947 -P to include them.
20948 · apidoc now has an option to not generate headings for packages and
20950 modules, for the case that the module docstring already includes a
20951 reST heading.
20952 · PR#161: apidoc can now write each module to a standalone page instead
20954 of combining all modules in a package on one page.
20955 · Builders: rebuild i18n target document when catalog updated.
20957 · Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
20959 HTML writer. The latex, manpage and texinfo writers also support
20960 their respective ‘writers’ sections.
20961 · The new html_extra_path config value allows to specify directories
20963 with files that should be copied directly to the HTML output direc‐
20964 tory.
20965 · Autodoc directives for module data and attributes now support an
20967 annotation option, so that the default display of the data/attribute
20968 value can be overridden.
20969 · PR#136: Autodoc directives now support an imported-members option to
20971 include members imported from different modules.
20972 · New locales: Macedonian, Sinhala, Indonesian.
20974 · Theme package collection by using setuptools plugin mechanism.
20976 Incompatible changes
20978 · PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
20979 ation-Date that was generated by gettext builder. Thanks to masklinn
20980 and Jakub Wilk.
20981 Bugs fixed
20983 · PR#132: Updated jQuery version to 1.8.3.
20984 · PR#141, #982: Avoid crash when writing PNG file using Python 3.
20986 Thanks to Marcin Wojdyr.
20987 · PR#145: In parallel builds, sphinx drops second document file to
20989 write. Thanks to tychoish.
20990 · PR#151: Some styling updates to tables in LaTeX.
20992 · PR#153: The “extensions” config value can now be overridden.
20994 · PR#155: Added support for some C++11 function qualifiers.
20996 · Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
20998 utf-8 encoded strings.
20999 · #828: use inspect.getfullargspec() to be able to document functions
21001 with keyword-only arguments on Python 3.
21002 · #1090: Fix i18n: multiple cross references (term, ref, doc) in the
21004 same line return the same link.
21005 · #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
21007 exception.
21008 · #1159: fix wrong generation of objects inventory for Python modules,
21010 and add a workaround in intersphinx to fix handling of affected
21011 inventories.
21012 · #1160: Citation target missing caused an AssertionError.
21014 · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
21016 · #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
21018 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
21019 der Dupuy.
21020 · #1185: Don’t crash when a Python module has a wrong or no encoding
21022 declared, and non-ASCII characters are included.
21023 · #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
21025 sion” includes non-ASCII characters.
21026 · #1189: “Title underline is too short” WARNING is given when using
21028 fullwidth characters to “Project name” on quickstart.
21029 · #1190: Output TeX/texinfo/man filename has no basename (only exten‐
21031 sion) when using non-ASCII characters in the “Project name” on quick‐
21032 start.
21033 · #1192: Fix escaping problem for hyperlinks in the manpage writer.
21035 · #1193: Fix i18n: multiple link references in the same line return the
21037 same link.
21038 · #1176: Fix i18n: footnote reference number missing for auto numbered
21040 named footnote and auto symbol footnote.
21041 · PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to
21043 tychoish.
21044 · #1204: Fix wrong generation of links to local intersphinx targets.
21046 · #1206: Fix i18n: gettext did not translate admonition directive’s
21048 title.
21049 · #1232: Sphinx generated broken ePub files on Windows.
21051 · #1259: Guard the debug output call when emitting events; to prevent
21053 the repr() implementation of arbitrary objects causing build fail‐
21054 ures.
21055 · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
21057 · #1234: Ignoring the string consists only of white-space characters.
21059 Release 1.2 beta1 (released Mar 31, 2013)
21061 Incompatible changes
21062 · Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
21063 eref_role() which were deprecated since version 1.0.
21064 · PR#122: the files given in latex_additional_files now override TeX
21066 files included by Sphinx, such as sphinx.sty.
21067 · PR#124: the node generated by versionadded, versionchanged and depre‐
21069 cated directives now includes all added markup (such as “New in ver‐
21070 sion X”) as child nodes, and no additional text must be generated by
21071 writers.
21072 · PR#99: the seealso directive now generates admonition nodes instead
21074 of the custom seealso node.
21075 Features added
21077 · Markup
21078 · The toctree directive and the toctree() template function now have
21080 an includehidden option that includes hidden toctree entries (bugs
21081 #790 and #1047). A bug in the maxdepth option for the toctree()
21082 template function has been fixed (bug #1046).
21083 · PR#99: Strip down seealso directives to normal admonitions. This
21085 removes their unusual CSS classes (admonition-see-also), inconsis‐
21086 tent LaTeX admonition title (“See Also” instead of “See also”), and
21087 spurious indentation in the text builder.
21088 · HTML builder
21090 · #783: Create a link to full size image if it is scaled with width
21092 or height.
21093 · #1067: Improve the ordering of the JavaScript search results:
21095 matches in titles come before matches in full text, and object
21096 results are better categorized. Also implement a pluggable search
21097 scorer.
21098 · #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
21100 options now work together.
21101 · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
21103 · Texinfo builder
21105 · An “Index” node is no longer added when there are no entries.
21107 · “deffn” categories are no longer capitalized if they contain capi‐
21109 tal letters.
21110 · desc_annotation nodes are now rendered.
21112 · strong and emphasis nodes are now formatted like literals. The rea‐
21114 son for this is because the standard Texinfo markup (*strong* and
21115 _emphasis_) resulted in confusing output due to the common usage of
21116 using these constructs for documenting parameter names.
21117 · Field lists formatting has been tweaked to better display “Info
21119 field lists”.
21120 · system_message and problematic nodes are now formatted in a similar
21122 fashion as done by the text builder.
21123 · “en-dash” and “em-dash” conversion of hyphens is no longer per‐
21125 formed in option directive signatures.
21126 · @ref is now used instead of @pxref for cross-references which pre‐
21128 vents the word “see” from being added before the link (does not
21129 affect the Info output).
21130 · The @finalout command has been added for better TeX output.
21132 · transition nodes are now formatted using underscores (“_”) instead
21134 of asterisks (“*”).
21135 · The default value for the paragraphindent has been changed from 2
21137 to 0 meaning that paragraphs are no longer indented by default.
21138 · #1110: A new configuration value texinfo_no_detailmenu has been
21140 added for controlling whether a @detailmenu is added in the “Top”
21141 node’s menu.
21142 · Detailed menus are no longer created except for the “Top” node.
21144 · Fixed an issue where duplicate domain indices would result in
21146 invalid output.
21147 · LaTeX builder:
21149 · PR#115: Add 'transition' item in latex_elements for customizing how
21151 transitions are displayed. Thanks to Jeff Klukas.
21152 · PR#114: The LaTeX writer now includes the “cmap” package by
21154 default. The 'cmappkg' item in latex_elements can be used to con‐
21155 trol this. Thanks to Dmitry Shachnev.
21156 · The 'fontpkg' item in latex_elements now defaults to '' when the
21158 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
21159 · The latex_documents, texinfo_documents, and man_pages configuration
21161 values will be set to default values based on the master_doc if not
21162 explicitly set in conf.py. Previously, if these values were not
21163 set, no output would be generated by their respective builders.
21164 · Internationalization:
21166 · Add i18n capabilities for custom templates. For example: The
21168 Sphinx reference documentation in doc directory provides a
21169 sphinx.pot file with message strings from doc/_templates/*.html
21170 when using make gettext.
21171 · PR#61,#703: Add support for non-ASCII filename handling.
21173 · Other builders:
21175 · Added the Docutils-native XML and pseudo-XML builders. See XML‐
21177 Builder and PseudoXMLBuilder.
21178 · PR#45: The linkcheck builder now checks #anchors for existence.
21180 · PR#123, #1106: Add epub_use_index configuration value. If pro‐
21182 vided, it will be used instead of html_use_index for epub builder.
21183 · PR#126: Add epub_tocscope configuration value. The setting controls
21185 the generation of the epub toc. The user can now also include hid‐
21186 den toc entries.
21187 · PR#112: Add epub_show_urls configuration value.
21189 · Extensions:
21191 · PR#52: special_members flag to autodoc now behaves like members.
21193 · PR#47: Added sphinx.ext.linkcode extension.
21195 · PR#25: In inheritance diagrams, the first line of the class doc‐
21197 string is now the tooltip for the class.
21198 · Command-line interfaces:
21200 · PR#75: Added --follow-links option to sphinx-apidoc.
21202 · #869: sphinx-build now has the option -T for printing the full
21204 traceback after an unhandled exception.
21205 · sphinx-build now supports the standard --help and --version
21207 options.
21208 · sphinx-build now provides more specific error messages when called
21210 with invalid options or arguments.
21211 · sphinx-build now has a verbose option -v which can be repeated for
21213 greater effect. A single occurrence provides a slightly more ver‐
21214 bose output than normal. Two or more occurrences of this option
21215 provides more detailed output which may be useful for debugging.
21216 · Locales:
21218 · PR#74: Fix some Russian translation.
21220 · PR#54: Added Norwegian bokmaal translation.
21222 · PR#35: Added Slovak translation.
21224 · PR#28: Added Hungarian translation.
21226 · #1113: Add Hebrew locale.
21228 · #1097: Add Basque locale.
21230 · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
21232 · #1012: Update Estonian translation.
21234 · Optimizations:
21236 · Speed up building the search index by caching the results of the
21238 word stemming routines. Saves about 20 seconds when building the
21239 Python documentation.
21240 · PR#108: Add experimental support for parallel building with a new
21242 sphinx-build -j option.
21243 Documentation
21245 · PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
21246 outlines the basic development process of the Sphinx project.
21247 · Added a detailed “Installing Sphinx” document (doc/install.rst).
21249 Bugs fixed
21251 · PR#124: Fix paragraphs in versionmodified are ignored when it has no
21252 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
21253 versionmodified is not translatable. Thanks to Nozomu Kaneko.
21254 · PR#111: Respect add_autodoc_attrgetter() even when inherited-members
21256 is set. Thanks to A. Jesse Jiryu Davis.
21257 · PR#97: Fix footnote handling in translated documents.
21259 · Fix text writer not handling visit_legend for figure directive con‐
21261 tents.
21262 · Fix text builder not respecting wide/fullwidth characters: title
21264 underline width, table layout width and text wrap width.
21265 · Fix leading space in LaTeX table header cells.
21267 · #1132: Fix LaTeX table output for multi-row cells in the first col‐
21269 umn.
21270 · #1128: Fix Unicode errors when trying to format time strings with a
21272 non-standard locale.
21273 · #1127: Fix traceback when autodoc tries to tokenize a non-Python
21275 file.
21276 · #1126: Fix double-hyphen to en-dash conversion in wrong places such
21278 as command-line option names in LaTeX.
21279 · #1123: Allow whitespaces in filenames given to literalinclude.
21281 · #1120: Added improvements about i18n for themes “basic”, “haiku” and
21283 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
21284 · #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
21286 G.
21287 · #1117: Handle .pyx files in sphinx-apidoc.
21289 · #1112: Avoid duplicate download files when referenced from documents
21291 in different ways (absolute/relative).
21292 · #1111: Fix failure to find uppercase words in search when
21294 html_search_language is ‘ja’. Thanks to Tomo Saito.
21295 · #1108: The text writer now correctly numbers enumerated lists with
21297 non-default start values (based on patch by Ewan Edwards).
21298 · #1102: Support multi-context “with” statements in autodoc.
21300 · #1090: Fix gettext not extracting glossary terms.
21302 · #1074: Add environment version info to the generated search index to
21304 avoid compatibility issues with old builds.
21305 · #1070: Avoid un-pickling issues when running Python 3 and the saved
21307 environment was created under Python 2.
21308 · #1069: Fixed error caused when autodoc would try to format signatures
21310 of “partial” functions without keyword arguments (patch by Artur Gas‐
21311 par).
21312 · #1062: sphinx.ext.autodoc use __init__ method signature for class
21314 signature.
21315 · #1055: Fix web support with relative path to source directory.
21317 · #1043: Fix sphinx-quickstart asking again for yes/no questions
21319 because input() returns values with an extra ‘r’ on Python 3.2.0 +
21320 Windows. Thanks to Régis Décamps.
21321 · #1041: Fix failure of the cpp domain parser to parse a const type
21323 with a modifier.
21324 · #1038: Fix failure of the cpp domain parser to parse C+11 “static
21326 constexpr” declarations. Thanks to Jakub Wilk.
21327 · #1029: Fix intersphinx_mapping values not being stable if the mapping
21329 has plural key/value set with Python 3.3.
21330 · #1028: Fix line block output in the text builder.
21332 · #1024: Improve Makefile/make.bat error message if Sphinx is not
21334 found. Thanks to Anatoly Techtonik.
21335 · #1018: Fix “container” directive handling in the text builder.
21337 · #1015: Stop overriding jQuery contains() in the JavaScript.
21339 · #1010: Make pngmath images transparent by default; IE7+ should handle
21341 it.
21342 · #1008: Fix test failures with Python 3.3.
21344 · #995: Fix table-of-contents and page numbering for the LaTeX “howto”
21346 class.
21347 · #976: Fix gettext does not extract index entries.
21349 · PR#72: #975: Fix gettext not extracting definition terms before docu‐
21351 tils 0.10.
21352 · #961: Fix LaTeX output for triple quotes in code snippets.
21354 · #958: Do not preserve environment.pickle after a failed build.
21356 · #955: Fix i18n transformation.
21358 · #940: Fix gettext does not extract figure caption.
21360 · #920: Fix PIL packaging issue that allowed to import Image without
21362 PIL namespace. Thanks to Marc Schlaich.
21363 · #723: Fix the search function on local files in WebKit based
21365 browsers.
21366 · #440: Fix coarse timestamp resolution in some filesystem generating a
21368 wrong list of outdated files.
21369 Release 1.1.3 (Mar 10, 2012)
21371 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
21372 characters correctly.
21373 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
21375 · PR#34: Restore Python 2.4 compatibility.
21377 · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
21379 the document class.
21380 · #695: When the highlight language “python” is specified explicitly,
21382 do not try to parse the code to recognize non-Python snippets.
21383 · #859: Fix exception under certain circumstances when not finding
21385 appropriate objects to link to.
21386 · #860: Do not crash when encountering invalid doctest examples, just
21388 emit a warning.
21389 · #864: Fix crash with some settings of modindex_common_prefix.
21391 · #862: Fix handling of -D and -A options on Python 3.
21393 · #851: Recognize and warn about circular toctrees, instead of running
21395 into recursion errors.
21396 · #853: Restore compatibility with docutils trunk.
21398 · #852: Fix HtmlHelp index entry links again.
21400 · #854: Fix inheritance_diagram raising attribute errors on builtins.
21402 · #832: Fix crashes when putting comments or lone terms in a glossary.
21404 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
21406 supported languages.
21407 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
21409 sion.
21410 · #831: Provide --project flag in setup_command as advertised.
21412 · #875: Fix reading config files under Python 3.
21414 · #876: Fix quickstart test under Python 3.
21416 · #870: Fix spurious KeyErrors when removing documents.
21418 · #892: Fix single-HTML builder misbehaving with the master document in
21420 a subdirectory.
21421 · #873: Fix assertion errors with empty only directives.
21423 · #816: Fix encoding issues in the Qt help builder.
21425 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
21427 · #809: Include custom fixers in the source distribution.
21428 Release 1.1.1 (Nov 1, 2011)
21430 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
21431 · #792: Include “sphinx-apidoc” in the source distribution.
21433 · #797: Don’t crash on a misformatted glossary.
21435 · #801: Make intersphinx work properly without SSL support.
21437 · #805: Make the Sphinx.add_index_to_domain method work correctly.
21439 · #780: Fix Python 2.5 compatibility.
21441 Release 1.1 (Oct 9, 2011)
21443 Incompatible changes
21444 · The py:module directive doesn’t output its platform option value any‐
21445 more. (It was the only thing that the directive did output, and
21446 therefore quite inconsistent.)
21447 · Removed support for old dependency versions; requirements are now:
21449 · Pygments >= 1.2
21451 · Docutils >= 0.7
21453 · Jinja2 >= 2.3
21455 Features added
21457 · Added Python 3.x support.
21458 · New builders and subsystems:
21460 · Added a Texinfo builder.
21462 · Added i18n support for content, a gettext builder and related util‐
21464 ities.
21465 · Added the websupport library and builder.
21467 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
21469 source files containing autodoc directives to document modules and
21470 packages.
21471 · #273: Add an API for adding full-text search support for languages
21473 other than English. Add support for Japanese.
21474 · Markup:
21476 · #138: Added an index role, to make inline index entries.
21478 · #454: Added more index markup capabilities: marking see/seealso
21480 entries, and main entries for a given key.
21481 · #460: Allowed limiting the depth of section numbers for HTML using
21483 the toctree’s numbered option.
21484 · #586: Implemented improved glossary markup which allows multiple
21486 terms per definition.
21487 · #478: Added py:decorator directive to describe decorators.
21489 · C++ domain now supports array definitions.
21491 · C++ domain now supports doc fields (:param x: inside directives).
21493 · Section headings in only directives are now correctly handled.
21495 · Added emphasize-lines option to source code directives.
21497 · #678: C++ domain now supports superclasses.
21499 · HTML builder:
21501 · Added pyramid theme.
21503 · #559: html_add_permalinks is now a string giving the text to dis‐
21505 play in permalinks.
21506 · #259: HTML table rows now have even/odd CSS classes to enable
21508 “Zebra styling”.
21509 · #554: Add theme option sidebarwidth to the basic theme.
21511 · Other builders:
21513 · #516: Added new value of the latex_show_urls option to show the
21515 URLs in footnotes.
21516 · #209: Added text_newlines and text_sectionchars config values.
21518 · Added man_show_urls config value.
21520 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
21522 requests and allow configuring the timeout. New config values:
21523 linkcheck_timeout and linkcheck_workers.
21524 · #521: Added linkcheck_ignore config value.
21526 · #28: Support row/colspans in tables in the LaTeX builder.
21528 · Configuration and extensibility:
21530 · #537: Added nitpick_ignore.
21532 · #306: Added env-get-outdated event.
21534 · Application.add_stylesheet() now accepts full URIs.
21536 · Autodoc:
21538 · #564: Add autodoc_docstring_signature. When enabled (the default),
21540 autodoc retrieves the signature from the first line of the doc‐
21541 string, if it is found there.
21542 · #176: Provide private-members option for autodoc directives.
21544 · #520: Provide special-members option for autodoc directives.
21546 · #431: Doc comments for attributes can now be given on the same line
21548 as the assignment.
21549 · #437: autodoc now shows values of class data attributes.
21551 · autodoc now supports documenting the signatures of functools.par‐
21553 tial objects.
21554 · Other extensions:
21556 · Added the sphinx.ext.mathjax extension.
21558 · #443: Allow referencing external graphviz files.
21560 · Added inline option to graphviz directives, and fixed the default
21562 (block-style) in LaTeX output.
21563 · #590: Added caption option to graphviz directives.
21565 · #553: Added testcleanup blocks in the doctest extension.
21567 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
21569 · #367: Added automatic exclusion of hidden members in inheritance
21571 diagrams, and an option to selectively enable it.
21572 · Added pngmath_add_tooltips.
21574 · The math extension displaymath directives now support name in addi‐
21576 tion to label for giving the equation label, for compatibility with
21577 Docutils.
21578 · New locales:
21580 · #221: Added Swedish locale.
21582 · #526: Added Iranian locale.
21584 · #694: Added Latvian locale.
21586 · Added Nepali locale.
21588 · #714: Added Korean locale.
21590 · #766: Added Estonian locale.
21592 · Bugs fixed:
21594 · #778: Fix “hide search matches” link on pages linked by search.
21596 · Fix the source positions referenced by the “viewcode” extension.
21598 Release 1.0.8 (Sep 23, 2011)
21600 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
21601 · Fix the abbr role when the abbreviation has newlines in it.
21603 · #727: Fix the links to search results with custom object types.
21605 · #648: Fix line numbers reported in warnings about undefined refer‐
21607 ences.
21608 · #696, #666: Fix C++ array definitions and template arguments that are
21610 not type names.
21611 · #633: Allow footnotes in section headers in LaTeX output.
21613 · #616: Allow keywords to be linked via intersphinx.
21615 · #613: Allow Unicode characters in production list token names.
21617 · #720: Add dummy visitors for graphviz nodes for text and man.
21619 · #704: Fix image file duplication bug.
21621 · #677: Fix parsing of multiple signatures in C++ domain.
21623 · #637: Ignore Emacs lock files when looking for source files.
21625 · #544: Allow .pyw extension for importable modules in autodoc.
21627 · #700: Use $(MAKE) in quickstart-generated Makefiles.
21629 · #734: Make sidebar search box width consistent in browsers.
21631 · #644: Fix spacing of centered figures in HTML output.
21633 · #767: Safely encode SphinxError messages when printing them to
21635 sys.stderr.
21636 · #611: Fix LaTeX output error with a document with no sections but a
21638 link target.
21639 · Correctly treat built-in method descriptors as methods in autodoc.
21641 · #706: Stop monkeypatching the Python textwrap module.
21643 · #657: viewcode now works correctly with source files that have
21645 non-ASCII encoding.
21646 · #669: Respect the noindex flag option in py:module directives.
21648 · #675: Fix IndexErrors when including nonexisting lines with literal‐
21650 include.
21651 · #676: Respect custom function/method parameter separator strings.
21653 · #682: Fix JS incompatibility with jQuery >= 1.5.
21655 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
21657 · #647: Do not apply SmartyPants in parsed-literal blocks.
21659 · C++ domain now supports array definitions.
21661 Release 1.0.7 (Jan 15, 2011)
21663 · #347: Fix wrong generation of directives of static methods in auto‐
21664 summary.
21665 · #599: Import PIL as from PIL import Image.
21667 · #558: Fix longtables with captions in LaTeX output.
21669 · Make token references work as hyperlinks again in LaTeX output.
21671 · #572: Show warnings by default when reference labels cannot be found.
21673 · #536: Include line number when complaining about missing reference
21675 targets in nitpicky mode.
21676 · #590: Fix inline display of graphviz diagrams in LaTeX output.
21678 · #589: Build using app.build() in setup command.
21680 · Fix a bug in the inheritance diagram exception that caused base
21682 classes to be skipped if one of them is a builtin.
21683 · Fix general index links for C++ domain objects.
21685 · #332: Make admonition boundaries in LaTeX output visible.
21687 · #573: Fix KeyErrors occurring on rebuild after removing a file.
21689 · Fix a traceback when removing files with globbed toctrees.
21691 · If an autodoc object cannot be imported, always re-read the document
21693 containing the directive on next build.
21694 · If an autodoc object cannot be imported, show the full traceback of
21696 the import error.
21697 · Fix a bug where the removal of download files and images wasn’t
21699 noticed.
21700 · #571: Implement ~ cross-reference prefix for the C domain.
21702 · Fix regression of LaTeX output with the fix of #556.
21704 · #568: Fix lookup of class attribute documentation on descriptors so
21706 that comment documentation now works.
21707 · Fix traceback with only directives preceded by targets.
21709 · Fix tracebacks occurring for duplicate C++ domain objects.
21711 · Fix JavaScript domain links to objects with $ in their name.
21713 Release 1.0.6 (Jan 04, 2011)
21715 · #581: Fix traceback in Python domain for empty cross-reference tar‐
21716 gets.
21717 · #283: Fix literal block display issues on Chrome browsers.
21719 · #383, #148: Support sorting a limited range of accented characters in
21721 the general index and the glossary.
21722 · #570: Try decoding -D and -A command-line arguments with the locale’s
21724 preferred encoding.
21725 · #528: Observe locale_dirs when looking for the JS translations file.
21727 · #574: Add special code for better support of Japanese documents in
21729 the LaTeX builder.
21730 · Regression of #77: If there is only one parameter given with :param:
21732 markup, the bullet list is now suppressed again.
21733 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
21735 tions.
21736 · #567: Emit the autodoc-process-docstring event even for objects with‐
21738 out a docstring so that it can add content.
21739 · #565: In the LaTeX builder, not only literal blocks require different
21741 table handling, but also quite a few other list-like block elements.
21742 · #515: Fix tracebacks in the viewcode extension for Python objects
21744 that do not have a valid signature.
21745 · Fix strange reports of line numbers for warnings generated from
21747 autodoc-included docstrings, due to different behavior depending on
21748 docutils version.
21749 · Several fixes to the C++ domain.
21751 Release 1.0.5 (Nov 12, 2010)
21753 · #557: Add CSS styles required by docutils 0.7 for aligned images and
21754 figures.
21755 · In the Makefile generated by LaTeX output, do not delete pdf files on
21757 clean; they might be required images.
21758 · #535: Fix LaTeX output generated for line blocks.
21760 · #544: Allow .pyw as a source file extension.
21762 Release 1.0.4 (Sep 17, 2010)
21764 · #524: Open intersphinx inventories in binary mode on Windows, since
21765 version 2 contains zlib-compressed data.
21766 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
21768 JSMath extension.
21769 · #512: Fix traceback when intersphinx_mapping is empty.
21771 Release 1.0.3 (Aug 23, 2010)
21773 · #495: Fix internal vs. external link distinction for links coming
21774 from a docutils table-of-contents.
21775 · #494: Fix the maxdepth option for the toctree() template callable
21777 when used with collapse=True.
21778 · #507: Fix crash parsing Python argument lists containing brackets in
21780 string literals.
21781 · #501: Fix regression when building LaTeX docs with figures that don’t
21783 have captions.
21784 · #510: Fix inheritance diagrams for classes that are not picklable.
21786 · #497: Introduce separate background color for the sidebar collapse
21788 button, making it easier to see.
21789 · #502, #503, #496: Fix small layout bugs in several builtin themes.
21791 Release 1.0.2 (Aug 14, 2010)
21793 · #490: Fix cross-references to objects of types added by the
21794 add_object_type() API function.
21795 · Fix handling of doc field types for different directive types.
21797 · Allow breaking long signatures, continuing with backlash-escaped new‐
21799 lines.
21800 · Fix unwanted styling of C domain references (because of a namespace
21802 clash with Pygments styles).
21803 · Allow references to PEPs and RFCs with explicit anchors.
21805 · #471: Fix LaTeX references to figures.
21807 · #482: When doing a non-exact search, match only the given type of
21809 object.
21810 · #481: Apply non-exact search for Python reference targets with .name
21812 for modules too.
21813 · #484: Fix crash when duplicating a parameter in an info field list.
21815 · #487: Fix setting the default role to one provided by the oldcmarkup
21817 extension.
21818 · #488: Fix crash when json-py is installed, which provides a json mod‐
21820 ule but is incompatible to simplejson.
21821 · #480: Fix handling of target naming in intersphinx.
21823 · #486: Fix removal of ! for all cross-reference roles.
21825 Release 1.0.1 (Jul 27, 2010)
21827 · #470: Fix generated target names for reST domain objects; they are
21828 not in the same namespace.
21829 · #266: Add Bengali language.
21831 · #473: Fix a bug in parsing JavaScript object names.
21833 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
21835 · Fix display names for objects linked to by intersphinx with explicit
21837 targets.
21838 · Fix building with the JSON builder.
21840 · Fix hyperrefs in object descriptions for LaTeX.
21842 Release 1.0 (Jul 23, 2010)
21844 Incompatible changes
21845 · Support for domains has been added. A domain is a collection of
21846 directives and roles that all describe objects belonging together,
21847 e.g. elements of a programming language. A few builtin domains are
21848 provided:
21849 · Python
21851 · C
21853 · C++
21855 · JavaScript
21857 · reStructuredText
21859 · The old markup for defining and linking to C directives is now depre‐
21861 cated. It will not work anymore in future versions without activat‐
21862 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
21863 default.
21864 · Removed support for old dependency versions; requirements are now:
21866 · docutils >= 0.5
21868 · Jinja2 >= 2.2
21870 · Removed deprecated elements:
21872 · exclude_dirs config value
21874 · sphinx.builder module
21876 Features added
21878 · General:
21879 · Added a “nitpicky” mode that emits warnings for all missing refer‐
21881 ences. It is activated by the sphinx-build -n command-line switch
21882 or the nitpicky config value.
21883 · Added latexpdf target in quickstart Makefile.
21885 · Markup:
21887 · The menuselection and guilabel roles now support ampersand acceler‐
21889 ators.
21890 · New more compact doc field syntax is now recognized: :param type
21892 name: description.
21893 · Added tab-width option to literalinclude directive.
21895 · Added titlesonly option to toctree directive.
21897 · Added the prepend and append options to the literalinclude direc‐
21899 tive.
21900 · #284: All docinfo metadata is now put into the document metadata,
21902 not just the author.
21903 · The ref role can now also reference tables by caption.
21905 · The include directive now supports absolute paths, which are inter‐
21907 preted as relative to the source directory.
21908 · In the Python domain, references like :func:`.name` now look for
21910 matching names with any prefix if no direct match is found.
21911 · Configuration:
21913 · Added rst_prolog config value.
21915 · Added html_secnumber_suffix config value to control section number‐
21917 ing format.
21918 · Added html_compact_lists config value to control docutils’ compact
21920 lists feature.
21921 · The html_sidebars config value can now contain patterns as keys,
21923 and the values can be lists that explicitly select which sidebar
21924 templates should be rendered. That means that the builtin sidebar
21925 contents can be included only selectively.
21926 · html_static_path can now contain single file entries.
21928 · The new universal config value exclude_patterns makes the old
21930 unused_docs, exclude_trees and exclude_dirnames obsolete.
21931 · Added html_output_encoding config value.
21933 · Added the latex_docclass config value and made the “twoside” docu‐
21935 mentclass option overridable by “oneside”.
21936 · Added the trim_doctest_flags config value, which is true by
21938 default.
21939 · Added html_show_copyright config value.
21941 · Added latex_show_pagerefs and latex_show_urls config values.
21943 · The behavior of html_file_suffix changed slightly: the empty string
21945 now means “no suffix” instead of “default suffix”, use None for
21946 “default suffix”.
21947 · New builders:
21949 · Added a builder for the Epub format.
21951 · Added a builder for manual pages.
21953 · Added a single-file HTML builder.
21955 · HTML output:
21957 · Inline roles now get a CSS class with their name, allowing styles
21959 to customize their appearance. Domain-specific roles get two
21960 classes, domain and domain-rolename.
21961 · References now get the class internal if they are internal to the
21963 whole project, as opposed to internal to the current page.
21964 · External references can be styled differently with the new exter‐
21966 nalrefs theme option for the default theme.
21967 · In the default theme, the sidebar can experimentally now be made
21969 collapsible using the new collapsiblesidebar theme option.
21970 · #129: Toctrees are now wrapped in a div tag with class toc‐
21972 tree-wrapper in HTML output.
21973 · The toctree callable in templates now has a maxdepth keyword argu‐
21975 ment to control the depth of the generated tree.
21976 · The toctree callable in templates now accepts a titles_only keyword
21978 argument.
21979 · Added htmltitle block in layout template.
21981 · In the JavaScript search, allow searching for object names includ‐
21983 ing the module name, like sys.argv.
21984 · Added new theme haiku, inspired by the Haiku OS user guide.
21986 · Added new theme nature.
21988 · Added new theme agogo, created by Andi Albrecht.
21990 · Added new theme scrolls, created by Armin Ronacher.
21992 · #193: Added a visitedlinkcolor theme option to the default theme.
21994 · #322: Improved responsiveness of the search page by loading the
21996 search index asynchronously.
21997 · Extension API:
21999 · Added html-collect-pages.
22001 · Added needs_sphinx config value and require_sphinx() application
22003 API method.
22004 · #200: Added add_stylesheet() application API method.
22006 · Extensions:
22008 · Added the viewcode extension.
22010 · Added the extlinks extension.
22012 · Added support for source ordering of members in autodoc, with
22014 autodoc_member_order = 'bysource'.
22015 · Added autodoc_default_flags config value, which can be used to
22017 select default flags for all autodoc directives.
22018 · Added a way for intersphinx to refer to named labels in other
22020 projects, and to specify the project you want to link to.
22021 · #280: Autodoc can now document instance attributes assigned in
22023 __init__ methods.
22024 · Many improvements and fixes to the autosummary extension, thanks to
22026 Pauli Virtanen.
22027 · #309: The graphviz extension can now output SVG instead of PNG
22029 images, controlled by the graphviz_output_format config value.
22030 · Added alt option to graphviz extension directives.
22032 · Added exclude argument to autodoc.between().
22034 · Translations:
22036 · Added Croatian translation, thanks to Bojan Mihelač.
22038 · Added Turkish translation, thanks to Firat Ozgul.
22040 · Added Catalan translation, thanks to Pau Fernández.
22042 · Added simplified Chinese translation.
22044 · Added Danish translation, thanks to Hjorth Larsen.
22046 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
22048 · Bugs fixed:
22050 · #445: Fix links to result pages when using the search function of
22052 HTML built with the dirhtml builder.
22053 · #444: In templates, properly re-escape values treated with the
22055 “striptags” Jinja filter.
22056 Previous versions
22058 The changelog for versions before 1.0 can be found in the file
22059 CHANGES.old in the source distribution or at GitHub.
22060
22062 This is an (incomplete) alphabetic list of projects that use Sphinx or
22063 are experimenting with using it for their documentation. If you like
22064 to be included, please mail to the Google group.
22065 I’ve grouped the list into sections to make it easier to find interest‐
22067 ing examples.
22068 Documentation using the alabaster theme
22070 · Alabaster
22071 · Blinker
22073 · Calibre
22075 · Click (customized)
22077 · coala (customized)
22079 · CodePy
22081 · Fabric
22083 · Fityk
22085 · Flask
22087 · Flask-OpenID
22089 · Invoke
22091 · Jinja
22093 · Lino (customized)
22095 · marbl
22097 · MDAnalysis (customized)
22099 · MeshPy
22101 · PyCUDA
22103 · PyOpenCL
22105 · PyLangAcq
22107 · pytest (customized)
22109 · python-apt
22111 · PyVisfile
22113 · Requests
22115 · searx
22117 · Spyder (customized)
22119 · Tablib
22121 · urllib3 (customized)
22123 · Werkzeug (customized)
22125 Documentation using the classic theme
22127 · Advanced Generic Widgets (customized)
22128 · Apache CouchDB (customized)
22130 · APSW
22132 · Arb
22134 · Bazaar (customized)
22136 · Beautiful Soup
22138 · Blender
22140 · Bugzilla
22142 · Buildbot
22144 · CMake (customized)
22146 · Chaco (customized)
22148 · Cormoran
22150 · DEAP (customized)
22152 · Director
22154 · EZ-Draw (customized)
22156 · F2py
22158 · Generic Mapping Tools (GMT) (customized)
22160 · Genomedata
22162 · GetFEM++ (customized)
22164 · Glasgow Haskell Compiler (customized)
22166 · Grok (customized)
22168 · GROMACS
22170 · GSL Shell
22172 · Hands-on Python Tutorial
22174 · Kaa (customized)
22176 · Leo
22178 · LEPL (customized)
22180 · Mayavi (customized)
22182 · MediaGoblin (customized)
22184 · mpmath
22186 · OpenCV (customized)
22188 · OpenEXR
22190 · OpenGDA
22192 · Peach^3 (customized)
22194 · Plone (customized)
22196 · PyEMD
22198 · Pyevolve
22200 · Pygame (customized)
22202 · PyMQI
22204 · PyQt4 (customized)
22206 · PyQt5 (customized)
22208 · Python 2
22210 · Python 3 (customized)
22212 · Python Packaging Authority (customized)
22214 · Ring programming language (customized)
22216 · SageMath (customized)
22218 · Segway
22220 · simuPOP (customized)
22222 · Sprox (customized)
22224 · SymPy
22226 · TurboGears (customized)
22228 · tvtk
22230 · Varnish (customized, alabaster for index)
22232 · Waf
22234 · wxPython Phoenix (customized)
22236 · z3c
22238 · zc.async (customized)
22240 · Zope (customized)
22242 Documentation using the sphinxdoc theme
22244 · cartopy
22245 · Jython
22247 · Matplotlib
22249 · MDAnalysis Tutorial
22251 · NetworkX
22253 · PyCantonese
22255 · Pyre
22257 · pySPACE
22259 · Pysparse
22261 · PyTango
22263 · Python Wild Magic (customized)
22265 · Reteisi (customized)
22267 · Sqlkit (customized)
22269 · Turbulenz
22271 Documentation using the nature theme
22273 · Alembic
22274 · Cython
22276 · easybuild
22278 · jsFiddle
22280 · libLAS (customized)
22282 · Lmod
22284 · MapServer (customized)
22286 · Pandas
22288 · pyglet (customized)
22290 · Setuptools
22292 · Spring Python
22294 · StatsModels (customized)
22296 · Sylli
22298 Documentation using another builtin theme
22300 · Breathe (haiku)
22301 · MPipe (sphinx13)
22303 · NLTK (agogo)
22305 · Programmieren mit PyGTK und Glade (German) (agogo, customized)
22307 · PyPubSub (bizstyle)
22309 · Pylons (pyramid)
22311 · Pyramid web framework (pyramid)
22313 · Sphinx (sphinx13) :-)
22315 · Valence (haiku, customized)
22317 Documentation using sphinx_rtd_theme
22319 · Annotator
22320 · Ansible (customized)
22322 · Arcade
22324 · aria2
22326 · ASE
22328 · Autofac
22330 · BigchainDB
22332 · Blocks
22334 · bootstrap-datepicker
22336 · Certbot
22338 · Chainer (customized)
22340 · CherryPy
22342 · CodeIgniter
22344 · Conda
22346 · Corda
22348 · Dask
22350 · Databricks (customized)
22352 · Dataiku DSS
22354 · edX
22356 · Electrum
22358 · Elemental
22360 · ESWP3
22362 · Ethereum Homestead
22364 · Fidimag
22366 · Flake8
22368 · GeoNode
22370 · Godot
22372 · Graylog
22374 · GPAW (customized)
22376 · HDF5 for Python (h5py)
22378 · Hyperledger Fabric
22380 · Hyperledger Sawtooth
22382 · IdentityServer
22384 · Idris
22386 · javasphinx
22388 · Julia
22390 · Jupyter Notebook
22392 · Lasagne
22394 · latexindent.pl
22396 · Linguistica
22398 · Linux kernel
22400 · MathJax
22402 · MDTraj (customized)
22404 · MICrobial Community Analysis (micca)
22406 · MicroPython
22408 · Minds (customized)
22410 · Mink
22412 · Mockery
22414 · mod_wsgi
22416 · MoinMoin
22418 · Mopidy
22420 · MyHDL
22422 · Nextflow
22424 · NICOS (customized)
22426 · Pelican
22428 · picamera
22430 · Pillow
22432 · pip
22434 · Paver
22436 · peewee
22438 · Phinx
22440 · phpMyAdmin
22442 · PROS (customized)
22444 · Pweave
22446 · PyPy
22448 · python-sqlparse
22450 · PyVISA
22452 · Read The Docs
22454 · Free your information from their silos (French) (customized)
22456 · Releases Sphinx extension
22458 · Qtile
22460 · Quex
22462 · Satchmo
22464 · Scapy
22466 · SimPy
22468 · SlamData
22470 · Solidity
22472 · Sonos Controller (SoCo)
22474 · Sphinx AutoAPI
22476 · sphinx-argparse
22478 · Sphinx-Gallery (customized)
22480 · SpotBugs
22482 · StarUML
22484 · Sublime Text Unofficial Documentation
22486 · SunPy
22488 · Sylius
22490 · Tango Controls (customized)
22492 · Topshelf
22494 · Theano
22496 · ThreatConnect
22498 · Tuleap
22500 · TYPO3 (customized)
22502 · uWSGI
22504 · Wagtail
22506 · Web Application Attack and Audit Framework (w3af)
22508 · Weblate
22510 · x265
22512 · ZeroNet
22514 Documentation using sphinx_bootstrap_theme
22516 · Bootstrap Theme
22517 · C/C++ Software Development with Eclipse
22519 · Dataverse
22521 · e-cidadania
22523 · Hangfire
22525 · Hedge
22527 · ObsPy
22529 · Open Dylan
22531 · Pootle
22533 · PyUblas
22535 · seaborn
22537 Documentation using a custom theme or integrated in a website
22539 · Apache Cassandra
22540 · Astropy
22542 · Bokeh
22544 · Boto 3
22546 · CakePHP
22548 · CasperJS
22550 · Ceph
22552 · Chef
22554 · CKAN
22556 · Confluent Platform
22558 · Django
22560 · Doctrine
22562 · Enterprise Toolkit for Acrobat products
22564 · Gameduino
22566 · gensim
22568 · GeoServer
22570 · gevent
22572 · GHC - Glasgow Haskell Compiler
22574 · Guzzle
22576 · H2O.ai
22578 · Istihza (Turkish Python documentation project)
22580 · Kombu
22582 · Lasso
22584 · Mako
22586 · MirrorBrain
22588 · MongoDB
22590 · Music21
22592 · MyHDL
22594 · nose
22596 · ns-3
22598 · NumPy
22600 · ObjectListView
22602 · OpenERP
22604 · OpenCV
22606 · OpenLayers
22608 · OpenTURNS
22610 · Open vSwitch
22612 · PlatformIO
22614 · PyEphem
22616 · Pygments
22618 · Plone User Manual (German)
22620 · PSI4
22622 · PyMOTW
22624 · python-aspectlib (sphinx_py3doc_enhanced_theme)
22626 · QGIS
22628 · qooxdoo
22630 · Roundup
22632 · SaltStack
22634 · scikit-learn
22636 · SciPy
22638 · Scrapy
22640 · Seaborn
22642 · Selenium
22644 · Self
22646 · Substance D
22648 · Sulu
22650 · SQLAlchemy
22652 · tinyTiM
22654 · Twisted
22656 · Ubuntu Packaging Guide
22658 · WebFaction
22660 · WTForms
22662 Homepages and other non-documentation sites
22664 · Arizona State University PHY494/PHY598/CHM598 Simulation approaches
22665 to Bio-and Nanophysics (classic)
22666 · Benoit Boissinot (classic, customized)
22668 · Computer Networks, Parallelization, and Simulation Laboratory
22670 (CNPSLab) (sphinx_rtd_theme)
22671 · Deep Learning Tutorials (sphinxdoc)
22673 · Loyola University Chicago COMP 339-439 Distributed Systems course
22675 (sphinx_bootstrap_theme)
22676 · Pylearn2 (sphinxdoc, customized)
22678 · PyXLL (sphinx_bootstrap_theme, customized)
22680 · SciPy Cookbook (sphinx_rtd_theme)
22682 · The Wine Cellar Book (sphinxdoc)
22684 · Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
22686 (standard)
22687 · UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
22689 Books produced using Sphinx
22691 · “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
22692 · “Expert Python Programming”
22694 · “Expert Python Programming” (Japanese translation)
22696 · “The Hitchhiker’s Guide to Python”
22698 · “LassoGuide”
22700 · “Learning Sphinx” (in Japanese)
22702 · “Mercurial: the definitive guide (Second edition)”
22704 · “Pioneers and Prominent Men of Utah”
22706 · “Pomodoro Technique Illustrated” (Japanese translation)
22708 · “Python Professional Programming” (in Japanese)
22710 · “Redmine Primer 5th Edition (in Japanese)”
22712 · “The repoze.bfg Web Application Framework”
22714 · “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
22716 panese)
22717 · “Software-Dokumentation mit Sphinx”
22719 · “Theoretical Physics Reference”
22721 · “The Varnish Book”
22723 Theses produced using Sphinx
22725 · “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
22726 the Use of CouchDB”
22727 · “Content Conditioning and Distribution for Dynamic Virtual Worlds”
22729 · “The Sphinx Thesis Resource”
22731 Projects integrating Sphinx functionality
22733 · Read the Docs, a software-as-a-service documentation hosting plat‐
22734 form, uses Sphinx to automatically build documentation updates that
22735 are pushed to GitHub
22736 · Spyder, the Scientific Python Development Environment, uses Sphinx in
22738 its help pane to render rich documentation for functions, classes and
22739 methods automatically or on-demand
22740
22742 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
22743 Substantial parts of the templates were written by Armin Ronacher <‐
22745 armin.ronacher@active-4.com>.
22746 Other co-maintainers:
22748 · Takayuki Shimizukawa <shimizukawa@gmail.com>
22750 · Daniel Neuhäuser <@DasIch>
22752 · Jon Waltman <@jonwaltman>
22754 · Rob Ruana <@RobRuana>
22756 · Robert Lehmann <@lehmannro>
22758 · Roland Meister <@rolmei>
22760 · Takeshi Komiya <@tk0miya>
22762 · Jean-François Burnol <@jfbu>
22764 · Yoshiki Shibukawa <@shibu_jp>
22766 · Timotheus Kampik - <@TimKam>
22768 Other contributors, listed alphabetically, are:
22770 · Alastair Houghton – Apple Help builder
22772 · Alexander Todorov – inheritance_diagram tests and improvements
22774 · Andi Albrecht – agogo theme
22776 · Jakob Lykke Andersen – Rewritten C++ domain
22778 · Henrique Bastos – SVG support for graphviz extension
22780 · Daniel Bültmann – todo extension
22782 · Marco Buttu – doctest extension (pyversion option)
22784 · Etienne Desautels – apidoc module
22786 · Michael Droettboom – inheritance_diagram extension
22788 · Charles Duffy – original graphviz extension
22790 · Kevin Dunn – MathJax extension
22792 · Josip Dzolonga – coverage builder
22794 · Buck Evan – dummy builder
22796 · Matthew Fernandez – todo extension fix
22798 · Hernan Grecco – search improvements
22800 · Horst Gutmann – internationalization support
22802 · Martin Hans – autodoc improvements
22804 · Zac Hatfield-Dodds – doctest reporting improvements
22806 · Doug Hellmann – graphviz improvements
22808 · Tim Hoffmann – theme improvements
22810 · Dave Kuhlman – original LaTeX writer
22812 · Blaise Laflamme – pyramid theme
22814 · Chris Lamb – reproducibility fixes
22816 · Thomas Lamb – linkcheck builder
22818 · Łukasz Langa – partial support for autodoc
22820 · Martin Larralde – additional napoleon admonitions
22822 · Ian Lee – quickstart improvements
22824 · Robert Lehmann – gettext builder (GSOC project)
22826 · Dan MacKinlay – metadata fixes
22828 · Martin Mahner – nature theme
22830 · Will Maier – directory HTML builder
22832 · Jacob Mason – websupport library (GSOC project)
22834 · Glenn Matthews – python domain signature improvements
22836 · Kurt McKee – documentation updates
22838 · Roland Meister – epub builder
22840 · Ezio Melotti – collapsible sidebar JavaScript
22842 · Bruce Mitchener – Minor epub improvement
22844 · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
22846 · Christopher Perkins – autosummary integration
22848 · Benjamin Peterson – unittests
22850 · T. Powers – HTML output improvements
22852 · Jeppe Pihl – literalinclude improvements
22854 · Rob Ruana – napoleon extension
22856 · Stefan Seefeld – toctree improvements
22858 · Gregory Szorc – performance improvements
22860 · Taku Shimizu – epub3 builder
22862 · Antonio Valentino – qthelp builder, docstring inheritance
22864 · Filip Vavera – napoleon todo directive
22866 · Pauli Virtanen – autodoc improvements, autosummary extension
22868 · Stefan van der Walt – autosummary extension
22870 · Thomas Waldmann – apidoc module fixes
22872 · John Waltman – Texinfo builder
22874 · Barry Warsaw – setup command improvements
22876 · Sebastian Wiesner – image handling, distutils support
22878 · Michael Wilson – Intersphinx HTTP basic auth support
22880 · Matthew Woodcraft – text output improvements
22882 · Joel Wurtz – cellspanning support in LaTeX
22884 · Hong Xu – svg support in imgmath extension and various bug fixes
22886 · Stephen Finucane – setup command improvements and documentation
22888 · Daniel Pizetta – inheritance diagram improvements
22890 Many thanks for all contributions!
22892 There are also a few modules or functions incorporated from other
22894 authors and projects:
22895 · sphinx.util.jsdump uses the basestring encoding from simplejson,
22897 written by Bob Ippolito, released under the MIT license
22898 · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
22900 Domain
22901 · modindex
22903 · glossary
22905
22907 Georg Brandl
22908
22910 2007-2019, Georg Brandl and the Sphinx team
229111.8.4 Feb 13, 2019 SPHINX-ALL(1)