1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 This is the documentation for the Sphinx documentation builder. Sphinx
10 is a tool that translates a set of reStructuredText source files into
11 various output formats, automatically producing cross-references,
12 indices, etc. That is, if you have a directory containing a bunch of
13 reST-formatted documents (and possibly subdirectories of docs in there
14 as well), Sphinx can generate a nicely-organized arrangement of HTML
15 files (in some other directory) for easy browsing and navigation. But
16 from the same source, it can also generate a PDF file using LaTeX.
17 The focus is on hand-written documentation, rather than auto-generated
19 API docs. Though there is support for that kind of documentation as
20 well (which is intended to be freely mixed with hand-written content),
21 if you need pure API docs have a look at Epydoc, which also understands
22 reST.
23 For a great “introduction” to writing docs in general – the whys and
25 hows, see also Write the docs, written by Eric Holscher.
26 Conversion from other systems
28 This section is intended to collect helpful hints for those wanting to
29 migrate to reStructuredText/Sphinx from other documentation systems.
30 · Gerard Flanagan has written a script to convert pure HTML to reST; it
32 can be found at the Python Package Index.
33 · For converting the old Python docs to Sphinx, a converter was written
35 which can be found at the Python SVN repository. It contains generic
36 code to convert Python-doc-style LaTeX markup to Sphinx reST.
37 · Marcin Wojdyr has written a script to convert Docbook to reST with
39 Sphinx markup; it is at GitHub.
40 · Christophe de Vienne wrote a tool to convert from Open/LibreOffice
42 documents to Sphinx: odt2sphinx.
43 · To convert different markups, Pandoc is a very helpful tool.
45 Use with other systems
47 See the pertinent section in the FAQ list.
48 Prerequisites
50 Sphinx needs at least Python 3.5 to run, as well as the docutils and
51 Jinja2 libraries. Sphinx should work with docutils version 0.12 or some
52 (not broken) SVN trunk snapshot.
53 Usage
55 See /usage/quickstart for an introduction. It also contains links to
56 more advanced sections in this manual for the topics it discusses.
57
59 · Overview
60 · Linux
62 · macOS
64 · Windows
66 · Installation from PyPI
68 · Installation from source
70 Overview
72 Sphinx is written in Python and supports Python 3.5+.
73 Linux
75 Debian/Ubuntu
76 Install either python3-sphinx (Python 3) or python-sphinx (Python 2)
77 using apt-get:
78 $ apt-get install python3-sphinx
80 If it not already present, this will install Python for you.
82 RHEL, CentOS
84 Install python-sphinx using yum:
85 $ yum install python-sphinx
87 If it not already present, this will install Python for you.
89 Other distributions
91 Most Linux distributions have Sphinx in their package repositories.
92 Usually the package is called python3-sphinx, python-sphinx or sphinx.
93 Be aware that there are at least two other packages with sphinx in
94 their name: a speech recognition toolkit (CMU Sphinx) and a full-text
95 search database (Sphinx search).
96 macOS
98 Sphinx can be installed using Homebrew, MacPorts, or as part of a
99 Python distribution such as Anaconda.
100 Homebrew
102 $ brew install sphinx-doc
103 For more information, refer to the package overview.
105 MacPorts
107 Install either python36-sphinx (Python 3) or python27-sphinx (Python 2)
108 using port:
109 $ sudo port install py36-sphinx
111 To set up the executable paths, use the port select command:
113 $ sudo port select --set python python36
115 $ sudo port select --set sphinx py36-sphinx
116 For more information, refer to the package overview.
118 Anaconda
120 $ conda install sphinx
121 Windows
123 Todo
124 Could we start packaging this?
125 Most Windows users do not have Python installed by default, so we begin
127 with the installation of Python itself. If you are unsure, open the
128 Command Prompt (⊞Win-r and type cmd). Once the command prompt is open,
129 type python --version and press Enter. If Python is available, you
130 will see the version of Python printed to the screen. If you do not
131 have Python installed, refer to the Hitchhikers Guide to Python’s
132 Python on Windows installation guides. You must install Python 3.
133 Once Python is installed, you can install Sphinx using pip. Refer to
135 the pip installation instructions below for more information.
136 Installation from PyPI
138 Sphinx packages are published on the Python Package Index. The pre‐
139 ferred tool for installing packages from PyPI is pip. This tool is
140 provided with all modern versions of Python.
141 On Linux or MacOS, you should open your terminal and run the following
143 command.
144 $ pip install -U sphinx
146 On Windows, you should open Command Prompt (⊞Win-r and type cmd) and
148 run the same command.
149 C:\> pip install -U sphinx
151 After installation, type sphinx-build --version on the command prompt.
153 If everything worked fine, you will see the version number for the
154 Sphinx package you just installed.
155 Installation from PyPI also allows you to install the latest develop‐
157 ment release. You will not generally need (or want) to do this, but it
158 can be useful if you see a possible bug in the latest stable release.
159 To do this, use the --pre flag.
160 $ pip install -U --pre sphinx
162 Installation from source
164 You can install Sphinx directly from a clone of the Git repository.
165 This can be done either by cloning the repo and installing from the
166 local clone, on simply installing directly via git.
167 $ git clone https://github.com/sphinx-doc/sphinx
169 $ cd sphinx
170 $ pip install .
171 $ pip install git+https://github.com/sphinx-doc/sphinx
173 You can also download a snapshot of the Git repo in either tar.gz or
175 zip format. Once downloaded and extracted, these can be installed with
176 pip as above.
177
179 Once Sphinx is installed, you can proceed with setting up your first
180 Sphinx project. To ease the process of getting started, Sphinx provides
181 a tool, sphinx-quickstart, which will generate a documentation source
182 directory and populate it with some defaults. We’re going to use the
183 sphinx-quickstart tool here, though it’s use by no means necessary.
184 Setting up the documentation sources
186 The root directory of a Sphinx collection of reStructuredText document
187 sources is called the source directory. This directory also contains
188 the Sphinx configuration file conf.py, where you can configure all
189 aspects of how Sphinx reads your sources and builds your documentation.
190 [1]
191 Sphinx comes with a script called sphinx-quickstart that sets up a
193 source directory and creates a default conf.py with the most useful
194 configuration values from a few questions it asks you. To use this,
195 run:
196 $ sphinx-quickstart
198 Answer each question asked. Be sure to say yes to the autodoc exten‐
200 sion, as we will use this later.
201 There is also an automatic “API documentation” generator called
203 sphinx-apidoc; see /man/sphinx-apidoc for details.
204 Defining document structure
206 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
207 tory with conf.py and a master document, index.rst (if you accepted the
208 defaults). The main function of the master document is to serve as a
209 welcome page, and to contain the root of the “table of contents tree”
210 (or toctree). This is one of the main things that Sphinx adds to
211 reStructuredText, a way to connect multiple files to a single hierarchy
212 of documents.
213 reStructuredText directives
215 toctree is a reStructuredText directive, a very versatile piece of
216 markup. Directives can have arguments, options and content.
217 Arguments are given directly after the double colon following the
219 directive’s name. Each directive decides whether it can have argu‐
220 ments, and how many.
221 Options are given after the arguments, in form of a “field list”. The
223 maxdepth is such an option for the toctree directive.
224 Content follows the options or arguments after a blank line. Each
226 directive decides whether to allow content, and what to do with it.
227 A common gotcha with directives is that the first line of the content
229 must be indented to the same level as the options are.
230 The toctree directive initially is empty, and looks like so:
232 .. toctree::
234 :maxdepth: 2
235 You add documents listing them in the content of the directive:
237 .. toctree::
239 :maxdepth: 2
240 usage/installation
242 usage/quickstart
243 ...
244 This is exactly how the toctree for this documentation looks. The doc‐
246 uments to include are given as document names, which in short means
247 that you leave off the file name extension and use forward slashes (/)
248 as directory separators.
249 [image: more info] [image]
251 Read more about the toctree directive.
252 You can now create the files you listed in the toctree and add content,
254 and their section titles will be inserted (up to the maxdepth level) at
255 the place where the toctree directive is placed. Also, Sphinx now
256 knows about the order and hierarchy of your documents. (They may con‐
257 tain toctree directives themselves, which means you can create deeply
258 nested hierarchies if necessary.)
259 Adding content
261 In Sphinx source files, you can use most features of standard reStruc‐
262 turedText. There are also several features added by Sphinx. For exam‐
263 ple, you can add cross-file references in a portable way (which works
264 for all output types) using the ref role.
265 For an example, if you are viewing the HTML version you can look at the
267 source for this document – use the “Show Source” link in the sidebar.
268 Todo
270 Update the below link when we add new guides on these.
271 [image: more info] [image]
273 See /usage/restructuredtext/index for a more in-depth introduction to
274 reStructuredText, including markup added by Sphinx.
275 Running the build
277 Now that you have added some files and content, let’s make a first
278 build of the docs. A build is started with the sphinx-build program:
279 $ sphinx-build -b html sourcedir builddir
281 where sourcedir is the source directory, and builddir is the directory
283 in which you want to place the built documentation. The -b option
284 selects a builder; in this example Sphinx will build HTML files.
285 [image: more info] [image]
287 Refer to the sphinx-build man page for all options that sphinx-build
288 supports.
289 However, sphinx-quickstart script creates a Makefile and a make.bat
291 which make life even easier for you. These can be executed by running
292 make with the name of the builder. For example.
293 $ make html
295 This will build HTML docs in the build directory you chose. Execute
297 make without an argument to see which targets are available.
298 How do I generate PDF documents?
300 make latexpdf runs the LaTeX builder and readily invokes the
302 pdfTeX toolchain for you.
303 Todo
305 Move this whole section into a guide on rST or directives
306 Documenting objects
308 One of Sphinx’s main objectives is easy documentation of objects (in a
309 very general sense) in any domain. A domain is a collection of object
310 types that belong together, complete with markup to create and refer‐
311 ence descriptions of these objects.
312 The most prominent domain is the Python domain. For example, to docu‐
314 ment Python’s built-in function enumerate(), you would add this to one
315 of your source files.
316 .. py:function:: enumerate(sequence[, start=0])
318 Return an iterator that yields tuples of an index and an item of the
320 *sequence*. (And so on.)
321 This is rendered like this:
323 enumerate(sequence[, start=0])
325 Return an iterator that yields tuples of an index and an item of
326 the sequence. (And so on.)
327 The argument of the directive is the signature of the object you
329 describe, the content is the documentation for it. Multiple signatures
330 can be given, each in its own line.
331 The Python domain also happens to be the default domain, so you don’t
333 need to prefix the markup with the domain name.
334 .. function:: enumerate(sequence[, start=0])
336 ...
338 does the same job if you keep the default setting for the default
340 domain.
341 There are several more directives for documenting other types of Python
343 objects, for example py:class or py:method. There is also a cross-ref‐
344 erencing role for each of these object types. This markup will create
345 a link to the documentation of enumerate().
346 The :py:func:`enumerate` function can be used for ...
348 And here is the proof: A link to enumerate().
350 Again, the py: can be left out if the Python domain is the default one.
352 It doesn’t matter which file contains the actual documentation for enu‐
353 merate(); Sphinx will find it and create a link to it.
354 Each domain will have special rules for how the signatures can look
356 like, and make the formatted output look pretty, or add specific fea‐
357 tures like links to parameter types, e.g. in the C/C++ domains.
358 [image: more info] [image]
360 See /usage/restructuredtext/domains for all the available domains and
361 their directives/roles.
362 Basic configuration
364 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
365 cesses your documents. In that file, which is executed as a Python
366 source file, you assign configuration values. For advanced users:
367 since it is executed by Sphinx, you can do non-trivial tasks in it,
368 like extending sys.path or importing a module to find out the version
369 you are documenting.
370 The config values that you probably want to change are already put into
372 the conf.py by sphinx-quickstart and initially commented out (with
373 standard Python syntax: a # comments the rest of the line). To change
374 the default value, remove the hash sign and modify the value. To cus‐
375 tomize a config value that is not automatically added by sphinx-quick‐
376 start, just add an additional assignment.
377 Keep in mind that the file uses Python syntax for strings, numbers,
379 lists and so on. The file is saved in UTF-8 by default, as indicated
380 by the encoding declaration in the first line. If you use non-ASCII
381 characters in any string value, you need to use Python Unicode strings
382 (like project = u'Exposé').
383 [image: more info] [image]
385 See /usage/configuration for documentation of all available config
386 values.
387 Todo
389 Move this entire doc to a different section
390 Autodoc
392 When documenting Python code, it is common to put a lot of documenta‐
393 tion in the source files, in documentation strings. Sphinx supports
394 the inclusion of docstrings from your modules with an extension (an
395 extension is a Python module that provides additional features for
396 Sphinx projects) called autodoc.
397 In order to use autodoc, you need to activate it in conf.py by putting
399 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
400 sions config value. Then, you have a few additional directives at your
401 disposal.
402 For example, to document the function io.open(), reading its signature
404 and docstring from the source file, you’d write this:
405 .. autofunction:: io.open
407 You can also document whole classes or even modules automatically,
409 using member options for the auto directives, like
410 .. automodule:: io
412 :members:
413 autodoc needs to import your modules in order to extract the doc‐
415 strings. Therefore, you must add the appropriate path to sys.path in
416 your conf.py.
417 WARNING:
419 autodoc imports the modules to be documented. If any modules have
420 side effects on import, these will be executed by autodoc when
421 sphinx-build is run.
422 If you document scripts (as opposed to library modules), make sure
424 their main routine is protected by a if __name__ == '__main__' con‐
425 dition.
426 [image: more info] [image]
428 See sphinx.ext.autodoc for the complete description of the features of
429 autodoc.
430 Todo
432 Move this doc to another section
433 Intersphinx
435 Many Sphinx documents including the Python documentation are published
436 on the Internet. When you want to make links to such documents from
437 your documentation, you can do it with sphinx.ext.intersphinx.
438 In order to use intersphinx, you need to activate it in conf.py by
440 putting the string 'sphinx.ext.intersphinx' into the extensions list
441 and set up the intersphinx_mapping config value.
442 For example, to link to io.open() in the Python library manual, you
444 need to setup your intersphinx_mapping like:
445 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
447 And now, you can write a cross-reference like :py:func:`io.open`. Any
449 cross-reference that has no matching target in the current documenta‐
450 tion set, will be looked up in the documentation sets configured in
451 intersphinx_mapping (this needs access to the URL in order to download
452 the list of valid targets). Intersphinx also works for some other
453 domain’s roles including :ref:, however it doesn’t work for :doc: as
454 that is non-domain role.
455 [image: more info] [image]
457 See sphinx.ext.intersphinx for the complete description of the fea‐
458 tures of intersphinx.
459 More topics to be covered
461 · Other extensions:
462 · Static files
464 · Selecting a theme
466 · /usage/advanced/setuptools
468 · Templating
470 · Using extensions
472 · Writing extensions
474
476 [1] This is the usual layout. However, conf.py can also live in
477 another directory, the configuration directory. Refer to the
478 sphinx-build man page for more information.
479
481 reStructuredText (reST) is the default plaintext markup language used
482 by both Docutils and Sphinx. Docutils provides the basic reStructured‐
483 Text syntax, while Sphinx extends this to support additional function‐
484 ality.
485 The below guides go through the most important aspects of reST. For the
487 authoritative reStructuredText reference, refer to the docutils docu‐
488 mentation.
489 reStructuredText Primer
491 reStructuredText is the default plaintext markup language used by
492 Sphinx. This section is a brief introduction to reStructuredText
493 (reST) concepts and syntax, intended to provide authors with enough
494 information to author documents productively. Since reST was designed
495 to be a simple, unobtrusive markup language, this will not take too
496 long.
497 SEE ALSO:
499 The authoritative reStructuredText User Documentation. The “ref”
500 links in this document link to the description of the individual
501 constructs in the reST reference.
502 Paragraphs
504 The paragraph (ref) is the most basic block in a reST document. Para‐
505 graphs are simply chunks of text separated by one or more blank lines.
506 As in Python, indentation is significant in reST, so all lines of the
507 same paragraph must be left-aligned to the same level of indentation.
508 Inline markup
510 The standard reST inline markup is quite simple: use
511 · one asterisk: *text* for emphasis (italics),
513 · two asterisks: **text** for strong emphasis (boldface), and
515 · backquotes: ``text`` for code samples.
517 If asterisks or backquotes appear in running text and could be confused
519 with inline markup delimiters, they have to be escaped with a back‐
520 slash.
521 Be aware of some restrictions of this markup:
523 · it may not be nested,
525 · content may not start or end with whitespace: * text* is wrong,
527 · it must be separated from surrounding text by non-word characters.
529 Use a backslash escaped space to work around that: thisis\ *one*\
530 word.
531 These restrictions may be lifted in future versions of the docutils.
533 It is also possible to replace or expand upon some of this inline
535 markup with roles. Refer to Roles for more information.
536 Lists and Quote-like blocks
538 List markup (ref) is natural: just place an asterisk at the start of a
539 paragraph and indent properly. The same goes for numbered lists; they
540 can also be autonumbered using a # sign:
541 * This is a bulleted list.
543 * It has two items, the second
544 item uses two lines.
545 1. This is a numbered list.
547 2. It has two items too.
548 #. This is a numbered list.
550 #. It has two items too.
551 Nested lists are possible, but be aware that they must be separated
553 from the parent list items by blank lines:
554 * this is
556 * a list
557 * with a nested list
559 * and some subitems
560 * and here the parent list continues
562 Definition lists (ref) are created as follows:
564 term (up to a line of text)
566 Definition of the term, which must be indented
567 and can even consist of multiple paragraphs
569 next term
571 Description.
572 Note that the term cannot have more than one line of text.
574 Quoted paragraphs (ref) are created by just indenting them more than
576 the surrounding paragraphs.
577 Line blocks (ref) are a way of preserving line breaks:
579 | These lines are
581 | broken exactly like in
582 | the source file.
583 There are also several more special blocks available:
585 · field lists (ref, with caveats noted in Field Lists)
587 · option lists (ref)
589 · quoted literal blocks (ref)
591 · doctest blocks (ref)
593 Literal blocks
595 Literal code blocks (ref) are introduced by ending a paragraph with the
596 special marker ::. The literal block must be indented (and, like all
597 paragraphs, separated from the surrounding ones by blank lines):
598 This is a normal text paragraph. The next paragraph is a code sample::
600 It is not processed in any way, except
602 that the indentation is removed.
603 It can span multiple lines.
605 This is a normal text paragraph again.
607 The handling of the :: marker is smart:
609 · If it occurs as a paragraph of its own, that paragraph is completely
611 left out of the document.
612 · If it is preceded by whitespace, the marker is removed.
614 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
616 gle colon.
617 That way, the second sentence in the above example’s first paragraph
619 would be rendered as “The next paragraph is a code sample:”.
620 Code highlighting can be enabled for these literal blocks on a docu‐
622 ment-wide basis using the highlight directive and on a project-wide
623 basis using the highlight_language configuration option. The code-block
624 directive can be used to set highlighting on a block-by-block basis.
625 These directives are discussed later.
626 Doctest blocks
628 Doctest blocks (ref) are interactive Python sessions cut-and-pasted
629 into docstrings. They do not require the literal blocks syntax. The
630 doctest block must end with a blank line and should not end with with
631 an unused prompt:
632 >>> 1 + 1
634 2
635 Tables
637 For grid tables (ref), you have to “paint” the cell grid yourself.
638 They look like this:
639 +------------------------+------------+----------+----------+
641 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
642 | (header rows optional) | | | |
643 +========================+============+==========+==========+
644 | body row 1, column 1 | column 2 | column 3 | column 4 |
645 +------------------------+------------+----------+----------+
646 | body row 2 | ... | ... | |
647 +------------------------+------------+----------+----------+
648 Simple tables (ref) are easier to write, but limited: they must contain
650 more than one row, and the first column cells cannot contain multiple
651 lines. They look like this:
652 ===== ===== =======
654 A B A and B
655 ===== ===== =======
656 False False False
657 True False False
658 False True False
659 True True True
660 ===== ===== =======
661 Two more syntaxes are supported: CSV tables and List tables. They use
663 an explicit markup block. Refer to table-directives for more informa‐
664 tion.
665 Hyperlinks
667 External links
668 Use `Link text <https://domain.invalid/>`_ for inline web links. If
669 the link text should be the web address, you don’t need special markup
670 at all, the parser finds links and mail addresses in ordinary text.
671 IMPORTANT:
673 There must be a space between the link text and the opening < for
674 the URL.
675 You can also separate the link and the target definition (ref), like
677 this:
678 This is a paragraph that contains `a link`_.
680 .. _a link: https://domain.invalid/
682 Internal links
684 Internal linking is done via a special reST role provided by Sphinx,
685 see the section on specific markup, ref-role.
686 Sections
688 Section headers (ref) are created by underlining (and optionally over‐
689 lining) the section title with a punctuation character, at least as
690 long as the text:
691 =================
693 This is a heading
694 =================
695 Normally, there are no heading levels assigned to certain characters as
697 the structure is determined from the succession of headings. However,
698 this convention is used in Python’s Style Guide for documenting which
699 you may follow:
700 · # with overline, for parts
702 · * with overline, for chapters
704 · =, for sections
706 · -, for subsections
708 · ^, for subsubsections
710 · ", for paragraphs
712 Of course, you are free to use your own marker characters (see the reST
714 documentation), and use a deeper nesting level, but keep in mind that
715 most target formats (HTML, LaTeX) have a limited supported nesting
716 depth.
717 Field Lists
719 Field lists (ref) are sequences of fields marked up like this:
720 :fieldname: Field content
722 They are commonly used in Python documentation:
724 def my_function(my_arg, my_other_arg):
726 """A function just for me.
727 :param my_arg: The first of my arguments.
729 :param my_other_arg: The second of my arguments.
730 :returns: A message (just for me, of course).
732 """
733 Sphinx extends standard docutils behavior and intercepts field lists
735 specified at the beginning of documents. Refer to field-lists for more
736 information.
737 Roles
739 A role or “custom interpreted text role” (ref) is an inline piece of
740 explicit markup. It signifies that that the enclosed text should be
741 interpreted in a specific way. Sphinx uses this to provide semantic
742 markup and cross-referencing of identifiers, as described in the appro‐
743 priate section. The general syntax is :rolename:`content`.
744 Docutils supports the following roles:
746 · emphasis – equivalent of *emphasis*
748 · strong – equivalent of **strong**
750 · literal – equivalent of ``literal``
752 · subscript – subscript text
754 · superscript – superscript text
756 · title-reference – for titles of books, periodicals, and other materi‐
758 als
759 Refer to roles for roles added by Sphinx.
761 Explicit Markup
763 “Explicit markup” (ref) is used in reST for most constructs that need
764 special handling, such as footnotes, specially-highlighted paragraphs,
765 comments, and generic directives.
766 An explicit markup block begins with a line starting with .. followed
768 by whitespace and is terminated by the next paragraph at the same level
769 of indentation. (There needs to be a blank line between explicit
770 markup and normal paragraphs. This may all sound a bit complicated,
771 but it is intuitive enough when you write it.)
772 Directives
774 A directive (ref) is a generic block of explicit markup. Along with
775 roles, it is one of the extension mechanisms of reST, and Sphinx makes
776 heavy use of it.
777 Docutils supports the following directives:
779 · Admonitions: attention, caution, danger, error, hint, important,
781 note, tip, warning and the generic admonition. (Most themes style
782 only “note” and “warning” specially.)
783 · Images:
785 · image (see also Images below)
787 · figure (an image with caption and optional legend)
789 · Additional body elements:
791 · contents (a local, i.e. for the current file only, table of con‐
793 tents)
794 · container (a container with a custom class, useful to generate an
796 outer <div> in HTML)
797 · rubric (a heading without relation to the document sectioning)
799 · topic, sidebar (special highlighted body elements)
801 · parsed-literal (literal block that supports inline markup)
803 · epigraph (a block quote with optional attribution line)
805 · highlights, pull-quote (block quotes with their own class
807 attribute)
808 · compound (a compound paragraph)
810 · Special tables:
812 · table (a table with title)
814 · csv-table (a table generated from comma-separated values)
816 · list-table (a table generated from a list of lists)
818 · Special directives:
820 · raw (include raw target-format markup)
822 · include (include reStructuredText from another file) – in Sphinx,
824 when given an absolute include file path, this directive takes it
825 as relative to the source directory
826 · class (assign a class attribute to the next element) [1]
828 · HTML specifics:
830 · meta (generation of HTML <meta> tags)
832 · title (override document title)
834 · Influencing markup:
836 · default-role (set a new default role)
838 · role (create a new role)
840 Since these are only per-file, better use Sphinx’s facilities for
842 setting the default_role.
843 WARNING:
845 Do not use the directives sectnum, header and footer.
846 Directives added by Sphinx are described in directives.
848 Basically, a directive consists of a name, arguments, options and con‐
850 tent. (Keep this terminology in mind, it is used in the next chapter
851 describing custom directives.) Looking at this example,
852 .. function:: foo(x)
854 foo(y, z)
855 :module: some.module.name
856 Return a line of text input from the user.
858 function is the directive name. It is given two arguments here, the
860 remainder of the first line and the second line, as well as one option
861 module (as you can see, options are given in the lines immediately fol‐
862 lowing the arguments and indicated by the colons). Options must be
863 indented to the same level as the directive content.
864 The directive content follows after a blank line and is indented rela‐
866 tive to the directive start.
867 Images
869 reST supports an image directive (ref), used like so:
870 .. image:: gnu.png
872 (options)
873 When used within Sphinx, the file name given (here gnu.png) must either
875 be relative to the source file, or absolute which means that they are
876 relative to the top source directory. For example, the file
877 sketch/spam.rst could refer to the image images/spam.png as
878 ../images/spam.png or /images/spam.png.
879 Sphinx will automatically copy image files over to a subdirectory of
881 the output directory on building (e.g. the _static directory for HTML
882 output.)
883 Interpretation of image size options (width and height) is as follows:
885 if the size has no unit or the unit is pixels, the given size will only
886 be respected for output channels that support pixels. Other units (like
887 pt for points) will be used for HTML and LaTeX output (the latter
888 replaces pt by bp as this is the TeX unit such that 72bp=1in).
889 Sphinx extends the standard docutils behavior by allowing an asterisk
891 for the extension:
892 .. image:: gnu.*
894 Sphinx then searches for all images matching the provided pattern and
896 determines their type. Each builder then chooses the best image out of
897 these candidates. For instance, if the file name gnu.* was given and
898 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
899 builder would choose the former, while the HTML builder would prefer
900 the latter. Supported image types and choosing priority are defined at
901 /usage/builders/index.
902 Note that image file names should not contain spaces.
904 Changed in version 0.4: Added the support for file names ending in an
906 asterisk.
907 Changed in version 0.6: Image paths can now be absolute.
910 Changed in version 1.5: latex target supports pixels (default is
913 96px=1in).
914 Footnotes
917 For footnotes (ref), use [#name]_ to mark the footnote location, and
918 add the footnote body at the bottom of the document after a “Footnotes”
919 rubric heading, like so:
920 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
922 .. rubric:: Footnotes
924 .. [#f1] Text of the first footnote.
926 .. [#f2] Text of the second footnote.
927 You can also explicitly number the footnotes ([1]_) or use auto-num‐
929 bered footnotes without names ([#]_).
930 Citations
932 Standard reST citations (ref) are supported, with the additional fea‐
933 ture that they are “global”, i.e. all citations can be referenced from
934 all files. Use them like so:
935 Lorem ipsum [Ref]_ dolor sit amet.
937 .. [Ref] Book or article reference, URL or whatever.
939 Citation usage is similar to footnote usage, but with a label that is
941 not numeric or begins with #.
942 Substitutions
944 reST supports “substitutions” (ref), which are pieces of text and/or
945 markup referred to in the text by |name|. They are defined like foot‐
946 notes with explicit markup blocks, like this:
947 .. |name| replace:: replacement *text*
949 or this:
951 .. |caution| image:: warning.png
953 :alt: Warning!
954 See the reST reference for substitutions for details.
956 If you want to use some substitutions for all documents, put them into
958 rst_prolog or rst_epilog or put them into a separate file and include
959 it into all documents you want to use them in, using the include direc‐
960 tive. (Be sure to give the include file a file name extension differ‐
961 ing from that of other source files, to avoid Sphinx finding it as a
962 standalone document.)
963 Sphinx defines some default substitutions, see default-substitutions.
965 Comments
967 Every explicit markup block which isn’t a valid markup construct (like
968 the footnotes above) is regarded as a comment (ref). For example:
969 .. This is a comment.
971 You can indent text after a comment start to form multiline comments:
973 ..
975 This whole indented block
976 is a comment.
977 Still in the comment.
979 Source encoding
981 Since the easiest way to include special characters like em dashes or
982 copyright signs in reST is to directly write them as Unicode charac‐
983 ters, one has to specify an encoding. Sphinx assumes source files to
984 be encoded in UTF-8 by default; you can change this with the
985 source_encoding config value.
986 Gotchas
988 There are some problems one commonly runs into while authoring reST
989 documents:
990 · Separation of inline markup: As said above, inline markup spans must
992 be separated from the surrounding text by non-word characters, you
993 have to use a backslash-escaped space to get around that. See the
994 reference for the details.
995 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
997 sible.
998
1000 [1] When the default domain contains a class directive, this directive
1001 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1002 Roles
1004 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1005 ments. They are written as :rolename:`content`.
1006 NOTE:
1008 The default role (`content`) has no special meaning by default. You
1009 are free to use it for anything you like, e.g. variable names; use
1010 the default_role config value to set it to a known role – the any
1011 role to find anything or the py:obj role to find Python objects are
1012 very useful for this.
1013 See /usage/restructuredtext/domains for roles added by domains.
1015 Cross-referencing syntax
1017 Cross-references are generated by many semantic interpreted text roles.
1018 Basically, you only need to write :role:`target`, and a link will be
1019 created to the item named target of the type indicated by role. The
1020 link’s text will be the same as target.
1021 There are some additional facilities, however, that make cross-refer‐
1023 encing roles more versatile:
1024 · You may supply an explicit title and reference target, like in reST
1026 direct hyperlinks: :role:`title <target>` will refer to target, but
1027 the link text will be title.
1028 · If you prefix the content with !, no reference/hyperlink will be cre‐
1030 ated.
1031 · If you prefix the content with ~, the link text will only be the last
1033 component of the target. For example, :py:meth:`~Queue.Queue.get`
1034 will refer to Queue.Queue.get but only display get as the link text.
1035 This does not work with all cross-reference roles, but is domain spe‐
1036 cific.
1037 In HTML output, the link’s title attribute (that is e.g. shown as a
1039 tool-tip on mouse-hover) will always be the full target name.
1040 Cross-referencing anything
1042 :any: New in version 1.3.
1043 This convenience role tries to do its best to find a valid tar‐
1046 get for its reference text.
1047 · First, it tries standard cross-reference targets that would be
1049 referenced by doc, ref or option.
1050 Custom objects added to the standard domain by extensions (see
1052 Sphinx.add_object_type()) are also searched.
1053 · Then, it looks for objects (targets) in all loaded domains.
1055 It is up to the domains how specific a match must be. For
1056 example, in the Python domain a reference of :any:`Builder`
1057 would match the sphinx.builders.Builder class.
1058 If none or multiple targets are found, a warning will be emit‐
1060 ted. In the case of multiple targets, you can change “any” to a
1061 specific role.
1062 This role is a good candidate for setting default_role. If you
1064 do, you can write cross-references without a lot of markup over‐
1065 head. For example, in this Python function documentation
1066 .. function:: install()
1068 This function installs a `handler` for every signal known by the
1070 `signal` module. See the section `about-signals` for more information.
1071 there could be references to a glossary term (usually
1073 :term:`handler`), a Python module (usually :py:mod:`signal` or
1074 :mod:`signal`) and a section (usually :ref:`about-signals`).
1075 The any role also works together with the intersphinx extension:
1077 when no local cross-reference is found, all object types of
1078 intersphinx inventories are also searched.
1079 Cross-referencing objects
1081 These roles are described with their respective domains:
1082 · Python
1084 · C
1086 · C++
1088 · JavaScript
1090 · ReST
1092 Cross-referencing arbitrary locations
1094 :ref: To support cross-referencing to arbitrary locations in any docu‐
1095 ment, the standard reST labels are used. For this to work label
1096 names must be unique throughout the entire documentation. There
1097 are two ways in which you can refer to labels:
1098 · If you place a label directly before a section title, you can
1100 reference to it with :ref:`label-name`. For example:
1101 .. _my-reference-label:
1103 Section to cross-reference
1105 --------------------------
1106 This is the text of the section.
1108 It refers to the section itself, see :ref:`my-reference-label`.
1110 The :ref: role would then generate a link to the section, with
1112 the link title being “Section to cross-reference”. This works
1113 just as well when section and reference are in different
1114 source files.
1115 Automatic labels also work with figures. For example:
1117 .. _my-figure:
1119 .. figure:: whatever
1121 Figure caption
1123 In this case, a reference :ref:`my-figure` would insert a
1125 reference to the figure with link text “Figure caption”.
1126 The same works for tables that are given an explicit caption
1128 using the table directive.
1129 · Labels that aren’t placed before a section title can still be
1131 referenced, but you must give the link an explicit title,
1132 using this syntax: :ref:`Link title <label-name>`.
1133 NOTE:
1135 Reference labels must start with an underscore. When refer‐
1136 encing a label, the underscore must be omitted (see examples
1137 above).
1138 Using ref is advised over standard reStructuredText links to
1140 sections (like `Section title`_) because it works across files,
1141 when section headings are changed, will raise warnings if incor‐
1142 rect, and works for all builders that support cross-references.
1143 Cross-referencing documents
1145 New in version 0.6.
1146 There is also a way to directly link to documents:
1149 :doc: Link to the specified document; the document name can be speci‐
1151 fied in absolute or relative fashion. For example, if the ref‐
1152 erence :doc:`parrot` occurs in the document sketches/index, then
1153 the link refers to sketches/parrot. If the reference is
1154 :doc:`/people` or :doc:`../people`, the link refers to people.
1155 If no explicit link text is given (like usual: :doc:`Monty
1157 Python members </people>`), the link caption will be the title
1158 of the given document.
1159 Referencing downloadable files
1161 New in version 0.6.
1162 :download:
1165 This role lets you link to files within your source tree that
1166 are not reST documents that can be viewed, but files that can be
1167 downloaded.
1168 When you use this role, the referenced file is automatically
1170 marked for inclusion in the output when building (obviously, for
1171 HTML output only). All downloadable files are put into the
1172 _downloads subdirectory of the output directory; duplicate file‐
1173 names are handled.
1174 An example:
1176 See :download:`this example script <../example.py>`.
1178 The given filename is usually relative to the directory the cur‐
1180 rent source file is contained in, but if it absolute (starting
1181 with /), it is taken as relative to the top source directory.
1182 The example.py file will be copied to the output directory, and
1184 a suitable link generated to it.
1185 Not to show unavailable download links, you should wrap whole
1187 paragraphs that have this role:
1188 .. only:: builder_html
1190 See :download:`this example script <../example.py>`.
1192 Cross-referencing figures by figure number
1194 New in version 1.3.
1195 Changed in version 1.5: numref role can also refer sections. And num‐
1198 ref allows {name} for the link text.
1199 :numref:
1202 Link to the specified figures, tables, code-blocks and sections;
1203 the standard reST labels are used. When you use this role, it
1204 will insert a reference to the figure with link text by its fig‐
1205 ure number like “Fig. 1.1”.
1206 If an explicit link text is given (as usual: :numref:`Image of
1208 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
1209 title of the reference. As placeholders, %s and {number} get
1210 replaced by the figure number and {name} by the figure caption.
1211 If no explicit link text is given, the numfig_format setting is
1212 used as fall-back default.
1213 If numfig is False, figures are not numbered, so this role
1215 inserts not a reference but the label or the link text.
1216 Cross-referencing other items of interest
1218 The following roles do possibly create a cross-reference, but do not
1219 refer to objects:
1220 :envvar:
1222 An environment variable. Index entries are generated. Also
1223 generates a link to the matching envvar directive, if it exists.
1224 :token:
1226 The name of a grammar token (used to create links between pro‐
1227 ductionlist directives).
1228 :keyword:
1230 The name of a keyword in Python. This creates a link to a ref‐
1231 erence label with that name, if it exists.
1232 :option:
1234 A command-line option to an executable program. This generates
1235 a link to a option directive, if it exists.
1236 The following role creates a cross-reference to a term in a glossary:
1238 :term: Reference to a term in a glossary. A glossary is created using
1240 the glossary directive containing a definition list with terms
1241 and definitions. It does not have to be in the same file as the
1242 term markup, for example the Python docs have one global glos‐
1243 sary in the glossary.rst file.
1244 If you use a term that’s not explained in a glossary, you’ll get
1246 a warning during build.
1247 Math
1249 :math: Role for inline math. Use like this:
1250 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
1252 :eq: Same as math:numref.
1254 Other semantic markup
1256 The following roles don’t do anything special except formatting the
1257 text in a different style:
1258 :abbr: An abbreviation. If the role content contains a parenthesized
1260 explanation, it will be treated specially: it will be shown in a
1261 tool-tip in HTML, and output only once in LaTeX.
1262 Example: :abbr:`LIFO (last-in, first-out)`.
1264 New in version 0.6.
1266 :command:
1269 The name of an OS-level command, such as rm.
1270 :dfn: Mark the defining instance of a term in the text. (No index
1272 entries are generated.)
1273 :file: The name of a file or directory. Within the contents, you can
1275 use curly braces to indicate a “variable” part, for example:
1276 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1278 In the built documentation, the x will be displayed differently
1280 to indicate that it is to be replaced by the Python minor ver‐
1281 sion.
1282 :guilabel:
1284 Labels presented as part of an interactive user interface should
1285 be marked using guilabel. This includes labels from text-based
1286 interfaces such as those created using curses or other
1287 text-based libraries. Any label used in the interface should be
1288 marked with this role, including button labels, window titles,
1289 field names, menu and menu selection names, and even values in
1290 selection lists.
1291 Changed in version 1.0: An accelerator key for the GUI label can
1293 be included using an ampersand; this will be stripped and dis‐
1294 played underlined in the output (example: :guilabel:`&Cancel`).
1295 To include a literal ampersand, double it.
1296 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1299 may depend on platform- or application-specific conventions.
1300 When there are no relevant conventions, the names of modifier
1301 keys should be spelled out, to improve accessibility for new
1302 users and non-native speakers. For example, an xemacs key
1303 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1304 ence to a specific application or platform, the same sequence
1305 should be marked as :kbd:`Control-x Control-f`.
1306 :mailheader:
1308 The name of an RFC 822-style mail header. This markup does not
1309 imply that the header is being used in an email message, but can
1310 be used to refer to any header of the same “style.” This is
1311 also used for headers defined by the various MIME specifica‐
1312 tions. The header name should be entered in the same way it
1313 would normally be found in practice, with the camel-casing con‐
1314 ventions being preferred where there is more than one common
1315 usage. For example: :mailheader:`Content-Type`.
1316 :makevar:
1318 The name of a make variable.
1319 :manpage:
1321 A reference to a Unix manual page including the section, e.g.
1322 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
1323 dering the manpage if manpages_url is defined.
1324 :menuselection:
1326 Menu selections should be marked using the menuselection role.
1327 This is used to mark a complete sequence of menu selections,
1328 including selecting submenus and choosing a specific operation,
1329 or any subsequence of such a sequence. The names of individual
1330 selections should be separated by -->.
1331 For example, to mark the selection “Start > Programs”, use this
1333 markup:
1334 :menuselection:`Start --> Programs`
1336 When including a selection that includes some trailing indica‐
1338 tor, such as the ellipsis some operating systems use to indicate
1339 that the command opens a dialog, the indicator should be omitted
1340 from the selection name.
1341 menuselection also supports ampersand accelerators just like
1343 guilabel.
1344 :mimetype:
1346 The name of a MIME type, or a component of a MIME type (the
1347 major or minor portion, taken alone).
1348 :newsgroup:
1350 The name of a Usenet newsgroup.
1351 Todo
1353 Is this not part of the standard domain?
1354 :program:
1356 The name of an executable program. This may differ from the
1357 file name for the executable for some platforms. In particular,
1358 the .exe (or other) extension should be omitted for Windows pro‐
1359 grams.
1360 :regexp:
1362 A regular expression. Quotes should not be included.
1363 :samp: A piece of literal text, such as code. Within the contents, you
1365 can use curly braces to indicate a “variable” part, as in file.
1366 For example, in :samp:`print 1+{variable}`, the part variable
1367 would be emphasized.
1368 If you don’t need the “variable part” indication, use the stan‐
1370 dard ``code`` instead.
1371 Changed in version 1.8: Allowed to escape curly braces with
1373 backslash
1374 There is also an index role to generate index entries.
1377 The following roles generate external links:
1379 :pep: A reference to a Python Enhancement Proposal. This generates
1381 appropriate index entries. The text “PEP number” is generated;
1382 in the HTML output, this text is a hyperlink to an online copy
1383 of the specified PEP. You can link to a specific section by
1384 saying :pep:`number#anchor`.
1385 :rfc: A reference to an Internet Request for Comments. This generates
1387 appropriate index entries. The text “RFC number” is generated;
1388 in the HTML output, this text is a hyperlink to an online copy
1389 of the specified RFC. You can link to a specific section by
1390 saying :rfc:`number#anchor`.
1391 Note that there are no special roles for including hyperlinks as you
1393 can use the standard reST markup for that purpose.
1394 Substitutions
1396 The documentation system provides three substitutions that are defined
1397 by default. They are set in the build configuration file.
1398 |release|
1400 Replaced by the project release the documentation refers to.
1401 This is meant to be the full version string including
1402 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1403 release.
1404 |version|
1406 Replaced by the project version the documentation refers to.
1407 This is meant to consist only of the major and minor version
1408 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1409 |today|
1411 Replaced by either today’s date (the date on which the document
1412 is read), or the date set in the build configuration file. Nor‐
1413 mally has the format April 14, 2007. Set by today_fmt and
1414 today.
1415 Directives
1417 As previously discussed, a directive is a generic block of explicit
1418 markup. While Docutils provides a number of directives, Sphinx provides
1419 many more and uses directives as one of the primary extension mecha‐
1420 nisms.
1421 See /usage/restructuredtext/domains for roles added by domains.
1423 SEE ALSO:
1425 Refer to the reStructuredText Primer for an overview of the direc‐
1426 tives provided by Docutils.
1427 Table of contents
1429 Since reST does not have facilities to interconnect several documents,
1430 or split documents into multiple output files, Sphinx uses a custom
1431 directive to add relations between the single files the documentation
1432 is made of, as well as tables of contents. The toctree directive is
1433 the central element.
1434 NOTE:
1436 Simple “inclusion” of one file in another can be done with the
1437 include directive.
1438 NOTE:
1440 To create table of contents for current document (.rst file), use
1441 the standard reST contents directive.
1442 .. toctree::
1444 This directive inserts a “TOC tree” at the current location,
1445 using the individual TOCs (including “sub-TOC trees”) of the
1446 documents given in the directive body. Relative document names
1447 (not beginning with a slash) are relative to the document the
1448 directive occurs in, absolute names are relative to the source
1449 directory. A numeric maxdepth option may be given to indicate
1450 the depth of the tree; by default, all levels are included. [1]
1451 Consider this example (taken from the Python docs’ library ref‐
1453 erence index):
1454 .. toctree::
1456 :maxdepth: 2
1457 intro
1459 strings
1460 datatypes
1461 numeric
1462 (many more documents listed here)
1463 This accomplishes two things:
1465 · Tables of contents from all those documents are inserted, with
1467 a maximum depth of two, that means one nested heading. toc‐
1468 tree directives in those documents are also taken into
1469 account.
1470 · Sphinx knows the relative order of the documents intro,
1472 strings and so forth, and it knows that they are children of
1473 the shown document, the library index. From this information
1474 it generates “next chapter”, “previous chapter” and “parent
1475 chapter” links.
1476 Entries
1478 Document titles in the toctree will be automatically read from
1480 the title of the referenced document. If that isn’t what you
1481 want, you can specify an explicit title and target using a simi‐
1482 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1483 syntax). This looks like:
1484 .. toctree::
1486 intro
1488 All about strings <strings>
1489 datatypes
1490 The second line above will link to the strings document, but
1492 will use the title “All about strings” instead of the title of
1493 the strings document.
1494 You can also add external links, by giving an HTTP URL instead
1496 of a document name.
1497 Section numbering
1499 If you want to have section numbers even in HTML output, give
1501 the toplevel toctree a numbered option. For example:
1502 .. toctree::
1504 :numbered:
1505 foo
1507 bar
1508 Numbering then starts at the heading of foo. Sub-toctrees are
1510 automatically numbered (don’t give the numbered flag to those).
1511 Numbering up to a specific depth is also possible, by giving the
1513 depth as a numeric argument to numbered.
1514 Additional options
1516 You can use caption option to provide a toctree caption and you
1518 can use name option to provide implicit target name that can be
1519 referenced by using ref:
1520 .. toctree::
1522 :caption: Table of Contents
1523 :name: mastertoc
1524 foo
1526 If you want only the titles of documents in the tree to show up,
1528 not other headings of the same level, you can use the titlesonly
1529 option:
1530 .. toctree::
1532 :titlesonly:
1533 foo
1535 bar
1536 You can use “globbing” in toctree directives, by giving the glob
1538 flag option. All entries are then matched against the list of
1539 available documents, and matches are inserted into the list
1540 alphabetically. Example:
1541 .. toctree::
1543 :glob:
1544 intro*
1546 recipe/*
1547 *
1548 This includes first all documents whose names start with intro,
1550 then all documents in the recipe folder, then all remaining doc‐
1551 uments (except the one containing the directive, of course.) [2]
1552 The special entry name self stands for the document containing
1554 the toctree directive. This is useful if you want to generate a
1555 “sitemap” from the toctree.
1556 You can use the reversed flag option to reverse the order of the
1558 entries in the list. This can be useful when using the glob flag
1559 option to reverse the ordering of the files. Example:
1560 .. toctree::
1562 :glob:
1563 :reversed:
1564 recipe/*
1566 You can also give a “hidden” option to the directive, like this:
1568 .. toctree::
1570 :hidden:
1571 doc_1
1573 doc_2
1574 This will still notify Sphinx of the document hierarchy, but not
1576 insert links into the document at the location of the directive
1577 – this makes sense if you intend to insert these links yourself,
1578 in a different style, or in the HTML sidebar.
1579 In cases where you want to have only one top-level toctree and
1581 hide all other lower level toctrees you can add the “includehid‐
1582 den” option to the top-level toctree entry:
1583 .. toctree::
1585 :includehidden:
1586 doc_1
1588 doc_2
1589 All other toctree entries can then be eliminated by the “hidden”
1591 option.
1592 In the end, all documents in the source directory (or subdirec‐
1594 tories) must occur in some toctree directive; Sphinx will emit a
1595 warning if it finds a file that is not included, because that
1596 means that this file will not be reachable through standard nav‐
1597 igation.
1598 Use exclude_patterns to explicitly exclude documents or directo‐
1600 ries from building completely. Use the “orphan” metadata to let
1601 a document be built, but notify Sphinx that it is not reachable
1602 via a toctree.
1603 The “master document” (selected by master_doc) is the “root” of
1605 the TOC tree hierarchy. It can be used as the documentation’s
1606 main page, or as a “full table of contents” if you don’t give a
1607 maxdepth option.
1608 Changed in version 0.3: Added “globbing” option.
1610 Changed in version 0.6: Added “numbered” and “hidden” options as
1613 well as external links and support for “self” references.
1614 Changed in version 1.0: Added “titlesonly” option.
1617 Changed in version 1.1: Added numeric argument to “numbered”.
1620 Changed in version 1.2: Added “includehidden” option.
1623 Changed in version 1.3: Added “caption” and “name” option.
1626 Special names
1629 Sphinx reserves some document names for its own use; you should not try
1630 to create documents with these names – it will cause problems.
1631 The special document names (and pages generated for them) are:
1633 · genindex, modindex, search
1635 These are used for the general index, the Python module index, and
1637 the search page, respectively.
1638 The general index is populated with entries from modules, all
1640 index-generating object descriptions, and from index directives.
1641 The Python module index contains one entry per py:module directive.
1643 The search page contains a form that uses the generated JSON search
1645 index and JavaScript to full-text search the generated documents for
1646 search words; it should work on every major browser that supports
1647 modern JavaScript.
1648 · every name beginning with _
1650 Though only few such names are currently used by Sphinx, you should
1652 not create documents or document-containing directories with such
1653 names. (Using _ as a prefix for a custom template directory is
1654 fine.)
1655 WARNING:
1657 Be careful with unusual characters in filenames. Some formats may
1658 interpret these characters in unexpected ways:
1659 · Do not use the colon : for HTML based formats. Links to other
1661 parts may not work.
1662 · Do not use the plus + for the ePub format. Some resources may not
1664 be found.
1665 Paragraph-level markup
1667 These directives create short paragraphs and can be used inside infor‐
1668 mation units as well as normal text.
1669 .. note::
1671 An especially important bit of information about an API that a
1672 user should be aware of when using whatever bit of API the note
1673 pertains to. The content of the directive should be written in
1674 complete sentences and include all appropriate punctuation.
1675 Example:
1677 .. note::
1679 This function is not suitable for sending spam e-mails.
1681 .. warning::
1683 An important bit of information about an API that a user should
1684 be very aware of when using whatever bit of API the warning per‐
1685 tains to. The content of the directive should be written in
1686 complete sentences and include all appropriate punctuation. This
1687 differs from note in that it is recommended over note for infor‐
1688 mation regarding security.
1689 .. versionadded:: version
1691 This directive documents the version of the project which added
1692 the described feature to the library or C API. When this applies
1693 to an entire module, it should be placed at the top of the mod‐
1694 ule section before any prose.
1695 The first argument must be given and is the version in question;
1697 you can add a second argument consisting of a brief explanation
1698 of the change.
1699 Example:
1701 .. versionadded:: 2.5
1703 The *spam* parameter.
1704 Note that there must be no blank line between the directive head
1706 and the explanation; this is to make these blocks visually con‐
1707 tinuous in the markup.
1708 .. versionchanged:: version
1710 Similar to versionadded, but describes when and what changed in
1711 the named feature in some way (new parameters, changed side
1712 effects, etc.).
1713 .. deprecated:: version
1715 Similar to versionchanged, but describes when the feature was
1716 deprecated. An explanation can also be given, for example to
1717 inform the reader what should be used instead. Example:
1718 .. deprecated:: 3.1
1720 Use :func:`spam` instead.
1721 .. seealso::
1723 Many sections include a list of references to module documenta‐
1724 tion or external documents. These lists are created using the
1725 seealso directive.
1726 The seealso directive is typically placed in a section just
1728 before any subsections. For the HTML output, it is shown boxed
1729 off from the main flow of the text.
1730 The content of the seealso directive should be a reST definition
1732 list. Example:
1733 .. seealso::
1735 Module :py:mod:`zipfile`
1737 Documentation of the :py:mod:`zipfile` standard module.
1738 `GNU tar manual, Basic Tar Format <http://link>`_
1740 Documentation for tar archive files, including GNU tar extensions.
1741 There’s also a “short form” allowed that looks like this:
1743 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1745 New in version 0.5: The short form.
1747 .. rubric:: title
1750 This directive creates a paragraph heading that is not used to
1751 create a table of contents node.
1752 NOTE:
1754 If the title of the rubric is “Footnotes” (or the selected
1755 language’s equivalent), this rubric is ignored by the LaTeX
1756 writer, since it is assumed to only contain footnote defini‐
1757 tions and therefore would create an empty heading.
1758 .. centered::
1760 This directive creates a centered boldfaced line of text. Use
1761 it as follows:
1762 .. centered:: LICENSE AGREEMENT
1764 Deprecated since version 1.1: This presentation-only directive
1766 is a legacy from older versions. Use a rst-class directive
1767 instead and add an appropriate style.
1768 .. hlist::
1771 This directive must contain a bullet list. It will transform it
1772 into a more compact list by either distributing more than one
1773 item horizontally, or reducing spacing between items, depending
1774 on the builder.
1775 For builders that support the horizontal distribution, there is
1777 a columns option that specifies the number of columns; it
1778 defaults to 2. Example:
1779 .. hlist::
1781 :columns: 3
1782 * A list of
1784 * short items
1785 * that should be
1786 * displayed
1787 * horizontally
1788 New in version 0.6.
1790 Showing code examples
1793 There are multiple ways to show syntax-highlighted literal code blocks
1794 in Sphinx: using reST doctest blocks; using reST literal blocks,
1795 optionally in combination with the highlight directive; using the
1796 code-block directive; and using the literalinclude directive. Doctest
1797 blocks can only be used to show interactive Python sessions, while the
1798 remaining three can be used for other languages. Of these three, lit‐
1799 eral blocks are useful when an entire document, or at least large sec‐
1800 tions of it, use code blocks with the same syntax and which should be
1801 styled in the same manner. On the other hand, the code-block directive
1802 makes more sense when you want more fine-tuned control over the styling
1803 of each block or when you have a document containing code blocks using
1804 multiple varied syntaxes. Finally, the literalinclude directive is use‐
1805 ful for including entire code files in your documentation.
1806 In all cases, Syntax highlighting is provided by Pygments. When using
1808 literal blocks, this is configured using any highlight directives in
1809 the source file. When a highlight directive is encountered, it is used
1810 until the next highlight directive is encountered. If there is no high‐
1811 light directive in the file, the global highlighting language is used.
1812 This defaults to python but can be configured using the highlight_lan‐
1813 guage config value. The following values are supported:
1814 · none (no highlighting)
1816 · default (similar to python3 but with a fallback to none without warn‐
1818 ing highlighting fails; the default when highlight_language isn’t
1819 set)
1820 · guess (let Pygments guess the lexer based on contents, only works
1822 with certain well-recognizable languages)
1823 · python
1825 · rest
1827 · c
1829 · … and any other lexer alias that Pygments supports
1831 If highlighting with the selected language fails (i.e. Pygments emits
1833 an “Error” token), the block is not highlighted in any way.
1834 IMPORTANT:
1836 The list of lexer aliases supported is tied to the Pygment version.
1837 If you want to ensure consistent highlighting, you should fix your
1838 version of Pygments.
1839 .. highlight:: language
1841 Example:
1842 .. highlight:: c
1844 This language is used until the next highlight directive is
1846 encountered. As discussed previously, language can be any lexer
1847 alias supported by Pygments.
1848 Additional options
1850 Pygments can generate line numbers for code blocks. To enable
1852 this, use the linenothreshold option.
1853 .. highlight:: python
1855 :linenothreshold: 5
1856 This will produce line numbers for all code blocks longer than
1858 five lines.
1859 To ignore minor errors on highlighting, you can specifiy :force:
1861 option.
1862 Changed in version 2.1: :force: option.
1864 .. code-block:: [language]
1867 Example:
1868 .. code-block:: ruby
1870 Some Ruby code.
1872 The directive’s alias name sourcecode works as well. This
1874 directive takes a language name as an argument. It can be any
1875 lexer alias supported by Pygments. If it is not given, the set‐
1876 ting of highlight directive will be used. If not set, high‐
1877 light_language will be used.
1878 Additional options
1880 Pygments can generate line numbers for code blocks. To enable
1882 this for, use the linenos flag option.
1883 .. code-block:: ruby
1885 :linenos:
1886 Some more Ruby code.
1888 The first line number can be selected with the lineno-start
1890 option. If present, linenos flag is automatically activated:
1891 .. code-block:: ruby
1893 :lineno-start: 10
1894 Some more Ruby code, with line numbering starting at 10.
1896 Additionally, an emphasize-lines option can be given to have
1898 Pygments emphasize particular lines:
1899 .. code-block:: python
1901 :emphasize-lines: 3,5
1902 def some_function():
1904 interesting = False
1905 print 'This line is highlighted.'
1906 print 'This one is not...'
1907 print '...but this one is.'
1908 A caption option can be given to show that name before the code
1910 block. A name option can be provided implicit target name that
1911 can be referenced by using ref. For example:
1912 .. code-block:: python
1914 :caption: this.py
1915 :name: this-py
1916 print 'Explicit is better than implicit.'
1918 A dedent option can be given to strip indentation characters
1920 from the code block. For example:
1921 .. code-block:: ruby
1923 :dedent: 4
1924 some ruby code
1926 A force option can ignore minor errors on highlighting.
1928 Changed in version 1.1: The emphasize-lines option has been
1930 added.
1931 Changed in version 1.3: The lineno-start, caption, name and
1934 dedent options have been added.
1935 Changed in version 1.6.6: LaTeX supports the emphasize-lines
1938 option.
1939 Changed in version 2.0: The language argument becomes optional.
1942 Changed in version 2.1: :force: option has been added.
1945 .. literalinclude:: filename
1948 Longer displays of verbatim text may be included by storing the
1949 example text in an external file containing only plain text.
1950 The file may be included using the literalinclude directive. [3]
1951 For example, to include the Python source file example.py, use:
1952 .. literalinclude:: example.py
1954 The file name is usually relative to the current file’s path.
1956 However, if it is absolute (starting with /), it is relative to
1957 the top source directory.
1958 Additional options
1960 Like code-block, the directive supports the linenos flag option
1962 to switch on line numbers, the lineno-start option to select the
1963 first line number, the emphasize-lines option to emphasize par‐
1964 ticular lines, the name option to provide an implicit target
1965 name, the dedent option to strip indentation characters for the
1966 code block, and a language option to select a language different
1967 from the current file’s standard language. In addition, it sup‐
1968 ports the caption option; however, this can be provided with no
1969 argument to use the filename as the caption. Example with
1970 options:
1971 .. literalinclude:: example.rb
1973 :language: ruby
1974 :emphasize-lines: 12,15-18
1975 :linenos:
1976 Tabs in the input are expanded if you give a tab-width option
1978 with the desired tab width.
1979 Include files are assumed to be encoded in the source_encoding.
1981 If the file has a different encoding, you can specify it with
1982 the encoding option:
1983 .. literalinclude:: example.py
1985 :encoding: latin-1
1986 The directive also supports including only parts of the file.
1988 If it is a Python module, you can select a class, function or
1989 method to include using the pyobject option:
1990 .. literalinclude:: example.py
1992 :pyobject: Timer.start
1993 This would only include the code lines belonging to the start()
1995 method in the Timer class within the file.
1996 Alternately, you can specify exactly which lines to include by
1998 giving a lines option:
1999 .. literalinclude:: example.py
2001 :lines: 1,3,5-10,20-
2002 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2004 line.
2005 Another way to control which part of the file is included is to
2007 use the start-after and end-before options (or only one of
2008 them). If start-after is given as a string option, only lines
2009 that follow the first line containing that string are included.
2010 If end-before is given as a string option, only lines that pre‐
2011 cede the first lines containing that string are included. The
2012 start-at and end-at options behave in a similar way, but the
2013 lines containing the matched string are included.
2014 With lines selected using start-after it is still possible to
2016 use lines, the first allowed line having by convention the line
2017 number 1.
2018 When lines have been selected in any of the ways described
2020 above, the line numbers in emphasize-lines refer to those
2021 selected lines, counted consecutively starting at 1.
2022 When specifying particular parts of a file to display, it can be
2024 useful to display the original line numbers. This can be done
2025 using the lineno-match option, which is however allowed only
2026 when the selection consists of contiguous lines.
2027 You can prepend and/or append a line to the included code, using
2029 the prepend and append option, respectively. This is useful
2030 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2031 markers.
2032 If you want to show the diff of the code, you can specify the
2034 old file by giving a diff option:
2035 .. literalinclude:: example.py
2037 :diff: example.py.orig
2038 This shows the diff between example.py and example.py.orig with
2040 unified diff format.
2041 A force option can ignore minor errors on highlighting.
2043 Changed in version 0.4.3: Added the encoding option.
2045 Changed in version 0.6: Added the pyobject, lines, start-after
2048 and end-before options, as well as support for absolute file‐
2049 names.
2050 Changed in version 1.0: Added the prepend, append, and tab-width
2053 options.
2054 Changed in version 1.3: Added the diff, lineno-match, caption,
2057 name, and dedent options.
2058 Changed in version 1.5: Added the start-at, and end-at options.
2061 Changed in version 1.6: With both start-after and lines in use,
2064 the first line as per start-after is considered to be with line
2065 number 1 for lines.
2066 Changed in version 2.1: Added the force option.
2069 Glossary
2072 .. glossary::
2073 This directive must contain a reST definition-list-like markup
2074 with terms and definitions. The definitions will then be refer‐
2075 enceable with the term role. Example:
2076 .. glossary::
2078 environment
2080 A structure where information about all documents under the root is
2081 saved, and used for cross-referencing. The environment is pickled
2082 after the parsing stage, so that successive runs only need to read
2083 and parse new and changed documents.
2084 source directory
2086 The directory which, including its subdirectories, contains all
2087 source files for one Sphinx project.
2088 In contrast to regular definition lists, multiple terms per
2090 entry are allowed, and inline markup is allowed in terms. You
2091 can link to all of the terms. For example:
2092 .. glossary::
2094 term 1
2096 term 2
2097 Definition of both terms.
2098 (When the glossary is sorted, the first term determines the sort
2100 order.)
2101 If you want to specify “grouping key” for general index entries,
2103 you can put a “key” as “term : key”. For example:
2104 .. glossary::
2106 term 1 : A
2108 term 2 : B
2109 Definition of both terms.
2110 Note that “key” is used for grouping key as is. The “key” isn’t
2112 normalized; key “A” and “a” become different groups. The whole
2113 characters in “key” is used instead of a first character; it is
2114 used for “Combining Character Sequence” and “Surrogate Pairs”
2115 grouping key.
2116 In i18n situation, you can specify “localized term : key” even
2118 if original text only have “term” part. In this case, translated
2119 “localized term” will be categorized in “key” group.
2120 New in version 0.6: You can now give the glossary directive a
2122 :sorted: flag that will automatically sort the entries alphabet‐
2123 ically.
2124 Changed in version 1.1: Now supports multiple terms and inline
2127 markup in terms.
2128 Changed in version 1.4: Index key for glossary term should be
2131 considered experimental.
2132 Meta-information markup
2135 .. sectionauthor:: name <email>
2136 Identifies the author of the current section. The argument
2137 should include the author’s name such that it can be used for
2138 presentation and email address. The domain name portion of the
2139 address should be lower case. Example:
2140 .. sectionauthor:: Guido van Rossum <guido@python.org>
2142 By default, this markup isn’t reflected in the output in any way
2144 (it helps keep track of contributions), but you can set the con‐
2145 figuration value show_authors to True to make them produce a
2146 paragraph in the output.
2147 .. codeauthor:: name <email>
2149 The codeauthor directive, which can appear multiple times, names
2150 the authors of the described code, just like sectionauthor names
2151 the author(s) of a piece of documentation. It too only produces
2152 output if the show_authors configuration value is True.
2153 Index-generating markup
2155 Sphinx automatically creates index entries from all object descriptions
2156 (like functions, classes or attributes) like discussed in
2157 /usage/restructuredtext/domains.
2158 However, there is also explicit markup available, to make the index
2160 more comprehensive and enable index entries in documents where informa‐
2161 tion is not mainly contained in information units, such as the language
2162 reference.
2163 .. index:: <entries>
2165 This directive contains one or more index entries. Each entry
2166 consists of a type and a value, separated by a colon.
2167 For example:
2169 .. index::
2171 single: execution; context
2172 module: __main__
2173 module: sys
2174 triple: module; search; path
2175 The execution context
2177 ---------------------
2178 ...
2180 This directive contains five entries, which will be converted to
2182 entries in the generated index which link to the exact location
2183 of the index statement (or, in case of offline media, the corre‐
2184 sponding page number).
2185 Since index directives generate cross-reference targets at their
2187 location in the source, it makes sense to put them before the
2188 thing they refer to – e.g. a heading, as in the example above.
2189 The possible entry types are:
2191 single Creates a single index entry. Can be made a subentry by
2193 separating the subentry text with a semicolon (this nota‐
2194 tion is also used below to describe what entries are cre‐
2195 ated).
2196 pair pair: loop; statement is a shortcut that creates two
2198 index entries, namely loop; statement and statement;
2199 loop.
2200 triple Likewise, triple: module; search; path is a shortcut that
2202 creates three index entries, which are module; search
2203 path, search; path, module and path; module search.
2204 see see: entry; other creates an index entry that refers from
2206 entry to other.
2207 seealso
2209 Like see, but inserts “see also” instead of “see”.
2210 module, keyword, operator, object, exception, statement, builtin
2212 These all create two index entries. For example, module:
2213 hashlib creates the entries module; hashlib and hashlib;
2214 module. (These are Python-specific and therefore depre‐
2215 cated.)
2216 You can mark up “main” index entries by prefixing them with an
2218 exclamation mark. The references to “main” entries are empha‐
2219 sized in the generated index. For example, if two pages contain
2220 .. index:: Python
2222 and one page contains
2224 .. index:: ! Python
2226 then the backlink to the latter page is emphasized among the
2228 three backlinks.
2229 For index directives containing only “single” entries, there is
2231 a shorthand notation:
2232 .. index:: BNF, grammar, syntax, notation
2234 This creates four index entries.
2236 Changed in version 1.1: Added see and seealso types, as well as
2238 marking main entries.
2239 :index:
2242 While the index directive is a block-level markup and links to
2243 the beginning of the next paragraph, there is also a correspond‐
2244 ing role that sets the link target directly where it is used.
2245 The content of the role can be a simple phrase, which is then
2247 kept in the text and used as an index entry. It can also be a
2248 combination of text and index entry, styled like with explicit
2249 targets of cross-references. In that case, the “target” part
2250 can be a full entry as described for the directive above. For
2251 example:
2252 This is a normal reST :index:`paragraph` that contains several
2254 :index:`index entries <pair: index; entry>`.
2255 New in version 1.1.
2257 Including content based on tags
2260 .. only:: <expression>
2261 Include the content of the directive only if the expression is
2262 true. The expression should consist of tags, like this:
2263 .. only:: html and draft
2265 Undefined tags are false, defined tags (via the -t command-line
2267 option or within conf.py, see here) are true. Boolean expres‐
2268 sions, also using parentheses (like html and (latex or draft))
2269 are supported.
2270 The format and the name of the current builder (html, latex or
2272 text) are always set as a tag [4]. To make the distinction
2273 between format and name explicit, they are also added with the
2274 prefix format_ and builder_, e.g. the epub builder defines the
2275 tags html, epub, format_html and builder_epub.
2276 These standard tags are set after the configuration file is
2278 read, so they are not available there.
2279 All tags must follow the standard Python identifier syntax as
2281 set out in the Identifiers and keywords documentation. That is,
2282 a tag expression may only consist of tags that conform to the
2283 syntax of Python variables. In ASCII, this consists of the
2284 uppercase and lowercase letters A through Z, the underscore _
2285 and, except for the first character, the digits 0 through 9.
2286 New in version 0.6.
2288 Changed in version 1.2: Added the name of the builder and the
2291 prefixes.
2292 WARNING:
2295 This directive is designed to control only content of docu‐
2296 ment. It could not control sections, labels and so on.
2297 Tables
2299 Use reStructuredText tables, i.e. either
2300 · grid table syntax (ref),
2302 · simple table syntax (ref),
2304 · csv-table syntax,
2306 · or list-table syntax.
2308 The table directive serves as optional wrapper of the grid and simple
2310 syntaxes.
2311 They work fine in HTML output, however there are some gotchas when
2313 using tables in LaTeX: the column width is hard to determine correctly
2314 automatically. For this reason, the following directive exists:
2315 .. tabularcolumns:: column spec
2317 This directive gives a “column spec” for the next table occur‐
2318 ring in the source file. The spec is the second argument to the
2319 LaTeX tabulary package’s environment (which Sphinx uses to
2320 translate tables). It can have values like
2321 |l|l|l|
2323 which means three left-adjusted, nonbreaking columns. For col‐
2325 umns with longer text that should automatically be broken, use
2326 either the standard p{width} construct, or tabulary’s automatic
2327 specifiers:
2328 ┌──┬────────────────────────────┐
2330 │L │ flush left column with │
2331 │ │ automatic width │
2332 ├──┼────────────────────────────┤
2333 │R │ flush right column with │
2334 │ │ automatic width │
2335 ├──┼────────────────────────────┤
2336 │C │ centered column with auto‐ │
2337 │ │ matic width │
2338 └──┴────────────────────────────┘
2339 │J │ justified column with │
2343 │ │ automatic width │
2344 └──┴────────────────────────────┘
2345 The automatic widths of the LRCJ columns are attributed by tabu‐
2347 lary in proportion to the observed shares in a first pass where
2348 the table cells are rendered at their natural “horizontal”
2349 widths.
2350 By default, Sphinx uses a table layout with J for every column.
2352 New in version 0.3.
2354 Changed in version 1.6: Merged cells may now contain multiple
2357 paragraphs and are much better handled, thanks to custom Sphinx
2358 LaTeX macros. This novel situation motivated the switch to J
2359 specifier and not L by default.
2360 HINT:
2363 Sphinx actually uses T specifier having done \newcolumn‐
2364 type{T}{J}. To revert to previous default, insert \newcolum‐
2365 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2366 A frequent issue with tabulary is that columns with little
2368 contents are “squeezed”. The minimal column width is a tabu‐
2369 lary parameter called \tymin. You may set it globally in the
2370 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2371 Else, use the tabularcolumns directive with an explicit
2373 p{40pt} (for example) for that column. You may use also l
2374 specifier but this makes the task of setting column widths
2375 more difficult if some merged cell intersects that column.
2376 WARNING:
2378 Tables with more than 30 rows are rendered using longtable,
2379 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2380 ifiers do not work for these tables.
2381 Tables that contain list-like elements such as object
2383 descriptions, blockquotes or any kind of lists cannot be set
2384 out of the box with tabulary. They are therefore set with the
2385 standard LaTeX tabular (or longtable) environment if you
2386 don’t give a tabularcolumns directive. If you do, the table
2387 will be set with tabulary but you must use the p{width} con‐
2388 struct (or Sphinx’s \X and \Y specifiers described below) for
2389 the columns containing these elements.
2390 Literal blocks do not work with tabulary at all, so tables
2392 containing a literal block are always set with tabular. The
2393 verbatim environment used for literal blocks only works in
2394 p{width} (and \X or \Y) columns, hence Sphinx generates such
2395 column specs for tables containing literal blocks.
2396 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2398 backslash in the specifier letter). It is like p{width} with the
2399 width set to a fraction a/b of the current line width. You can
2400 use it in the tabularcolumns (it is not a problem if some LaTeX
2401 macro is also called \X.)
2402 It is not needed for b to be the total number of columns, nor
2404 for the sum of the fractions of the \X specifiers to add up to
2405 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2406 the table will occupy 80% of the line width, the first of its
2407 three columns having the same width as the sum of the next two.
2408 This is used by the :widths: option of the table directive.
2410 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2412 a decimal argument, such has \Y{0.15}: this would have the same
2413 effect as \X{3}{20}.
2414 Changed in version 1.6: Merged cells from complex grid tables
2416 (either multi-row, multi-column, or both) now allow blockquotes,
2417 lists, literal blocks, … as do regular cells.
2418 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2420 Y{f} and tabulary’s columns.
2421 NOTE:
2424 tabularcolumns conflicts with :widths: option of table direc‐
2425 tives. If both are specified, :widths: option will be
2426 ignored.
2427 Math
2429 The input language for mathematics is LaTeX markup. This is the
2430 de-facto standard for plain-text math notation and has the added advan‐
2431 tage that no further translation is necessary when building LaTeX out‐
2432 put.
2433 Keep in mind that when you put math markup in Python docstrings read by
2435 autodoc, you either have to double all backslashes, or use Python raw
2436 strings (r"raw").
2437 .. math::
2439 Directive for displayed math (math that takes the whole line for
2440 itself).
2441 The directive supports multiple equations, which should be sepa‐
2443 rated by a blank line:
2444 .. math::
2446 (a + b)^2 = a^2 + 2ab + b^2
2448 (a - b)^2 = a^2 - 2ab + b^2
2450 In addition, each single equation is set within a split environ‐
2452 ment, which means that you can have multiple aligned lines in an
2453 equation, aligned at & and separated by \\:
2454 .. math::
2456 (a + b)^2 &= (a + b)(a + b) \\
2458 &= a^2 + 2ab + b^2
2459 For more details, look into the documentation of the AmSMath
2461 LaTeX package.
2462 When the math is only one line of text, it can also be given as
2464 a directive argument:
2465 .. math:: (a + b)^2 = a^2 + 2ab + b^2
2467 Normally, equations are not numbered. If you want your equation
2469 to get a number, use the label option. When given, it selects
2470 an internal label for the equation, by which it can be
2471 cross-referenced, and causes an equation number to be issued.
2472 See eq for an example. The numbering style depends on the out‐
2473 put format.
2474 There is also an option nowrap that prevents any wrapping of the
2476 given math in a math environment. When you give this option,
2477 you must make sure yourself that the math is properly set up.
2478 For example:
2479 .. math::
2481 :nowrap:
2482 \begin{eqnarray}
2484 y & = & ax^2 + bx + c \\
2485 f(x) & = & x^2 + 2xy + y^2
2486 \end{eqnarray}
2487 SEE ALSO:
2489 math-support
2491 Rendering options for math with HTML builders.
2492 latex_engine
2494 Explains how to configure LaTeX builder to support Unicode
2495 literals in math mark-up.
2496 Grammar production displays
2498 Special markup is available for displaying the productions of a formal
2499 grammar. The markup is simple and does not attempt to model all
2500 aspects of BNF (or any derived forms), but provides enough to allow
2501 context-free grammars to be displayed in a way that causes uses of a
2502 symbol to be rendered as hyperlinks to the definition of the symbol.
2503 There is this directive:
2504 .. productionlist:: [name]
2506 This directive is used to enclose a group of productions. Each
2507 production is given on a single line and consists of a name,
2508 separated by a colon from the following definition. If the def‐
2509 inition spans multiple lines, each continuation line must begin
2510 with a colon placed at the same column as in the first line.
2511 The argument to productionlist serves to distinguish different
2513 sets of production lists that belong to different grammars.
2514 Blank lines are not allowed within productionlist directive
2516 arguments.
2517 The definition can contain token names which are marked as
2519 interpreted text (e.g. sum ::= `integer` "+" `integer`) – this
2520 generates cross-references to the productions of these tokens.
2521 Outside of the production list, you can reference to token pro‐
2522 ductions using token.
2523 Note that no further reST parsing is done in the production, so
2525 that you don’t have to escape * or | characters.
2526 The following is an example taken from the Python Reference Manual:
2528 .. productionlist::
2530 try_stmt: try1_stmt | try2_stmt
2531 try1_stmt: "try" ":" `suite`
2532 : ("except" [`expression` ["," `target`]] ":" `suite`)+
2533 : ["else" ":" `suite`]
2534 : ["finally" ":" `suite`]
2535 try2_stmt: "try" ":" `suite`
2536 : "finally" ":" `suite`
2537
2539 [1] The LaTeX writer only refers the maxdepth option of first toctree
2540 directive in the document.
2541 [2] A note on available globbing syntax: you can use the standard
2543 shell constructs *, ?, [...] and [!...] with the feature that
2544 these all don’t match slashes. A double star ** can be used to
2545 match any sequence of characters including slashes.
2546 [3] There is a standard .. include directive, but it raises errors if
2548 the file is not found. This one only emits a warning.
2549 [4] For most builders name and format are the same. At the moment only
2551 builders derived from the html builder distinguish between the
2552 builder format and the builder name.
2553 Note that the current builder tag is not available in conf.py, it
2555 is only available after the builder is initialized.
2556 Field Lists
2558 As previously discussed, field lists are sequences of fields marked up
2559 like this:
2560 :fieldname: Field content
2562 Sphinx provides custom behavior for bibliographic fields compared to
2564 docutils.
2565 File-wide metadata
2567 A field list near the top of a file is normally parsed by docutils as
2568 the docinfo which is generally used to record the author, date of pub‐
2569 lication and other metadata. However, in Sphinx, a field list preced‐
2570 ing any other markup is moved from the docinfo to the Sphinx environ‐
2571 ment as document metadata and is not displayed in the output; a field
2572 list appearing after the document title will be part of the docinfo as
2573 normal and will be displayed in the output.
2574 At the moment, these metadata fields are recognized:
2576 tocdepth
2578 The maximum depth for a table of contents of this file.
2579 :tocdepth: 2
2581 New in version 0.4.
2583 nocomments
2586 If set, the web application won’t display a comment form for a
2587 page generated from this source file.
2588 :nocomments:
2590 orphan If set, warnings about this file not being included in any toc‐
2592 tree will be suppressed.
2593 :orphan:
2595 New in version 1.0.
2597 Domains
2600 New in version 1.0.
2601 Originally, Sphinx was conceived for a single project, the documenta‐
2604 tion of the Python language. Shortly afterwards, it was made available
2605 for everyone as a documentation tool, but the documentation of Python
2606 modules remained deeply built in – the most fundamental directives,
2607 like function, were designed for Python objects. Since Sphinx has
2608 become somewhat popular, interest developed in using it for many dif‐
2609 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2610 markup (like in this documentation).
2611 While this was always possible, it is now much easier to easily support
2613 documentation of projects using different programming languages or even
2614 ones not supported by the main Sphinx distribution, by providing a
2615 domain for every such purpose.
2616 A domain is a collection of markup (reStructuredText directives and
2618 roles) to describe and link to objects belonging together, e.g. ele‐
2619 ments of a programming language. Directive and role names in a domain
2620 have names like domain:name, e.g. py:function. Domains can also pro‐
2621 vide custom indices (like the Python Module Index).
2622 Having domains means that there are no naming problems when one set of
2624 documentation wants to refer to e.g. C++ and Python classes. It also
2625 means that extensions that support the documentation of whole new lan‐
2626 guages are much easier to write.
2627 This section describes what the domains that are included with Sphinx
2629 provide. The domain API is documented as well, in the section
2630 domain-api.
2631 Basic Markup
2633 Most domains provide a number of object description directives, used to
2634 describe specific objects provided by modules. Each directive requires
2635 one or more signatures to provide basic information about what is being
2636 described, and the content should be the description. The basic ver‐
2637 sion makes entries in the general index; if no index entry is desired,
2638 you can give the directive option flag :noindex:. An example using a
2639 Python domain directive:
2640 .. py:function:: spam(eggs)
2642 ham(eggs)
2643 Spam or ham the foo.
2645 This describes the two Python functions spam and ham. (Note that when
2647 signatures become too long, you can break them if you add a backslash
2648 to lines that are continued in the next line. Example:
2649 .. py:function:: filterwarnings(action, message='', category=Warning, \
2651 module='', lineno=0, append=False)
2652 :noindex:
2653 (This example also shows how to use the :noindex: flag.)
2655 The domains also provide roles that link back to these object descrip‐
2657 tions. For example, to link to one of the functions described in the
2658 example above, you could say
2659 The function :py:func:`spam` does a similar thing.
2661 As you can see, both directive and role names contain the domain name
2663 and the directive name.
2664 Default Domain
2666 For documentation describing objects from solely one domain, authors
2668 will not have to state again its name at each directive, role, etc…
2669 after having specified a default. This can be done either via the con‐
2670 fig value primary_domain or via this directive:
2671 .. default-domain:: name
2673 Select a new default domain. While the primary_domain selects a
2674 global default, this only has an effect within the same file.
2675 If no other default is selected, the Python domain (named py) is the
2677 default one, mostly for compatibility with documentation written for
2678 older versions of Sphinx.
2679 Directives and roles that belong to the default domain can be mentioned
2681 without giving the domain name, i.e.
2682 .. function:: pyfunc()
2684 Describes a Python function.
2686 Reference to :func:`pyfunc`.
2688 Cross-referencing syntax
2690 For cross-reference roles provided by domains, the same facilities
2691 exist as for general cross-references. See xref-syntax.
2692 In short:
2694 · You may supply an explicit title and reference target: :role:`title
2696 <target>` will refer to target, but the link text will be title.
2697 · If you prefix the content with !, no reference/hyperlink will be cre‐
2699 ated.
2700 · If you prefix the content with ~, the link text will only be the last
2702 component of the target. For example, :py:meth:`~Queue.Queue.get`
2703 will refer to Queue.Queue.get but only display get as the link text.
2704 The Python Domain
2706 The Python domain (name py) provides the following directives for mod‐
2707 ule declarations:
2708 .. py:module:: name
2710 This directive marks the beginning of the description of a mod‐
2711 ule (or package submodule, in which case the name should be
2712 fully qualified, including the package name). It does not cre‐
2713 ate content (like e.g. py:class does).
2714 This directive will also cause an entry in the global module
2716 index.
2717 options
2719 :platform: platforms (comma separated list)
2721 Indicate platforms which the module is available (if it
2722 is available on all platforms, the option should be omit‐
2723 ted). The keys are short identifiers; examples that are
2724 in use include “IRIX”, “Mac”, “Windows” and “Unix”. It
2725 is important to use a key which has already been used
2726 when applicable.
2727 :synopsis: purpose (text)
2729 Consist of one sentence describing the module’s purpose –
2730 it is currently only used in the Global Module Index.
2731 :deprecated: (no argument)
2733 Mark a module as deprecated; it will be designated as
2734 such in various locations then.
2735 .. py:currentmodule:: name
2737 This directive tells Sphinx that the classes, functions etc.
2738 documented from here are in the given module (like py:module),
2739 but it will not create index entries, an entry in the Global
2740 Module Index, or a link target for py:mod. This is helpful in
2741 situations where documentation for things in a module is spread
2742 over multiple files or sections – one location has the py:module
2743 directive, the others only py:currentmodule.
2744 The following directives are provided for module and class contents:
2746 .. py:function:: name(parameters)
2748 Describes a module-level function. The signature should include
2749 the parameters as given in the Python function definition, see
2750 Python Signatures. For example:
2751 .. py:function:: Timer.repeat(repeat=3, number=1000000)
2753 For methods you should use py:method.
2755 The description normally includes information about the parame‐
2757 ters required and how they are used (especially whether mutable
2758 objects passed as parameters are modified), side effects, and
2759 possible exceptions.
2760 This information can (in any py directive) optionally be given
2762 in a structured form, see Info field lists.
2763 options
2765 :async: (no value)
2767 Indicate the function is an async function.
2768 New in version 2.1.
2770 .. py:data:: name
2773 Describes global data in a module, including both variables and
2774 values used as “defined constants.” Class and object attributes
2775 are not documented using this environment.
2776 .. py:exception:: name
2778 Describes an exception class. The signature can, but need not
2779 include parentheses with constructor arguments.
2780 .. py:class:: name
2782 .. py:class:: name(parameters)
2784 Describes a class. The signature can optionally include paren‐
2785 theses with parameters which will be shown as the constructor
2786 arguments. See also Python Signatures.
2787 Methods and attributes belonging to the class should be placed
2789 in this directive’s body. If they are placed outside, the sup‐
2790 plied name should contain the class name so that cross-refer‐
2791 ences still work. Example:
2792 .. py:class:: Foo
2794 .. py:method:: quux()
2796 -- or --
2798 .. py:class:: Bar
2800 .. py:method:: Bar.quux()
2802 The first way is the preferred one.
2804 .. py:attribute:: name
2806 Describes an object data attribute. The description should
2807 include information about the type of the data to be expected
2808 and whether it may be changed directly.
2809 .. py:method:: name(parameters)
2811 Describes an object method. The parameters should not include
2812 the self parameter. The description should include similar
2813 information to that described for function. See also Python
2814 Signatures and Info field lists.
2815 options
2817 :abstractmethod: (no value)
2819 Indicate the method is an abstract method.
2820 New in version 2.1.
2822 :async: (no value)
2825 Indicate the method is an async method.
2826 New in version 2.1.
2828 :classmethod: (no value)
2831 Indicate the method is a class method.
2832 New in version 2.1.
2834 :property: (no value)
2837 Indicate the method is a property.
2838 New in version 2.1.
2840 :staticmethod: (no value)
2843 Indicate the method is a static method.
2844 New in version 2.1.
2846 .. py:staticmethod:: name(parameters)
2849 Like py:method, but indicates that the method is a static
2850 method.
2851 New in version 0.4.
2853 .. py:classmethod:: name(parameters)
2856 Like py:method, but indicates that the method is a class method.
2857 New in version 0.6.
2859 .. py:decorator:: name
2862 .. py:decorator:: name(parameters)
2864 Describes a decorator function. The signature should represent
2865 the usage as a decorator. For example, given the functions
2866 def removename(func):
2868 func.__name__ = ''
2869 return func
2870 def setnewname(name):
2872 def decorator(func):
2873 func.__name__ = name
2874 return func
2875 return decorator
2876 the descriptions should look like this:
2878 .. py:decorator:: removename
2880 Remove name of the decorated function.
2882 .. py:decorator:: setnewname(name)
2884 Set name of the decorated function to *name*.
2886 (as opposed to .. py:decorator:: removename(func).)
2888 There is no py:deco role to link to a decorator that is marked
2890 up with this directive; rather, use the py:func role.
2891 .. py:decoratormethod:: name
2893 .. py:decoratormethod:: name(signature)
2895 Same as py:decorator, but for decorators that are methods.
2896 Refer to a decorator method using the py:meth role.
2898 Python Signatures
2900 Signatures of functions, methods and class constructors can be given
2901 like they would be written in Python.
2902 Default values for optional arguments can be given (but if they contain
2904 commas, they will confuse the signature parser). Python 3-style argu‐
2905 ment annotations can also be given as well as return type annotations:
2906 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
2908 For functions with optional parameters that don’t have default values
2910 (typically functions implemented in C extension modules without keyword
2911 argument support), you can use brackets to specify the optional parts:
2912 compile(source[, filename[, symbol]])
2914 It is customary to put the opening bracket before the comma.
2916 Info field lists
2918 New in version 0.4.
2919 Inside Python object description directives, reST field lists with
2922 these fields are recognized and formatted nicely:
2923 · param, parameter, arg, argument, key, keyword: Description of a
2925 parameter.
2926 · type: Type of a parameter. Creates a link if possible.
2928 · raises, raise, except, exception: That (and when) a specific excep‐
2930 tion is raised.
2931 · var, ivar, cvar: Description of a variable.
2933 · vartype: Type of a variable. Creates a link if possible.
2935 · returns, return: Description of the return value.
2937 · rtype: Return type. Creates a link if possible.
2939 NOTE:
2941 In current release, all var, ivar and cvar are represented as “Vari‐
2942 able”. There is no difference at all.
2943 The field names must consist of one of these keywords and an argument
2945 (except for returns and rtype, which do not need an argument). This is
2946 best explained by an example:
2947 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
2949 Send a message to a recipient
2951 :param str sender: The person sending the message
2953 :param str recipient: The recipient of the message
2954 :param str message_body: The body of the message
2955 :param priority: The priority of the message, can be a number 1-5
2956 :type priority: integer or None
2957 :return: the message id
2958 :rtype: int
2959 :raises ValueError: if the message_body exceeds 160 characters
2960 :raises TypeError: if the message_body is not a basestring
2961 This will render like this:
2963 send_message(sender, recipient, message_body[, priority=1])
2965 Send a message to a recipient
2966 Parameters
2968 · sender (str) – The person sending the message
2970 · recipient (str) – The recipient of the message
2972 · message_body (str) – The body of the message
2974 · priority (integer or None) – The priority of the
2976 message, can be a number 1-5
2977 Returns
2979 the message id
2980 Return type
2982 int
2983 Raises
2985 · ValueError – if the message_body exceeds 160 charac‐
2987 ters
2988 · TypeError – if the message_body is not a basestring
2990 It is also possible to combine parameter type and description, if the
2992 type is a single word, like this:
2993 :param int priority: The priority of the message, can be a number 1-5
2995 New in version 1.5.
2997 Container types such as lists and dictionaries can be linked automati‐
3000 cally using the following syntax:
3001 :type priorities: list(int)
3003 :type priorities: list[int]
3004 :type mapping: dict(str, int)
3005 :type mapping: dict[str, int]
3006 :type point: tuple(float, float)
3007 :type point: tuple[float, float]
3008 Multiple types in a type field will be linked automatically if sepa‐
3010 rated by the word “or”:
3011 :type an_arg: int or None
3013 :vartype a_var: str or int
3014 :rtype: float or str
3015 Cross-referencing Python objects
3017 The following roles refer to objects in modules and are possibly hyper‐
3018 linked if a matching identifier is found:
3019 :py:mod:
3021 Reference a module; a dotted name may be used. This should also
3022 be used for package names.
3023 :py:func:
3025 Reference a Python function; dotted names may be used. The role
3026 text needs not include trailing parentheses to enhance readabil‐
3027 ity; they will be added automatically by Sphinx if the add_func‐
3028 tion_parentheses config value is True (the default).
3029 :py:data:
3031 Reference a module-level variable.
3032 :py:const:
3034 Reference a “defined” constant. This may be a Python variable
3035 that is not intended to be changed.
3036 :py:class:
3038 Reference a class; a dotted name may be used.
3039 :py:meth:
3041 Reference a method of an object. The role text can include the
3042 type name and the method name; if it occurs within the descrip‐
3043 tion of a type, the type name can be omitted. A dotted name may
3044 be used.
3045 :py:attr:
3047 Reference a data attribute of an object.
3048 :py:exc:
3050 Reference an exception. A dotted name may be used.
3051 :py:obj:
3053 Reference an object of unspecified type. Useful e.g. as the
3054 default_role.
3055 New in version 0.4.
3057 The name enclosed in this markup can include a module name and/or a
3060 class name. For example, :py:func:`filter` could refer to a function
3061 named filter in the current module, or the built-in function of that
3062 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3063 function in the foo module.
3064 Normally, names in these roles are searched first without any further
3066 qualification, then with the current module name prepended, then with
3067 the current module and class name (if any) prepended. If you prefix
3068 the name with a dot, this order is reversed. For example, in the docu‐
3069 mentation of Python’s codecs module, :py:func:`open` always refers to
3070 the built-in function, while :py:func:`.open` refers to codecs.open().
3071 A similar heuristic is used to determine whether the name is an
3073 attribute of the currently documented class.
3074 Also, if the name is prefixed with a dot, and no exact match is found,
3076 the target is taken as a suffix and all object names with that suffix
3077 are searched. For example, :py:meth:`.TarFile.close` references the
3078 tarfile.TarFile.close() function, even if the current module is not
3079 tarfile. Since this can get ambiguous, if there is more than one pos‐
3080 sible match, you will get a warning from Sphinx.
3081 Note that you can combine the ~ and . prefixes:
3083 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3084 method, but the visible link caption will only be close().
3085 The C Domain
3087 The C domain (name c) is suited for documentation of C API.
3088 .. c:function:: function prototype
3090 Describes a C function. The signature should be given as in C,
3091 e.g.:
3092 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3094 This is also used to describe function-like preprocessor macros.
3096 The names of the arguments should be given so they may be used
3097 in the description.
3098 Note that you don’t have to backslash-escape asterisks in the
3100 signature, as it is not parsed by the reST inliner.
3101 .. c:member:: declaration
3103 Describes a C struct member. Example signature:
3104 .. c:member:: PyObject* PyTypeObject.tp_bases
3106 The text of the description should include the range of values
3108 allowed, how the value should be interpreted, and whether the
3109 value can be changed. References to structure members in text
3110 should use the member role.
3111 .. c:macro:: name
3113 Describes a “simple” C macro. Simple macros are macros which
3114 are used for code expansion, but which do not take arguments so
3115 cannot be described as functions. This is a simple C-language
3116 #define. Examples of its use in the Python documentation
3117 include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
3118 .. c:type:: name
3120 Describes a C type (whether defined by a typedef or struct). The
3121 signature should just be the type name.
3122 .. c:var:: declaration
3124 Describes a global C variable. The signature should include the
3125 type, such as:
3126 .. c:var:: PyObject* PyClass_Type
3128 Cross-referencing C constructs
3130 The following roles create cross-references to C-language constructs if
3131 they are defined in the documentation:
3132 :c:func:
3134 Reference a C-language function. Should include trailing paren‐
3135 theses.
3136 :c:member:
3138 Reference a C-language member of a struct.
3139 :c:macro:
3141 Reference a “simple” C macro, as defined above.
3142 :c:type:
3144 Reference a C-language type.
3145 :c:data:
3147 Reference a C-language variable.
3148 The C++ Domain
3150 The C++ domain (name cpp) supports documenting C++ projects.
3151 Directives for Declaring Entities
3153 The following directives are available. All declarations can start with
3154 a visibility statement (public, private or protected).
3155 .. cpp:class:: class specifier
3157 .. cpp:struct:: class specifier
3159 Describe a class/struct, possibly with specification of inheri‐
3160 tance, e.g.,:
3161 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3163 The difference between cpp:class and cpp:struct is only cos‐
3165 metic: the prefix rendered in the output, and the specifier
3166 shown in the index.
3167 The class can be directly declared inside a nested scope, e.g.,:
3169 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3171 A class template can be declared:
3173 .. cpp:class:: template<typename T, std::size_t N> std::array
3175 or with a line break:
3177 .. cpp:class:: template<typename T, std::size_t N> \
3179 std::array
3180 Full and partial template specialisations can be declared:
3182 .. cpp:class:: template<> \
3184 std::array<bool, 256>
3185 .. cpp:class:: template<typename T> \
3187 std::array<T, 42>
3188 New in version 2.0: The cpp:struct directive.
3190 .. cpp:function:: (member) function prototype
3193 Describe a function or member function, e.g.,:
3194 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3196 A function with parameters and types.
3198 .. cpp:function:: bool myMethod(int, double)
3200 A function with unnamed parameters.
3202 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3204 An overload for the indexing operator.
3206 .. cpp:function:: operator bool() const
3208 A casting operator.
3210 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3212 A constexpr function.
3214 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3216 A copy constructor with default implementation.
3218 Function templates can also be described:
3220 .. cpp:function:: template<typename U> \
3222 void print(U &&u)
3223 and function template specialisations:
3225 .. cpp:function:: template<> \
3227 void print(int i)
3228 .. cpp:member:: (member) variable declaration
3230 .. cpp:var:: (member) variable declaration
3232 Describe a variable or member variable, e.g.,:
3233 .. cpp:member:: std::string MyClass::myMember
3235 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3237 .. cpp:member:: int a = 42
3239 Variable templates can also be described:
3241 .. cpp:member:: template<class T> \
3243 constexpr T pi = T(3.1415926535897932385)
3244 .. cpp:type:: typedef declaration
3246 .. cpp:type:: name
3248 .. cpp:type:: type alias declaration
3250 Describe a type as in a typedef declaration, a type alias decla‐
3251 ration, or simply the name of a type with unspecified type,
3252 e.g.,:
3253 .. cpp:type:: std::vector<int> MyList
3255 A typedef-like declaration of a type.
3257 .. cpp:type:: MyContainer::const_iterator
3259 Declaration of a type alias with unspecified type.
3261 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3263 Declaration of a type alias.
3265 A type alias can also be templated:
3267 .. cpp:type:: template<typename T> \
3269 MyContainer = std::vector<T>
3270 The example are rendered as follows.
3272 typedef std::vector<int> MyList
3274 A typedef-like declaration of a type.
3275 type MyContainer::const_iterator
3277 Declaration of a type alias with unspecified type.
3278 using MyType = std::unordered_map<int, std::string>
3280 Declaration of a type alias.
3281 template<typename T> using MyContainer = std::vector<T>
3283 .. cpp:enum:: unscoped enum declaration
3285 .. cpp:enum-struct:: scoped enum declaration
3287 .. cpp:enum-class:: scoped enum declaration
3289 Describe a (scoped) enum, possibly with the underlying type
3290 specified. Any enumerators declared inside an unscoped enum
3291 will be declared both in the enum scope and in the parent scope.
3292 Examples:
3293 .. cpp:enum:: MyEnum
3295 An unscoped enum.
3297 .. cpp:enum:: MySpecificEnum : long
3299 An unscoped enum with specified underlying type.
3301 .. cpp:enum-class:: MyScopedEnum
3303 A scoped enum.
3305 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3307 A scoped enum with non-default visibility, and with a specified
3309 underlying type.
3310 .. cpp:enumerator:: name
3312 .. cpp:enumerator:: name = constant
3314 Describe an enumerator, optionally with its value defined,
3315 e.g.,:
3316 .. cpp:enumerator:: MyEnum::myEnumerator
3318 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3320 .. cpp:union:: name
3322 Describe a union.
3323 New in version 1.8.
3325 .. cpp:concept:: template-parameter-list name
3328 WARNING:
3330 The support for concepts is experimental. It is based on the
3331 current draft standard and the Concepts Technical Specifica‐
3332 tion. The features may change as they evolve.
3333 Describe a concept. It must have exactly 1 template parameter
3335 list. The name may be a nested name. Example:
3336 .. cpp:concept:: template<typename It> std::Iterator
3338 Proxy to an element of a notional sequence that can be compared,
3340 indirected, or incremented.
3341 **Notation**
3343 .. cpp:var:: It r
3345 An lvalue.
3347 **Valid Expressions**
3349 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3351 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when
3352 :cpp:expr:`r` is incrementable.
3353 This will render as follows:
3355 template<typename It> concept std::Iterator
3357 Proxy to an element of a notional sequence that can be
3358 compared, indirected, or incremented.
3359 Notation
3361 It r An lvalue.
3363 Valid Expressions
3365 · *r, when r is dereferenceable.
3367 · ++r, with return type It&, when r is incrementable.
3369 New in version 1.5.
3371 Options
3374 Some directives support options:
3375 · :noindex:, see Basic Markup.
3377 · :tparam-line-spec:, for templated declarations. If specified, each
3379 template parameter will be rendered on a separate line.
3380 New in version 1.6.
3382 Anonymous Entities
3385 C++ supports anonymous namespaces, classes, enums, and unions. For the
3386 sake of documentation they must be given some name that starts with @,
3387 e.g., @42 or @data. These names can also be used in cross-references
3388 and (type) expressions, though nested symbols will be found even when
3389 omitted. The @... name will always be rendered as [anonymous] (possi‐
3390 bly as a link).
3391 Example:
3393 .. cpp:class:: Data
3395 .. cpp:union:: @data
3397 .. cpp:var:: int a
3399 .. cpp:var:: double b
3401 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
3403 This will be rendered as:
3405 class Data
3407 union [anonymous]
3409 int a
3411 double b
3413 Explicit ref: Data::[anonymous]::a. Short-hand ref: Data::a.
3415 New in version 1.8.
3417 Aliasing Declarations
3420 Sometimes it may be helpful list declarations elsewhere than their main
3421 documentation, e.g., when creating a synopsis of a class interface.
3422 The following directive can be used for this purpose.
3423 .. cpp:alias:: name or function signature
3425 Insert one or more alias declarations. Each entity can be speci‐
3426 fied as they can in the cpp:any role. If the name of a function
3427 is given (as opposed to the complete signature), then all over‐
3428 loads of the function will be listed.
3429 For example:
3431 .. cpp:alias:: Data::a
3433 overload_example::C::f
3434 becomes
3436 int a
3438 void f(double d) const
3440 void f(double d)
3442 void f(int i)
3444 void f()
3446 whereas:
3448 .. cpp:alias:: void overload_example::C::f(double d) const
3450 void overload_example::C::f(double d)
3451 becomes
3453 void f(double d) const
3455 void f(double d)
3457 New in version 2.0.
3459 Constrained Templates
3462 WARNING:
3463 The support for concepts is experimental. It is based on the current
3464 draft standard and the Concepts Technical Specification. The fea‐
3465 tures may change as they evolve.
3466 NOTE:
3468 Sphinx does not currently support requires clauses.
3469 Placeholders
3471 Declarations may use the name of a concept to introduce constrained
3472 template parameters, or the keyword auto to introduce unconstrained
3473 template parameters:
3474 .. cpp:function:: void f(auto &&arg)
3476 A function template with a single unconstrained template parameter.
3478 .. cpp:function:: void f(std::Iterator it)
3480 A function template with a single template parameter, constrained by the
3482 Iterator concept.
3483 Template Introductions
3485 Simple constrained function or class templates can be declared with a
3486 template introduction instead of a template parameter list:
3487 .. cpp:function:: std::Iterator{It} void advance(It &it)
3489 A function template with a template parameter constrained to be an
3491 Iterator.
3492 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3494 A class template with a template parameter constrained to be
3496 LessThanComparable.
3497 They are rendered as follows.
3499 std::Iterator{It} void advance(It &it)
3501 A function template with a template parameter constrained to be
3502 an Iterator.
3503 std::LessThanComparable{T} class MySortedContainer
3505 A class template with a template parameter constrained to be
3506 LessThanComparable.
3507 Note however that no checking is performed with respect to parameter
3509 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3510 tion even though it would not be valid C++.
3511 Inline Expressions and Types
3513 :cpp:expr:
3514 :cpp:texpr:
3516 Insert a C++ expression or type either as inline code (cpp:expr)
3517 or inline text (cpp:texpr). For example:
3518 .. cpp:var:: int a = 42
3520 .. cpp:function:: int f(int i)
3522 An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
3524 A type: :cpp:expr:`const MySortedContainer<int>&`
3526 (or as text :cpp:texpr:`const MySortedContainer<int>&`).
3527 will be rendered as follows:
3529 int a = 42
3531 int f(int i)
3533 An expression: a * f(a) (or as text: a * f(a)).
3535 A type: const MySortedContainer<int>& (or as text const MySort‐
3537 edContainer<int>&).
3538 New in version 1.7: The cpp:expr role.
3540 New in version 1.8: The cpp:texpr role.
3543 Namespacing
3546 Declarations in the C++ domain are as default placed in global scope.
3547 The current scope can be changed using three namespace directives.
3548 They manage a stack declarations where cpp:namespace resets the stack
3549 and changes a given scope.
3550 The cpp:namespace-push directive changes the scope to a given inner
3552 scope of the current one.
3553 The cpp:namespace-pop directive undoes the most recent cpp:names‐
3555 pace-push directive.
3556 .. cpp:namespace:: scope specification
3558 Changes the current scope for the subsequent objects to the
3559 given scope, and resets the namespace directive stack. Note
3560 that the namespace does not need to correspond to C++ names‐
3561 paces, but can end in names of classes, e.g.,:
3562 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3564 All subsequent objects will be defined as if their name were
3566 declared with the scope prepended. The subsequent cross-refer‐
3567 ences will be searched for starting in the current scope.
3568 Using NULL, 0, or nullptr as the scope will change to global
3570 scope.
3571 A namespace declaration can also be templated, e.g.,:
3573 .. cpp:class:: template<typename T> \
3575 std::vector
3576 .. cpp:namespace:: template<typename T> std::vector
3578 .. cpp:function:: std::size_t size() const
3580 declares size as a member function of the class template
3582 std::vector. Equivalently this could have been declared using:
3583 .. cpp:class:: template<typename T> \
3585 std::vector
3586 .. cpp:function:: std::size_t size() const
3588 or:
3590 .. cpp:class:: template<typename T> \
3592 std::vector
3593 .. cpp:namespace-push:: scope specification
3595 Change the scope relatively to the current scope. For example,
3596 after:
3597 .. cpp:namespace:: A::B
3599 .. cpp:namespace-push:: C::D
3601 the current scope will be A::B::C::D.
3603 New in version 1.4.
3605 .. cpp:namespace-pop::
3608 Undo the previous cpp:namespace-push directive (not just pop a
3609 scope). For example, after:
3610 .. cpp:namespace:: A::B
3612 .. cpp:namespace-push:: C::D
3614 .. cpp:namespace-pop::
3616 the current scope will be A::B (not A::B::C).
3618 If no previous cpp:namespace-push directive has been used, but
3620 only a cpp:namespace directive, then the current scope will be
3621 reset to global scope. That is, .. cpp:namespace:: A::B is
3622 equivalent to:
3623 .. cpp:namespace:: nullptr
3625 .. cpp:namespace-push:: A::B
3627 New in version 1.4.
3629 Info field lists
3632 The C++ directives support the following info fields (see also Info
3633 field lists):
3634 · param, parameter, arg, argument: Description of a parameter.
3636 · tparam: Description of a template parameter.
3638 · returns, return: Description of a return value.
3640 · throws, throw, exception: Description of a possibly thrown exception.
3642 Cross-referencing
3644 These roles link to the given declaration types:
3645 :cpp:any:
3647 :cpp:class:
3649 :cpp:struct:
3651 :cpp:func:
3653 :cpp:member:
3655 :cpp:var:
3657 :cpp:type:
3659 :cpp:concept:
3661 :cpp:enum:
3663 :cpp:enumerator:
3665 Reference a C++ declaration by name (see below for details).
3666 The name must be properly qualified relative to the position of
3667 the link.
3668 New in version 2.0: The cpp:struct role as alias for the
3670 cpp:class role.
3671 Note on References with Templates Parameters/Arguments
3674 These roles follow the Sphinx xref-syntax rules. This means
3676 care must be taken when referencing a (partial) template spe‐
3677 cialization, e.g. if the link looks like this:
3678 :cpp:class:`MyClass<int>`. This is interpreted as a link to
3679 int with a title of MyClass. In this case, escape the open‐
3680 ing angle bracket with a backslash, like this:
3681 :cpp:class:`MyClass\<int>`.
3682 When a custom title is not needed it may be useful to use the
3684 roles for inline expressions, cpp:expr and cpp:texpr, where
3685 angle brackets do not need escaping.
3686 Declarations without template parameters and template arguments
3688 For linking to non-templated declarations the name must be a nested
3689 name, e.g., f or MyClass::f.
3690 Overloaded (member) functions
3692 When a (member) function is referenced using just its name, the refer‐
3693 ence will point to an arbitrary matching overload. The cpp:any and
3694 cpp:func roles use an alternative format, which simply is a complete
3695 function declaration. This will resolve to the exact matching over‐
3696 load. As example, consider the following class declaration:
3697 class C
3699 void f(double d) const
3701 void f(double d)
3703 void f(int i)
3705 void f()
3707 References using the cpp:func role:
3709 · Arbitrary overload: C::f, C::f()
3711 · Also arbitrary overload: C::f(), C::f()
3713 · Specific overload: void C::f(), void C::f()
3715 · Specific overload: void C::f(int), void C::f(int)
3717 · Specific overload: void C::f(double), void C::f(double)
3719 · Specific overload: void C::f(double) const, void C::f(double) const
3721 Note that the add_function_parentheses configuration variable does not
3723 influence specific overload references.
3724 Templated declarations
3726 Assume the following declarations.
3727 class Wrapper
3729 template<typename TOuter> class Outer
3731 template<typename TInner> class Inner
3733 In general the reference must include the template parameter declara‐
3735 tions, and template arguments for the prefix of qualified names. For
3736 example:
3737 · template\<typename TOuter> Wrapper::Outer (template<typename TOuter>
3739 Wrapper::Outer)
3740 · template\<typename TOuter> template\<typename TInner> Wrap‐
3742 per::Outer<TOuter>::Inner (template<typename TOuter> template<type‐
3743 name TInner> Wrapper::Outer<TOuter>::Inner)
3744 Currently the lookup only succeed if the template parameter identifiers
3746 are equal strings. That is, template\<typename UOuter> Wrapper::Outer
3747 will not work.
3748 As a shorthand notation, if a template parameter list is omitted, then
3750 the lookup will assume either a primary template or a non-template, but
3751 not a partial template specialisation. This means the following refer‐
3752 ences work as well:
3753 · Wrapper::Outer (Wrapper::Outer)
3755 · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
3757 · template\<typename TInner> Wrapper::Outer::Inner (template<typename
3759 TInner> Wrapper::Outer::Inner)
3760 (Full) Template Specialisations
3762 Assume the following declarations.
3763 template<typename TOuter> class Outer
3765 template<typename TInner> class Inner
3767 template<> class Outer<int>
3769 template<typename TInner> class Inner
3771 template<> class Inner<bool>
3773 In general the reference must include a template parameter list for
3775 each template argument list. The full specialisation above can there‐
3776 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
3777 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
3778 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
3779 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
3780 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
3781 Partial Template Specialisations
3783 Assume the following declaration.
3784 template<typename T> class Outer<T *>
3786 References to partial specialisations must always include the template
3788 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
3789 template<typename T> Outer<T*>). Currently the lookup only succeed if
3790 the template parameter identifiers are equal strings.
3791 Configuration Variables
3793 See cpp-config.
3794 The Standard Domain
3796 The so-called “standard” domain collects all markup that doesn’t war‐
3797 rant a domain of its own. Its directives and roles are not prefixed
3798 with a domain name.
3799 The standard domain is also where custom object descriptions, added
3801 using the add_object_type() API, are placed.
3802 There is a set of directives allowing documenting command-line pro‐
3804 grams:
3805 .. option:: name args, name args, ...
3807 Describes a command line argument or switch. Option argument
3808 names should be enclosed in angle brackets. Examples:
3809 .. option:: dest_dir
3811 Destination directory.
3813 .. option:: -m <module>, --module <module>
3815 Run a module as a script.
3817 The directive will create cross-reference targets for the given
3819 options, referenceable by option (in the example case, you’d use
3820 something like :option:`dest_dir`, :option:`-m`, or
3821 :option:`--module`).
3822 cmdoption directive is a deprecated alias for the option direc‐
3824 tive.
3825 .. envvar:: name
3827 Describes an environment variable that the documented code or
3828 program uses or defines. Referenceable by envvar.
3829 .. program:: name
3831 Like py:currentmodule, this directive produces no output.
3832 Instead, it serves to notify Sphinx that all following option
3833 directives document options for the program called name.
3834 If you use program, you have to qualify the references in your
3836 option roles by the program name, so if you have the following
3837 situation
3838 .. program:: rm
3840 .. option:: -r
3842 Work recursively.
3844 .. program:: svn
3846 .. option:: -r revision
3848 Specify the revision to work upon.
3850 then :option:`rm -r` would refer to the first option, while
3852 :option:`svn -r` would refer to the second one.
3853 The program name may contain spaces (in case you want to docu‐
3855 ment subcommands like svn add and svn commit separately).
3856 New in version 0.5.
3858 There is also a very generic object description directive, which is not
3861 tied to any domain:
3862 .. describe:: text
3864 .. object:: text
3866 This directive produces the same formatting as the specific ones
3867 provided by domains, but does not create index entries or
3868 cross-referencing targets. Example:
3869 .. describe:: PAPER
3871 You can set this variable to select a paper size.
3873 The JavaScript Domain
3875 The JavaScript domain (name js) provides the following directives:
3876 .. js:module:: name
3878 This directive sets the module name for object declarations that
3879 follow after. The module name is used in the global module index
3880 and in cross references. This directive does not create an
3881 object heading like py:class would, for example.
3882 By default, this directive will create a linkable entity and
3884 will cause an entry in the global module index, unless the noin‐
3885 dex option is specified. If this option is specified, the
3886 directive will only update the current module name.
3887 New in version 1.6.
3889 .. js:function:: name(signature)
3892 Describes a JavaScript function or method. If you want to
3893 describe arguments as optional use square brackets as documented
3894 for Python signatures.
3895 You can use fields to give more details about arguments and
3897 their expected types, errors which may be thrown by the func‐
3898 tion, and the value being returned:
3899 .. js:function:: $.getJSON(href, callback[, errback])
3901 :param string href: An URI to the location of the resource.
3903 :param callback: Gets called with the object.
3904 :param errback:
3905 Gets called in case the request fails. And a lot of other
3906 text so we need multiple lines.
3907 :throws SomeError: For whatever reason in that case.
3908 :returns: Something.
3909 This is rendered as:
3911 $.getJSON(href, callback[, errback])
3913 Arguments
3915 · href (string) – An URI to the location of the
3917 resource.
3918 · callback – Gets called with the object.
3920 · errback – Gets called in case the request
3922 fails. And a lot of other text so we need
3923 multiple lines.
3924 Throws SomeError – For whatever reason in that case.
3926 Returns
3928 Something.
3929 .. js:method:: name(signature)
3931 This directive is an alias for js:function, however it describes
3932 a function that is implemented as a method on a class object.
3933 New in version 1.6.
3935 .. js:class:: name
3938 Describes a constructor that creates an object. This is basi‐
3939 cally like a function but will show up with a class prefix:
3940 .. js:class:: MyAnimal(name[, age])
3942 :param string name: The name of the animal
3944 :param number age: an optional age for the animal
3945 This is rendered as:
3947 class MyAnimal(name[, age])
3949 Arguments
3951 · name (string) – The name of the animal
3953 · age (number) – an optional age for the animal
3955 .. js:data:: name
3957 Describes a global variable or constant.
3958 .. js:attribute:: object.name
3960 Describes the attribute name of object.
3961 These roles are provided to refer to the described objects:
3963 :js:mod:
3965 :js:func:
3967 :js:meth:
3969 :js:class:
3971 :js:data:
3973 :js:attr:
3975 The reStructuredText domain
3977 The reStructuredText domain (name rst) provides the following direc‐
3978 tives:
3979 .. rst:directive:: name
3981 Describes a reST directive. The name can be a single directive
3982 name or actual directive syntax (.. prefix and :: suffix) with
3983 arguments that will be rendered differently. For example:
3984 .. rst:directive:: foo
3986 Foo description.
3988 .. rst:directive:: .. bar:: baz
3990 Bar description.
3992 will be rendered as:
3994 .. foo::
3996 Foo description.
3997 .. bar:: baz
3999 Bar description.
4000 .. rst:directive:option:: name
4002 Describes an option for reST directive. The name can be a sin‐
4003 gle option name or option name with arguments which separated
4004 with colon (:). For example:
4005 .. rst:directive:: toctree
4007 .. rst:directive:option:: caption: caption of ToC
4009 .. rst:directive:option:: glob
4011 will be rendered as:
4013 .. toctree::
4015 :caption: caption of ToC
4017 :glob:
4019 options
4021 :type: description of argument (text)
4023 Describe the type of option value.
4024 For example:
4026 .. rst:directive:: toctree
4028 .. rst:directive:option:: maxdepth
4030 :type: integer or no value
4031 New in version 2.1.
4033 .. rst:role:: name
4036 Describes a reST role. For example:
4037 .. rst:role:: foo
4039 Foo description.
4041 will be rendered as:
4043 :foo: Foo description.
4045 These roles are provided to refer to the described objects:
4047 :rst:dir:
4049 :rst:role:
4051 The Math Domain
4053 The math domain (name math) provides the following roles:
4054 .. rst:role:: math:numref
4056 Role for cross-referencing equations defined by math directive via
4057 their label. Example:
4058 .. math:: e^{i\pi} + 1 = 0
4060 :label: euler
4061 Euler's identity, equation :math:numref:`euler`, was elected one of the
4063 most beautiful mathematical formulas.
4064 New in version 1.8.
4066 More domains
4069 The sphinx-contrib repository contains more domains available as exten‐
4070 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4071 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4072 dqn, Go, Jinja, Operation, and Scala.
4073
4075 Markdown is a lightweight markup language with a simplistic plain text
4076 formatting syntax. It exists in many syntactically different flavors.
4077 To support Markdown-based documentation, Sphinx can use recommonmark.
4078 recommonmark is a Docutils bridge to CommonMark-py, a Python package
4079 for parsing the CommonMark Markdown flavor.
4080 Configuration
4082 To configure your Sphinx project for Markdown support, proceed as fol‐
4083 lows:
4084 1. Install the Markdown parser recommonmark:
4086 pip install --upgrade recommonmark
4088 NOTE:
4090 The configuration as explained here requires recommonmark version
4091 0.5.0 or later.
4092 2. Add recommonmark to the list of configured extensions:
4094 extensions = ['recommonmark']
4096 Changed in version 1.8: Version 1.8 deprecates and version 3.0
4098 removes the source_parsers configuration variable that was used by
4099 older recommonmark versions.
4100 3. If you want to use Markdown files with extensions other than .md,
4103 adjust the source_suffix variable. The following example configures
4104 Sphinx to parse all files with the extensions .md and .txt as Mark‐
4105 down:
4106 source_suffix = {
4108 '.rst': 'restructuredtext',
4109 '.txt': 'markdown',
4110 '.md': 'markdown',
4111 }
4112 4. You can further configure recommonmark to allow custom syntax that
4114 standard CommonMark doesn’t support. Read more in the recommonmark
4115 documentation.
4116
4118 The configuration directory must contain a file named conf.py. This
4119 file (containing Python code) is called the “build configuration file”
4120 and contains (almost) all configuration needed to customize Sphinx
4121 input and output behavior.
4122 An optional file docutils.conf can be added to the configuration
4123 directory to adjust Docutils configuration if not otherwise overrid‐
4124 den or set by Sphinx.
4125 The configuration file is executed as Python code at build time (using
4127 execfile(), and with the current directory set to its containing direc‐
4128 tory), and therefore can execute arbitrarily complex code. Sphinx then
4129 reads simple names from the file’s namespace as its configuration.
4130 Important points to note:
4132 · If not otherwise documented, values must be strings, and their
4134 default is the empty string.
4135 · The term “fully-qualified name” refers to a string that names an
4137 importable Python object inside a module; for example, the FQN
4138 "sphinx.builders.Builder" means the Builder class in the
4139 sphinx.builders module.
4140 · Remember that document names use / as the path separator and don’t
4142 contain the file name extension.
4143 · Since conf.py is read as a Python file, the usual rules apply for
4145 encodings and Unicode support.
4146 · The contents of the config namespace are pickled (so that Sphinx can
4148 find out when configuration changes), so it may not contain unpick‐
4149 leable values – delete them from the namespace with del if appropri‐
4150 ate. Modules are removed automatically, so you don’t need to del
4151 your imports after use.
4152 · There is a special object named tags available in the config file.
4154 It can be used to query and change the tags (see tags). Use
4155 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4156 change. Only tags set via the -t command-line option or via
4157 tags.add('tag') can be queried using tags.has('tag'). Note that the
4158 current builder tag is not available in conf.py, as it is created
4159 after the builder is initialized.
4160 Project information
4162 project
4163 The documented project’s name.
4164 author The author name(s) of the document. The default value is
4166 'unknown'.
4167 copyright
4169 A copyright statement in the style '2008, Author Name'.
4170 version
4172 The major project version, used as the replacement for |ver‐
4173 sion|. For example, for the Python documentation, this may be
4174 something like 2.6.
4175 release
4177 The full project version, used as the replacement for |release|
4178 and e.g. in the HTML templates. For example, for the Python
4179 documentation, this may be something like 2.6.0rc1.
4180 If you don’t need the separation provided between version and
4182 release, just set them both to the same value.
4183 General configuration
4185 extensions
4186 A list of strings that are module names of extensions. These can
4187 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4188 ones.
4189 Note that you can extend sys.path within the conf file if your
4191 extensions live in another directory – but make sure you use
4192 absolute paths. If your extension path is relative to the con‐
4193 figuration directory, use os.path.abspath() like so:
4194 import sys, os
4196 sys.path.append(os.path.abspath('sphinxext'))
4198 extensions = ['extname']
4200 That way, you can load an extension called extname from the sub‐
4202 directory sphinxext.
4203 The configuration file itself can be an extension; for that, you
4205 only need to provide a setup() function in it.
4206 source_suffix
4208 The file extensions of source files. Sphinx considers the files
4209 with this suffix as sources. The value can be a dictionary map‐
4210 ping file extensions to file types. For example:
4211 source_suffix = {
4213 '.rst': 'restructuredtext',
4214 '.txt': 'restructuredtext',
4215 '.md': 'markdown',
4216 }
4217 By default, Sphinx only supports 'restructuredtext' file type.
4219 You can add a new file type using source parser extensions.
4220 Please read a document of the extension to know which file type
4221 the extension supports.
4222 The value may also be a list of file extensions: then Sphinx
4224 will consider that they all map to the 'restructuredtext' file
4225 type.
4226 Default is {'.rst': 'restructuredtext'}.
4228 NOTE:
4230 file extensions have to start with a dot (e.g. .rst).
4231 Changed in version 1.3: Can now be a list of extensions.
4233 Changed in version 1.8: Support file type mapping
4236 source_encoding
4239 The encoding of all reST source files. The recommended encod‐
4240 ing, and the default value, is 'utf-8-sig'.
4241 New in version 0.5: Previously, Sphinx accepted only UTF-8
4243 encoded sources.
4244 source_parsers
4247 If given, a dictionary of parser classes for different source
4248 suffices. The keys are the suffix, the values can be either a
4249 class or a string giving a fully-qualified name of a parser
4250 class. The parser class can be either docutils.parsers.Parser
4251 or sphinx.parsers.Parser. Files with a suffix that is not in
4252 the dictionary will be parsed with the default reStructuredText
4253 parser.
4254 For example:
4256 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4258 NOTE:
4260 Refer to /usage/markdown for more information on using Mark‐
4261 down with Sphinx.
4262 New in version 1.3.
4264 Deprecated since version 1.8: Now Sphinx provides an API
4267 Sphinx.add_source_parser() to register a source parser. Please
4268 use it instead.
4269 master_doc
4272 The document name of the “master” document, that is, the docu‐
4273 ment that contains the root toctree directive. Default is
4274 'index'.
4275 Changed in version 2.0: The default is changed to 'index' from
4277 'contents'.
4278 exclude_patterns
4281 A list of glob-style patterns that should be excluded when look‐
4282 ing for source files. [1] They are matched against the source
4283 file names relative to the source directory, using slashes as
4284 directory separators on all platforms.
4285 Example patterns:
4287 · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4289 entry in unused_docs)
4290 · 'library/xml' – ignores the library/xml directory
4292 · 'library/xml*' – ignores all files and directories starting
4294 with library/xml
4295 · '**/.svn' – ignores all .svn directories
4297 exclude_patterns is also consulted when looking for static files
4299 in html_static_path and html_extra_path.
4300 New in version 1.0.
4302 templates_path
4305 A list of paths that contain extra templates (or templates that
4306 overwrite builtin/theme-specific templates). Relative paths are
4307 taken as relative to the configuration directory.
4308 Changed in version 1.3: As these files are not meant to be
4310 built, they are automatically added to exclude_patterns.
4311 template_bridge
4314 A string with the fully-qualified name of a callable (or simply
4315 a class) that returns an instance of TemplateBridge. This
4316 instance is then used to render HTML documents, and possibly the
4317 output of other builders (currently the changes builder). (Note
4318 that the template bridge must be made theme-aware if HTML themes
4319 are to be used.)
4320 rst_epilog
4322 A string of reStructuredText that will be included at the end of
4323 every source file that is read. This is a possible place to add
4324 substitutions that should be available in every file (another
4325 being rst_prolog). An example:
4326 rst_epilog = """
4328 .. |psf| replace:: Python Software Foundation
4329 """
4330 New in version 0.6.
4332 rst_prolog
4335 A string of reStructuredText that will be included at the begin‐
4336 ning of every source file that is read. This is a possible
4337 place to add substitutions that should be available in every
4338 file (another being rst_epilog). An example:
4339 rst_prolog = """
4341 .. |psf| replace:: Python Software Foundation
4342 """
4343 New in version 1.0.
4345 primary_domain
4348 The name of the default domain. Can also be None to disable a
4349 default domain. The default is 'py'. Those objects in other
4350 domains (whether the domain name is given explicitly, or
4351 selected by a default-domain directive) will have the domain
4352 name explicitly prepended when named (e.g., when the default
4353 domain is C, Python functions will be named “Python function”,
4354 not just “function”).
4355 New in version 1.0.
4357 default_role
4360 The name of a reST role (builtin or Sphinx extension) to use as
4361 the default role, that is, for text marked up `like this`. This
4362 can be set to 'py:obj' to make `filter` a cross-reference to the
4363 Python function “filter”. The default is None, which doesn’t
4364 reassign the default role.
4365 The default role can always be set within individual documents
4367 using the standard reST default-role directive.
4368 New in version 0.4.
4370 keep_warnings
4373 If true, keep warnings as “system message” paragraphs in the
4374 built documents. Regardless of this setting, warnings are
4375 always written to the standard error stream when sphinx-build is
4376 run.
4377 The default is False, the pre-0.5 behavior was to always keep
4379 them.
4380 New in version 0.5.
4382 suppress_warnings
4385 A list of warning types to suppress arbitrary warning messages.
4386 Sphinx supports following warning types:
4388 · app.add_node
4390 · app.add_directive
4392 · app.add_role
4394 · app.add_generic_role
4396 · app.add_source_parser
4398 · download.not_readable
4400 · image.not_readable
4402 · ref.term
4404 · ref.ref
4406 · ref.numref
4408 · ref.keyword
4410 · ref.option
4412 · ref.citation
4414 · ref.footnote
4416 · ref.doc
4418 · ref.python
4420 · misc.highlighting_failure
4422 · toc.secnum
4424 · epub.unknown_project_files
4426 · autosectionlabel.*
4428 You can choose from these types.
4430 Now, this option should be considered experimental.
4432 New in version 1.4.
4434 Changed in version 1.5: Added misc.highlighting_failure
4437 Changed in version 1.5.1: Added epub.unknown_project_files
4440 Changed in version 1.6: Added ref.footnote
4443 Changed in version 2.1: Added autosectionlabel.*
4446 needs_sphinx
4449 If set to a major.minor version string like '1.1', Sphinx will
4450 compare it with its version and refuse to build if it is too
4451 old. Default is no requirement.
4452 New in version 1.0.
4454 Changed in version 1.4: also accepts micro version string
4457 needs_extensions
4460 This value can be a dictionary specifying version requirements
4461 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4462 contrib.something': '1.5'}. The version strings should be in
4463 the form major.minor. Requirements do not have to be specified
4464 for all extensions, only for those you want to check.
4465 This requires that the extension specifies its version to Sphinx
4467 (see dev-extensions for how to do that).
4468 New in version 1.3.
4470 manpages_url
4473 A URL to cross-reference manpage directives. If this is defined
4474 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4475 role will link to <https://manpages.debian.org/man(1)>. The pat‐
4476 terns available are:
4477 · page - the manual page (man)
4479 · section - the manual section (1)
4481 · path - the original manual page and section specified
4483 (man(1))
4484 This also supports manpages specified as man.1.
4486 NOTE:
4488 This currently affects only HTML writers but could be
4489 expanded in the future.
4490 New in version 1.7.
4492 nitpicky
4495 If true, Sphinx will warn about all references where the target
4496 cannot be found. Default is False. You can activate this mode
4497 temporarily using the -n command-line switch.
4498 New in version 1.0.
4500 nitpick_ignore
4503 A list of (type, target) tuples (by default empty) that should
4504 be ignored when generating warnings in “nitpicky mode”. Note
4505 that type should include the domain name if present. Example
4506 entries would be ('py:func', 'int') or ('envvar',
4507 'LD_LIBRARY_PATH').
4508 New in version 1.1.
4510 numfig If true, figures, tables and code-blocks are automatically num‐
4513 bered if they have a caption. The numref role is enabled.
4514 Obeyed so far only by HTML and LaTeX builders. Default is False.
4515 NOTE:
4517 The LaTeX builder always assigns numbers whether this option
4518 is enabled or not.
4519 New in version 1.3.
4521 numfig_format
4524 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4525 tion' to strings that are used for format of figure numbers. As
4526 a special character, %s will be replaced to figure number.
4527 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4529 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4530 New in version 1.3.
4532 numfig_secnum_depth
4535 · if set to 0, figures, tables and code-blocks are continuously
4537 numbered starting at 1.
4538 · if 1 (default) numbers will be x.1, x.2, … with x the section
4540 number (top level sectioning; no x. if no section). This nat‐
4541 urally applies only if section numbering has been activated
4542 via the :numbered: option of the toctree directive.
4543 · 2 means that numbers will be x.y.1, x.y.2, … if located in a
4545 sub-section (but still x.1, x.2, … if located directly under a
4546 section and 1, 2, … if not in any top level section.)
4547 · etc…
4549 New in version 1.3.
4551 Changed in version 1.7: The LaTeX builder obeys this setting (if
4554 numfig is set to True).
4555 smartquotes
4558 If true, the Docutils Smart Quotes transform, originally based
4559 on SmartyPants (limited to English) and currently applying to
4560 many languages, will be used to convert quotes and dashes to
4561 typographically correct entities. Default: True.
4562 New in version 1.6.6: It replaces deprecated
4564 html_use_smartypants. It applies by default to all builders
4565 except man and text (see smartquotes_excludes.)
4566 A docutils.conf file located in the configuration directory (or
4569 a global ~/.docutils file) is obeyed unconditionally if it deac‐
4570 tivates smart quotes via the corresponding Docutils option. But
4571 if it activates them, then smartquotes does prevail.
4572 smartquotes_action
4574 This string, for use with Docutils 0.14 or later, customizes the
4575 Smart Quotes transform. See the file smartquotes.py at the
4576 Docutils repository for details. The default 'qDe' educates
4577 normal quote characters ", ', em- and en-Dashes ---, --, and
4578 ellipses ....
4579 New in version 1.6.6.
4581 smartquotes_excludes
4584 This is a dict whose default is:
4585 {'languages': ['ja'], 'builders': ['man', 'text']}
4587 Each entry gives a sufficient condition to ignore the
4589 smartquotes setting and deactivate the Smart Quotes transform.
4590 Accepted keys are as above 'builders' or 'languages'. The val‐
4591 ues are lists.
4592 NOTE:
4594 Currently, in case of invocation of make with multiple tar‐
4595 gets, the first target name is the only one which is tested
4596 against the 'builders' entry and it decides for all. Also, a
4597 make text following make html needs to be issued in the form
4598 make text O="-E" to force re-parsing of source files, as the
4599 cached ones are already transformed. On the other hand the
4600 issue does not arise with direct usage of sphinx-build as it
4601 caches (in its default usage) the parsed source files in per
4602 builder locations.
4603 HINT:
4605 An alternative way to effectively deactivate (or customize)
4606 the smart quotes for a given builder, for example latex, is
4607 to use make this way:
4608 make latex O="-D smartquotes_action="
4610 This can follow some make html with no problem, in contrast
4612 to the situation from the prior note. It requires Docutils
4613 0.14 or later.
4614 New in version 1.6.6.
4616 tls_verify
4619 If true, Sphinx verifies server certifications. Default is
4620 True.
4621 New in version 1.5.
4623 tls_cacerts
4626 A path to a certification file of CA or a path to directory
4627 which contains the certificates. This also allows a dictionary
4628 mapping hostname to the path to certificate file. The certifi‐
4629 cates are used to verify server certifications.
4630 New in version 1.5.
4632 TIP:
4635 Sphinx uses requests as a HTTP library internally. There‐
4636 fore, Sphinx refers a certification file on the directory
4637 pointed REQUESTS_CA_BUNDLE environment variable if tls_cac‐
4638 erts not set.
4639 today
4641 today_fmt
4643 These values determine how to format the current date, used as
4644 the replacement for |today|.
4645 · If you set today to a non-empty value, it is used.
4647 · Otherwise, the current time is formatted using time.strftime()
4649 and the format given in today_fmt.
4650 The default is now today and a today_fmt of '%B %d, %Y' (or, if
4652 translation is enabled with language, an equivalent format for
4653 the selected locale).
4654 highlight_language
4656 The default language to highlight source code in. The default
4657 is 'python3'. The value should be a valid Pygments lexer name,
4658 see code-examples for more details.
4659 New in version 0.5.
4661 Changed in version 1.4: The default is now 'default'. It is sim‐
4664 ilar to 'python3'; it is mostly a superset of 'python' but it
4665 fallbacks to 'none' without warning if failed. 'python3' and
4666 other languages will emit warning if failed. If you prefer
4667 Python 2 only highlighting, you can set it back to 'python'.
4668 highlight_options
4671 A dictionary of options that modify how the lexer specified by
4672 highlight_language generates highlighted source code. These are
4673 lexer-specific; for the options understood by each, see the
4674 Pygments documentation.
4675 New in version 1.3.
4677 pygments_style
4680 The style name to use for Pygments highlighting of source code.
4681 If not set, either the theme’s default style or 'sphinx' is
4682 selected for HTML output.
4683 Changed in version 0.3: If the value is a fully-qualified name
4685 of a custom Pygments style class, this is then used as custom
4686 style.
4687 add_function_parentheses
4690 A boolean that decides whether parentheses are appended to func‐
4691 tion and method role text (e.g. the content of :func:`input`) to
4692 signify that the name is callable. Default is True.
4693 add_module_names
4695 A boolean that decides whether module names are prepended to all
4696 object names (for object types where a “module” of some kind is
4697 defined), e.g. for py:function directives. Default is True.
4698 show_authors
4700 A boolean that decides whether codeauthor and sectionauthor
4701 directives produce any output in the built files.
4702 modindex_common_prefix
4704 A list of prefixes that are ignored for sorting the Python mod‐
4705 ule index (e.g., if this is set to ['foo.'], then foo.bar is
4706 shown under B, not F). This can be handy if you document a
4707 project that consists of a single package. Works only for the
4708 HTML builder currently. Default is [].
4709 New in version 0.6.
4711 trim_footnote_reference_space
4714 Trim spaces before footnote references that are necessary for
4715 the reST parser to recognize the footnote, but do not look too
4716 nice in the output.
4717 New in version 0.6.
4719 trim_doctest_flags
4722 If true, doctest flags (comments looking like # doctest: FLAG,
4723 ...) at the ends of lines and <BLANKLINE> markers are removed
4724 for all code blocks showing interactive Python sessions (i.e.
4725 doctests). Default is True. See the extension doctest for more
4726 possibilities of including doctests.
4727 New in version 1.0.
4729 Changed in version 1.1: Now also removes <BLANKLINE>.
4732 Options for internationalization
4735 These options influence Sphinx’s Native Language Support. See the doc‐
4736 umentation on intl for details.
4737 language
4739 The code for the language the docs are written in. Any text
4740 automatically generated by Sphinx will be in that language.
4741 Also, Sphinx will try to substitute individual paragraphs from
4742 your documents with the translation sets obtained from
4743 locale_dirs. Sphinx will search language-specific figures named
4744 by figure_language_filename and substitute them for original
4745 figures. In the LaTeX builder, a suitable language will be
4746 selected as an option for the Babel package. Default is None,
4747 which means that no translation will be done.
4748 New in version 0.5.
4750 Changed in version 1.4: Support figure substitution
4753 Currently supported languages by Sphinx are:
4756 · bn – Bengali
4758 · ca – Catalan
4760 · cs – Czech
4762 · da – Danish
4764 · de – German
4766 · en – English
4768 · es – Spanish
4770 · et – Estonian
4772 · eu – Basque
4774 · fa – Iranian
4776 · fi – Finnish
4778 · fr – French
4780 · he – Hebrew
4782 · hr – Croatian
4784 · hu – Hungarian
4786 · id – Indonesian
4788 · it – Italian
4790 · ja – Japanese
4792 · ko – Korean
4794 · lt – Lithuanian
4796 · lv – Latvian
4798 · mk – Macedonian
4800 · nb_NO – Norwegian Bokmal
4802 · ne – Nepali
4804 · nl – Dutch
4806 · pl – Polish
4808 · pt_BR – Brazilian Portuguese
4810 · pt_PT – European Portuguese
4812 · ru – Russian
4814 · si – Sinhala
4816 · sk – Slovak
4818 · sl – Slovenian
4820 · sv – Swedish
4822 · tr – Turkish
4824 · uk_UA – Ukrainian
4826 · vi – Vietnamese
4828 · zh_CN – Simplified Chinese
4830 · zh_TW – Traditional Chinese
4832 locale_dirs
4834 New in version 0.5.
4835 Directories in which to search for additional message catalogs
4838 (see language), relative to the source directory. The directo‐
4839 ries on this path are searched by the standard gettext module.
4840 Internal messages are fetched from a text domain of sphinx; so
4842 if you add the directory ./locale to this setting, the message
4843 catalogs (compiled from .po format using msgfmt) must be in
4844 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
4845 individual documents depends on gettext_compact.
4846 The default is ['locales'].
4848 Changed in version 1.5: Use locales directory as a default value
4850 gettext_compact
4853 New in version 1.1.
4854 If true, a document’s text domain is its docname if it is a
4857 top-level project file and its very base directory otherwise.
4858 By default, the document markup/code.rst ends up in the markup
4860 text domain. With this option set to False, it is markup/code.
4861 gettext_uuid
4863 If true, Sphinx generates uuid information for version tracking
4864 in message catalogs. It is used for:
4865 · Add uid line for each msgids in .pot files.
4867 · Calculate similarity between new msgids and previously saved
4869 old msgids. This calculation takes a long time.
4870 If you want to accelerate the calculation, you can use
4872 python-levenshtein 3rd-party package written in C by using pip
4873 install python-levenshtein.
4874 The default is False.
4876 New in version 1.3.
4878 gettext_location
4881 If true, Sphinx generates location information for messages in
4882 message catalogs.
4883 The default is True.
4885 New in version 1.3.
4887 gettext_auto_build
4890 If true, Sphinx builds mo file for each translation catalog
4891 files.
4892 The default is True.
4894 New in version 1.3.
4896 gettext_additional_targets
4899 To specify names to enable gettext extracting and translation
4900 applying for i18n additionally. You can specify below names:
4901 Index index terms
4903 Literal-block
4905 literal blocks: :: and code-block.
4906 Doctest-block
4908 doctest block
4909 Raw raw content
4911 Image image/figure uri and alt
4913 For example: gettext_additional_targets = ['literal-block',
4915 'image'].
4916 The default is [].
4918 New in version 1.3.
4920 figure_language_filename
4923 The filename format for language-specific figures. The default
4924 value is {root}.{language}{ext}. It will be expanded to
4925 dirname/filename.en.png from .. image:: dirname/filename.png.
4926 The available format tokens are:
4927 · {root} - the filename, including any path component, without
4929 the file extension, e.g. dirname/filename
4930 · {path} - the directory path component of the filename, with a
4932 trailing slash if non-empty, e.g. dirname/
4933 · {basename} - the filename without the directory path or file
4935 extension components, e.g. filename
4936 · {ext} - the file extension, e.g. .png
4938 · {language} - the translation language, e.g. en
4940 For example, setting this to {path}{language}/{basename}{ext}
4942 will expand to dirname/en/filename.png instead.
4943 New in version 1.4.
4945 Changed in version 1.5: Added {path} and {basename} tokens.
4948 Options for Math
4951 These options influence Math notations.
4952 math_number_all
4954 Set this option to True if you want all displayed math to be
4955 numbered. The default is False.
4956 math_eqref_format
4958 A string used for formatting the labels of references to equa‐
4959 tions. The {number} place-holder stands for the equation num‐
4960 ber.
4961 Example: 'Eq.{number}' gets rendered as, for example, Eq.10.
4963 math_numfig
4965 If True, displayed math equations are numbered across pages when
4966 numfig is enabled. The numfig_secnum_depth setting is
4967 respected. The eq, not numref, role must be used to reference
4968 equation numbers. Default is True.
4969 New in version 1.7.
4971 Options for HTML output
4974 These options influence HTML as well as HTML Help output, and other
4975 builders that use Sphinx’s HTMLWriter class.
4976 html_theme
4978 The “theme” that the HTML output should use. See the section
4979 about theming. The default is 'alabaster'.
4980 New in version 0.6.
4982 html_theme_options
4985 A dictionary of options that influence the look and feel of the
4986 selected theme. These are theme-specific. For the options
4987 understood by the builtin themes, see this section.
4988 New in version 0.6.
4990 html_theme_path
4993 A list of paths that contain custom themes, either as subdirec‐
4994 tories or as zip files. Relative paths are taken as relative to
4995 the configuration directory.
4996 New in version 0.6.
4998 html_style
5001 The style sheet to use for HTML pages. A file of that name must
5002 exist either in Sphinx’s static/ path, or in one of the custom
5003 paths given in html_static_path. Default is the stylesheet
5004 given by the selected theme. If you only want to add or over‐
5005 ride a few things compared to the theme’s stylesheet, use CSS
5006 @import to import the theme’s stylesheet.
5007 html_title
5009 The “title” for HTML documentation generated with Sphinx’s own
5010 templates. This is appended to the <title> tag of individual
5011 pages, and used in the navigation bar as the “topmost” element.
5012 It defaults to '<project> v<revision> documentation'.
5013 html_short_title
5015 A shorter “title” for the HTML docs. This is used in for links
5016 in the header and in the HTML Help docs. If not given, it
5017 defaults to the value of html_title.
5018 New in version 0.4.
5020 html_baseurl
5023 The URL which points to the root of the HTML documentation. It
5024 is used to indicate the location of document like canonical_url.
5025 New in version 1.8.
5027 html_context
5030 A dictionary of values to pass into the template engine’s con‐
5031 text for all pages. Single values can also be put in this dic‐
5032 tionary using the -A command-line option of sphinx-build.
5033 New in version 0.5.
5035 html_logo
5038 If given, this must be the name of an image file (path relative
5039 to the configuration directory) that is the logo of the docs.
5040 It is placed at the top of the sidebar; its width should there‐
5041 fore not exceed 200 pixels. Default: None.
5042 New in version 0.4.1: The image file will be copied to the
5044 _static directory of the output HTML, but only if the file does
5045 not already exist there.
5046 html_favicon
5049 If given, this must be the name of an image file (path relative
5050 to the configuration directory) that is the favicon of the docs.
5051 Modern browsers use this as the icon for tabs, windows and book‐
5052 marks. It should be a Windows-style icon file (.ico), which is
5053 16x16 or 32x32 pixels large. Default: None.
5054 New in version 0.4: The image file will be copied to the _static
5056 directory of the output HTML, but only if the file does not
5057 already exist there.
5058 html_css_files
5061 A list of CSS files. The entry must be a filename string or a
5062 tuple containing the filename string and the attributes dictio‐
5063 nary. The filename must be relative to the html_static_path, or
5064 a full URI with scheme like http://example.org/style.css. The
5065 attributes is used for attributes of <link> tag. It defaults to
5066 an empty list.
5067 Example:
5069 html_css_files = ['custom.css'
5071 'https://example.com/css/custom.css',
5072 ('print.css', {'media': 'print'})]
5073 New in version 1.8.
5075 html_js_files
5078 A list of JavaScript filename. The entry must be a filename
5079 string or a tuple containing the filename string and the
5080 attributes dictionary. The filename must be relative to the
5081 html_static_path, or a full URI with scheme like http://exam‐
5082 ple.org/script.js. The attributes is used for attributes of
5083 <script> tag. It defaults to an empty list.
5084 Example:
5086 html_js_files = ['script.js',
5088 'https://example.com/scripts/custom.js',
5089 ('custom.js', {'async': 'async'})]
5090 New in version 1.8.
5092 html_static_path
5095 A list of paths that contain custom static files (such as style
5096 sheets or script files). Relative paths are taken as relative
5097 to the configuration directory. They are copied to the output’s
5098 _static directory after the theme’s static files, so a file
5099 named default.css will overwrite the theme’s default.css.
5100 As these files are not meant to be built, they are automatically
5102 excluded from source files.
5103 NOTE:
5105 For security reasons, dotfiles under html_static_path will
5106 not be copied. If you would like to copy them intentionally,
5107 please add each filepath to this setting:
5108 html_static_path = ['_static', '_static/.htaccess']
5110 Another way to do that, you can also use html_extra_path. It
5112 allows to copy dotfiles under the directories.
5113 Changed in version 0.4: The paths in html_static_path can now
5115 contain subdirectories.
5116 Changed in version 1.0: The entries in html_static_path can now
5119 be single files.
5120 Changed in version 1.8: The files under html_static_path are
5123 excluded from source files.
5124 html_extra_path
5127 A list of paths that contain extra files not directly related to
5128 the documentation, such as robots.txt or .htaccess. Relative
5129 paths are taken as relative to the configuration directory.
5130 They are copied to the output directory. They will overwrite
5131 any existing file of the same name.
5132 As these files are not meant to be built, they are automatically
5134 excluded from source files.
5135 New in version 1.2.
5137 Changed in version 1.4: The dotfiles in the extra directory will
5140 be copied to the output directory. And it refers
5141 exclude_patterns on copying extra files and directories, and
5142 ignores if path matches to patterns.
5143 html_last_updated_fmt
5146 If this is not None, a ‘Last updated on:’ timestamp is inserted
5147 at every page bottom, using the given strftime() format. The
5148 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5149 equivalent).
5150 html_use_smartypants
5152 If true, quotes and dashes are converted to typographically cor‐
5153 rect entities. Default: True.
5154 Deprecated since version 1.6: To disable smart quotes, use
5156 rather smartquotes.
5157 html_add_permalinks
5160 Sphinx will add “permalinks” for each heading and description
5161 environment as paragraph signs that become visible when the
5162 mouse hovers over them.
5163 This value determines the text for the permalink; it defaults to
5165 "¶". Set it to None or the empty string to disable permalinks.
5166 New in version 0.6: Previously, this was always activated.
5168 Changed in version 1.1: This can now be a string to select the
5171 actual text of the link. Previously, only boolean values were
5172 accepted.
5173 html_sidebars
5176 Custom sidebar templates, must be a dictionary that maps docu‐
5177 ment names to template names.
5178 The keys can contain glob-style patterns [1], in which case all
5180 matching documents will get the specified sidebars. (A warning
5181 is emitted when a more than one glob-style pattern matches for
5182 any document.)
5183 The values can be either lists or single strings.
5185 · If a value is a list, it specifies the complete list of side‐
5187 bar templates to include. If all or some of the default side‐
5188 bars are to be included, they must be put into this list as
5189 well.
5190 The default sidebars (for documents that don’t match any pat‐
5192 tern) are defined by theme itself. Builtin themes are using
5193 these templates by default: ['localtoc.html', 'rela‐
5194 tions.html', 'sourcelink.html', 'searchbox.html'].
5195 · If a value is a single string, it specifies a custom sidebar
5197 to be added between the 'sourcelink.html' and 'searchbox.html'
5198 entries. This is for compatibility with Sphinx versions
5199 before 1.0.
5200 Deprecated since version 1.7: a single string value for
5202 html_sidebars will be removed in 2.0
5203 Builtin sidebar templates that can be rendered are:
5206 · localtoc.html – a fine-grained table of contents of the cur‐
5208 rent document
5209 · globaltoc.html – a coarse-grained table of contents for the
5211 whole documentation set, collapsed
5212 · relations.html – two links to the previous and next documents
5214 · sourcelink.html – a link to the source of the current docu‐
5216 ment, if enabled in html_show_sourcelink
5217 · searchbox.html – the “quick search” box
5219 Example:
5221 html_sidebars = {
5223 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5224 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5225 }
5226 This will render the custom template windowssidebar.html and the
5228 quick search box within the sidebar of the given document, and
5229 render the default sidebars for all other pages (except that the
5230 local TOC is replaced by the global TOC).
5231 New in version 1.0: The ability to use globbing keys and to
5233 specify multiple sidebars.
5234 Note that this value only has no effect if the chosen theme does
5237 not possess a sidebar, like the builtin scrolls and haiku
5238 themes.
5239 html_additional_pages
5241 Additional templates that should be rendered to HTML pages, must
5242 be a dictionary that maps document names to template names.
5243 Example:
5245 html_additional_pages = {
5247 'download': 'customdownload.html',
5248 }
5249 This will render the template customdownload.html as the page
5251 download.html.
5252 html_domain_indices
5254 If true, generate domain-specific indices in addition to the
5255 general index. For e.g. the Python domain, this is the global
5256 module index. Default is True.
5257 This value can be a bool or a list of index names that should be
5259 generated. To find out the index name for a specific index,
5260 look at the HTML file name. For example, the Python module
5261 index has the name 'py-modindex'.
5262 New in version 1.0.
5264 html_use_index
5267 If true, add an index to the HTML documents. Default is True.
5268 New in version 0.4.
5270 html_split_index
5273 If true, the index is generated twice: once as a single page
5274 with all the entries, and once as one page per starting letter.
5275 Default is False.
5276 New in version 0.4.
5278 html_copy_source
5281 If true, the reST sources are included in the HTML build as
5282 _sources/name. The default is True.
5283 html_show_sourcelink
5285 If true (and html_copy_source is true as well), links to the
5286 reST sources will be added to the sidebar. The default is True.
5287 New in version 0.6.
5289 html_sourcelink_suffix
5292 Suffix to be appended to source links (see
5293 html_show_sourcelink), unless they have this suffix already.
5294 Default is '.txt'.
5295 New in version 1.5.
5297 html_use_opensearch
5300 If nonempty, an OpenSearch description file will be output, and
5301 all pages will contain a <link> tag referring to it. Since
5302 OpenSearch doesn’t support relative URLs for its search page
5303 location, the value of this option must be the base URL from
5304 which these documents are served (without trailing slash), e.g.
5305 "https://docs.python.org". The default is ''.
5306 html_file_suffix
5308 This is the file name suffix for generated HTML files. The
5309 default is ".html".
5310 New in version 0.4.
5312 html_link_suffix
5315 Suffix for generated links to HTML files. The default is what‐
5316 ever html_file_suffix is set to; it can be set differently (e.g.
5317 to support different web server setups).
5318 New in version 0.6.
5320 html_show_copyright
5323 If true, “(C) Copyright …” is shown in the HTML footer. Default
5324 is True.
5325 New in version 1.0.
5327 html_show_sphinx
5330 If true, “Created using Sphinx” is shown in the HTML footer.
5331 Default is True.
5332 New in version 0.4.
5334 html_output_encoding
5337 Encoding of HTML output files. Default is 'utf-8'. Note that
5338 this encoding name must both be a valid Python encoding name and
5339 a valid HTML charset value.
5340 New in version 1.0.
5342 html_compact_lists
5345 If true, a list all whose items consist of a single paragraph
5346 and/or a sub-list all whose items etc… (recursive definition)
5347 will not use the <p> element for any of its items. This is stan‐
5348 dard docutils behavior. Default: True.
5349 New in version 1.0.
5351 html_secnumber_suffix
5354 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5355 press the final dot on section numbers.
5356 New in version 1.0.
5358 html_search_language
5361 Language to be used for generating the HTML full-text search
5362 index. This defaults to the global language selected with
5363 language. If there is no support for this language, "en" is
5364 used which selects the English language.
5365 Support is present for these languages:
5367 · da – Danish
5369 · nl – Dutch
5371 · en – English
5373 · fi – Finnish
5375 · fr – French
5377 · de – German
5379 · hu – Hungarian
5381 · it – Italian
5383 · ja – Japanese
5385 · no – Norwegian
5387 · pt – Portuguese
5389 · ro – Romanian
5391 · ru – Russian
5393 · es – Spanish
5395 · sv – Swedish
5397 · tr – Turkish
5399 · zh – Chinese
5401 Accelerating build speed
5403 Each language (except Japanese) provides its own stem‐
5405 ming algorithm. Sphinx uses a Python implementation
5406 by default. You can use a C implementation to accel‐
5407 erate building the index file.
5408 · PorterStemmer (en)
5410 · PyStemmer (all languages)
5412 New in version 1.1: With support for en and ja.
5414 Changed in version 1.3: Added additional languages.
5417 html_search_options
5420 A dictionary with options for the search language support, empty
5421 by default. The meaning of these options depends on the lan‐
5422 guage selected.
5423 The English support has no options.
5425 The Japanese support has these options:
5427 Type
5429 is dotted module path string to specify Splitter imple‐
5430 mentation which should be derived from
5431 sphinx.search.ja.BaseSplitter. If not specified or None
5432 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5433 used.
5434 You can choose from these modules:
5436 ‘sphinx.search.ja.DefaultSplitter’
5438 TinySegmenter algorithm. This is default splitter.
5439 ‘sphinx.search.ja.MecabSplitter’
5441 MeCab binding. To use this splitter, ‘mecab’
5442 python binding or dynamic link library (‘libme‐
5443 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5444 required.
5445 ‘sphinx.search.ja.JanomeSplitter’
5447 Janome binding. To use this splitter, Janome is
5448 required.
5449 Deprecated since version 1.6: 'mecab', 'janome' and
5451 'default' is deprecated. To keep compatibility, 'mecab',
5452 'janome' and 'default' are also acceptable.
5453 Other option values depend on splitter value which you choose.
5456 Options for 'mecab':
5458 dic_enc
5460 is the encoding for the MeCab algorithm.
5461 dict
5463 is the dictionary to use for the MeCab algorithm.
5464 lib
5466 is the library name for finding the MeCab library
5467 via ctypes if the Python binding is not installed.
5468 For example:
5470 html_search_options = {
5472 'type': 'mecab',
5473 'dic_enc': 'utf-8',
5474 'dict': '/path/to/mecab.dic',
5475 'lib': '/path/to/libmecab.so',
5476 }
5477 Options for 'janome':
5479 user_dic
5481 is the user dictionary file path for Janome.
5482 user_dic_enc
5484 is the encoding for the user dictionary file
5485 specified by user_dic option. Default is ‘utf8’.
5486 New in version 1.1.
5488 Changed in version 1.4: html_search_options for Japanese is
5491 re-organized and any custom splitter can be used by type set‐
5492 tings.
5493 The Chinese support has these options:
5496 · dict – the jieba dictionary path if want to use custom dic‐
5498 tionary.
5499 html_search_scorer
5501 The name of a JavaScript file (relative to the configuration
5502 directory) that implements a search results scorer. If empty,
5503 the default will be used.
5504 New in version 1.2.
5506 html_scaled_image_link
5509 If true, images itself links to the original image if it doesn’t
5510 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5511 ‘height’. The default is True.
5512 New in version 1.3.
5514 html_math_renderer
5517 The name of math_renderer extension for HTML output. The
5518 default is 'mathjax'.
5519 New in version 1.8.
5521 html_experimental_html5_writer
5524 Output is processed with HTML5 writer. This feature needs docu‐
5525 tils 0.13 or newer. Default is False.
5526 New in version 1.6.
5528 Deprecated since version 2.0.
5531 html4_writer
5534 Output is processed with HTML4 writer. Default is False.
5535 Options for Single HTML output
5537 singlehtml_sidebars
5538 Custom sidebar templates, must be a dictionary that maps docu‐
5539 ment names to template names. And it only allows a key named
5540 ‘index’. All other keys are ignored. For more information,
5541 refer to html_sidebars. By default, it is same as
5542 html_sidebars.
5543 Options for HTML help output
5545 htmlhelp_basename
5546 Output file base name for HTML help builder. Default is
5547 'pydoc'.
5548 htmlhelp_file_suffix
5550 This is the file name suffix for generated HTML help files. The
5551 default is ".html".
5552 New in version 2.0.
5554 htmlhelp_link_suffix
5557 Suffix for generated links to HTML files. The default is
5558 ".html".
5559 New in version 2.0.
5561 Options for Apple Help output
5564 New in version 1.3.
5565 These options influence the Apple Help output. This builder derives
5568 from the HTML builder, so the HTML options also apply where appropri‐
5569 ate.
5570 NOTE:
5572 Apple Help output will only work on Mac OS X 10.6 and higher, as it
5573 requires the hiutil and codesign command line tools, neither of
5574 which are Open Source.
5575 You can disable the use of these tools using
5577 applehelp_disable_external_tools, but the result will not be a valid
5578 help book until the indexer is run over the .lproj folders within
5579 the bundle.
5580 applehelp_bundle_name
5582 The basename for the Apple Help Book. Defaults to the project
5583 name.
5584 applehelp_bundle_id
5586 The bundle ID for the help book bundle.
5587 WARNING:
5589 You must set this value in order to generate Apple Help.
5590 applehelp_dev_region
5592 The development region. Defaults to 'en-us', which is Apple’s
5593 recommended setting.
5594 applehelp_bundle_version
5596 The bundle version (as a string). Defaults to '1'.
5597 applehelp_icon
5599 The help bundle icon file, or None for no icon. According to
5600 Apple’s documentation, this should be a 16-by-16 pixel version
5601 of the application’s icon with a transparent background, saved
5602 as a PNG file.
5603 applehelp_kb_product
5605 The product tag for use with applehelp_kb_url. Defaults to
5606 '<project>-<release>'.
5607 applehelp_kb_url
5609 The URL for your knowledgebase server, e.g. https://exam‐
5610 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
5611 will replace the values 'product', 'query' and 'lang' at runtime
5612 with the contents of applehelp_kb_product, the text entered by
5613 the user in the search box and the user’s system language
5614 respectively.
5615 Defaults to None for no remote search.
5617 applehelp_remote_url
5619 The URL for remote content. You can place a copy of your Help
5620 Book’s Resources folder at this location and Help Viewer will
5621 attempt to use it to fetch updated content.
5622 e.g. if you set it to https://example.com/help/Foo/ and Help
5624 Viewer wants a copy of index.html for an English speaking cus‐
5625 tomer, it will look at https://exam‐
5626 ple.com/help/Foo/en.lproj/index.html.
5627 Defaults to None for no remote content.
5629 applehelp_index_anchors
5631 If True, tell the help indexer to index anchors in the generated
5632 HTML. This can be useful for jumping to a particular topic
5633 using the AHLookupAnchor function or the openHelpAnchor:inBook:
5634 method in your code. It also allows you to use help:anchor
5635 URLs; see the Apple documentation for more information on this
5636 topic.
5637 applehelp_min_term_length
5639 Controls the minimum term length for the help indexer. Defaults
5640 to None, which means the default will be used.
5641 applehelp_stopwords
5643 Either a language specification (to use the built-in stopwords),
5644 or the path to a stopwords plist, or None if you do not want to
5645 use stopwords. The default stopwords plist can be found at
5646 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
5647 ing, stopwords for the following languages:
5648 ┌──────────┬──────┐
5650 │Language │ Code │
5651 ├──────────┼──────┤
5652 │English │ en │
5653 ├──────────┼──────┤
5654 │German │ de │
5655 ├──────────┼──────┤
5656 │Spanish │ es │
5657 ├──────────┼──────┤
5658 │French │ fr │
5659 ├──────────┼──────┤
5660 │Swedish │ sv │
5661 ├──────────┼──────┤
5662 │Hungarian │ hu │
5663 ├──────────┼──────┤
5664 │Italian │ it │
5665 └──────────┴──────┘
5666 Defaults to language, or if that is not set, to en.
5668 applehelp_locale
5670 Specifies the locale to generate help for. This is used to
5671 determine the name of the .lproj folder inside the Help Book’s
5672 Resources, and is passed to the help indexer.
5673 Defaults to language, or if that is not set, to en.
5675 applehelp_title
5677 Specifies the help book title. Defaults to '<project> Help'.
5678 applehelp_codesign_identity
5680 Specifies the identity to use for code signing, or None if code
5681 signing is not to be performed.
5682 Defaults to the value of the environment variable
5684 CODE_SIGN_IDENTITY, which is set by Xcode for script build
5685 phases, or None if that variable is not set.
5686 applehelp_codesign_flags
5688 A list of additional arguments to pass to codesign when signing
5689 the help book.
5690 Defaults to a list based on the value of the environment vari‐
5692 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
5693 build phases, or the empty list if that variable is not set.
5694 applehelp_indexer_path
5696 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
5697 applehelp_codesign_path
5699 The path to the codesign program. Defaults to '/usr/bin/code‐
5700 sign'.
5701 applehelp_disable_external_tools
5703 If True, the builder will not run the indexer or the code sign‐
5704 ing tool, no matter what other settings are specified.
5705 This is mainly useful for testing, or where you want to run the
5707 Sphinx build on a non-Mac OS X platform and then complete the
5708 final steps on OS X for some reason.
5709 Defaults to False.
5711 Options for epub output
5713 These options influence the epub output. As this builder derives from
5714 the HTML builder, the HTML options also apply where appropriate. The
5715 actual values for some of the options is not really important, they
5716 just have to be entered into the Dublin Core metadata.
5717 epub_basename
5719 The basename for the epub file. It defaults to the project
5720 name.
5721 epub_theme
5723 The HTML theme for the epub output. Since the default themes
5724 are not optimized for small screen space, using the same theme
5725 for HTML and epub output is usually not wise. This defaults to
5726 'epub', a theme designed to save visual space.
5727 epub_theme_options
5729 A dictionary of options that influence the look and feel of the
5730 selected theme. These are theme-specific. For the options
5731 understood by the builtin themes, see this section.
5732 New in version 1.2.
5734 epub_title
5737 The title of the document. It defaults to the html_title option
5738 but can be set independently for epub creation. It defaults to
5739 the project option.
5740 Changed in version 2.0: It defaults to the project option.
5742 epub_description
5745 The description of the document. The default value is 'unknown'.
5746 New in version 1.4.
5748 Changed in version 1.5: Renamed from epub3_description
5751 epub_author
5754 The author of the document. This is put in the Dublin Core
5755 metadata. It defaults to the author option.
5756 epub_contributor
5758 The name of a person, organization, etc. that played a secondary
5759 role in the creation of the content of an EPUB Publication. The
5760 default value is 'unknown'.
5761 New in version 1.4.
5763 Changed in version 1.5: Renamed from epub3_contributor
5766 epub_language
5769 The language of the document. This is put in the Dublin Core
5770 metadata. The default is the language option or 'en' if unset.
5771 epub_publisher
5773 The publisher of the document. This is put in the Dublin Core
5774 metadata. You may use any sensible string, e.g. the project
5775 homepage. The defaults to the author option.
5776 epub_copyright
5778 The copyright of the document. It defaults to the copyright
5779 option but can be set independently for epub creation.
5780 epub_identifier
5782 An identifier for the document. This is put in the Dublin Core
5783 metadata. For published documents this is the ISBN number, but
5784 you can also use an alternative scheme, e.g. the project home‐
5785 page. The default value is 'unknown'.
5786 epub_scheme
5788 The publication scheme for the epub_identifier. This is put in
5789 the Dublin Core metadata. For published books the scheme is
5790 'ISBN'. If you use the project homepage, 'URL' seems reason‐
5791 able. The default value is 'unknown'.
5792 epub_uid
5794 A unique identifier for the document. This is put in the Dublin
5795 Core metadata. You may use a XML’s Name format string. You
5796 can’t use hyphen, period, numbers as a first character. The
5797 default value is 'unknown'.
5798 epub_cover
5800 The cover page information. This is a tuple containing the
5801 filenames of the cover image and the html template. The ren‐
5802 dered html cover page is inserted as the first item in the spine
5803 in content.opf. If the template filename is empty, no html
5804 cover page is created. No cover at all is created if the tuple
5805 is empty. Examples:
5806 epub_cover = ('_static/cover.png', 'epub-cover.html')
5808 epub_cover = ('_static/cover.png', '')
5809 epub_cover = ()
5810 The default value is ().
5812 New in version 1.1.
5814 epub_css_files
5817 A list of CSS files. The entry must be a filename string or a
5818 tuple containing the filename string and the attributes dictio‐
5819 nary. For more information, see html_css_files.
5820 New in version 1.8.
5822 epub_guide
5825 Meta data for the guide element of content.opf. This is a
5826 sequence of tuples containing the type, the uri and the title of
5827 the optional guide information. See the OPF documentation at
5828 http://idpf.org/epub for details. If possible, default entries
5829 for the cover and toc types are automatically inserted. However,
5830 the types can be explicitly overwritten if the default entries
5831 are not appropriate. Example:
5832 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
5834 The default value is ().
5836 epub_pre_files
5838 Additional files that should be inserted before the text gener‐
5839 ated by Sphinx. It is a list of tuples containing the file name
5840 and the title. If the title is empty, no entry is added to
5841 toc.ncx. Example:
5842 epub_pre_files = [
5844 ('index.html', 'Welcome'),
5845 ]
5846 The default value is [].
5848 epub_post_files
5850 Additional files that should be inserted after the text gener‐
5851 ated by Sphinx. It is a list of tuples containing the file name
5852 and the title. This option can be used to add an appendix. If
5853 the title is empty, no entry is added to toc.ncx. The default
5854 value is [].
5855 epub_exclude_files
5857 A list of files that are generated/copied in the build directory
5858 but should not be included in the epub file. The default value
5859 is [].
5860 epub_tocdepth
5862 The depth of the table of contents in the file toc.ncx. It
5863 should be an integer greater than zero. The default value is 3.
5864 Note: A deeply nested table of contents may be difficult to nav‐
5865 igate.
5866 epub_tocdup
5868 This flag determines if a toc entry is inserted again at the
5869 beginning of its nested toc listing. This allows easier naviga‐
5870 tion to the top of a chapter, but can be confusing because it
5871 mixes entries of different depth in one list. The default value
5872 is True.
5873 epub_tocscope
5875 This setting control the scope of the epub table of contents.
5876 The setting can have the following values:
5877 · 'default' – include all toc entries that are not hidden
5879 (default)
5880 · 'includehidden' – include all toc entries
5882 New in version 1.2.
5884 epub_fix_images
5887 This flag determines if sphinx should try to fix image formats
5888 that are not supported by some epub readers. At the moment pal‐
5889 ette images with a small color table are upgraded. You need
5890 Pillow, the Python Image Library, installed to use this option.
5891 The default value is False because the automatic conversion may
5892 lose information.
5893 New in version 1.2.
5895 epub_max_image_width
5898 This option specifies the maximum width of images. If it is set
5899 to a value greater than zero, images with a width larger than
5900 the given value are scaled accordingly. If it is zero, no scal‐
5901 ing is performed. The default value is 0. You need the Python
5902 Image Library (Pillow) installed to use this option.
5903 New in version 1.2.
5905 epub_show_urls
5908 Control whether to display URL addresses. This is very useful
5909 for readers that have no other means to display the linked URL.
5910 The settings can have the following values:
5911 · 'inline' – display URLs inline in parentheses (default)
5913 · 'footnote' – display URLs in footnotes
5915 · 'no' – do not display URLs
5917 The display of inline URLs can be customized by adding CSS rules
5919 for the class link-target.
5920 New in version 1.2.
5922 epub_use_index
5925 If true, add an index to the epub document. It defaults to the
5926 html_use_index option but can be set independently for epub cre‐
5927 ation.
5928 New in version 1.2.
5930 epub_writing_mode
5933 It specifies writing direction. It can accept 'horizontal'
5934 (default) and 'vertical'
5935 ┌────────────────────┬─────────────────────┬─────────────────────┐
5937 │epub_writing_mode │ 'horizontal' │ 'vertical' │
5938 ├────────────────────┼─────────────────────┼─────────────────────┤
5939 │writing-mode [2] │ horizontal-tb │ vertical-rl │
5940 ├────────────────────┼─────────────────────┼─────────────────────┤
5941 │page progression │ left to right │ right to left │
5942 ├────────────────────┼─────────────────────┼─────────────────────┤
5943 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
5944 │Theme support │ tical. │ izontal. │
5945 └────────────────────┴─────────────────────┴─────────────────────┘
5946 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
5948 Options for LaTeX output
5950 These options influence LaTeX output.
5951 latex_engine
5953 The LaTeX engine to build the docs. The setting can have the
5954 following values:
5955 · 'pdflatex' – PDFLaTeX (default)
5957 · 'xelatex' – XeLaTeX
5959 · 'lualatex' – LuaLaTeX
5961 · 'platex' – pLaTeX (default if language is 'ja')
5963 'pdflatex'’s support for Unicode characters is limited.
5965 NOTE:
5967 2.0 adds to 'pdflatex' support in Latin language document of
5968 occasional Cyrillic or Greek letters or words. This is not
5969 automatic, see the discussion of the latex_elements 'fontenc'
5970 key.
5971 If your project uses Unicode characters, setting the engine to
5973 'xelatex' or 'lualatex' and making sure to use an OpenType font
5974 with wide-enough glyph coverage is often easier than trying to
5975 make 'pdflatex' work with the extra Unicode characters. Since
5976 Sphinx 2.0 the default is the GNU FreeFont which covers well
5977 Latin, Cyrillic and Greek.
5978 Contrarily to MathJaX math rendering in HTML output, LaTeX
5980 requires some extra configuration to support Unicode literals in
5981 math: the only comprehensive solution (as far as we know) is to
5982 use 'xelatex' or 'lualatex' and to add r'\usepackage{uni‐
5983 code-math}' (e.g. via the latex_elements 'preamble' key). You
5984 may prefer r'\usepackage[math-style=literal]{unicode-math}' to
5985 keep a Unicode literal such as α (U+03B1) for example as is in
5986 output, rather than being rendered as \alpha.
5987 latex_documents
5989 This value determines how to group the document tree into LaTeX
5990 source files. It must be a list of tuples (startdocname, tar‐
5991 getname, title, author, documentclass, toctree_only), where the
5992 items are:
5993 startdocname
5995 String that specifies the document name of the LaTeX
5996 file’s master document. All documents referenced by the
5997 startdoc document in TOC trees will be included in the
5998 LaTeX file. (If you want to use the default master docu‐
5999 ment for your LaTeX build, provide your master_doc here.)
6000 targetname
6002 File name of the LaTeX file in the output directory.
6003 title LaTeX document title. Can be empty to use the title of
6005 the startdoc document. This is inserted as LaTeX markup,
6006 so special characters like a backslash or ampersand must
6007 be represented by the proper LaTeX commands if they are
6008 to be inserted literally.
6009 author Author for the LaTeX document. The same LaTeX markup
6011 caveat as for title applies. Use \\and to separate mul‐
6012 tiple authors, as in: 'John \\and Sarah' (backslashes
6013 must be Python-escaped to reach LaTeX).
6014 documentclass
6016 Normally, one of 'manual' or 'howto' (provided by Sphinx
6017 and based on 'report', resp. 'article'; Japanese docu‐
6018 ments use 'jsbook', resp. 'jreport'.) “howto” (non-Japa‐
6019 nese) documents will not get appendices. Also they have a
6020 simpler title page. Other document classes can be given.
6021 Independently of the document class, the “sphinx” package
6022 is always loaded in order to define Sphinx’s custom LaTeX
6023 commands.
6024 toctree_only
6026 Must be True or False. If true, the startdoc document
6027 itself is not included in the output, only the documents
6028 referenced by it via TOC trees. With this option, you
6029 can put extra stuff in the master document that shows up
6030 in the HTML, but not the LaTeX output.
6031 New in version 1.2: In the past including your own document
6033 class required you to prepend the document class name with the
6034 string “sphinx”. This is not necessary anymore.
6035 New in version 0.3: The 6th item toctree_only. Tuples with 5
6038 items are still accepted.
6039 latex_logo
6042 If given, this must be the name of an image file (relative to
6043 the configuration directory) that is the logo of the docs. It
6044 is placed at the top of the title page. Default: None.
6045 latex_toplevel_sectioning
6047 This value determines the topmost sectioning unit. It should be
6048 chosen from 'part', 'chapter' or 'section'. The default is None;
6049 the topmost sectioning unit is switched by documentclass: sec‐
6050 tion is used if documentclass will be howto, otherwise chapter
6051 will be used.
6052 Note that if LaTeX uses \part command, then the numbering of
6054 sectioning units one level deep gets off-sync with HTML number‐
6055 ing, because LaTeX numbers continuously \chapter (or \section
6056 for howto.)
6057 New in version 1.4.
6059 latex_appendices
6062 A list of document names to append as an appendix to all manu‐
6063 als.
6064 latex_domain_indices
6066 If true, generate domain-specific indices in addition to the
6067 general index. For e.g. the Python domain, this is the global
6068 module index. Default is True.
6069 This value can be a bool or a list of index names that should be
6071 generated, like for html_domain_indices.
6072 New in version 1.0.
6074 latex_show_pagerefs
6077 If true, add page references after internal references. This is
6078 very useful for printed copies of the manual. Default is False.
6079 New in version 1.0.
6081 latex_show_urls
6084 Control whether to display URL addresses. This is very useful
6085 for printed copies of the manual. The setting can have the fol‐
6086 lowing values:
6087 · 'no' – do not display URLs (default)
6089 · 'footnote' – display URLs in footnotes
6091 · 'inline' – display URLs inline in parentheses
6093 New in version 1.0.
6095 Changed in version 1.1: This value is now a string; previously
6098 it was a boolean value, and a true value selected the 'inline'
6099 display. For backwards compatibility, True is still accepted.
6100 latex_use_latex_multicolumn
6103 The default is False: it means that Sphinx’s own macros are used
6104 for merged cells from grid tables. They allow general contents
6105 (literal blocks, lists, blockquotes, …) but may have problems if
6106 the tabularcolumns directive was used to inject LaTeX mark-up of
6107 the type >{..}, <{..}, @{..} as column specification.
6108 Setting to True means to use LaTeX’s standard \multicolumn; this
6110 is incompatible with literal blocks in the horizontally merged
6111 cell, and also with multiple paragraphs in such cell if the ta‐
6112 ble is rendered using tabulary.
6113 New in version 1.6.
6115 latex_use_xindy
6118 If True, the PDF build from the LaTeX files created by Sphinx
6119 will use xindy (doc) rather than makeindex for preparing the
6120 index of general terms (from index usage). This means that
6121 words with UTF-8 characters will get ordered correctly for the
6122 language.
6123 · This option is ignored if latex_engine is 'platex' (Japanese
6125 documents; mendex replaces makeindex then).
6126 · The default is True for 'xelatex' or 'lualatex' as makeindex,
6128 if any indexed term starts with a non-ascii character, creates
6129 .ind files containing invalid bytes for UTF-8 encoding. With
6130 'lualatex' this then breaks the PDF build.
6131 · The default is False for 'pdflatex' but True is recommended
6133 for non-English documents as soon as some indexed terms use
6134 non-ascii characters from the language script.
6135 Sphinx adds to xindy base distribution some dedicated support
6137 for using 'pdflatex' engine with Cyrillic scripts. And whether
6138 with 'pdflatex' or Unicode engines, Cyrillic documents handle
6139 correctly the indexing of Latin names, even with diacritics.
6140 New in version 1.8.
6142 latex_elements
6145 New in version 0.5.
6146 Its documentation has moved to /latex.
6149 latex_docclass
6151 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6152 ment classes that will be used as the base for the two Sphinx
6153 classes. Default is to use 'article' for 'howto' and 'report'
6154 for 'manual'.
6155 New in version 1.0.
6157 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6160 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6161 latex_additional_files
6164 A list of file names, relative to the configuration directory,
6165 to copy to the build directory when building LaTeX output. This
6166 is useful to copy files that Sphinx doesn’t copy automatically,
6167 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6168 ments. Image files that are referenced in source files (e.g.
6169 via .. image::) are copied automatically.
6170 You have to make sure yourself that the filenames don’t collide
6172 with those of any automatically copied files.
6173 New in version 0.6.
6175 Changed in version 1.2: This overrides the files which is pro‐
6178 vided from Sphinx such as sphinx.sty.
6179 Options for text output
6182 These options influence text output.
6183 text_newlines
6185 Determines which end-of-line character(s) are used in text out‐
6186 put.
6187 · 'unix': use Unix-style line endings (\n)
6189 · 'windows': use Windows-style line endings (\r\n)
6191 · 'native': use the line ending style of the platform the docu‐
6193 mentation is built on
6194 Default: 'unix'.
6196 New in version 1.1.
6198 text_sectionchars
6201 A string of 7 characters that should be used for underlining
6202 sections. The first character is used for first-level headings,
6203 the second for second-level headings and so on.
6204 The default is '*=-~"+`'.
6206 New in version 1.1.
6208 text_add_secnumbers
6211 A boolean that decides whether section numbers are included in
6212 text output. Default is True.
6213 New in version 1.7.
6215 text_secnumber_suffix
6218 Suffix for section numbers in text output. Default: ". ". Set
6219 to " " to suppress the final dot on section numbers.
6220 New in version 1.7.
6222 Options for manual page output
6225 These options influence manual page output.
6226 man_pages
6228 This value determines how to group the document tree into manual
6229 pages. It must be a list of tuples (startdocname, name,
6230 description, authors, section), where the items are:
6231 startdocname
6233 String that specifies the document name of the manual
6234 page’s master document. All documents referenced by the
6235 startdoc document in TOC trees will be included in the
6236 manual file. (If you want to use the default master doc‐
6237 ument for your manual pages build, use your master_doc
6238 here.)
6239 name Name of the manual page. This should be a short string
6241 without spaces or special characters. It is used to
6242 determine the file name as well as the name of the manual
6243 page (in the NAME section).
6244 description
6246 Description of the manual page. This is used in the NAME
6247 section.
6248 authors
6250 A list of strings with authors, or a single string. Can
6251 be an empty string or list if you do not want to automat‐
6252 ically generate an AUTHORS section in the manual page.
6253 section
6255 The manual page section. Used for the output file name
6256 as well as in the manual page header.
6257 New in version 1.0.
6259 man_show_urls
6262 If true, add URL addresses after links. Default is False.
6263 New in version 1.1.
6265 Options for Texinfo output
6268 These options influence Texinfo output.
6269 texinfo_documents
6271 This value determines how to group the document tree into Tex‐
6272 info source files. It must be a list of tuples (startdocname,
6273 targetname, title, author, dir_entry, description, category,
6274 toctree_only), where the items are:
6275 startdocname
6277 String that specifies the document name of the the Tex‐
6278 info file’s master document. All documents referenced by
6279 the startdoc document in TOC trees will be included in
6280 the Texinfo file. (If you want to use the default master
6281 document for your Texinfo build, provide your master_doc
6282 here.)
6283 targetname
6285 File name (no extension) of the Texinfo file in the out‐
6286 put directory.
6287 title Texinfo document title. Can be empty to use the title of
6289 the startdoc document. Inserted as Texinfo markup, so
6290 special characters like @ and {} will need to be escaped
6291 to be inserted literally.
6292 author Author for the Texinfo document. Inserted as Texinfo
6294 markup. Use @* to separate multiple authors, as in:
6295 'John@*Sarah'.
6296 dir_entry
6298 The name that will appear in the top-level DIR menu file.
6299 description
6301 Descriptive text to appear in the top-level DIR menu
6302 file.
6303 category
6305 Specifies the section which this entry will appear in the
6306 top-level DIR menu file.
6307 toctree_only
6309 Must be True or False. If true, the startdoc document
6310 itself is not included in the output, only the documents
6311 referenced by it via TOC trees. With this option, you
6312 can put extra stuff in the master document that shows up
6313 in the HTML, but not the Texinfo output.
6314 New in version 1.1.
6316 texinfo_appendices
6319 A list of document names to append as an appendix to all manu‐
6320 als.
6321 New in version 1.1.
6323 texinfo_domain_indices
6326 If true, generate domain-specific indices in addition to the
6327 general index. For e.g. the Python domain, this is the global
6328 module index. Default is True.
6329 This value can be a bool or a list of index names that should be
6331 generated, like for html_domain_indices.
6332 New in version 1.1.
6334 texinfo_show_urls
6337 Control how to display URL addresses.
6338 · 'footnote' – display URLs in footnotes (default)
6340 · 'no' – do not display URLs
6342 · 'inline' – display URLs inline in parentheses
6344 New in version 1.1.
6346 texinfo_no_detailmenu
6349 If true, do not generate a @detailmenu in the “Top” node’s menu
6350 containing entries for each sub-node in the document. Default
6351 is False.
6352 New in version 1.2.
6354 texinfo_elements
6357 A dictionary that contains Texinfo snippets that override those
6358 Sphinx usually puts into the generated .texi files.
6359 · Keys that you may want to override include:
6361 'paragraphindent'
6363 Number of spaces to indent the first line of each para‐
6364 graph, default 2. Specify 0 for no indentation.
6365 'exampleindent'
6367 Number of spaces to indent the lines for examples or
6368 literal blocks, default 4. Specify 0 for no indenta‐
6369 tion.
6370 'preamble'
6372 Texinfo markup inserted near the beginning of the file.
6373 'copying'
6375 Texinfo markup inserted within the @copying block and
6376 displayed after the title. The default value consists
6377 of a simple title page identifying the project.
6378 · Keys that are set by other options and therefore should not be
6380 overridden are:
6381 'author' 'body' 'date' 'direntry' 'filename' 'project'
6383 'release' 'title'
6384 New in version 1.1.
6386 Options for QtHelp output
6389 These options influence qthelp output. As this builder derives from
6390 the HTML builder, the HTML options also apply where appropriate.
6391 qthelp_basename
6393 The basename for the qthelp file. It defaults to the project
6394 name.
6395 qthelp_namespace
6397 The namespace for the qthelp file. It defaults to
6398 org.sphinx.<project_name>.<project_version>.
6399 qthelp_theme
6401 The HTML theme for the qthelp output. This defaults to 'nonav'.
6402 qthelp_theme_options
6404 A dictionary of options that influence the look and feel of the
6405 selected theme. These are theme-specific. For the options
6406 understood by the builtin themes, see this section.
6407 Options for the linkcheck builder
6409 linkcheck_ignore
6410 A list of regular expressions that match URIs that should not be
6411 checked when doing a linkcheck build. Example:
6412 linkcheck_ignore = [r'http://localhost:\d+/']
6414 New in version 1.1.
6416 linkcheck_retries
6419 The number of times the linkcheck builder will attempt to check
6420 a URL before declaring it broken. Defaults to 1 attempt.
6421 New in version 1.4.
6423 linkcheck_timeout
6426 A timeout value, in seconds, for the linkcheck builder. The
6427 default is to use Python’s global socket timeout.
6428 New in version 1.1.
6430 linkcheck_workers
6433 The number of worker threads to use when checking links.
6434 Default is 5 threads.
6435 New in version 1.1.
6437 linkcheck_anchors
6440 If true, check the validity of #anchors in links. Since this
6441 requires downloading the whole document, it’s considerably
6442 slower when enabled. Default is True.
6443 New in version 1.2.
6445 linkcheck_anchors_ignore
6448 A list of regular expressions that match anchors Sphinx should
6449 skip when checking the validity of anchors in links. This allows
6450 skipping anchors that a website’s JavaScript adds to control
6451 dynamic pages or when triggering an internal REST request.
6452 Default is ["^!"].
6453 NOTE:
6455 If you want to ignore anchors of a specific page or of pages
6456 that match a specific pattern (but still check occurrences of
6457 the same page(s) that don’t have anchors), use
6458 linkcheck_ignore instead, for example as follows:
6459 linkcheck_ignore = [
6461 'http://www.sphinx-doc.org/en/1.7/intro.html#'
6462 ]
6463 New in version 1.5.
6465 Options for the XML builder
6468 xml_pretty
6469 If true, pretty-print the XML. Default is True.
6470 New in version 1.2.
6472
6475 [1] A note on available globbing syntax: you can use the standard
6476 shell constructs *, ?, [...] and [!...] with the feature that
6477 these all don’t match slashes. A double star ** can be used to
6478 match any sequence of characters including slashes.
6479 Options for the C++ domain
6481 cpp_index_common_prefix
6482 A list of prefixes that will be ignored when sorting C++ objects
6483 in the global index. For example ['awesome_lib::'].
6484 New in version 1.5.
6486 cpp_id_attributes
6489 A list of strings that the parser additionally should accept as
6490 attributes. This can for example be used when attributes have
6491 been #define d for portability.
6492 New in version 1.5.
6494 cpp_paren_attributes
6497 A list of strings that the parser additionally should accept as
6498 attributes with one argument. That is, if my_align_as is in the
6499 list, then my_align_as(X) is parsed as an attribute for all
6500 strings X that have balanced braces ((), [], and {}). This can
6501 for example be used when attributes have been #define d for
6502 portability.
6503 New in version 1.5.
6505 Example of configuration file
6508 # test documentation build configuration file, created by
6509 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
6510 #
6511 # This file is execfile()d with the current directory set to its
6512 # containing dir.
6513 #
6514 # Note that not all possible configuration values are present in this
6515 # autogenerated file.
6516 #
6517 # All configuration values have a default; values that are commented out
6518 # serve to show the default.
6519 # If extensions (or modules to document with autodoc) are in another directory,
6521 # add these directories to sys.path here. If the directory is relative to the
6522 # documentation root, use os.path.abspath to make it absolute, like shown here.
6523 #
6524 # import os
6525 # import sys
6526 # sys.path.insert(0, os.path.abspath('.'))
6527 # -- General configuration ------------------------------------------------
6529 # If your documentation needs a minimal Sphinx version, state it here.
6531 #
6532 # needs_sphinx = '1.0'
6533 # Add any Sphinx extension module names here, as strings. They can be
6535 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
6536 # ones.
6537 extensions = []
6538 # Add any paths that contain templates here, relative to this directory.
6540 templates_path = ['_templates']
6541 # The suffix(es) of source filenames.
6543 # You can specify multiple suffix as a list of string:
6544 #
6545 # source_suffix = ['.rst', '.md']
6546 source_suffix = '.rst'
6547 # The encoding of source files.
6549 #
6550 # source_encoding = 'utf-8-sig'
6551 # The master toctree document.
6553 master_doc = 'index'
6554 # General information about the project.
6556 project = u'test'
6557 copyright = u'2016, test'
6558 author = u'test'
6559 # The version info for the project you're documenting, acts as replacement for
6561 # |version| and |release|, also used in various other places throughout the
6562 # built documents.
6563 #
6564 # The short X.Y version.
6565 version = u'test'
6566 # The full version, including alpha/beta/rc tags.
6567 release = u'test'
6568 # The language for content autogenerated by Sphinx. Refer to documentation
6570 # for a list of supported languages.
6571 #
6572 # This is also used if you do content translation via gettext catalogs.
6573 # Usually you set "language" from the command line for these cases.
6574 language = None
6575 # There are two options for replacing |today|: either, you set today to some
6577 # non-false value, then it is used:
6578 #
6579 # today = ''
6580 #
6581 # Else, today_fmt is used as the format for a strftime call.
6582 #
6583 # today_fmt = '%B %d, %Y'
6584 # List of patterns, relative to source directory, that match files and
6586 # directories to ignore when looking for source files.
6587 # These patterns also affect html_static_path and html_extra_path
6588 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
6589 # The reST default role (used for this markup: `text`) to use for all
6591 # documents.
6592 #
6593 # default_role = None
6594 # If true, '()' will be appended to :func: etc. cross-reference text.
6596 #
6597 # add_function_parentheses = True
6598 # If true, the current module name will be prepended to all description
6600 # unit titles (such as .. function::).
6601 #
6602 # add_module_names = True
6603 # If true, sectionauthor and moduleauthor directives will be shown in the
6605 # output. They are ignored by default.
6606 #
6607 # show_authors = False
6608 # The name of the Pygments (syntax highlighting) style to use.
6610 pygments_style = 'sphinx'
6611 # A list of ignored prefixes for module index sorting.
6613 # modindex_common_prefix = []
6614 # If true, keep warnings as "system message" paragraphs in the built documents.
6616 # keep_warnings = False
6617 # If true, `todo` and `todoList` produce output, else they produce nothing.
6619 todo_include_todos = False
6620 # -- Options for HTML output ----------------------------------------------
6623 # The theme to use for HTML and HTML Help pages. See the documentation for
6625 # a list of builtin themes.
6626 #
6627 html_theme = 'alabaster'
6628 # Theme options are theme-specific and customize the look and feel of a theme
6630 # further. For a list of options available for each theme, see the
6631 # documentation.
6632 #
6633 # html_theme_options = {}
6634 # Add any paths that contain custom themes here, relative to this directory.
6636 # html_theme_path = []
6637 # The name for this set of Sphinx documents.
6639 # "<project> v<release> documentation" by default.
6640 #
6641 # html_title = u'test vtest'
6642 # A shorter title for the navigation bar. Default is the same as html_title.
6644 #
6645 # html_short_title = None
6646 # The name of an image file (relative to this directory) to place at the top
6648 # of the sidebar.
6649 #
6650 # html_logo = None
6651 # The name of an image file (relative to this directory) to use as a favicon of
6653 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
6654 # pixels large.
6655 #
6656 # html_favicon = None
6657 # Add any paths that contain custom static files (such as style sheets) here,
6659 # relative to this directory. They are copied after the builtin static files,
6660 # so a file named "default.css" will overwrite the builtin "default.css".
6661 html_static_path = ['_static']
6662 # Add any extra paths that contain custom files (such as robots.txt or
6664 # .htaccess) here, relative to this directory. These files are copied
6665 # directly to the root of the documentation.
6666 #
6667 # html_extra_path = []
6668 # If not None, a 'Last updated on:' timestamp is inserted at every page
6670 # bottom, using the given strftime format.
6671 # The empty string is equivalent to '%b %d, %Y'.
6672 #
6673 # html_last_updated_fmt = None
6674 # Custom sidebar templates, maps document names to template names.
6676 #
6677 # html_sidebars = {}
6678 # Additional templates that should be rendered to pages, maps page names to
6680 # template names.
6681 #
6682 # html_additional_pages = {}
6683 # If false, no module index is generated.
6685 #
6686 # html_domain_indices = True
6687 # If false, no index is generated.
6689 #
6690 # html_use_index = True
6691 # If true, the index is split into individual pages for each letter.
6693 #
6694 # html_split_index = False
6695 # If true, links to the reST sources are added to the pages.
6697 #
6698 # html_show_sourcelink = True
6699 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
6701 #
6702 # html_show_sphinx = True
6703 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
6705 #
6706 # html_show_copyright = True
6707 # If true, an OpenSearch description file will be output, and all pages will
6709 # contain a <link> tag referring to it. The value of this option must be the
6710 # base URL from which the finished HTML is served.
6711 #
6712 # html_use_opensearch = ''
6713 # This is the file name suffix for HTML files (e.g. ".xhtml").
6715 # html_file_suffix = None
6716 # Language to be used for generating the HTML full-text search index.
6718 # Sphinx supports the following languages:
6719 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
6720 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
6721 #
6722 # html_search_language = 'en'
6723 # A dictionary with options for the search language support, empty by default.
6725 # 'ja' uses this config value.
6726 # 'zh' user can custom change `jieba` dictionary path.
6727 #
6728 # html_search_options = {'type': 'default'}
6729 # The name of a javascript file (relative to the configuration directory) that
6731 # implements a search results scorer. If empty, the default will be used.
6732 #
6733 # html_search_scorer = 'scorer.js'
6734 # Output file base name for HTML help builder.
6736 htmlhelp_basename = 'testdoc'
6737 # -- Options for LaTeX output ---------------------------------------------
6739 latex_elements = {
6741 # The paper size ('letterpaper' or 'a4paper').
6742 #
6743 # 'papersize': 'letterpaper',
6744 # The font size ('10pt', '11pt' or '12pt').
6746 #
6747 # 'pointsize': '10pt',
6748 # Additional stuff for the LaTeX preamble.
6750 #
6751 # 'preamble': '',
6752 # Latex figure (float) alignment
6754 #
6755 # 'figure_align': 'htbp',
6756 }
6757 # Grouping the document tree into LaTeX files. List of tuples
6759 # (source start file, target name, title,
6760 # author, documentclass [howto, manual, or own class]).
6761 latex_documents = [
6762 (master_doc, 'test.tex', u'test Documentation',
6763 u'test', 'manual'),
6764 ]
6765 # The name of an image file (relative to this directory) to place at the top of
6767 # the title page.
6768 #
6769 # latex_logo = None
6770 # If true, show page references after internal links.
6772 #
6773 # latex_show_pagerefs = False
6774 # If true, show URL addresses after external links.
6776 #
6777 # latex_show_urls = False
6778 # Documents to append as an appendix to all manuals.
6780 #
6781 # latex_appendices = []
6782 # If false, no module index is generated.
6784 #
6785 # latex_domain_indices = True
6786 # -- Options for manual page output ---------------------------------------
6789 # One entry per manual page. List of tuples
6791 # (source start file, name, description, authors, manual section).
6792 man_pages = [
6793 (master_doc, 'test', u'test Documentation',
6794 [author], 1)
6795 ]
6796 # If true, show URL addresses after external links.
6798 #
6799 # man_show_urls = False
6800 # -- Options for Texinfo output -------------------------------------------
6803 # Grouping the document tree into Texinfo files. List of tuples
6805 # (source start file, target name, title, author,
6806 # dir menu entry, description, category)
6807 texinfo_documents = [
6808 (master_doc, 'test', u'test Documentation',
6809 author, 'test', 'One line description of project.',
6810 'Miscellaneous'),
6811 ]
6812 # Documents to append as an appendix to all manuals.
6814 #
6815 # texinfo_appendices = []
6816 # If false, no module index is generated.
6818 #
6819 # texinfo_domain_indices = True
6820 # How to display URL addresses: 'footnote', 'no', or 'inline'.
6822 #
6823 # texinfo_show_urls = 'footnote'
6824 # If true, do not generate a @detailmenu in the "Top" node's menu.
6826 #
6827 # texinfo_no_detailmenu = False
6828 # -- A random example -----------------------------------------------------
6830 import sys, os
6832 sys.path.insert(0, os.path.abspath('.'))
6833 exclude_patterns = ['zzz']
6834 numfig = True
6836 #language = 'ja'
6837 extensions.append('sphinx.ext.todo')
6839 extensions.append('sphinx.ext.autodoc')
6840 #extensions.append('sphinx.ext.autosummary')
6841 extensions.append('sphinx.ext.intersphinx')
6842 extensions.append('sphinx.ext.mathjax')
6843 extensions.append('sphinx.ext.viewcode')
6844 extensions.append('sphinx.ext.graphviz')
6845 autosummary_generate = True
6848 html_theme = 'default'
6849 #source_suffix = ['.rst', '.txt']
6850
6853 These are the built-in Sphinx builders. More builders can be added by
6854 extensions.
6855 The builder’s “name” must be given to the -b command-line option of
6857 sphinx-build to select a builder.
6858 class sphinx.builders.html.StandaloneHTMLBuilder
6860 This is the standard HTML builder. Its output is a directory
6861 with HTML files, complete with style sheets and optionally the
6862 reST sources. There are quite a few configuration values that
6863 customize the output of this builder, see the chapter
6864 html-options for details.
6865 name = 'html'
6867 format = 'html'
6869 supported_image_types = ['image/svg+xml', 'image/png',
6871 'image/gif', 'image/jpeg']
6872 class sphinx.builders.dirhtml.DirectoryHTMLBuilder
6874 This is a subclass of the standard HTML builder. Its output is
6875 a directory with HTML files, where each file is called
6876 index.html and placed in a subdirectory named like its page
6877 name. For example, the document markup/rest.rst will not result
6878 in an output file markup/rest.html, but markup/rest/index.html.
6879 When generating links between pages, the index.html is omitted,
6880 so that the URL would look like markup/rest/.
6881 name = 'dirhtml'
6883 format = 'html'
6885 supported_image_types = ['image/svg+xml', 'image/png',
6887 'image/gif', 'image/jpeg']
6888 New in version 0.6.
6890 class sphinx.builders.singlehtml.SingleFileHTMLBuilder
6893 This is an HTML builder that combines the whole project in one
6894 output file. (Obviously this only works with smaller projects.)
6895 The file is named like the master document. No indices will be
6896 generated.
6897 name = 'singlehtml'
6899 format = 'html'
6901 supported_image_types = ['image/svg+xml', 'image/png',
6903 'image/gif', 'image/jpeg']
6904 New in version 1.0.
6906 class sphinxcontrib.htmlhelp.HTMLHelpBuilder
6909 This builder produces the same output as the standalone HTML
6910 builder, but also generates HTML Help support files that allow
6911 the Microsoft HTML Help Workshop to compile them into a CHM
6912 file.
6913 name = 'htmlhelp'
6915 format = 'html'
6917 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
6919 class sphinxcontrib.qthelp.QtHelpBuilder
6921 This builder produces the same output as the standalone HTML
6922 builder, but also generates Qt help collection support files
6923 that allow the Qt collection generator to compile them.
6924 Changed in version 2.0: Moved to sphinxcontrib.qthelp from
6926 sphinx.builders package.
6927 name = 'qthelp'
6930 format = 'html'
6932 supported_image_types = ['image/svg+xml', 'image/png',
6934 'image/gif', 'image/jpeg']
6935 class sphinxcontrib.applehelp.AppleHelpBuilder
6937 This builder produces an Apple Help Book based on the same out‐
6938 put as the standalone HTML builder.
6939 If the source directory contains any .lproj folders, the one
6941 corresponding to the selected language will have its contents
6942 merged with the generated output. These folders will be ignored
6943 by all other documentation types.
6944 In order to generate a valid help book, this builder requires
6946 the command line tool hiutil, which is only available on Mac OS
6947 X 10.6 and above. You can disable the indexing step by setting
6948 applehelp_disable_external_tools to True, in which case the out‐
6949 put will not be valid until hiutil has been run on all of the
6950 .lproj folders within the bundle.
6951 name = 'applehelp'
6953 format = 'html'
6955 supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
6957 'image/tiff', 'image/jp2', 'image/svg+xml']
6958 New in version 1.3.
6960 Changed in version 2.0: Moved to sphinxcontrib.applehelp from
6963 sphinx.builders package.
6964 class sphinxcontrib.devhelp.DevhelpBuilder
6967 This builder produces the same output as the standalone HTML
6968 builder, but also generates GNOME Devhelp support file that
6969 allows the GNOME Devhelp reader to view them.
6970 name = 'devhelp'
6972 format = 'html'
6974 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
6976 Changed in version 2.0: Moved to sphinxcontrib.devhelp from
6978 sphinx.builders package.
6979 class sphinx.builders.epub3.Epub3Builder
6982 This builder produces the same output as the standalone HTML
6983 builder, but also generates an epub file for ebook readers. See
6984 epub-faq for details about it. For definition of the epub for‐
6985 mat, have a look at http://idpf.org/epub or
6986 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
6987 files.
6988 name = 'epub'
6990 format = 'html'
6992 supported_image_types = ['image/svg+xml', 'image/png',
6994 'image/gif', 'image/jpeg']
6995 New in version 1.4.
6997 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
7000 used for the default builder of epub.
7001 class sphinx.builders.latex.LaTeXBuilder
7004 This builder produces a bunch of LaTeX files in the output
7005 directory. You have to specify which documents are to be
7006 included in which LaTeX files via the latex_documents configura‐
7007 tion value. There are a few configuration values that customize
7008 the output of this builder, see the chapter latex-options for
7009 details.
7010 The produced LaTeX file uses several LaTeX packages that may not
7012 be present in a “minimal” TeX distribution installation.
7013 On Ubuntu xenial, the following packages need to be installed
7015 for successful PDF builds:
7016 · texlive-latex-recommended
7018 · texlive-fonts-recommended
7020 · texlive-latex-extra
7022 · latexmk (this is a Sphinx requirement on GNU/Linux and MacOS X
7024 for functioning of make latexpdf)
7025 Additional packages are needed in some circumstances (see the
7027 discussion of the 'fontpkg' key of latex_elements for more
7028 information):
7029 · to support occasional Cyrillic letters or words, and a for‐
7031 tiori if language is set to a Cyrillic language, the package
7032 texlive-lang-cyrillic is required, and, with unmodified
7033 'fontpkg', also cm-super or cm-super-minimal,
7034 · to support occasional Greek letters or words (in text, not in
7036 math directive contents), texlive-lang-greek is required, and,
7037 with unmodified 'fontpkg', also cm-super or cm-super-minimal,
7038 · for 'xelatex' or 'lualatex' (see latex_engine), texlive-xetex
7040 resp. texlive-luatex, and, if leaving unchanged 'fontpkg',
7041 fonts-freefont-otf.
7042 The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX
7044 distribution is based on a TeXLive 2015 snapshot dated March
7045 2016.
7046 Changed in version 1.6: Formerly, testing had been done on
7048 Ubuntu precise (TeXLive 2009).
7049 Changed in version 2.0: Formerly, testing had been done on
7052 Ubuntu trusty (TeXLive 2013).
7053 NOTE:
7056 Since 1.6, make latexpdf uses latexmk (not on Windows). This
7057 makes sure the needed number of runs is automatically exe‐
7058 cuted to get the cross-references, bookmarks, indices, and
7059 tables of contents right.
7060 One can pass to latexmk options via the LATEXMKOPTS Makefile
7062 variable. For example:
7063 make latexpdf LATEXMKOPTS="-silent"
7065 reduces console output to a minimum.
7067 Also, if latexmk is at version 4.52b or higher (January 2017)
7069 LATEXMKOPTS="-xelatex" speeds up PDF builds via XeLateX in
7070 case of numerous graphics inclusions.
7071 To pass options directly to the (pdf|xe|lua)latex binary, use
7073 variable LATEXOPTS, for example:
7074 make latexpdf LATEXOPTS="--halt-on-error"
7076 name = 'latex'
7078 format = 'latex'
7080 supported_image_types = ['application/pdf', 'image/png',
7082 'image/jpeg']
7083 Note that a direct PDF builder is being provided by rinohtype. The
7085 builder’s name is rinoh. Refer to the rinohtype manual for details.
7086 class sphinx.builders.text.TextBuilder
7088 This builder produces a text file for each reST file – this is
7089 almost the same as the reST source, but with much of the markup
7090 stripped for better readability.
7091 name = 'text'
7093 format = 'text'
7095 supported_image_types = []
7097 New in version 0.4.
7099 class sphinx.builders.manpage.ManualPageBuilder
7102 This builder produces manual pages in the groff format. You
7103 have to specify which documents are to be included in which man‐
7104 ual pages via the man_pages configuration value.
7105 name = 'man'
7107 format = 'man'
7109 supported_image_types = []
7111 New in version 1.0.
7113 class sphinx.builders.texinfo.TexinfoBuilder
7116 This builder produces Texinfo files that can be processed into
7117 Info files by the makeinfo program. You have to specify which
7118 documents are to be included in which Texinfo files via the tex‐
7119 info_documents configuration value.
7120 The Info format is the basis of the on-line help system used by
7122 GNU Emacs and the terminal-based program info. See texinfo-faq
7123 for more details. The Texinfo format is the official documenta‐
7124 tion system used by the GNU project. More information on Tex‐
7125 info can be found at https://www.gnu.org/software/texinfo/.
7126 name = 'texinfo'
7128 format = 'texinfo'
7130 supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
7132 New in version 1.1.
7134 class sphinxcontrib.serializinghtml.SerializingHTMLBuilder
7137 This builder uses a module that implements the Python serializa‐
7138 tion API (pickle, simplejson, phpserialize, and others) to dump
7139 the generated HTML documentation. The pickle builder is a sub‐
7140 class of it.
7141 A concrete subclass of this builder serializing to the PHP seri‐
7143 alization format could look like this:
7144 import phpserialize
7146 class PHPSerializedBuilder(SerializingHTMLBuilder):
7148 name = 'phpserialized'
7149 implementation = phpserialize
7150 out_suffix = '.file.phpdump'
7151 globalcontext_filename = 'globalcontext.phpdump'
7152 searchindex_filename = 'searchindex.phpdump'
7153 implementation
7155 A module that implements dump(), load(), dumps() and
7156 loads() functions that conform to the functions with the
7157 same names from the pickle module. Known modules imple‐
7158 menting this interface are simplejson, phpserialize,
7159 plistlib, and others.
7160 out_suffix
7162 The suffix for all regular files.
7163 globalcontext_filename
7165 The filename for the file that contains the “global con‐
7166 text”. This is a dict with some general configuration
7167 values such as the name of the project.
7168 searchindex_filename
7170 The filename for the search index Sphinx generates.
7171 See Serialization builder details for details about the output
7173 format.
7174 New in version 0.5.
7176 class sphinxcontrib.serializinghtml.PickleHTMLBuilder
7179 This builder produces a directory with pickle files containing
7180 mostly HTML fragments and TOC information, for use of a web
7181 application (or custom postprocessing tool) that doesn’t use the
7182 standard HTML templates.
7183 See Serialization builder details for details about the output
7185 format.
7186 name = 'pickle'
7188 The old name web still works as well.
7189 format = 'html'
7191 supported_image_types = ['image/svg+xml', 'image/png',
7193 'image/gif', 'image/jpeg']
7194 The file suffix is .fpickle. The global context is called glob‐
7196 alcontext.pickle, the search index searchindex.pickle.
7197 class sphinxcontrib.serializinghtml.JSONHTMLBuilder
7199 This builder produces a directory with JSON files containing
7200 mostly HTML fragments and TOC information, for use of a web
7201 application (or custom postprocessing tool) that doesn’t use the
7202 standard HTML templates.
7203 See Serialization builder details for details about the output
7205 format.
7206 name = 'json'
7208 format = 'html'
7210 supported_image_types = ['image/svg+xml', 'image/png',
7212 'image/gif', 'image/jpeg']
7213 The file suffix is .fjson. The global context is called global‐
7215 context.json, the search index searchindex.json.
7216 New in version 0.5.
7218 class sphinx.builders.gettext.MessageCatalogBuilder
7221 This builder produces gettext-style message catalogs. Each
7222 top-level file or subdirectory grows a single .pot catalog tem‐
7223 plate.
7224 See the documentation on intl for further reference.
7226 name = 'gettext'
7228 format = ''
7230 supported_image_types = []
7232 New in version 1.1.
7234 class sphinx.builders.changes.ChangesBuilder
7237 This builder produces an HTML overview of all versionadded, ver‐
7238 sionchanged and deprecated directives for the current version.
7239 This is useful to generate a ChangeLog file, for example.
7240 name = 'changes'
7242 format = ''
7244 supported_image_types = []
7246 class sphinx.builders.dummy.DummyBuilder
7248 This builder produces no output. The input is only parsed and
7249 checked for consistency. This is useful for linting purposes.
7250 name = 'dummy'
7252 supported_image_types = []
7254 New in version 1.4.
7256 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
7259 This builder scans all documents for external links, tries to
7260 open them with requests, and writes an overview which ones are
7261 broken and redirected to standard output and to output.txt in
7262 the output directory.
7263 name = 'linkcheck'
7265 format = ''
7267 supported_image_types = []
7269 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
7271 comes to use requests module.
7272 class sphinx.builders.xml.XMLBuilder
7275 This builder produces Docutils-native XML files. The output can
7276 be transformed with standard XML tools such as XSLT processors
7277 into arbitrary final forms.
7278 name = 'xml'
7280 format = 'xml'
7282 supported_image_types = []
7284 New in version 1.2.
7286 class sphinx.builders.xml.PseudoXMLBuilder
7289 This builder is used for debugging the Sphinx/Docutils “Reader
7290 to Transform to Writer” pipeline. It produces compact
7291 pretty-printed “pseudo-XML”, files where nesting is indicated by
7292 indentation (no end-tags). External attributes for all elements
7293 are output, and internal attributes for any leftover “pending”
7294 elements are also given.
7295 name = 'pseudoxml'
7297 format = 'pseudoxml'
7299 supported_image_types = []
7301 New in version 1.2.
7303 Built-in Sphinx extensions that offer more builders are:
7306 · doctest
7308 · coverage
7310 Serialization builder details
7312 All serialization builders outputs one file per source file and a few
7313 special files. They also copy the reST source files in the directory
7314 _sources under the output directory.
7315 The PickleHTMLBuilder is a builtin subclass that implements the pickle
7317 serialization interface.
7318 The files per source file have the extensions of out_suffix, and are
7320 arranged in directories just as the source files are. They unserialize
7321 to a dictionary (or dictionary like structure) with these keys:
7322 body The HTML “body” (that is, the HTML rendering of the source
7324 file), as rendered by the HTML translator.
7325 title The title of the document, as HTML (may contain markup).
7327 toc The table of contents for the file, rendered as an HTML <ul>.
7329 display_toc
7331 A boolean that is True if the toc contains more than one entry.
7332 current_page_name
7334 The document name of the current file.
7335 parents, prev and next
7337 Information about related chapters in the TOC tree. Each rela‐
7338 tion is a dictionary with the keys link (HREF for the relation)
7339 and title (title of the related document, as HTML). parents is
7340 a list of relations, while prev and next are a single relation.
7341 sourcename
7343 The name of the source file under _sources.
7344 The special files are located in the root output directory. They are:
7346 SerializingHTMLBuilder.globalcontext_filename
7348 A pickled dict with these keys:
7349 project, copyright, release, version
7351 The same values as given in the configuration file.
7352 style html_style.
7354 last_updated
7356 Date of last build.
7357 builder
7359 Name of the used builder, in the case of pickles this is
7360 always 'pickle'.
7361 titles A dictionary of all documents’ titles, as HTML strings.
7363 SerializingHTMLBuilder.searchindex_filename
7365 An index that can be used for searching the documentation. It
7366 is a pickled list with these entries:
7367 · A list of indexed docnames.
7369 · A list of document titles, as HTML strings, in the same order
7371 as the first list.
7372 · A dict mapping word roots (processed by an English-language
7374 stemmer) to a list of integers, which are indices into the
7375 first list.
7376 environment.pickle
7378 The build environment. This is always a pickle file, indepen‐
7379 dent of the builder and a copy of the environment that was used
7380 when the builder was started.
7381 Todo
7383 Document common members.
7384 Unlike the other pickle files this pickle file requires that the
7386 sphinx package is available on unpickling.
7387
7389 Since many projects will need special features in their documentation,
7390 Sphinx allows adding “extensions” to the build process, each of which
7391 can modify almost any aspect of document processing.
7392 This chapter describes the extensions bundled with Sphinx. For the API
7394 documentation on writing your own extension, refer to dev-extensions.
7395 Built-in extensions
7397 These extensions are built in and can be activated by respective
7398 entries in the extensions configuration value:
7399 sphinx.ext.autodoc – Include documentation from docstrings
7401 This extension can import the modules you are documenting, and pull in
7402 documentation from docstrings in a semi-automatic way.
7403 NOTE:
7405 For Sphinx (actually, the Python interpreter that executes Sphinx)
7406 to find your module, it must be importable. That means that the
7407 module or the package must be in one of the directories on sys.path
7408 – adapt your sys.path in the configuration file accordingly.
7409 WARNING:
7411 autodoc imports the modules to be documented. If any modules have
7412 side effects on import, these will be executed by autodoc when
7413 sphinx-build is run.
7414 If you document scripts (as opposed to library modules), make sure
7416 their main routine is protected by a if __name__ == '__main__' con‐
7417 dition.
7418 For this to work, the docstrings must of course be written in correct
7420 reStructuredText. You can then use all of the usual Sphinx markup in
7421 the docstrings, and it will end up correctly in the documentation.
7422 Together with hand-written documentation, this technique eases the pain
7423 of having to maintain two locations for documentation, while at the
7424 same time avoiding auto-generated-looking pure API documentation.
7425 If you prefer NumPy or Google style docstrings over reStructuredText,
7427 you can also enable the napoleon extension. napoleon is a preprocessor
7428 that converts your docstrings to correct reStructuredText before
7429 autodoc processes them.
7430 Directives
7432 autodoc provides several directives that are versions of the usual
7433 py:module, py:class and so forth. On parsing time, they import the
7434 corresponding module and extract the docstring of the given objects,
7435 inserting them into the page source under a suitable py:module,
7436 py:class etc. directive.
7437 NOTE:
7439 Just as py:class respects the current py:module, autoclass will also
7440 do so. Likewise, automethod will respect the current py:class.
7441 .. automodule::
7443 .. autoclass::
7445 .. autoexception::
7447 Document a module, class or exception. All three directives
7448 will by default only insert the docstring of the object itself:
7449 .. autoclass:: Noodle
7451 will produce source like this:
7453 .. class:: Noodle
7455 Noodle's docstring.
7457 The “auto” directives can also contain content of their own, it
7459 will be inserted into the resulting non-auto directive source
7460 after the docstring (but before any automatic member documenta‐
7461 tion).
7462 Therefore, you can also mix automatic and non-automatic member
7464 documentation, like so:
7465 .. autoclass:: Noodle
7467 :members: eat, slurp
7468 .. method:: boil(time=10)
7470 Boil the noodle *time* minutes.
7472 Options and advanced usage
7474 · If you want to automatically document members, there’s a mem‐
7476 bers option:
7477 .. automodule:: noodle
7479 :members:
7480 will document all module members (recursively), and
7482 .. autoclass:: Noodle
7484 :members:
7485 will document all non-private member functions and properties
7487 (that is, those whose name doesn’t start with _).
7488 For modules, __all__ will be respected when looking for mem‐
7490 bers unless you give the ignore-module-all flag option. With‐
7491 out ignore-module-all, the order of the members will also be
7492 the order in __all__.
7493 You can also give an explicit list of members; only these will
7495 then be documented:
7496 .. autoclass:: Noodle
7498 :members: eat, slurp
7499 · If you want to make the members option (or other options
7501 described below) the default, see autodoc_default_options.
7502 TIP:
7504 You can use a negated form, 'no-flag', as an option of
7505 autodoc directive, to disable it temporarily. For example:
7506 .. automodule:: foo
7508 :no-undoc-members:
7509 · Members without docstrings will be left out, unless you give
7511 the undoc-members flag option:
7512 .. automodule:: noodle
7514 :members:
7515 :undoc-members:
7516 · “Private” members (that is, those named like _private or
7518 __private) will be included if the private-members flag option
7519 is given.
7520 New in version 1.1.
7522 · Python “special” members (that is, those named like __spe‐
7525 cial__) will be included if the special-members flag option is
7526 given:
7527 .. autoclass:: my.Class
7529 :members:
7530 :private-members:
7531 :special-members:
7532 would document both “private” and “special” members of the
7534 class.
7535 New in version 1.1.
7537 Changed in version 1.2: The option can now take arguments,
7540 i.e. the special members to document.
7541 · For classes and exceptions, members inherited from base
7544 classes will be left out when documenting all members, unless
7545 you give the inherited-members flag option, in addition to
7546 members:
7547 .. autoclass:: Noodle
7549 :members:
7550 :inherited-members:
7551 This can be combined with undoc-members to document all avail‐
7553 able members of the class or module.
7554 Note: this will lead to markup errors if the inherited members
7556 come from a module whose docstrings are not reST formatted.
7557 New in version 0.3.
7559 · It’s possible to override the signature for explicitly docu‐
7562 mented callable objects (functions, methods, classes) with the
7563 regular syntax that will override the signature gained from
7564 introspection:
7565 .. autoclass:: Noodle(type)
7567 .. automethod:: eat(persona)
7569 This is useful if the signature from the method is hidden by a
7571 decorator.
7572 New in version 0.4.
7574 · The automodule, autoclass and autoexception directives also
7577 support a flag option called show-inheritance. When given, a
7578 list of base classes will be inserted just below the class
7579 signature (when used with automodule, this will be inserted
7580 for every class that is documented in the module).
7581 New in version 0.4.
7583 · All autodoc directives support the noindex flag option that
7586 has the same effect as for standard py:function etc. direc‐
7587 tives: no index entries are generated for the documented
7588 object (and all autodocumented members).
7589 New in version 0.4.
7591 · automodule also recognizes the synopsis, platform and depre‐
7594 cated options that the standard py:module directive supports.
7595 New in version 0.5.
7597 · automodule and autoclass also has an member-order option that
7600 can be used to override the global value of
7601 autodoc_member_order for one directive.
7602 New in version 0.6.
7604 · The directives supporting member documentation also have a
7607 exclude-members option that can be used to exclude single mem‐
7608 ber names from documentation, if all members are to be docu‐
7609 mented.
7610 New in version 0.6.
7612 · In an automodule directive with the members option set, only
7615 module members whose __module__ attribute is equal to the mod‐
7616 ule name as given to automodule will be documented. This is
7617 to prevent documentation of imported classes or functions.
7618 Set the imported-members option if you want to prevent this
7619 behavior and document all available members. Note that
7620 attributes from imported modules will not be documented,
7621 because attribute documentation is discovered by parsing the
7622 source file of the current module.
7623 New in version 1.2.
7625 · Add a list of modules in the autodoc_mock_imports to prevent
7628 import errors to halt the building process when some external
7629 dependencies are not importable at build time.
7630 New in version 1.3.
7632 .. autofunction::
7635 .. autodecorator::
7637 .. autodata::
7639 .. automethod::
7641 .. autoattribute::
7643 These work exactly like autoclass etc., but do not offer the
7644 options used for automatic member documentation.
7645 autodata and autoattribute support the annotation option. With‐
7647 out this option, the representation of the object will be shown
7648 in the documentation. When the option is given without argu‐
7649 ments, only the name of the object will be printed:
7650 .. autodata:: CD_DRIVE
7652 :annotation:
7653 You can tell sphinx what should be printed after the name:
7655 .. autodata:: CD_DRIVE
7657 :annotation: = your CD device name
7658 For module data members and class attributes, documentation can
7660 either be put into a comment with special formatting (using a #:
7661 to start the comment instead of just #), or in a docstring after
7662 the definition. Comments need to be either on a line of their
7663 own before the definition, or immediately after the assignment
7664 on the same line. The latter form is restricted to one line
7665 only.
7666 This means that in the following class definition, all
7668 attributes can be autodocumented:
7669 class Foo:
7671 """Docstring for class Foo."""
7672 #: Doc comment for class attribute Foo.bar.
7674 #: It can have multiple lines.
7675 bar = 1
7676 flox = 1.5 #: Doc comment for Foo.flox. One line only.
7678 baz = 2
7680 """Docstring for class attribute Foo.baz."""
7681 def __init__(self):
7683 #: Doc comment for instance attribute qux.
7684 self.qux = 3
7685 self.spam = 4
7687 """Docstring for instance attribute spam."""
7688 Changed in version 0.6: autodata and autoattribute can now
7690 extract docstrings.
7691 Changed in version 1.1: Comment docs are now allowed on the same
7694 line after an assignment.
7695 Changed in version 1.2: autodata and autoattribute have an anno‐
7698 tation option.
7699 Changed in version 2.0: autodecorator added.
7702 NOTE:
7705 If you document decorated functions or methods, keep in mind
7706 that autodoc retrieves its docstrings by importing the module
7707 and inspecting the __doc__ attribute of the given function or
7708 method. That means that if a decorator replaces the deco‐
7709 rated function with another, it must copy the original
7710 __doc__ to the new function.
7711 From Python 2.5, functools.wraps() can be used to create
7713 well-behaved decorating functions.
7714 Configuration
7716 There are also 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': True,
7782 'exclude-members': '__weakref__'
7783 }
7784 Setting None or True to the value is equivalent to giving only
7786 the option name to the directives.
7787 The supported options are 'members', 'member-order', 'undoc-mem‐
7789 bers', 'private-members', 'special-members', 'inherited-mem‐
7790 bers', 'show-inheritance', 'ignore-module-all', 'imported-mem‐
7791 bers' and 'exclude-members'.
7792 New in version 1.8.
7794 Changed in version 2.0: Accepts True as a value.
7797 Changed in version 2.1: Added 'imported-members'.
7800 autodoc_docstring_signature
7803 Functions imported from C modules cannot be introspected, and
7804 therefore the signature for such functions cannot be automati‐
7805 cally determined. However, it is an often-used convention to
7806 put the signature into the first line of the function’s doc‐
7807 string.
7808 If this boolean value is set to True (which is the default),
7810 autodoc will look at the first line of the docstring for func‐
7811 tions and methods, and if it looks like a signature, use the
7812 line as the signature and remove it from the docstring content.
7813 New in version 1.1.
7815 autodoc_mock_imports
7818 This value contains a list of modules to be mocked up. This is
7819 useful when some external dependencies are not met at build time
7820 and break the building process. You may only specify the root
7821 package of the dependencies themselves and omit the sub-modules:
7822 autodoc_mock_imports = ["django"]
7824 Will mock all imports under the django package.
7826 New in version 1.3.
7828 Changed in version 1.6: This config value only requires to
7831 declare the top-level modules that should be mocked.
7832 autodoc_typehints
7835 This value controls how to represents typehints. The setting
7836 takes the following values:
7837 · 'signature' – Show typehints as its signature (default)
7839 · 'none' – Do not show typehints
7841 autodoc_warningiserror
7843 This value controls the behavior of sphinx-build -W during
7844 importing modules. If False is given, autodoc forcedly sup‐
7845 presses the error if the imported module emits warnings. By
7846 default, True.
7847 autodoc_inherit_docstrings
7849 This value controls the docstrings inheritance. If set to True
7850 the docstring for classes or methods, if not explicitly set, is
7851 inherited form parents.
7852 The default is True.
7854 New in version 1.7.
7856 suppress_warnings
7859 autodoc supports to suppress warning messages via suppress_warn‐
7860 ings. It allows following warnings types in addition:
7861 · autodoc
7863 · autodoc.import_object
7865 Docstring preprocessing
7867 autodoc provides the following additional events:
7868 autodoc-process-docstring(app, what, name, obj, options, lines)
7870 New in version 0.4.
7871 Emitted when autodoc has read and processed a docstring. lines
7874 is a list of strings – the lines of the processed docstring –
7875 that the event handler can modify in place to change what Sphinx
7876 puts into the output.
7877 Parameters
7879 · app – the Sphinx application object
7881 · what – the type of the object which the docstring
7883 belongs to (one of "module", "class", "exception",
7884 "function", "method", "attribute")
7885 · name – the fully qualified name of the object
7887 · obj – the object itself
7889 · options – the options given to the directive: an object
7891 with attributes inherited_members, undoc_members,
7892 show_inheritance and noindex that are true if the flag
7893 option of same name was given to the auto directive
7894 · lines – the lines of the docstring, see above
7896 autodoc-process-signature(app, what, name, obj, options, signature,
7898 return_annotation)
7899 New in version 0.5.
7900 Emitted when autodoc has formatted a signature for an object.
7903 The event handler can return a new tuple (signature,
7904 return_annotation) to change what Sphinx puts into the output.
7905 Parameters
7907 · app – the Sphinx application object
7909 · what – the type of the object which the docstring
7911 belongs to (one of "module", "class", "exception",
7912 "function", "method", "attribute")
7913 · name – the fully qualified name of the object
7915 · obj – the object itself
7917 · options – the options given to the directive: an object
7919 with attributes inherited_members, undoc_members,
7920 show_inheritance and noindex that are true if the flag
7921 option of same name was given to the auto directive
7922 · signature – function signature, as a string of the form
7924 "(parameter_1, parameter_2)", or None if introspection
7925 didn’t succeed and signature wasn’t specified in the
7926 directive.
7927 · return_annotation – function return annotation as a
7929 string of the form " -> annotation", or None if there
7930 is no return annotation
7931 The sphinx.ext.autodoc module provides factory functions for commonly
7933 needed docstring processing in event autodoc-process-docstring:
7934 sphinx.ext.autodoc.cut_lines(pre, post=0, what=None)
7936 Return a listener that removes the first pre and last post lines
7937 of every docstring. If what is a sequence of strings, only doc‐
7938 strings of a type in what will be processed.
7939 Use like this (e.g. in the setup() function of conf.py):
7941 from sphinx.ext.autodoc import cut_lines
7943 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
7944 This can (and should) be used in place of automodule_skip_lines.
7946 sphinx.ext.autodoc.between(marker, what=None, keepempty=False,
7948 exclude=False)
7949 Return a listener that either keeps, or if exclude is True
7950 excludes, lines between lines that match the marker regular
7951 expression. If no line matches, the resulting docstring would
7952 be empty, so no change will be made unless keepempty is true.
7953 If what is a sequence of strings, only docstrings of a type in
7955 what will be processed.
7956 Skipping members
7958 autodoc allows the user to define a custom method for determining
7959 whether a member should be included in the documentation by using the
7960 following event:
7961 autodoc-skip-member(app, what, name, obj, skip, options)
7963 New in version 0.5.
7964 Emitted when autodoc has to decide whether a member should be
7967 included in the documentation. The member is excluded if a han‐
7968 dler returns True. It is included if the handler returns False.
7969 If more than one enabled extension handles the autodoc-skip-mem‐
7971 ber event, autodoc will use the first non-None value returned by
7972 a handler. Handlers should return None to fall back to the
7973 skipping behavior of autodoc and other enabled extensions.
7974 Parameters
7976 · app – the Sphinx application object
7978 · what – the type of the object which the docstring
7980 belongs to (one of "module", "class", "exception",
7981 "function", "method", "attribute")
7982 · name – the fully qualified name of the object
7984 · obj – the object itself
7986 · skip – a boolean indicating if autodoc will skip this
7988 member if the user handler does not override the deci‐
7989 sion
7990 · options – the options given to the directive: an object
7992 with attributes inherited_members, undoc_members,
7993 show_inheritance and noindex that are true if the flag
7994 option of same name was given to the auto directive
7995 sphinx.ext.autosectionlabel – Allow reference sections using its title
7997 New in version 1.4.
7998 This extension allows you to refer sections its title. This affects to
8001 the reference role (ref).
8002 For example:
8004 A Plain Title
8006 -------------
8007 This is the text of the section.
8009 It refers to the section title, see :ref:`A Plain Title`.
8011 Internally, this extension generates the labels for each section. If
8013 same section names are used in whole of document, any one is used for a
8014 target by default. The autosectionlabel_prefix_document configuration
8015 variable can be used to make headings which appear multiple times but
8016 in different documents unique.
8017 Configuration
8019 autosectionlabel_prefix_document
8020 True to prefix each section label with the name of the document
8021 it is in, followed by a colon. For example, index:Introduction
8022 for a section called Introduction that appears in document
8023 index.rst. Useful for avoiding ambiguity when the same section
8024 heading appears in different documents.
8025 autosectionlabel_maxdepth
8027 If set, autosectionlabel chooses the sections for labeling by
8028 its depth. For example, when set 1 to autosectionlabel_maxdepth,
8029 labels are generated only for top level sections, and deeper
8030 sections are not labeled. It defaults to None (disabled).
8031 sphinx.ext.autosummary – Generate autodoc summaries
8033 New in version 0.6.
8034 This extension generates function/method/attribute summary lists, simi‐
8037 lar to those output e.g. by Epydoc and other API doc generation tools.
8038 This is especially useful when your docstrings are long and detailed,
8039 and putting each one of them on a separate page makes them easier to
8040 read.
8041 The sphinx.ext.autosummary extension does this in two parts:
8043 1. There is an autosummary directive for generating summary listings
8045 that contain links to the documented items, and short summary blurbs
8046 extracted from their docstrings.
8047 2. Optionally, the convenience script sphinx-autogen or the new
8049 autosummary_generate config value can be used to generate short
8050 “stub” files for the entries listed in the autosummary directives.
8051 These files by default contain only the corresponding
8052 sphinx.ext.autodoc directive, but can be customized with templates.
8053 .. autosummary::
8055 Insert a table that contains links to documented items, and a
8056 short summary blurb (the first sentence of the docstring) for
8057 each of them.
8058 The autosummary directive can also optionally serve as a toctree
8060 entry for the included items. Optionally, stub .rst files for
8061 these items can also be automatically generated.
8062 For example,
8064 .. currentmodule:: sphinx
8066 .. autosummary::
8068 environment.BuildEnvironment
8070 util.relative_uri
8071 produces a table like this:
8073 ┌──────────────────────────┬────────────────────────────┐
8075 │environment.BuildEnviron‐ │ The environment in which │
8076 │ment([app]) │ the ReST files are trans‐ │
8077 │ │ lated. │
8078 ├──────────────────────────┼────────────────────────────┤
8079 │util.relative_uri(base, │ Return a relative URL from │
8080 │to) │ base to to. │
8081 └──────────────────────────┴────────────────────────────┘
8082 Autosummary preprocesses the docstrings and signatures with the
8084 same autodoc-process-docstring and autodoc-process-signature
8085 hooks as autodoc.
8086 Options
8088 · If you want the autosummary table to also serve as a toctree
8090 entry, use the toctree option, for example:
8091 .. autosummary::
8093 :toctree: DIRNAME
8094 sphinx.environment.BuildEnvironment
8096 sphinx.util.relative_uri
8097 The toctree option also signals to the sphinx-autogen script
8099 that stub pages should be generated for the entries listed in
8100 this directive. The option accepts a directory name as an
8101 argument; sphinx-autogen will by default place its output in
8102 this directory. If no argument is given, output is placed in
8103 the same directory as the file that contains the directive.
8104 · If you don’t want the autosummary to show function signatures
8106 in the listing, include the nosignatures option:
8107 .. autosummary::
8109 :nosignatures:
8110 sphinx.environment.BuildEnvironment
8112 sphinx.util.relative_uri
8113 · You can specify a custom template with the template option.
8115 For example,
8116 .. autosummary::
8118 :template: mytemplate.rst
8119 sphinx.environment.BuildEnvironment
8121 would use the template mytemplate.rst in your templates_path
8123 to generate the pages for all entries listed. See Customizing
8124 templates below.
8125 New in version 1.0.
8127 sphinx-autogen – generate autodoc stub pages
8130 The sphinx-autogen script can be used to conveniently generate stub
8131 documentation pages for items included in autosummary listings.
8132 For example, the command
8134 $ sphinx-autogen -o generated *.rst
8136 will read all autosummary tables in the *.rst files that have the :toc‐
8138 tree: option set, and output corresponding stub pages in directory gen‐
8139 erated for all documented items. The generated pages by default con‐
8140 tain text of the form:
8141 sphinx.util.relative_uri
8143 ========================
8144 .. autofunction:: sphinx.util.relative_uri
8146 If the -o option is not given, the script will place the output files
8148 in the directories specified in the :toctree: options.
8149 For more information, refer to the sphinx-autogen documentation
8151 Generating stub pages automatically
8153 If you do not want to create stub pages with sphinx-autogen, you can
8154 also use these config values:
8155 autosummary_generate
8157 Boolean indicating whether to scan all found documents for auto‐
8158 summary directives, and to generate stub pages for each.
8159 Can also be a list of documents for which stub pages should be
8161 generated.
8162 The new files will be placed in the directories specified in the
8164 :toctree: options of the directives.
8165 autosummary_mock_imports
8167 This value contains a list of modules to be mocked up. See
8168 autodoc_mock_imports for more details. It defaults to
8169 autodoc_mock_imports.
8170 New in version 2.0.
8172 autosummary_imported_members
8175 A boolean flag indicating whether to document classes and func‐
8176 tions imported in modules. Default is False
8177 New in version 2.1.
8179 Customizing templates
8182 New in version 1.0.
8183 You can customize the stub page templates, in a similar way as the HTML
8186 Jinja templates, see templating. (TemplateBridge is not supported.)
8187 NOTE:
8189 If you find yourself spending much time tailoring the stub tem‐
8190 plates, this may indicate that it’s a better idea to write custom
8191 narrative documentation instead.
8192 Autosummary uses the following Jinja template files:
8194 · autosummary/base.rst – fallback template
8196 · autosummary/module.rst – template for modules
8198 · autosummary/class.rst – template for classes
8200 · autosummary/function.rst – template for functions
8202 · autosummary/attribute.rst – template for class attributes
8204 · autosummary/method.rst – template for class methods
8206 The following variables available in the templates:
8208 name Name of the documented object, excluding the module and class
8210 parts.
8211 objname
8213 Name of the documented object, excluding the module parts.
8214 fullname
8216 Full name of the documented object, including module and class
8217 parts.
8218 module Name of the module the documented object belongs to.
8220 class Name of the class the documented object belongs to. Only avail‐
8222 able for methods and attributes.
8223 underline
8225 A string containing len(full_name) * '='. Use the underline fil‐
8226 ter instead.
8227 members
8229 List containing names of all members of the module or class.
8230 Only available for modules and classes.
8231 inherited_members
8233 List containing names of all inherited members of class. Only
8234 available for classes.
8235 New in version 1.8.0.
8237 functions
8240 List containing names of “public” functions in the module.
8241 Here, “public” here means that the name does not start with an
8242 underscore. Only available for modules.
8243 classes
8245 List containing names of “public” classes in the module. Only
8246 available for modules.
8247 exceptions
8249 List containing names of “public” exceptions in the module.
8250 Only available for modules.
8251 methods
8253 List containing names of “public” methods in the class. Only
8254 available for classes.
8255 attributes
8257 List containing names of “public” attributes in the class. Only
8258 available for classes.
8259 Additionally, the following filters are available
8261 escape(s)
8263 Escape any special characters in the text to be used in format‐
8264 ting RST contexts. For instance, this prevents asterisks making
8265 things bold. This replaces the builtin Jinja escape filter that
8266 does html-escaping.
8267 underline(s, line='=')
8269 Add a title underline to a piece of text.
8270 For instance, {{ fullname | escape | underline }} should be used to
8272 produce the title of a page.
8273 NOTE:
8275 You can use the autosummary directive in the stub pages. Stub pages
8276 are generated also based on these directives.
8277 sphinx.ext.coverage – Collect doc coverage stats
8279 This extension features one additional builder, the CoverageBuilder.
8280 class sphinx.ext.coverage.CoverageBuilder
8282 To use this builder, activate the coverage extension in your
8283 configuration file and give -b coverage on the command line.
8284 Todo
8286 Write this section.
8287 Several configuration values can be used to specify what the builder
8289 should check:
8290 coverage_ignore_modules
8292 coverage_ignore_functions
8294 coverage_ignore_classes
8296 coverage_ignore_pyobjects
8298 List of Python regular expressions.
8299 If any of these regular expressions matches any part of the full
8301 import path of a Python object, that Python object is excluded
8302 from the documentation coverage report.
8303 New in version 2.1.
8305 coverage_c_path
8308 coverage_c_regexes
8310 coverage_ignore_c_items
8312 coverage_write_headline
8314 Set to False to not write headlines.
8315 New in version 1.1.
8317 coverage_skip_undoc_in_source
8320 Skip objects that are not documented in the source with a doc‐
8321 string. False by default.
8322 New in version 1.1.
8324 sphinx.ext.doctest – Test snippets in the documentation
8327 This extension allows you to test snippets in the documentation in a
8328 natural way. It works by collecting specially-marked up code blocks
8329 and running them as doctest tests.
8330 Within one document, test code is partitioned in groups, where each
8332 group consists of:
8333 · zero or more setup code blocks (e.g. importing the module to test)
8335 · one or more test blocks
8337 When building the docs with the doctest builder, groups are collected
8339 for each document and run one after the other, first executing setup
8340 code blocks, then the test blocks in the order they appear in the file.
8341 There are two kinds of test blocks:
8343 · doctest-style blocks mimic interactive sessions by interleaving
8345 Python code (including the interpreter prompt) and output.
8346 · code-output-style blocks consist of an ordinary piece of Python code,
8348 and optionally, a piece of output for that code.
8349 Directives
8351 The group argument below is interpreted as follows: if it is empty, the
8352 block is assigned to the group named default. If it is *, the block is
8353 assigned to all groups (including the default group). Otherwise, it
8354 must be a comma-separated list of group names.
8355 .. testsetup:: [group]
8357 A setup code block. This code is not shown in the output for
8358 other builders, but executed before the doctests of the group(s)
8359 it belongs to.
8360 .. testcleanup:: [group]
8362 A cleanup code block. This code is not shown in the output for
8363 other builders, but executed after the doctests of the group(s)
8364 it belongs to.
8365 New in version 1.1.
8367 .. doctest:: [group]
8370 A doctest-style code block. You can use standard doctest flags
8371 for controlling how actual output is compared with what you give
8372 as output. The default set of flags is specified by the
8373 doctest_default_flags configuration variable.
8374 This directive supports three options:
8376 · hide, a flag option, hides the doctest block in other
8378 builders. By default it is shown as a highlighted doctest
8379 block.
8380 · options, a string option, can be used to give a comma-sepa‐
8382 rated list of doctest flags that apply to each example in the
8383 tests. (You still can give explicit flags per example, with
8384 doctest comments, but they will show up in other builders
8385 too.)
8386 · pyversion, a string option, can be used to specify the
8388 required Python version for the example to be tested. For
8389 instance, in the following case the example will be tested
8390 only for Python versions greater than 3.3:
8391 .. doctest::
8393 :pyversion: > 3.3
8394 The following operands are supported:
8396 · ~=: Compatible release clause
8398 · ==: Version matching clause
8400 · !=: Version exclusion clause
8402 · <=, >=: Inclusive ordered comparison clause
8404 · <, >: Exclusive ordered comparison clause
8406 · ===: Arbitrary equality clause.
8408 pyversion option is followed PEP-440: Version Specifiers.
8410 New in version 1.6.
8412 Changed in version 1.7: Supported PEP-440 operands and nota‐
8415 tions
8416 Note that like with standard doctests, you have to use
8419 <BLANKLINE> to signal a blank line in the expected output. The
8420 <BLANKLINE> is removed when building presentation output (HTML,
8421 LaTeX etc.).
8422 Also, you can give inline doctest options, like in doctest:
8424 >>> datetime.date.now() # doctest: +SKIP
8426 datetime.date(2008, 1, 1)
8427 They will be respected when the test is run, but stripped from
8429 presentation output.
8430 .. testcode:: [group]
8432 A code block for a code-output-style test.
8433 This directive supports one option:
8435 · hide, a flag option, hides the code block in other builders.
8437 By default it is shown as a highlighted code block.
8438 NOTE:
8440 Code in a testcode block is always executed all at once, no
8441 matter how many statements it contains. Therefore, output
8442 will not be generated for bare expressions – use print.
8443 Example:
8444 .. testcode::
8446 1+1 # this will give no output!
8448 print 2+2 # this will give output
8449 .. testoutput::
8451 4
8453 Also, please be aware that since the doctest module does not
8455 support mixing regular output and an exception message in the
8456 same snippet, this applies to testcode/testoutput as well.
8457 .. testoutput:: [group]
8459 The corresponding output, or the exception message, for the last
8460 testcode block.
8461 This directive supports two options:
8463 · hide, a flag option, hides the output block in other builders.
8465 By default it is shown as a literal block without highlight‐
8466 ing.
8467 · options, a string option, can be used to give doctest flags
8469 (comma-separated) just like in normal doctest blocks.
8470 Example:
8472 .. testcode::
8474 print 'Output text.'
8476 .. testoutput::
8478 :hide:
8479 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
8480 Output text.
8482 The following is an example for the usage of the directives. The test
8484 via doctest and the test via testcode and testoutput are equivalent.
8485 The parrot module
8487 =================
8488 .. testsetup:: *
8490 import parrot
8492 The parrot module is a module about parrots.
8494 Doctest example:
8496 .. doctest::
8498 >>> parrot.voom(3000)
8500 This parrot wouldn't voom if you put 3000 volts through it!
8501 Test-Output example:
8503 .. testcode::
8505 parrot.voom(3000)
8507 This would output:
8509 .. testoutput::
8511 This parrot wouldn't voom if you put 3000 volts through it!
8513 Skipping tests conditionally
8515 skipif, a string option, can be used to skip directives conditionally.
8516 This may be useful e.g. when a different set of tests should be run
8517 depending on the environment (hardware, network/VPN, optional dependen‐
8518 cies or different versions of dependencies). The skipif option is sup‐
8519 ported by all of the doctest directives. Below are typical use cases
8520 for skipif when used for different directives:
8521 · testsetup and testcleanup
8523 · conditionally skip test setup and/or cleanup
8525 · customize setup/cleanup code per environment
8527 · doctest
8529 · conditionally skip both a test and its output verification
8531 · testcode
8533 · conditionally skip a test
8535 · customize test code per environment
8537 · testoutput
8539 · conditionally skip output assertion for a skipped test
8541 · expect different output depending on the environment
8543 The value of the skipif option is evaluated as a Python expression. If
8545 the result is a true value, the directive is omitted from the test run
8546 just as if it wasn’t present in the file at all.
8547 Instead of repeating an expression, the doctest_global_setup configura‐
8549 tion option can be used to assign it to a variable which can then be
8550 used instead.
8551 Here’s an example which skips some tests if Pandas is not installed:
8553 conf.py
8555 extensions = ['sphinx.ext.doctest']
8557 doctest_global_setup = '''
8558 try:
8559 import pandas as pd
8560 except ImportError:
8561 pd = None
8562 '''
8563 contents.rst
8565 .. testsetup::
8567 :skipif: pd is None
8568 data = pd.Series([42])
8570 .. doctest::
8572 :skipif: pd is None
8573 >>> data.iloc[0]
8575 42
8576 .. testcode::
8578 :skipif: pd is None
8579 print(data.iloc[-1])
8581 .. testoutput::
8583 :skipif: pd is None
8584 42
8586 Configuration
8588 The doctest extension uses the following configuration values:
8589 doctest_default_flags
8591 By default, these options are enabled:
8592 · ELLIPSIS, allowing you to put ellipses in the expected output
8594 that match anything in the actual output;
8595 · IGNORE_EXCEPTION_DETAIL, causing everything following the
8597 leftmost colon and any module information in the exception
8598 name to be ignored;
8599 · DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
8601 “1” is given – the default behavior of accepting this substi‐
8602 tution is a relic of pre-Python 2.2 times.
8603 New in version 1.5.
8605 doctest_path
8608 A list of directories that will be added to sys.path when the
8609 doctest builder is used. (Make sure it contains absolute
8610 paths.)
8611 doctest_global_setup
8613 Python code that is treated like it were put in a testsetup
8614 directive for every file that is tested, and for every group.
8615 You can use this to e.g. import modules you will always need in
8616 your doctests.
8617 New in version 0.6.
8619 doctest_global_cleanup
8622 Python code that is treated like it were put in a testcleanup
8623 directive for every file that is tested, and for every group.
8624 You can use this to e.g. remove any temporary files that the
8625 tests leave behind.
8626 New in version 1.1.
8628 doctest_test_doctest_blocks
8631 If this is a nonempty string (the default is 'default'), stan‐
8632 dard reST doctest blocks will be tested too. They will be
8633 assigned to the group name given.
8634 reST doctest blocks are simply doctests put into a paragraph of
8636 their own, like so:
8637 Some documentation text.
8639 >>> print 1
8641 1
8642 Some more documentation text.
8644 (Note that no special :: is used to introduce a doctest block;
8646 docutils recognizes them from the leading >>>. Also, no addi‐
8647 tional indentation is used, though it doesn’t hurt.)
8648 If this value is left at its default value, the above snippet is
8650 interpreted by the doctest builder exactly like the following:
8651 Some documentation text.
8653 .. doctest::
8655 >>> print 1
8657 1
8658 Some more documentation text.
8660 This feature makes it easy for you to test doctests in doc‐
8662 strings included with the autodoc extension without marking them
8663 up with a special directive.
8664 Note though that you can’t have blank lines in reST doctest
8666 blocks. They will be interpreted as one block ending and
8667 another one starting. Also, removal of <BLANKLINE> and #
8668 doctest: options only works in doctest blocks, though you may
8669 set trim_doctest_flags to achieve that in all code blocks with
8670 Python console content.
8671 sphinx.ext.extlinks – Markup to shorten external links
8673 Module author: Georg Brandl
8674 New in version 1.0.
8676 This extension is meant to help with the common pattern of having many
8679 external links that point to URLs on one and the same site, e.g. links
8680 to bug trackers, version control web interfaces, or simply subpages in
8681 other websites. It does so by providing aliases to base URLs, so that
8682 you only need to give the subpage name when creating a link.
8683 Let’s assume that you want to include many links to issues at the
8685 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
8686 Typing this URL again and again is tedious, so you can use extlinks to
8687 avoid repeating yourself.
8688 The extension adds a config value:
8690 extlinks
8692 This config value must be a dictionary of external sites, map‐
8693 ping unique short alias names to a base URL and a prefix. For
8694 example, to create an alias for the above mentioned issues, you
8695 would add
8696 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
8698 'issue ')}
8699 Now, you can use the alias name as a new role, e.g.
8701 :issue:`123`. This then inserts a link to
8702 https://github.com/sphinx-doc/sphinx/issues/123. As you can
8703 see, the target given in the role is substituted in the base URL
8704 in the place of %s.
8705 The link caption depends on the second item in the tuple, the
8707 prefix:
8708 · If the prefix is None, the link caption is the full URL.
8710 · If the prefix is the empty string, the link caption is the
8712 partial URL given in the role content (123 in this case.)
8713 · If the prefix is a non-empty string, the link caption is the
8715 partial URL, prepended by the prefix – in the above example,
8716 the link caption would be issue 123.
8717 You can also use the usual “explicit title” syntax supported by
8719 other roles that generate links, i.e. :issue:`this issue <123>`.
8720 In this case, the prefix is not relevant.
8721 NOTE:
8723 Since links are generated from the role in the reading stage, they
8724 appear as ordinary links to e.g. the linkcheck builder.
8725 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
8727 New in version 1.4.
8728 Changed in version 2.0: Support CNAME file
8731 This extension creates .nojekyll file on generated HTML directory to
8734 publish the document on GitHub Pages.
8735 It also creates a CNAME file for custom domains when html_baseurl set.
8737 sphinx.ext.graphviz – Add Graphviz graphs
8739 New in version 0.6.
8740 This extension allows you to embed Graphviz graphs in your documents.
8743 It adds these directives:
8745 .. graphviz::
8747 Directive to embed graphviz code. The input code for dot is
8748 given as the content. For example:
8749 .. graphviz::
8751 digraph foo {
8753 "bar" -> "baz";
8754 }
8755 In HTML output, the code will be rendered to a PNG or SVG image
8757 (see graphviz_output_format). In LaTeX output, the code will be
8758 rendered to an embeddable PDF file.
8759 You can also embed external dot files, by giving the file name
8761 as an argument to graphviz and no additional content:
8762 .. graphviz:: external.dot
8764 As for all file references in Sphinx, if the filename is abso‐
8766 lute, it is taken as relative to the source directory.
8767 Changed in version 1.1: Added support for external files.
8769 options
8772 :alt: alternate text (text)
8774 The alternate text of the graph. By default, the graph
8775 code is used to the alternate text.
8776 New in version 1.0.
8778 :align: alignment of the graph (left, center or right)
8781 The horizontal alignment of the graph.
8782 New in version 1.5.
8784 :caption: caption of the graph (text)
8787 The caption of the graph.
8788 New in version 1.1.
8790 :graphviz_dot: dot command of the graph (text)
8793 The graphviz command (ex. dot, neato and so on) for ren‐
8794 dering the graph. By default, graphviz_dot is used.
8795 New in version 1.4.
8797 :name: label (text)
8800 The label of the graph.
8801 New in version 1.6.
8803 .. graph::
8806 Directive for embedding a single undirected graph. The name is
8807 given as a directive argument, the contents of the graph are the
8808 directive content. This is a convenience directive to generate
8809 graph <name> { <content> }.
8810 For example:
8812 .. graph:: foo
8814 "bar" -- "baz";
8816 NOTE:
8818 The graph name is passed unchanged to Graphviz. If it con‐
8819 tains non-alphanumeric characters (e.g. a dash), you will
8820 have to double-quote it.
8821 options
8823 Same as graphviz.
8825 :alt: alternate text (text)
8827 New in version 1.0.
8828 :align: alignment of the graph (left, center or right)
8831 New in version 1.5.
8832 :caption: caption of the graph (text)
8835 New in version 1.1.
8836 :graphviz_dot: dot command of the graph (text)
8839 New in version 1.4.
8840 :name: label (text)
8843 New in version 1.6.
8844 .. digraph::
8847 Directive for embedding a single directed graph. The name is
8848 given as a directive argument, the contents of the graph are the
8849 directive content. This is a convenience directive to generate
8850 digraph <name> { <content> }.
8851 For example:
8853 .. digraph:: foo
8855 "bar" -> "baz" -> "quux";
8857 options
8859 Same as graphviz.
8861 :alt: alternate text (text)
8863 New in version 1.0.
8864 :align: alignment of the graph (left, center or right)
8867 New in version 1.5.
8868 :caption: caption of the graph (text)
8871 New in version 1.1.
8872 :graphviz_dot: dot command of the graph (text)
8875 New in version 1.4.
8876 :name: label (text)
8879 New in version 1.6.
8880 There are also these config values:
8883 graphviz_dot
8885 The command name with which to invoke dot. The default is
8886 'dot'; you may need to set this to a full path if dot is not in
8887 the executable search path.
8888 Since this setting is not portable from system to system, it is
8890 normally not useful to set it in conf.py; rather, giving it on
8891 the sphinx-build command line via the -D option should be
8892 preferable, like this:
8893 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
8895 graphviz_dot_args
8897 Additional command-line arguments to give to dot, as a list.
8898 The default is an empty list. This is the right place to set
8899 global graph, node or edge attributes via dot’s -G, -N and -E
8900 options.
8901 graphviz_output_format
8903 The output format for Graphviz when building HTML files. This
8904 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
8905 used, in order to make the URL links work properly, an appropri‐
8906 ate target attribute must be set, such as "_top" and "_blank".
8907 For example, the link in the following graph should work in the
8908 svg output:
8909 .. graphviz::
8911 digraph example {
8913 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
8914 b [label="other"];
8915 a -> b;
8916 }
8917 New in version 1.0: Previously, output always was PNG.
8919 sphinx.ext.ifconfig – Include content based on configuration
8922 This extension is quite simple, and features only one directive:
8923 WARNING:
8925 This directive is designed to control only content of document. It
8926 could not control sections, labels and so on.
8927 .. ifconfig::
8929 Include content of the directive only if the Python expression
8930 given as an argument is True, evaluated in the namespace of the
8931 project’s configuration (that is, all registered variables from
8932 conf.py are available).
8933 For example, one could write
8935 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
8937 This stuff is only included in the built docs for unstable versions.
8939 To make a custom config value known to Sphinx, use add_con‐
8941 fig_value() in the setup function in conf.py, e.g.:
8942 def setup(app):
8944 app.add_config_value('releaselevel', '', 'env')
8945 The second argument is the default value, the third should
8947 always be 'env' for such values (it selects if Sphinx re-reads
8948 the documents if the value changes).
8949 sphinx.ext.imgconverter – A reference image converter using Imagemagick
8951 New in version 1.6.
8952 This extension converts images in your document to appropriate format
8955 for builders. For example, it allows you to use SVG images with LaTeX
8956 builder. As a result, you don’t mind what image format the builder
8957 supports.
8958 Internally, this extension uses Imagemagick to convert images.
8960 NOTE:
8962 Imagemagick rasterizes a SVG image on conversion. As a result, the
8963 image becomes not scalable. To avoid that, please use other image
8964 converters like sphinxcontrib-svg2pdfconverter (which uses Inkscape
8965 or rsvg-convert).
8966 Configuration
8968 image_converter
8969 A path to convert command. By default, the imgconverter uses
8970 the command from search paths.
8971 image_converter_args
8973 Additional command-line arguments to give to convert, as a list.
8974 The default is an empty list [].
8975 sphinx.ext.inheritance_diagram – Include inheritance diagrams
8977 New in version 0.6.
8978 This extension allows you to include inheritance diagrams, rendered via
8981 the Graphviz extension.
8982 It adds this directive:
8984 .. inheritance-diagram::
8986 This directive has one or more arguments, each giving a module
8987 or class name. Class names can be unqualified; in that case
8988 they are taken to exist in the currently described module (see
8989 py:module).
8990 For each given class, and each class in each given module, the
8992 base classes are determined. Then, from all classes and their
8993 base classes, a graph is generated which is then rendered via
8994 the graphviz extension to a directed graph.
8995 This directive supports an option called parts that, if given,
8997 must be an integer, advising the directive to keep that many
8998 dot-separated parts in the displayed names (from right to left).
8999 For example, parts=1 will only display class names, without the
9000 names of the modules that contain them.
9001 Changed in version 2.0: The value of for parts can also be nega‐
9003 tive, indicating how many parts to drop from the left. For
9004 example, if all your class names start with lib., you can give
9005 :parts: -1 to remove that prefix from the displayed node names.
9006 The directive also supports a private-bases flag option; if
9009 given, private base classes (those whose name starts with _)
9010 will be included.
9011 You can use caption option to give a caption to the diagram.
9013 Changed in version 1.1: Added private-bases option; previously,
9015 all bases were always included.
9016 Changed in version 1.5: Added caption option
9019 It also supports a top-classes option which requires one or more
9022 class names separated by comma. If specified inheritance traver‐
9023 sal will stop at the specified class names. Given the following
9024 Python module:
9025 """
9027 A
9028 / \
9029 B C
9030 / \ / \
9031 E D F
9032 """
9033 class A:
9035 pass
9036 class B(A):
9038 pass
9039 class C(A):
9041 pass
9042 class D(B, C):
9044 pass
9045 class E(B):
9047 pass
9048 class F(C):
9050 pass
9051 If you have specified a module in the inheritance diagram like
9053 this:
9054 .. inheritance-diagram:: dummy.test
9056 :top-classes: dummy.test.B, dummy.test.C
9057 any base classes which are ancestors to top-classes and are also
9059 defined in the same module will be rendered as stand alone
9060 nodes. In this example class A will be rendered as stand alone
9061 node in the graph. This is a known issue due to how this exten‐
9062 sion works internally.
9063 If you don’t want class A (or any other ancestors) to be visible
9065 then specify only the classes you would like to generate the
9066 diagram for like this:
9067 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
9069 :top-classes: dummy.test.B, dummy.test.C
9070 Changed in version 1.7: Added top-classes option to limit the
9072 scope of inheritance graphs.
9073 Examples
9076 The following are different inheritance diagrams for the internal
9077 InheritanceDiagram class that implements the directive.
9078 With full names:
9080 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9082 Showing class names only:
9084 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9086 :parts: 1
9087 Stopping the diagram at sphinx.util.docutils.SphinxDirective (the high‐
9089 est superclass still part of Sphinx), and dropping the common left-most
9090 part (sphinx) from all names:
9091 .. inheritance-diagram:: sphinx.ext.inheritance_diagram.InheritanceDiagram
9093 :top-classes: sphinx.util.docutils.SphinxDirective
9094 :parts: -1
9095 Configuration
9097 inheritance_graph_attrs
9098 A dictionary of graphviz graph attributes for inheritance dia‐
9099 grams.
9100 For example:
9102 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
9104 fontsize=14, ratio='compress')
9105 inheritance_node_attrs
9107 A dictionary of graphviz node attributes for inheritance dia‐
9108 grams.
9109 For example:
9111 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
9113 color='dodgerblue1', style='filled')
9114 inheritance_edge_attrs
9116 A dictionary of graphviz edge attributes for inheritance dia‐
9117 grams.
9118 inheritance_alias
9120 Allows mapping the full qualified name of the class to custom
9121 values (useful when exposing the underlying path of a class is
9122 not desirable, e.g. it’s a private class and should not be
9123 instantiated by the user).
9124 For example:
9126 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
9128 sphinx.ext.intersphinx – Link to other projects’ documentation
9130 New in version 0.5.
9131 This extension can generate automatic links to the documentation of
9134 objects in other projects.
9135 Usage is simple: whenever Sphinx encounters a cross-reference that has
9137 no matching target in the current documentation set, it looks for tar‐
9138 gets in the documentation sets configured in intersphinx_mapping. A
9139 reference like :py:class:`zipfile.ZipFile` can then link to the Python
9140 documentation for the ZipFile class, without you having to specify
9141 where it is located exactly.
9142 When using the “new” format (see below), you can even force lookup in a
9144 foreign set by prefixing the link target appropriately. A link like
9145 :ref:`comparison manual <python:comparisons>` will then link to the
9146 label “comparisons” in the doc set “python”, if it exists.
9147 Behind the scenes, this works as follows:
9149 · Each Sphinx HTML build creates a file named objects.inv that contains
9151 a mapping from object names to URIs relative to the HTML set’s root.
9152 · Projects using the Intersphinx extension can specify the location of
9154 such mapping files in the intersphinx_mapping config value. The map‐
9155 ping will then be used to resolve otherwise missing references to
9156 objects into links to the other documentation.
9157 · By default, the mapping file is assumed to be at the same location as
9159 the rest of the documentation; however, the location of the mapping
9160 file can also be specified individually, e.g. if the docs should be
9161 buildable without Internet access.
9162 Configuration
9164 To use Intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
9165 sions config value, and use these config values to activate linking:
9166 intersphinx_mapping
9168 This config value contains the locations and names of other
9169 projects that should be linked to in this documentation.
9170 Relative local paths for target locations are taken as relative
9172 to the base of the built documentation, while relative local
9173 paths for inventory locations are taken as relative to the
9174 source directory.
9175 When fetching remote inventory files, proxy settings will be
9177 read from the $HTTP_PROXY environment variable.
9178 Old format for this config value
9180 This is the format used before Sphinx 1.0. It is still recog‐
9182 nized.
9183 A dictionary mapping URIs to either None or an URI. The keys
9185 are the base URI of the foreign Sphinx documentation sets and
9186 can be local paths or HTTP URIs. The values indicate where the
9187 inventory file can be found: they can be None (at the same loca‐
9188 tion as the base URI) or another local or HTTP URI.
9189 New format for this config value
9191 New in version 1.0.
9193 A dictionary mapping unique identifiers to a tuple (target,
9196 inventory). Each target is the base URI of a foreign Sphinx
9197 documentation set and can be a local path or an HTTP URI. The
9198 inventory indicates where the inventory file can be found: it
9199 can be None (at the same location as the base URI) or another
9200 local or HTTP URI.
9201 The unique identifier can be used to prefix cross-reference tar‐
9203 gets, so that it is clear which intersphinx set the target
9204 belongs to. A link like :ref:`comparison manual <python:compar‐
9205 isons>` will link to the label “comparisons” in the doc set
9206 “python”, if it exists.
9207 Example
9209 To add links to modules and objects in the Python standard
9211 library documentation, use:
9212 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
9214 This will download the corresponding objects.inv file from the
9216 Internet and generate links to the pages under the given URI.
9217 The downloaded inventory is cached in the Sphinx environment, so
9218 it must be re-downloaded whenever you do a full rebuild.
9219 A second example, showing the meaning of a non-None value of the
9221 second tuple item:
9222 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9224 'python-inv.txt')}
9225 This will read the inventory from python-inv.txt in the source
9227 directory, but still generate links to the pages under
9228 https://docs.python.org/3. It is up to you to update the inven‐
9229 tory file as new objects are added to the Python documentation.
9230 Multiple target for the inventory
9232 New in version 1.3.
9234 Alternative files can be specified for each inventory. One can
9237 give a tuple for the second inventory tuple item as shown in the
9238 following example. This will read the inventory iterating
9239 through the (second) tuple items until the first successful
9240 fetch. The primary use case for this to specify mirror sites for
9241 server downtime of the primary inventory:
9242 intersphinx_mapping = {'python': ('https://docs.python.org/3',
9244 (None, 'python-inv.txt'))}
9245 intersphinx_cache_limit
9247 The maximum number of days to cache remote inventories. The
9248 default is 5, meaning five days. Set this to a negative value
9249 to cache inventories for unlimited time.
9250 intersphinx_timeout
9252 The number of seconds for timeout. The default is None, meaning
9253 do not timeout.
9254 NOTE:
9256 timeout is not a time limit on the entire response download;
9257 rather, an exception is raised if the server has not issued a
9258 response for timeout seconds.
9259 Showing all links of an Intersphinx mapping file
9261 To show all Intersphinx links and their targets of an Intersphinx map‐
9262 ping file, run python -msphinx.ext.intersphinx url-or-path. This is
9263 helpful when searching for the root cause of a broken Intersphinx link
9264 in a documentation project. The following example prints the Inter‐
9265 sphinx mapping of the Python 3 documentation:
9266 $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
9268 sphinx.ext.linkcode – Add external links to source code
9270 Module author: Pauli Virtanen
9271 New in version 1.2.
9273 This extension looks at your object descriptions (.. class::, .. func‐
9276 tion:: etc.) and adds external links to code hosted somewhere on the
9277 web. The intent is similar to the sphinx.ext.viewcode extension, but
9278 assumes the source code can be found somewhere on the Internet.
9279 In your configuration, you need to specify a linkcode_resolve function
9281 that returns an URL based on the object.
9282 Configuration
9284 linkcode_resolve
9285 This is a function linkcode_resolve(domain, info), which should
9286 return the URL to source code corresponding to the object in
9287 given domain with given information.
9288 The function should return None if no link is to be added.
9290 The argument domain specifies the language domain the object is
9292 in. info is a dictionary with the following keys guaranteed to
9293 be present (dependent on the domain):
9294 · py: module (name of the module), fullname (name of the object)
9296 · c: names (list of names for the object)
9298 · cpp: names (list of names for the object)
9300 · javascript: object (name of the object), fullname (name of the
9302 item)
9303 Example:
9305 def linkcode_resolve(domain, info):
9307 if domain != 'py':
9308 return None
9309 if not info['module']:
9310 return None
9311 filename = info['module'].replace('.', '/')
9312 return "https://somesite/sourcerepo/%s.py" % filename
9313 Math support for HTML outputs in Sphinx
9315 New in version 0.5.
9316 Changed in version 1.8: Math support for non-HTML builders is inte‐
9319 grated to sphinx-core. So mathbase extension is no longer needed.
9320 Since mathematical notation isn’t natively supported by HTML in any
9323 way, Sphinx gives a math support to HTML document with several exten‐
9324 sions. These use the reStructuredText math directive and role.
9325 sphinx.ext.imgmath – Render math as images
9327 New in version 1.4.
9328 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
9331 SVG images. This of course means that the computer where the docs are
9332 built must have both programs available.
9333 There are various config values you can set to influence how the images
9335 are built:
9336 imgmath_image_format
9338 The output image format. The default is 'png'. It should be
9339 either 'png' or 'svg'.
9340 imgmath_latex
9342 The command name with which to invoke LaTeX. The default is
9343 'latex'; you may need to set this to a full path if latex is not
9344 in the executable search path.
9345 Since this setting is not portable from system to system, it is
9347 normally not useful to set it in conf.py; rather, giving it on
9348 the sphinx-build command line via the -D option should be
9349 preferable, like this:
9350 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
9352 This value should only contain the path to the latex executable,
9354 not further arguments; use imgmath_latex_args for that purpose.
9355 imgmath_dvipng
9357 The command name with which to invoke dvipng. The default is
9358 'dvipng'; you may need to set this to a full path if dvipng is
9359 not in the executable search path. This option is only used when
9360 imgmath_image_format is set to 'png'.
9361 imgmath_dvisvgm
9363 The command name with which to invoke dvisvgm. The default is
9364 'dvisvgm'; you may need to set this to a full path if dvisvgm is
9365 not in the executable search path. This option is only used
9366 when imgmath_image_format is 'svg'.
9367 imgmath_latex_args
9369 Additional arguments to give to latex, as a list. The default
9370 is an empty list.
9371 imgmath_latex_preamble
9373 Additional LaTeX code to put into the preamble of the short
9374 LaTeX files that are used to translate the math snippets. This
9375 is empty by default. Use it e.g. to add more packages whose
9376 commands you want to use in the math.
9377 imgmath_dvipng_args
9379 Additional arguments to give to dvipng, as a list. The default
9380 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
9381 which makes the image a bit darker and larger then it is by
9382 default, and produces PNGs with a transparent background. This
9383 option is used only when imgmath_image_format is 'png'.
9384 imgmath_dvisvgm_args
9386 Additional arguments to give to dvisvgm, as a list. The default
9387 value is ['--no-fonts']. This option is used only when img‐
9388 math_image_format is 'svg'.
9389 imgmath_use_preview
9391 dvipng has the ability to determine the “depth” of the rendered
9392 text: for example, when typesetting a fraction inline, the base‐
9393 line of surrounding text should not be flush with the bottom of
9394 the image, rather the image should extend a bit below the base‐
9395 line. This is what TeX calls “depth”. When this is enabled,
9396 the images put into the HTML document will get a vertical-align
9397 style that correctly aligns the baselines.
9398 Unfortunately, this only works when the preview-latex package is
9400 installed (on Ubuntu xenial, it is available as
9401 preview-latex-style). Therefore, the default for this option is
9402 False.
9403 Currently this option is only used when imgmath_image_format is
9405 'png'.
9406 imgmath_add_tooltips
9408 Default: True. If false, do not add the LaTeX code as an “alt”
9409 attribute for math images.
9410 imgmath_font_size
9412 The font size (in pt) of the displayed math. The default value
9413 is 12. It must be a positive integer.
9414 sphinx.ext.mathjax – Render math via JavaScript
9416 New in version 1.1.
9417 This extension puts math as-is into the HTML files. The JavaScript
9420 package MathJax is then loaded and transforms the LaTeX markup to read‐
9421 able math live in the browser.
9422 Because MathJax (and the necessary fonts) is very large, it is not
9424 included in Sphinx but is set to automatically include it from a
9425 third-party site.
9426 ATTENTION:
9428 You should use the math directive and role, not the native MathJax
9429 $$, \(, etc.
9430 mathjax_path
9432 The path to the JavaScript file to include in the HTML files in
9433 order to load MathJax.
9434 The default is the https:// URL that loads the JS files from the
9436 cdnjs Content Delivery Network. See the MathJax Getting Started
9437 page for details. If you want MathJax to be available offline or
9438 without including resources from a third-party site, you have to
9439 download it and set this value to a different path.
9440 The path can be absolute or relative; if it is relative, it is
9442 relative to the _static directory of the built docs.
9443 For example, if you put MathJax into the static path of the
9445 Sphinx docs, this value would be MathJax/MathJax.js. If you
9446 host more than one Sphinx documentation set on one server, it is
9447 advisable to install MathJax in a shared location.
9448 You can also give a full https:// URL different from the CDN
9450 URL.
9451 mathjax_options
9453 The options to script tag for mathjax. For example, you can set
9454 integrity option with following setting:
9455 mathjax_options = {
9457 'integrity': 'sha384-......',
9458 }
9459 The default is empty ({}).
9461 mathjax_config
9463 The inline configuration options for mathjax. The value is used
9464 as a parameter of MathJax.Hub.Config(). For more information,
9465 please read Using in-line configuration options.
9466 For example:
9468 mathjax_config = {
9470 'extensions': ['tex2jax.js'],
9471 'jax': ['input/TeX', 'output/HTML-CSS'],
9472 }
9473 The default is empty (not configured).
9475 sphinx.ext.jsmath – Render math via JavaScript
9477 This extension works just as the MathJax extension does, but uses the
9478 older package jsMath. It provides this config value:
9479 jsmath_path
9481 The path to the JavaScript file to include in the HTML files in
9482 order to load JSMath. There is no default.
9483 The path can be absolute or relative; if it is relative, it is
9485 relative to the _static directory of the built docs.
9486 For example, if you put JSMath into the static path of the
9488 Sphinx docs, this value would be jsMath/easy/load.js. If you
9489 host more than one Sphinx documentation set on one server, it is
9490 advisable to install jsMath in a shared location.
9491 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
9493 Module author: Rob Ruana
9494 New in version 1.3.
9496 Overview
9499 Are you tired of writing docstrings that look like this:
9500 :param path: The path of the file to wrap
9502 :type path: str
9503 :param field_storage: The :class:`FileStorage` instance to wrap
9504 :type field_storage: FileStorage
9505 :param temporary: Whether or not to delete the file when the File
9506 instance is destructed
9507 :type temporary: bool
9508 :returns: A buffered writable file descriptor
9509 :rtype: BufferedFileStorage
9510 reStructuredText is great, but it creates visually dense, hard to read
9512 docstrings. Compare the jumble above to the same thing rewritten
9513 according to the Google Python Style Guide:
9514 Args:
9516 path (str): The path of the file to wrap
9517 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
9518 temporary (bool): Whether or not to delete the file when the File
9519 instance is destructed
9520 Returns:
9522 BufferedFileStorage: A buffered writable file descriptor
9523 Much more legible, no?
9525 Napoleon is a extension that enables Sphinx to parse both NumPy and
9527 Google style docstrings - the style recommended by Khan Academy.
9528 Napoleon is a pre-processor that parses NumPy and Google style doc‐
9530 strings and converts them to reStructuredText before Sphinx attempts to
9531 parse them. This happens in an intermediate step while Sphinx is pro‐
9532 cessing the documentation, so it doesn’t modify any of the docstrings
9533 in your actual source code files.
9534 Getting Started
9536 1. After setting up Sphinx to build your docs, enable napoleon in the
9537 Sphinx conf.py file:
9538 # conf.py
9540 # Add napoleon to the extensions list
9542 extensions = ['sphinx.ext.napoleon']
9543 2. Use sphinx-apidoc to build your API documentation:
9545 $ sphinx-apidoc -f -o docs/source projectdir
9547 Docstrings
9549 Napoleon interprets every docstring that autodoc can find, including
9550 docstrings on: modules, classes, attributes, methods, functions, and
9551 variables. Inside each docstring, specially formatted Sections are
9552 parsed and converted to reStructuredText.
9553 All standard reStructuredText formatting still works as expected.
9555 Docstring Sections
9557 All of the following section headers are supported:
9558 · Args (alias of Parameters)
9560 · Arguments (alias of Parameters)
9562 · Attention
9564 · Attributes
9566 · Caution
9568 · Danger
9570 · Error
9572 · Example
9574 · Examples
9576 · Hint
9578 · Important
9580 · Keyword Args (alias of Keyword Arguments)
9582 · Keyword Arguments
9584 · Methods
9586 · Note
9588 · Notes
9590 · Other Parameters
9592 · Parameters
9594 · Return (alias of Returns)
9596 · Returns
9598 · Raises
9600 · References
9602 · See Also
9604 · Tip
9606 · Todo
9608 · Warning
9610 · Warnings (alias of Warning)
9612 · Warns
9614 · Yield (alias of Yields)
9616 · Yields
9618 Google vs NumPy
9620 Napoleon supports two styles of docstrings: Google and NumPy. The main
9621 difference between the two styles is that Google uses indentation to
9622 separate sections, whereas NumPy uses underlines.
9623 Google style:
9625 def func(arg1, arg2):
9627 """Summary line.
9628 Extended description of function.
9630 Args:
9632 arg1 (int): Description of arg1
9633 arg2 (str): Description of arg2
9634 Returns:
9636 bool: Description of return value
9637 """
9639 return True
9640 NumPy style:
9642 def func(arg1, arg2):
9644 """Summary line.
9645 Extended description of function.
9647 Parameters
9649 ----------
9650 arg1 : int
9651 Description of arg1
9652 arg2 : str
9653 Description of arg2
9654 Returns
9656 -------
9657 bool
9658 Description of return value
9659 """
9661 return True
9662 NumPy style tends to require more vertical space, whereas Google style
9664 tends to use more horizontal space. Google style tends to be easier to
9665 read for short and simple docstrings, whereas NumPy style tends be eas‐
9666 ier to read for long and in-depth docstrings.
9667 The Khan Academy recommends using Google style.
9669 The choice between styles is largely aesthetic, but the two styles
9671 should not be mixed. Choose one style for your project and be consis‐
9672 tent with it.
9673 SEE ALSO:
9675 For complete examples:
9676 · example_google
9678 · example_numpy
9680 Type Annotations
9682 PEP 484 introduced a standard way to express types in Python code.
9683 This is an alternative to expressing types directly in docstrings. One
9684 benefit of expressing types according to PEP 484 is that type checkers
9685 and IDEs can take advantage of them for static code analysis.
9686 Google style with Python 3 type annotations:
9688 def func(arg1: int, arg2: str) -> bool:
9690 """Summary line.
9691 Extended description of function.
9693 Args:
9695 arg1: Description of arg1
9696 arg2: Description of arg2
9697 Returns:
9699 Description of return value
9700 """
9702 return True
9703 Google style with types in docstrings:
9705 def func(arg1, arg2):
9707 """Summary line.
9708 Extended description of function.
9710 Args:
9712 arg1 (int): Description of arg1
9713 arg2 (str): Description of arg2
9714 Returns:
9716 bool: Description of return value
9717 """
9719 return True
9720 NOTE:
9722 Python 2/3 compatible annotations aren’t currently supported by
9723 Sphinx and won’t show up in the docs.
9724 Configuration
9726 Listed below are all the settings used by napoleon and their default
9727 values. These settings can be changed in the Sphinx conf.py file. Make
9728 sure that “sphinx.ext.napoleon” is enabled in conf.py:
9729 # conf.py
9731 # Add any Sphinx extension module names here, as strings
9733 extensions = ['sphinx.ext.napoleon']
9734 # Napoleon settings
9736 napoleon_google_docstring = True
9737 napoleon_numpy_docstring = True
9738 napoleon_include_init_with_doc = False
9739 napoleon_include_private_with_doc = False
9740 napoleon_include_special_with_doc = True
9741 napoleon_use_admonition_for_examples = False
9742 napoleon_use_admonition_for_notes = False
9743 napoleon_use_admonition_for_references = False
9744 napoleon_use_ivar = False
9745 napoleon_use_param = True
9746 napoleon_use_rtype = True
9747 napoleon_google_docstring
9749 True to parse Google style docstrings. False to disable support
9750 for Google style docstrings. Defaults to True.
9751 napoleon_numpy_docstring
9753 True to parse NumPy style docstrings. False to disable support
9754 for NumPy style docstrings. Defaults to True.
9755 napoleon_include_init_with_doc
9757 True to list __init___ docstrings separately from the class doc‐
9758 string. False to fall back to Sphinx’s default behavior, which
9759 considers the __init___ docstring as part of the class documen‐
9760 tation. Defaults to False.
9761 If True:
9763 def __init__(self):
9765 \"\"\"
9766 This will be included in the docs because it has a docstring
9767 \"\"\"
9768 def __init__(self):
9770 # This will NOT be included in the docs
9771 napoleon_include_private_with_doc
9773 True to include private members (like _membername) with doc‐
9774 strings in the documentation. False to fall back to Sphinx’s
9775 default behavior. Defaults to False.
9776 If True:
9778 def _included(self):
9780 """
9781 This will be included in the docs because it has a docstring
9782 """
9783 pass
9784 def _skipped(self):
9786 # This will NOT be included in the docs
9787 pass
9788 napoleon_include_special_with_doc
9790 True to include special members (like __membername__) with doc‐
9791 strings in the documentation. False to fall back to Sphinx’s
9792 default behavior. Defaults to True.
9793 If True:
9795 def __str__(self):
9797 """
9798 This will be included in the docs because it has a docstring
9799 """
9800 return unicode(self).encode('utf-8')
9801 def __unicode__(self):
9803 # This will NOT be included in the docs
9804 return unicode(self.__class__.__name__)
9805 napoleon_use_admonition_for_examples
9807 True to use the .. admonition:: directive for the Example and
9808 Examples sections. False to use the .. rubric:: directive
9809 instead. One may look better than the other depending on what
9810 HTML theme is used. Defaults to False.
9811 This NumPy style snippet will be converted as follows:
9813 Example
9815 -------
9816 This is just a quick example
9817 If True:
9819 .. admonition:: Example
9821 This is just a quick example
9823 If False:
9825 .. rubric:: Example
9827 This is just a quick example
9829 napoleon_use_admonition_for_notes
9831 True to use the .. admonition:: directive for Notes sections.
9832 False to use the .. rubric:: directive instead. Defaults to
9833 False.
9834 NOTE:
9836 The singular Note section will always be converted to a ..
9837 note:: directive.
9838 SEE ALSO:
9840 napoleon_use_admonition_for_examples
9841 napoleon_use_admonition_for_references
9843 True to use the .. admonition:: directive for References sec‐
9844 tions. False to use the .. rubric:: directive instead. Defaults
9845 to False.
9846 SEE ALSO:
9848 napoleon_use_admonition_for_examples
9849 napoleon_use_ivar
9851 True to use the :ivar: role for instance variables. False to use
9852 the .. attribute:: directive instead. Defaults to False.
9853 This NumPy style snippet will be converted as follows:
9855 Attributes
9857 ----------
9858 attr1 : int
9859 Description of `attr1`
9860 If True:
9862 :ivar attr1: Description of `attr1`
9864 :vartype attr1: int
9865 If False:
9867 .. attribute:: attr1
9869 Description of `attr1`
9871 :type: int
9873 napoleon_use_param
9875 True to use a :param: role for each function parameter. False to
9876 use a single :parameters: role for all the parameters. Defaults
9877 to True.
9878 This NumPy style snippet will be converted as follows:
9880 Parameters
9882 ----------
9883 arg1 : str
9884 Description of `arg1`
9885 arg2 : int, optional
9886 Description of `arg2`, defaults to 0
9887 If True:
9889 :param arg1: Description of `arg1`
9891 :type arg1: str
9892 :param arg2: Description of `arg2`, defaults to 0
9893 :type arg2: int, optional
9894 If False:
9896 :parameters: * **arg1** (*str*) --
9898 Description of `arg1`
9899 * **arg2** (*int, optional*) --
9900 Description of `arg2`, defaults to 0
9901 napoleon_use_keyword
9903 True to use a :keyword: role for each function keyword argument.
9904 False to use a single :keyword arguments: role for all the key‐
9905 words. Defaults to True.
9906 This behaves similarly to napoleon_use_param. Note unlike docu‐
9908 tils, :keyword: and :param: will not be treated the same way -
9909 there will be a separate “Keyword Arguments” section, rendered
9910 in the same fashion as “Parameters” section (type links created
9911 if possible)
9912 SEE ALSO:
9914 napoleon_use_param
9915 napoleon_use_rtype
9917 True to use the :rtype: role for the return type. False to out‐
9918 put the return type inline with the description. Defaults to
9919 True.
9920 This NumPy style snippet will be converted as follows:
9922 Returns
9924 -------
9925 bool
9926 True if successful, False otherwise
9927 If True:
9929 :returns: True if successful, False otherwise
9931 :rtype: bool
9932 If False:
9934 :returns: *bool* -- True if successful, False otherwise
9936 sphinx.ext.todo – Support for todo items
9938 Module author: Daniel Bültmann
9939 New in version 0.5.
9941 There are two additional directives when using this extension:
9944 .. todo::
9946 Use this directive like, for example, note.
9947 It will only show up in the output if todo_include_todos is
9949 True.
9950 New in version 1.3.2: This directive supports an class option
9952 that determines the class attribute for HTML output. If not
9953 given, the class defaults to admonition-todo.
9954 .. todolist::
9957 This directive is replaced by a list of all todo directives in
9958 the whole documentation, if todo_include_todos is True.
9959 These can be configured as seen below.
9961 Configuration
9963 todo_include_todos
9964 If this is True, todo and todolist produce output, else they
9965 produce nothing. The default is False.
9966 todo_emit_warnings
9968 If this is True, todo emits a warning for each TODO entries.
9969 The default is False.
9970 New in version 1.5.
9972 todo_link_only
9975 If this is True, todolist produce output without file path and
9976 line, The default is False.
9977 New in version 1.4.
9979 autodoc provides the following an additional event:
9982 todo-defined(app, node)
9984 New in version 1.5.
9985 Emitted when a todo is defined. node is the defined
9988 sphinx.ext.todo.todo_node node.
9989 sphinx.ext.viewcode – Add links to highlighted source code
9991 Module author: Georg Brandl
9992 New in version 1.0.
9994 This extension looks at your Python object descriptions (.. class::, ..
9997 function:: etc.) and tries to find the source files where the objects
9998 are contained. When found, a separate HTML page will be output for
9999 each module with a highlighted version of the source code, and a link
10000 will be added to all object descriptions that leads to the source code
10001 of the described object. A link back from the source to the descrip‐
10002 tion will also be inserted.
10003 WARNING:
10005 Basically, viewcode extension will import the modules being linked
10006 to. If any modules have side effects on import, these will be exe‐
10007 cuted when sphinx-build is run.
10008 If you document scripts (as opposed to library modules), make sure
10010 their main routine is protected by a if __name__ == '__main__' con‐
10011 dition.
10012 In addition, if you don’t want to import the modules by viewcode,
10014 you can tell the location of the location of source code to viewcode
10015 using the viewcode-find-source event.
10016 If viewcode_follow_imported_members is enabled, you will also need
10018 to resolve imported attributes using the viewcode-follow-imported
10019 event.
10020 This extension works only on HTML related builders like html, apple‐
10022 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
10023 epub builder doesn’t support this extension (see viewcode_enable_epub).
10024 Configuration
10026 viewcode_follow_imported_members
10027 If this is True, viewcode extension will emit
10028 viewcode-follow-imported event to resolve the name of the module
10029 by other extensions. The default is True.
10030 New in version 1.3.
10032 Changed in version 1.8: Renamed from viewcode_import to view‐
10035 code_follow_imported_members.
10036 viewcode_enable_epub
10039 If this is True, viewcode extension is also enabled even if you
10040 use epub builders. This extension generates pages outside toc‐
10041 tree, but this is not preferred as epub format.
10042 Until 1.4.x, this extension is always enabled. If you want to
10044 generate epub as same as 1.4.x, you should set True, but epub
10045 format checker’s score becomes worse.
10046 The default is False.
10048 New in version 1.5.
10050 WARNING:
10053 Not all epub readers support pages generated by viewcode
10054 extension. These readers ignore links to pages are not under
10055 toctree.
10056 Some reader’s rendering result are corrupted and epubcheck’s
10058 score becomes worse even if the reader supports.
10059 viewcode-find-source(app, modname)
10061 New in version 1.8.
10062 Find the source code for a module. An event handler for this
10065 event should return a tuple of the source code itself and a dic‐
10066 tionary of tags. The dictionary maps the name of a class, func‐
10067 tion, attribute, etc to a tuple of its type, the start line num‐
10068 ber, and the end line number. The type should be one of
10069 “class”, “def”, or “other”.
10070 Parameters
10072 · app – The Sphinx application object.
10074 · modname – The name of the module to find source code
10076 for.
10077 viewcode-follow-imported(app, modname, attribute)
10079 New in version 1.8.
10080 Find the name of the original module for an attribute.
10083 Parameters
10085 · app – The Sphinx application object.
10087 · modname – The name of the module that the attribute
10089 belongs to.
10090 · attribute – The name of the member to follow.
10092 Third-party extensions
10094 Todo
10095 This should reference the GitHub organization now
10096 You can find several extensions contributed by users in the Sphinx Con‐
10098 trib repository. It is open for anyone who wants to maintain an exten‐
10099 sion publicly; just send a short message asking for write permissions.
10100 There are also several extensions hosted elsewhere. The Sphinx exten‐
10102 sion survey and awesome-sphinxdoc contains a comprehensive list.
10103 If you write an extension that you think others will find useful or you
10105 think should be included as a part of Sphinx, please write to the
10106 project mailing list (join here).
10107 Where to put your own extensions?
10109 Extensions local to a project should be put within the project’s direc‐
10110 tory structure. Set Python’s module search path, sys.path, accordingly
10111 so that Sphinx can find them. For example, if your extension foo.py
10112 lies in the exts subdirectory of the project root, put into conf.py:
10113 import sys, os
10115 sys.path.append(os.path.abspath('exts'))
10117 extensions = ['foo']
10119 You can also install extensions anywhere else on sys.path, e.g. in the
10121 site-packages directory.
10122
10124 Sphinx provides a number of builders for HTML and HTML-based formats.
10125 Builders
10127 Todo
10128 Populate when the ‘builders’ document is split up.
10129 Themes
10131 New in version 0.6.
10132 NOTE:
10135 This section provides information about using pre-existing HTML
10136 themes. If you wish to create your own theme, refer to /theming.
10137 Sphinx supports changing the appearance of its HTML output via themes.
10139 A theme is a collection of HTML templates, stylesheet(s) and other
10140 static files. Additionally, it has a configuration file which speci‐
10141 fies from which theme to inherit, which highlighting style to use, and
10142 what options exist for customizing the theme’s look and feel.
10143 Themes are meant to be project-unaware, so they can be used for differ‐
10145 ent projects without change.
10146 Using a theme
10148 Using a theme provided with Sphinx is easy. Since these do not need to
10149 be installed, you only need to set the html_theme config value. For
10150 example, to enable the classic theme, add the following to conf.py:
10151 html_theme = "classic"
10153 You can also set theme-specific options using the html_theme_options
10155 config value. These options are generally used to change the look and
10156 feel of the theme. For example, to place the sidebar on the right side
10157 and a black background for the relation bar (the bar with the naviga‐
10158 tion links at the page’s top and bottom), add the following conf.py:
10159 html_theme_options = {
10161 "rightsidebar": "true",
10162 "relbarbgcolor": "black"
10163 }
10164 If the theme does not come with Sphinx, it can be in two static forms
10166 or as a Python package. For the static forms, either a directory (con‐
10167 taining theme.conf and other needed files), or a zip file with the same
10168 contents is supported. The directory or zipfile must be put where
10169 Sphinx can find it; for this there is the config value html_theme_path.
10170 This can be a list of directories, relative to the directory containing
10171 conf.py, that can contain theme directories or zip files. For example,
10172 if you have a theme in the file blue.zip, you can put it right in the
10173 directory containing conf.py and use this configuration:
10174 html_theme = "blue"
10176 html_theme_path = ["."]
10177 The third form is a Python package. If a theme you want to use is dis‐
10179 tributed as a Python package, you can use it after installing
10180 # installing theme package
10182 $ pip install sphinxjp.themes.dotted
10183 Once installed, this can be used in the same manner as a directory or
10185 zipfile-based theme:
10186 html_theme = "dotted"
10188 For more information on the design of themes, including information
10190 about writing your own themes, refer to /theming.
10191 Builtin themes
10193 ┌───────────────────────────┬────────────────────────────┐
10194 │Theme overview │ │
10195 ├───────────────────────────┼────────────────────────────┤
10196 │[image: alabaster] [image] │ [image: classic] [image] │
10197 │ │ │
10198 │ │ │
10199 │alabaster │ classic │
10200 ├───────────────────────────┼────────────────────────────┤
10201 │[image: sphinxdoc] [image] │ [image: scrolls] [image] │
10202 │ │ │
10203 │ │ │
10204 │sphinxdoc │ scrolls │
10205 ├───────────────────────────┼────────────────────────────┤
10206 │[image: agogo] [image] │ [image: traditional] │
10207 │ │ [image] │
10208 │ │ │
10209 │agogo │ │
10210 │ │ traditional │
10211 ├───────────────────────────┼────────────────────────────┤
10212 │[image: nature] [image] │ [image: haiku] [image] │
10213 │ │ │
10214 │ │ │
10215 │nature │ haiku │
10216 ├───────────────────────────┼────────────────────────────┤
10217 │[image: pyramid] [image] │ [image: bizstyle] [image] │
10218 │ │ │
10219 │ │ │
10220 │pyramid │ bizstyle │
10221 └───────────────────────────┴────────────────────────────┘
10222 Sphinx comes with a selection of themes to choose from.
10224 These themes are:
10226 basic This is a basically unstyled layout used as the base for the
10228 other themes, and usable as the base for custom themes as well.
10229 The HTML contains all important elements like sidebar and rela‐
10230 tion bar. There are these options (which are inherited by the
10231 other themes):
10232 · nosidebar (true or false): Don’t include the sidebar.
10234 Defaults to False.
10235 · sidebarwidth (int or str): Width of the sidebar in pixels.
10237 This can be an int, which is interpreted as pixels or a valid
10238 CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230
10239 pixels.
10240 · body_min_width (int or str): Minimal width of the document
10242 body. This can be an int, which is interpreted as pixels or a
10243 valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if
10244 you don’t want a width limit. Defaults may depend on the theme
10245 (often 450px).
10246 · body_max_width (int or str): Maximal width of the document
10248 body. This can be an int, which is interpreted as pixels or a
10249 valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’
10250 if you don’t want a width limit. Defaults may depend on the
10251 theme (often 800px).
10252 alabaster
10254 Alabaster theme is a modified “Kr” Sphinx theme from @kennethre‐
10255 itz (especially as used in his Requests project), which was
10256 itself originally based on @mitsuhiko’s theme used for Flask &
10257 related projects. Refer to its installation page for informa‐
10258 tion on how to configure html_sidebars for its use.
10259 classic
10261 This is the classic theme, which looks like the Python 2 docu‐
10262 mentation. It can be customized via these options:
10263 · rightsidebar (true or false): Put the sidebar on the right
10265 side. Defaults to False.
10266 · stickysidebar (true or false): Make the sidebar “fixed” so
10268 that it doesn’t scroll out of view for long body content.
10269 This may not work well with all browsers. Defaults to False.
10270 · collapsiblesidebar (true or false): Add an experimental
10272 JavaScript snippet that makes the sidebar collapsible via a
10273 button on its side. Defaults to False.
10274 · externalrefs (true or false): Display external links differ‐
10276 ently from internal links. Defaults to False.
10277 There are also various color and font options that can change
10279 the color scheme without having to write a custom stylesheet:
10280 · footerbgcolor (CSS color): Background color for the footer
10282 line.
10283 · footertextcolor (CSS color): Text color for the footer line.
10285 · sidebarbgcolor (CSS color): Background color for the sidebar.
10287 · sidebarbtncolor (CSS color): Background color for the sidebar
10289 collapse button (used when collapsiblesidebar is True).
10290 · sidebartextcolor (CSS color): Text color for the sidebar.
10292 · sidebarlinkcolor (CSS color): Link color for the sidebar.
10294 · relbarbgcolor (CSS color): Background color for the relation
10296 bar.
10297 · relbartextcolor (CSS color): Text color for the relation bar.
10299 · relbarlinkcolor (CSS color): Link color for the relation bar.
10301 · bgcolor (CSS color): Body background color.
10303 · textcolor (CSS color): Body text color.
10305 · linkcolor (CSS color): Body link color.
10307 · visitedlinkcolor (CSS color): Body color for visited links.
10309 · headbgcolor (CSS color): Background color for headings.
10311 · headtextcolor (CSS color): Text color for headings.
10313 · headlinkcolor (CSS color): Link color for headings.
10315 · codebgcolor (CSS color): Background color for code blocks.
10317 · codetextcolor (CSS color): Default text color for code blocks,
10319 if not set differently by the highlighting style.
10320 · bodyfont (CSS font-family): Font for normal text.
10322 · headfont (CSS font-family): Font for headings.
10324 sphinxdoc
10326 The theme originally used by this documentation. It features a
10327 sidebar on the right side. There are currently no options beyond
10328 nosidebar and sidebarwidth.
10329 NOTE:
10331 The Sphinx documentation now uses an adjusted version of the
10332 sphinxdoc theme.
10333 scrolls
10335 A more lightweight theme, based on the Jinja documentation. The
10336 following color options are available:
10337 · headerbordercolor
10339 · subheadlinecolor
10341 · linkcolor
10343 · visitedlinkcolor
10345 · admonitioncolor
10347 agogo A theme created by Andi Albrecht. The following options are
10349 supported:
10350 · bodyfont (CSS font family): Font for normal text.
10352 · headerfont (CSS font family): Font for headings.
10354 · pagewidth (CSS length): Width of the page content, default
10356 70em.
10357 · documentwidth (CSS length): Width of the document (without
10359 sidebar), default 50em.
10360 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
10362 · bgcolor (CSS color): Background color.
10364 · headerbg (CSS value for “background”): background for the
10366 header area, default a grayish gradient.
10367 · footerbg (CSS value for “background”): background for the
10369 footer area, default a light gray gradient.
10370 · linkcolor (CSS color): Body link color.
10372 · headercolor1, headercolor2 (CSS color): colors for <h1> and
10374 <h2> headings.
10375 · headerlinkcolor (CSS color): Color for the backreference link
10377 in headings.
10378 · textalign (CSS text-align value): Text alignment for the body,
10380 default is justify.
10381 nature A greenish theme. There are currently no options beyond noside‐
10383 bar and sidebarwidth.
10384 pyramid
10386 A theme from the Pyramid web framework project, designed by
10387 Blaise Laflamme. There are currently no options beyond noside‐
10388 bar and sidebarwidth.
10389 haiku A theme without sidebar inspired by the Haiku OS user guide.
10391 The following options are supported:
10392 · full_logo (true or false, default False): If this is true, the
10394 header will only show the html_logo. Use this for large
10395 logos. If this is false, the logo (if present) will be shown
10396 floating right, and the documentation title will be put in the
10397 header.
10398 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hover‐
10400 linkcolor (CSS colors): Colors for various body elements.
10401 traditional
10403 A theme resembling the old Python documentation. There are cur‐
10404 rently no options beyond nosidebar and sidebarwidth.
10405 epub A theme for the epub builder. This theme tries to save visual
10407 space which is a sparse resource on ebook readers. The follow‐
10408 ing options are supported:
10409 · relbar1 (true or false, default True): If this is true, the
10411 relbar1 block is inserted in the epub output, otherwise it is
10412 omitted.
10413 · footer (true or false, default True): If this is true, the
10415 footer block is inserted in the epub output, otherwise it is
10416 omitted.
10417 bizstyle
10419 A simple bluish theme. The following options are supported
10420 beyond nosidebar and sidebarwidth:
10421 · rightsidebar (true or false): Put the sidebar on the right
10423 side. Defaults to False.
10424 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
10426 theme.
10427 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
10430 sic’. ‘default’ is still available, however it will emit a notice that
10431 it is an alias for the new ‘alabaster’ theme.
10432 Third Party Themes
10435 ┌───────────────────────────┬───┐
10436 │Theme overview │ │
10437 ├───────────────────────────┼───┤
10438 │[image: sphinx_rtd_theme] │ │
10439 │[image] │ │
10440 │ │ │
10441 │ │ │
10442 │sphinx_rtd_theme │ │
10443 └───────────────────────────┴───┘
10444 There are many third-party themes available. Some of these are general
10446 use, while others are specific to an individual project. A section of
10447 third-party themes is listed below. Many more can be found on PyPI,
10448 GitHub and sphinx-themes.org.
10449 sphinx_rtd_theme
10451 Read the Docs Sphinx Theme. This is a mobile-friendly sphinx
10452 theme that was made for readthedocs.org. View a working demo
10453 over on readthedocs.org. You can get install and options infor‐
10454 mation at Read the Docs Sphinx Theme page.
10455 Changed in version 1.4: sphinx_rtd_theme has become optional.
10457
10460 New in version 1.1.
10461 Complementary to translations provided for Sphinx-generated messages
10464 such as navigation bars, Sphinx provides mechanisms facilitating docu‐
10465 ment translations in itself. See the intl-options for details on con‐
10466 figuration.
10467 [image] Workflow visualization of translations in Sphinx. (The
10468 stick-figure is taken from an XKCD comic.).UNINDENT
10469 · Sphinx internationalization details
10471 · Translating with sphinx-intl
10473 · Quick guide
10475 · Translating
10477 · Update your po files by new pot files
10479 · Using Transifex service for team translation
10481 · Contributing to Sphinx reference translation
10483 Sphinx internationalization details
10485 gettext [1] is an established standard for internationalization and
10486 localization. It naively maps messages in a program to a translated
10487 string. Sphinx uses these facilities to translate whole documents.
10488 Initially project maintainers have to collect all translatable strings
10490 (also referred to as messages) to make them known to translators.
10491 Sphinx extracts these through invocation of sphinx-build -b gettext.
10492 Every single element in the doctree will end up in a single message
10494 which results in lists being equally split into different chunks while
10495 large paragraphs will remain as coarsely-grained as they were in the
10496 original document. This grants seamless document updates while still
10497 providing a little bit of context for translators in free-text pas‐
10498 sages. It is the maintainer’s task to split up paragraphs which are
10499 too large as there is no sane automated way to do that.
10500 After Sphinx successfully ran the MessageCatalogBuilder you will find a
10502 collection of .pot files in your output directory. These are catalog
10503 templates and contain messages in your original language only.
10504 They can be delivered to translators which will transform them to .po
10506 files — so called message catalogs — containing a mapping from the
10507 original messages to foreign-language strings.
10508 gettext compiles them into a binary format known as binary catalogs
10510 through msgfmt for efficiency reasons. If you make these files discov‐
10511 erable with locale_dirs for your language, Sphinx will pick them up
10512 automatically.
10513 An example: you have a document usage.rst in your Sphinx project. The
10515 gettext builder will put its messages into usage.pot. Imagine you have
10516 Spanish translations [2] stored in usage.po — for your builds to be
10517 translated you need to follow these instructions:
10518 · Compile your message catalog to a locale directory, say locale, so it
10520 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
10521 (where es is the language code for Spanish.)
10522 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
10524 · Set locale_dirs to ["locale/"].
10526 · Set language to es (also possible via -D).
10528 · Run your desired build.
10530 Translating with sphinx-intl
10532 Quick guide
10533 sphinx-intl is a useful tool to work with Sphinx translation flow.
10534 This section describe an easy way to translate with sphinx-intl.
10535 1. Install sphinx-intl.
10537 $ pip install sphinx-intl
10539 2. Add configurations to conf.py.
10541 locale_dirs = ['locale/'] # path is example but recommended.
10543 gettext_compact = False # optional.
10544 This case-study assumes that locale_dirs is set to locale/ and get‐
10546 text_compact is set to False (the Sphinx document is already config‐
10547 ured as such).
10548 3. Extract translatable messages into pot files.
10550 $ make gettext
10552 The generated pot files will be placed in the _build/gettext direc‐
10554 tory.
10555 4. Generate po files.
10557 We’ll use the pot files generated in the above step.
10559 $ sphinx-intl update -p _build/gettext -l de -l ja
10561 Once completed, the generated po files will be placed in the below
10563 directories:
10564 · ./locale/de/LC_MESSAGES/
10566 · ./locale/ja/LC_MESSAGES/
10568 5. Translate po files.
10570 AS noted above, these are located in the ./locale/<lang>/LC_MESSAGES
10572 directory. An example of one such file, from Sphinx, builders.po,
10573 is given below.
10574 # a5600c3d2e3d48fc8c261ea0284db79b
10576 #: ../../builders.rst:4
10577 msgid "Available builders"
10578 msgstr "<FILL HERE BY TARGET LANGUAGE>"
10579 Another case, msgid is multi-line text and contains reStructuredText
10581 syntax:
10582 # 302558364e1d41c69b3277277e34b184
10584 #: ../../builders.rst:9
10585 msgid ""
10586 "These are the built-in Sphinx builders. More builders can be added by "
10587 ":ref:`extensions <extensions>`."
10588 msgstr ""
10589 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
10590 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
10591 Please be careful not to break reST notation. Most po-editors will
10593 help you with that.
10594 6. Build translated document.
10596 You need a language parameter in conf.py or you may also specify the
10598 parameter on the command line.
10599 For for BSD/GNU make, run:
10601 $ make -e SPHINXOPTS="-D language='de'" html
10603 For Windows cmd.exe, run:
10605 > set SPHINXOPTS=-D language=de
10607 > .\make.bat html
10608 For PowerShell, run:
10610 > Set-Item env:SPHINXOPTS "-D language=de"
10612 > .\make.bat html
10613 Congratulations! You got the translated documentation in the
10615 _build/html directory.
10616 New in version 1.3: sphinx-build that is invoked by make command will
10618 build po files into mo files.
10619 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
10621 mand before make command.
10622 Translating
10625 Update your po files by new pot files
10626 If a document is updated, it is necessary to generate updated pot files
10627 and to apply differences to translated po files. In order to apply the
10628 updates from a pot file to the po file, use the sphinx-intl update com‐
10629 mand.
10630 $ sphinx-intl update -p _build/locale
10632 Using Transifex service for team translation
10634 Transifex is one of several services that allow collaborative transla‐
10635 tion via a web interface. It has a nifty Python-based command line
10636 client that makes it easy to fetch and push translations.
10637 1. Install transifex-client.
10639 You need tx command to upload resources (pot files).
10641 $ pip install transifex-client
10643 SEE ALSO:
10645 Transifex Client documentation
10646 2. Create your transifex account and create new project for your docu‐
10648 ment.
10649 Currently, transifex does not allow for a translation project to
10651 have more than one version of the document, so you’d better include
10652 a version number in your project name.
10653 For example:
10655 Project ID
10657 sphinx-document-test_1_0
10658 Project URL
10660 https://www.transifex.com/projects/p/sphinx-docu‐
10661 ment-test_1_0/
10662 3. Create config files for tx command.
10664 This process will create .tx/config in the current directory, as
10666 well as a ~/.transifexrc file that includes auth information.
10667 $ tx init
10669 Creating .tx folder...
10670 Transifex instance [https://www.transifex.com]:
10671 ...
10672 Please enter your transifex username: <transifex-username>
10673 Password: <transifex-password>
10674 ...
10675 Done.
10676 4. Upload pot files to transifex service.
10678 Register pot files to .tx/config file:
10680 $ cd /your/document/root
10682 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
10683 --transifex-project-name sphinx-document-test_1_0
10684 and upload pot files:
10686 $ tx push -s
10688 Pushing translations for resource sphinx-document-test_1_0.builders:
10689 Pushing source file (locale/pot/builders.pot)
10690 Resource does not exist. Creating...
10691 ...
10692 Done.
10693 5. Forward the translation on transifex.
10695 6. Pull translated po files and make translated HTML.
10697 Get translated catalogs and build mo files. For example, to build mo
10699 files for German (de):
10700 $ cd /your/document/root
10702 $ tx pull -l de
10703 Pulling translations for resource sphinx-document-test_1_0.builders (...)
10704 -> de: locale/de/LC_MESSAGES/builders.po
10705 ...
10706 Done.
10707 Invoke make html (for BSD/GNU make):
10709 $ make -e SPHINXOPTS="-D language='de'" html
10711 That’s all!
10713 TIP:
10715 Translating locally and on Transifex
10716 If you want to push all language’s po files, you can be done by
10718 using tx push -t command. Watch out! This operation overwrites
10719 translations in transifex.
10720 In other words, if you have updated each in the service and local po
10722 files, it would take much time and effort to integrate them.
10723 Contributing to Sphinx reference translation
10725 The recommended way for new contributors to translate Sphinx reference
10726 is to join the translation team on Transifex.
10727 There is sphinx translation page for Sphinx (master) documentation.
10729 1. Login to transifex service.
10731 2. Go to sphinx translation page.
10733 3. Click Request language and fill form.
10735 4. Wait acceptance by transifex sphinx translation maintainers.
10737 5. (After acceptance) Translate on transifex.
10739
10741 [1] See the GNU gettext utilities for details on that software suite.
10742 [2] Because nobody expects the Spanish Inquisition!
10744
10746 Sphinx supports integration with setuptools and distutils through a
10747 custom command - BuildDoc.
10748 Using setuptools integration
10750 The Sphinx build can then be triggered from distutils, and some Sphinx
10751 options can be set in setup.py or setup.cfg instead of Sphinx’s own
10752 configuration file.
10753 For instance, from setup.py:
10755 # this is only necessary when not using setuptools/distribute
10757 from sphinx.setup_command import BuildDoc
10758 cmdclass = {'build_sphinx': BuildDoc}
10759 name = 'My project'
10761 version = '1.2'
10762 release = '1.2.0'
10763 setup(
10764 name=name,
10765 author='Bernard Montgomery',
10766 version=release,
10767 cmdclass=cmdclass,
10768 # these are optional and override conf.py settings
10769 command_options={
10770 'build_sphinx': {
10771 'project': ('setup.py', name),
10772 'version': ('setup.py', version),
10773 'release': ('setup.py', release),
10774 'source_dir': ('setup.py', 'doc')}},
10775 )
10776 NOTE:
10778 If you set Sphinx options directly in the setup() command, replace
10779 hyphens in variable names with underscores. In the example above,
10780 source-dir becomes source_dir.
10781 Or add this section in setup.cfg:
10783 [build_sphinx]
10785 project = 'My project'
10786 version = 1.2
10787 release = 1.2.0
10788 source-dir = 'doc'
10789 Once configured, call this by calling the relevant command on setup.py:
10791 $ python setup.py build_sphinx
10793 Options for setuptools integration
10795 fresh-env
10796 A boolean that determines whether the saved environment should
10797 be discarded on build. Default is false.
10798 This can also be set by passing the -E flag to setup.py:
10800 $ python setup.py build_sphinx -E
10802 all-files
10804 A boolean that determines whether all files should be built from
10805 scratch. Default is false.
10806 This can also be set by passing the -a flag to setup.py:
10808 $ python setup.py build_sphinx -a
10810 source-dir
10812 The target source directory. This can be relative to the set‐
10813 up.py or setup.cfg file, or it can be absolute. It defaults to
10814 ./doc or ./docs if either contains a file named conf.py (check‐
10815 ing ./doc first); otherwise it defaults to the current direc‐
10816 tory.
10817 This can also be set by passing the -s flag to setup.py:
10819 $ python setup.py build_sphinx -s $SOURCE_DIR
10821 build-dir
10823 The target build directory. This can be relative to the setup.py
10824 or setup.cfg file, or it can be absolute. Default is
10825 ./build/sphinx.
10826 config-dir
10828 Location of the configuration directory. This can be relative to
10829 the setup.py or setup.cfg file, or it can be absolute. Default
10830 is to use source-dir.
10831 This can also be set by passing the -c flag to setup.py:
10833 $ python setup.py build_sphinx -c $CONFIG_DIR
10835 New in version 1.0.
10837 builder
10840 The builder or list of builders to use. Default is html.
10841 This can also be set by passing the -b flag to setup.py:
10843 $ python setup.py build_sphinx -b $BUILDER
10845 Changed in version 1.6: This can now be a comma- or space-sepa‐
10847 rated list of builders
10848 warning-is-error
10851 A boolean that ensures Sphinx warnings will result in a failed
10852 build. Default is false.
10853 This can also be set by passing the -W flag to setup.py:
10855 $ python setup.py build_sphinx -W
10857 New in version 1.5.
10859 project
10862 The documented project’s name. Default is ''.
10863 New in version 1.0.
10865 version
10868 The short X.Y version. Default is ''.
10869 New in version 1.0.
10871 release
10874 The full version, including alpha/beta/rc tags. Default is ''.
10875 New in version 1.0.
10877 today How to format the current date, used as the replacement for
10880 |today|. Default is ''.
10881 New in version 1.0.
10883 link-index
10886 A boolean that ensures index.html will be linked to the master
10887 doc. Default is false.
10888 This can also be set by passing the -i flag to setup.py:
10890 $ python setup.py build_sphinx -i
10892 New in version 1.0.
10894 copyright
10897 The copyright string. Default is ''.
10898 New in version 1.3.
10900 nitpicky
10903 Run in nit-picky mode. Currently, this generates warnings for
10904 all missing references. See the config value nitpick_ignore for
10905 a way to exclude some references as “known missing”.
10906 New in version 1.8.
10908 pdb A boolean to configure pdb on exception. Default is false.
10911 New in version 1.5.
10913
10916 New in version 1.1.
10917 Sphinx provides a Python API to easily integrate Sphinx documentation
10920 into your web application. To learn more read the websupportquick‐
10921 start.
10922 Web Support Quick Start
10924 Building Documentation Data
10925 To make use of the web support package in your application you’ll need
10926 to build the data it uses. This data includes pickle files represent‐
10927 ing documents, search indices, and node data that is used to track
10928 where comments and other things are in a document. To do this you will
10929 need to create an instance of the WebSupport class and call its build()
10930 method:
10931 from sphinxcontrib.websupport import WebSupport
10933 support = WebSupport(srcdir='/path/to/rst/sources/',
10935 builddir='/path/to/build/outdir',
10936 search='xapian')
10937 support.build()
10939 This will read reStructuredText sources from srcdir and place the nec‐
10941 essary data in builddir. The builddir will contain two sub-directo‐
10942 ries: one named “data” that contains all the data needed to display
10943 documents, search through documents, and add comments to documents.
10944 The other directory will be called “static” and contains static files
10945 that should be served from “/static”.
10946 NOTE:
10948 If you wish to serve static files from a path other than “/static”,
10949 you can do so by providing the staticdir keyword argument when cre‐
10950 ating the WebSupport object.
10951 Integrating Sphinx Documents Into Your Webapp
10953 Now that the data is built, it’s time to do something useful with it.
10954 Start off by creating a WebSupport object for your application:
10955 from sphinxcontrib.websupport import WebSupport
10957 support = WebSupport(datadir='/path/to/the/data',
10959 search='xapian')
10960 You’ll only need one of these for each set of documentation you will be
10962 working with. You can then call its get_document() method to access
10963 individual documents:
10964 contents = support.get_document('contents')
10966 This will return a dictionary containing the following items:
10968 · body: The main body of the document as HTML
10970 · sidebar: The sidebar of the document as HTML
10972 · relbar: A div containing links to related documents
10974 · title: The title of the document
10976 · css: Links to CSS files used by Sphinx
10978 · script: JavaScript containing comment options
10980 This dict can then be used as context for templates. The goal is to be
10982 easy to integrate with your existing templating system. An example
10983 using Jinja2 is:
10984 {%- extends "layout.html" %}
10986 {%- block title %}
10988 {{ document.title }}
10989 {%- endblock %}
10990 {% block css %}
10992 {{ super() }}
10993 {{ document.css|safe }}
10994 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
10995 {% endblock %}
10996 {%- block script %}
10998 {{ super() }}
10999 {{ document.script|safe }}
11000 {%- endblock %}
11001 {%- block relbar %}
11003 {{ document.relbar|safe }}
11004 {%- endblock %}
11005 {%- block body %}
11007 {{ document.body|safe }}
11008 {%- endblock %}
11009 {%- block sidebar %}
11011 {{ document.sidebar|safe }}
11012 {%- endblock %}
11013 Authentication
11015 To use certain features such as voting, it must be possible to authen‐
11016 ticate users. The details of the authentication are left to your
11017 application. Once a user has been authenticated you can pass the
11018 user’s details to certain WebSupport methods using the username and
11019 moderator keyword arguments. The web support package will store the
11020 username with comments and votes. The only caveat is that if you allow
11021 users to change their username you must update the websupport package’s
11022 data:
11023 support.update_username(old_username, new_username)
11025 username should be a unique string which identifies a user, and modera‐
11027 tor should be a boolean representing whether the user has moderation
11028 privileges. The default value for moderator is False.
11029 An example Flask function that checks whether a user is logged in and
11031 then retrieves a document is:
11032 from sphinxcontrib.websupport.errors import *
11034 @app.route('/<path:docname>')
11036 def doc(docname):
11037 username = g.user.name if g.user else ''
11038 moderator = g.user.moderator if g.user else False
11039 try:
11040 document = support.get_document(docname, username, moderator)
11041 except DocumentNotFoundError:
11042 abort(404)
11043 return render_template('doc.html', document=document)
11044 The first thing to notice is that the docname is just the request path.
11046 This makes accessing the correct document easy from a single view. If
11047 the user is authenticated, then the username and moderation status are
11048 passed along with the docname to get_document(). The web support pack‐
11049 age will then add this data to the COMMENT_OPTIONS that are used in the
11050 template.
11051 NOTE:
11053 This only works if your documentation is served from your document
11054 root. If it is served from another directory, you will need to pre‐
11055 fix the url route with that directory, and give the docroot keyword
11056 argument when creating the web support object:
11057 support = WebSupport(..., docroot='docs')
11059 @app.route('/docs/<path:docname>')
11061 Performing Searches
11063 To use the search form built-in to the Sphinx sidebar, create a func‐
11064 tion to handle requests to the URL ‘search’ relative to the documenta‐
11065 tion root. The user’s search query will be in the GET parameters, with
11066 the key q. Then use the get_search_results() method to retrieve search
11067 results. In Flask that would be like this:
11068 @app.route('/search')
11070 def search():
11071 q = request.args.get('q')
11072 document = support.get_search_results(q)
11073 return render_template('doc.html', document=document)
11074 Note that we used the same template to render our search results as we
11076 did to render our documents. That’s because get_search_results()
11077 returns a context dict in the same format that get_document() does.
11078 Comments & Proposals
11080 Now that this is done it’s time to define the functions that handle the
11081 AJAX calls from the script. You will need three functions. The first
11082 function is used to add a new comment, and will call the web support
11083 method add_comment():
11084 @app.route('/docs/add_comment', methods=['POST'])
11086 def add_comment():
11087 parent_id = request.form.get('parent', '')
11088 node_id = request.form.get('node', '')
11089 text = request.form.get('text', '')
11090 proposal = request.form.get('proposal', '')
11091 username = g.user.name if g.user is not None else 'Anonymous'
11092 comment = support.add_comment(text, node_id='node_id',
11093 parent_id='parent_id',
11094 username=username, proposal=proposal)
11095 return jsonify(comment=comment)
11096 You’ll notice that both a parent_id and node_id are sent with the
11098 request. If the comment is being attached directly to a node, parent_id
11099 will be empty. If the comment is a child of another comment, then
11100 node_id will be empty. Then next function handles the retrieval of com‐
11101 ments for a specific node, and is aptly named get_data():
11102 @app.route('/docs/get_comments')
11104 def get_comments():
11105 username = g.user.name if g.user else None
11106 moderator = g.user.moderator if g.user else False
11107 node_id = request.args.get('node', '')
11108 data = support.get_data(node_id, username, moderator)
11109 return jsonify(**data)
11110 The final function that is needed will call process_vote(), and will
11112 handle user votes on comments:
11113 @app.route('/docs/process_vote', methods=['POST'])
11115 def process_vote():
11116 if g.user is None:
11117 abort(401)
11118 comment_id = request.form.get('comment_id')
11119 value = request.form.get('value')
11120 if value is None or comment_id is None:
11121 abort(400)
11122 support.process_vote(comment_id, g.user.id, value)
11123 return "success"
11124 Comment Moderation
11126 By default, all comments added through add_comment() are automatically
11127 displayed. If you wish to have some form of moderation, you can pass
11128 the displayed keyword argument:
11129 comment = support.add_comment(text, node_id='node_id',
11131 parent_id='parent_id',
11132 username=username, proposal=proposal,
11133 displayed=False)
11134 You can then create a new view to handle the moderation of comments.
11136 It will be called when a moderator decides a comment should be accepted
11137 and displayed:
11138 @app.route('/docs/accept_comment', methods=['POST'])
11140 def accept_comment():
11141 moderator = g.user.moderator if g.user else False
11142 comment_id = request.form.get('id')
11143 support.accept_comment(comment_id, moderator=moderator)
11144 return 'OK'
11145 Rejecting comments happens via comment deletion.
11147 To perform a custom action (such as emailing a moderator) when a new
11149 comment is added but not displayed, you can pass callable to the Web‐
11150 Support class when instantiating your support object:
11151 def moderation_callback(comment):
11153 """Do something..."""
11154 support = WebSupport(..., moderation_callback=moderation_callback)
11156 The moderation callback must take one argument, which will be the same
11158 comment dict that is returned by add_comment().
11159 The WebSupport Class
11161 class sphinxcontrib.websupport.WebSupport
11162 The main API class for the web support package. All interac‐
11163 tions with the web support package should occur through this
11164 class.
11165 The class takes the following keyword arguments:
11167 srcdir The directory containing reStructuredText source files.
11169 builddir
11171 The directory that build data and static files should be
11172 placed in. This should be used when creating a
11173 WebSupport object that will be used to build data.
11174 datadir
11176 The directory that the web support data is in. This
11177 should be used when creating a WebSupport object that
11178 will be used to retrieve data.
11179 search This may contain either a string (e.g. ‘xapian’) refer‐
11181 encing a built-in search adapter to use, or an instance
11182 of a subclass of BaseSearch.
11183 storage
11185 This may contain either a string representing a database
11186 uri, or an instance of a subclass of StorageBackend. If
11187 this is not provided, a new sqlite database will be cre‐
11188 ated.
11189 moderation_callback
11191 A callable to be called when a new comment is added that
11192 is not displayed. It must accept one argument: a dictio‐
11193 nary representing the comment that was added.
11194 staticdir
11196 If the static files should be created in a different
11197 location and not in '/static', this should be a string
11198 with the name of that location (e.g. builddir +
11199 '/static_files').
11200 NOTE:
11202 If you specify staticdir, you will typically want to
11203 adjust staticroot accordingly.
11204 staticroot
11206 If the static files are not served from '/static', this
11207 should be a string with the name of that location (e.g.
11208 '/static_files').
11209 docroot
11211 If the documentation is not served from the base path of
11212 a URL, this should be a string specifying that path (e.g.
11213 'docs').
11214 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
11216 support from sphinx.websupport. Please add sphinxcontrib-websupport
11217 package in your dependency and use moved class instead.
11218 Methods
11221 WebSupport.build()
11222 Build the documentation. Places the data into the outdir direc‐
11223 tory. Use it like this:
11224 support = WebSupport(srcdir, builddir, search='xapian')
11226 support.build()
11227 This will read reStructured text files from srcdir. Then it will
11229 build the pickles and search index, placing them into builddir.
11230 It will also save node data to the database.
11231 WebSupport.get_document(docname, username='', moderator=False)
11233 Load and return a document from a pickle. The document will be a
11234 dict object which can be used to render a template:
11235 support = WebSupport(datadir=datadir)
11237 support.get_document('index', username, moderator)
11238 In most cases docname will be taken from the request path and
11240 passed directly to this function. In Flask, that would be some‐
11241 thing like this:
11242 @app.route('/<path:docname>')
11244 def index(docname):
11245 username = g.user.name if g.user else ''
11246 moderator = g.user.moderator if g.user else False
11247 try:
11248 document = support.get_document(docname, username,
11249 moderator)
11250 except DocumentNotFoundError:
11251 abort(404)
11252 render_template('doc.html', document=document)
11253 The document dict that is returned contains the following items
11255 to be used during template rendering.
11256 · body: The main body of the document as HTML
11258 · sidebar: The sidebar of the document as HTML
11260 · relbar: A div containing links to related documents
11262 · title: The title of the document
11264 · css: Links to css files used by Sphinx
11266 · script: Javascript containing comment options
11268 This raises DocumentNotFoundError if a document matching docname
11270 is not found.
11271 Parameters
11273 docname – the name of the document to load.
11274 WebSupport.get_data(node_id, username=None, moderator=False)
11276 Get the comments and source associated with node_id. If username
11277 is given vote information will be included with the returned
11278 comments. The default CommentBackend returns a dict with two
11279 keys, source, and comments. source is raw source of the node and
11280 is used as the starting point for proposals a user can add. com‐
11281 ments is a list of dicts that represent a comment, each having
11282 the following items:
11283 ┌──────────────┬────────────────────────────┐
11285 │Key │ Contents │
11286 ├──────────────┼────────────────────────────┤
11287 │text │ The comment text. │
11288 ├──────────────┼────────────────────────────┤
11289 │username │ The username that was │
11290 │ │ stored with the comment. │
11291 ├──────────────┼────────────────────────────┤
11292 │id │ The comment’s unique iden‐ │
11293 │ │ tifier. │
11294 ├──────────────┼────────────────────────────┤
11295 │rating │ The comment’s current rat‐ │
11296 │ │ ing. │
11297 ├──────────────┼────────────────────────────┤
11298 │age │ The time in seconds since │
11299 │ │ the comment was added. │
11300 ├──────────────┼────────────────────────────┤
11301 │time │ A dict containing time │
11302 │ │ information. It contains │
11303 │ │ the following keys: year, │
11304 │ │ month, day, hour, minute, │
11305 │ │ second, iso, and delta. │
11306 │ │ iso is the time formatted │
11307 │ │ in ISO 8601 format. delta │
11308 │ │ is a printable form of how │
11309 │ │ old the comment is (e.g. │
11310 │ │ “3 hours ago”). │
11311 ├──────────────┼────────────────────────────┤
11312 │vote │ If user_id was given, this │
11313 │ │ will be an integer repre‐ │
11314 │ │ senting the vote. 1 for an │
11315 │ │ upvote, -1 for a downvote, │
11316 │ │ or 0 if unvoted. │
11317 ├──────────────┼────────────────────────────┤
11318 │node │ The id of the node that │
11319 │ │ the comment is attached │
11320 │ │ to. If the comment’s par‐ │
11321 │ │ ent is another comment │
11322 │ │ rather than a node, this │
11323 │ │ will be null. │
11324 ├──────────────┼────────────────────────────┤
11325 │parent │ The id of the comment that │
11326 │ │ this comment is attached │
11327 │ │ to if it is not attached │
11328 │ │ to a node. │
11329 ├──────────────┼────────────────────────────┤
11330 │children │ A list of all children, in │
11331 │ │ this format. │
11332 ├──────────────┼────────────────────────────┤
11333 │proposal_diff │ An HTML representation of │
11334 │ │ the differences between │
11335 │ │ the the current source and │
11336 │ │ the user’s proposed │
11337 │ │ source. │
11338 └──────────────┴────────────────────────────┘
11339 Parameters
11341 · node_id – the id of the node to get comments for.
11343 · username – the username of the user viewing the com‐
11345 ments.
11346 · moderator – whether the user is a moderator.
11348 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
11350 username=None, time=None, proposal=None, moderator=False)
11351 Add a comment to a node or another comment. Returns the comment
11352 in the same format as get_comments(). If the comment is being
11353 attached to a node, pass in the node’s id (as a string) with the
11354 node keyword argument:
11355 comment = support.add_comment(text, node_id=node_id)
11357 If the comment is the child of another comment, provide the par‐
11359 ent’s id (as a string) with the parent keyword argument:
11360 comment = support.add_comment(text, parent_id=parent_id)
11362 If you would like to store a username with the comment, pass in
11364 the optional username keyword argument:
11365 comment = support.add_comment(text, node=node_id,
11367 username=username)
11368 Parameters
11370 · parent_id – the prefixed id of the comment’s parent.
11372 · text – the text of the comment.
11374 · displayed – for moderation purposes
11376 · username – the username of the user making the comment.
11378 · time – the time the comment was created, defaults to
11380 now.
11381 WebSupport.process_vote(comment_id, username, value)
11383 Process a user’s vote. The web support package relies on the API
11384 user to perform authentication. The API user will typically
11385 receive a comment_id and value from a form, and then make sure
11386 the user is authenticated. A unique username must be passed in,
11387 which will also be used to retrieve the user’s past voting data.
11388 An example, once again in Flask:
11389 @app.route('/docs/process_vote', methods=['POST'])
11391 def process_vote():
11392 if g.user is None:
11393 abort(401)
11394 comment_id = request.form.get('comment_id')
11395 value = request.form.get('value')
11396 if value is None or comment_id is None:
11397 abort(400)
11398 support.process_vote(comment_id, g.user.name, value)
11399 return "success"
11400 Parameters
11402 · comment_id – the comment being voted on
11404 · username – the unique username of the user voting
11406 · value – 1 for an upvote, -1 for a downvote, 0 for an
11408 unvote.
11409 WebSupport.get_search_results(q)
11411 Perform a search for the query q, and create a set of search
11412 results. Then render the search results as html and return a
11413 context dict like the one created by get_document():
11414 document = support.get_search_results(q)
11416 Parameters
11418 q – the search query
11419 Search Adapters
11421 To create a custom search adapter you will need to subclass the
11422 BaseSearch class. Then create an instance of the new class and pass
11423 that as the search keyword argument when you create the WebSupport
11424 object:
11425 support = WebSupport(srcdir=srcdir,
11427 builddir=builddir,
11428 search=MySearch())
11429 For more information about creating a custom search adapter, please see
11431 the documentation of the BaseSearch class below.
11432 class sphinxcontrib.websupport.search.BaseSearch
11434 Defines an interface for search adapters.
11435 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
11437 support.search from sphinx.websupport.search.
11438 Methods
11441 The following methods are defined in the BaseSearch class. Some methods
11442 do not need to be overridden, but some (add_document() and
11443 handle_query()) must be overridden in your subclass. For a working
11444 example, look at the built-in adapter for whoosh.
11445 BaseSearch.init_indexing(changed=[])
11447 Called by the builder to initialize the search indexer. changed
11448 is a list of pagenames that will be reindexed. You may want to
11449 remove these from the search index before indexing begins.
11450 Parameters
11452 changed – a list of pagenames that will be re-indexed
11453 BaseSearch.finish_indexing()
11455 Called by the builder when writing has been completed. Use this
11456 to perform any finalization or cleanup actions after indexing is
11457 complete.
11458 BaseSearch.feed(pagename, filename, title, doctree)
11460 Called by the builder to add a doctree to the index. Converts
11461 the doctree to text and passes it to add_document(). You proba‐
11462 bly won’t want to override this unless you need access to the
11463 doctree. Override add_document() instead.
11464 Parameters
11466 · pagename – the name of the page to be indexed
11468 · filename – the name of the original source file
11470 · title – the title of the page to be indexed
11472 · doctree – is the docutils doctree representation of the
11474 page
11475 BaseSearch.add_document(pagename, filename, title, text)
11477 Called by feed() to add a document to the search index. This
11478 method should should do everything necessary to add a single
11479 document to the search index.
11480 pagename is name of the page being indexed. It is the combina‐
11482 tion of the source files relative path and filename, minus the
11483 extension. For example, if the source file is
11484 “ext/builders.rst”, the pagename would be “ext/builders”. This
11485 will need to be returned with search results when processing a
11486 query.
11487 Parameters
11489 · pagename – the name of the page being indexed
11491 · filename – the name of the original source file
11493 · title – the page’s title
11495 · text – the full text of the page
11497 BaseSearch.query(q)
11499 Called by the web support api to get search results. This method
11500 compiles the regular expression to be used when extracting con‐
11501 text, then calls handle_query(). You won’t want to override
11502 this unless you don’t want to use the included extract_context()
11503 method. Override handle_query() instead.
11504 Parameters
11506 q – the search query string.
11507 BaseSearch.handle_query(q)
11509 Called by query() to retrieve search results for a search query
11510 q. This should return an iterable containing tuples of the fol‐
11511 lowing format:
11512 (<path>, <title>, <context>)
11514 path and title are the same values that were passed to
11516 add_document(), and context should be a short text snippet of
11517 the text surrounding the search query in the document.
11518 The extract_context() method is provided as a simple way to cre‐
11520 ate the context.
11521 Parameters
11523 q – the search query
11524 BaseSearch.extract_context(text, length=240)
11526 Extract the context for the search query from the document’s
11527 full text.
11528 Parameters
11530 · text – the full text of the document to create the con‐
11532 text for
11533 · length – the length of the context snippet to return.
11535 Storage Backends
11537 To create a custom storage backend you will need to subclass the
11538 StorageBackend class. Then create an instance of the new class and
11539 pass that as the storage keyword argument when you create the WebSup‐
11540 port object:
11541 support = WebSupport(srcdir=srcdir,
11543 builddir=builddir,
11544 storage=MyStorage())
11545 For more information about creating a custom storage backend, please
11547 see the documentation of the StorageBackend class below.
11548 class sphinxcontrib.websupport.storage.StorageBackend
11550 Defines an interface for storage backends.
11551 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
11553 trib.websupport.storage from sphinx.websupport.storage.
11554 Methods
11557 StorageBackend.pre_build()
11558 Called immediately before the build process begins. Use this to
11559 prepare the StorageBackend for the addition of nodes.
11560 StorageBackend.add_node(id, document, source)
11562 Add a node to the StorageBackend.
11563 Parameters
11565 · id – a unique id for the comment.
11567 · document – the name of the document the node belongs
11569 to.
11570 · source – the source files name.
11572 StorageBackend.post_build()
11574 Called after a build has completed. Use this to finalize the
11575 addition of nodes if needed.
11576 StorageBackend.add_comment(text, displayed, username, time, proposal,
11578 node_id, parent_id, moderator)
11579 Called when a comment is being added.
11580 Parameters
11582 · text – the text of the comment
11584 · displayed – whether the comment should be displayed
11586 · username – the name of the user adding the comment
11588 · time – a date object with the time the comment was
11590 added
11591 · proposal – the text of the proposal the user made
11593 · node_id – the id of the node that the comment is being
11595 added to
11596 · parent_id – the id of the comment’s parent comment.
11598 · moderator – whether the user adding the comment is a
11600 moderator
11601 StorageBackend.delete_comment(comment_id, username, moderator)
11603 Delete a comment.
11604 Raises UserNotAuthorizedError if moderator is False and username
11606 doesn’t match the username on the comment.
11607 Parameters
11609 · comment_id – The id of the comment being deleted.
11611 · username – The username of the user requesting the
11613 deletion.
11614 · moderator – Whether the user is a moderator.
11616 StorageBackend.get_data(node_id, username, moderator)
11618 Called to retrieve all data for a node. This should return a
11619 dict with two keys, source and comments as described by WebSup‐
11620 port’s get_data() method.
11621 Parameters
11623 · node_id – The id of the node to get data for.
11625 · username – The name of the user requesting the data.
11627 · moderator – Whether the requestor is a moderator.
11629 StorageBackend.process_vote(comment_id, username, value)
11631 Process a vote that is being cast. value will be either -1, 0,
11632 or 1.
11633 Parameters
11635 · comment_id – The id of the comment being voted on.
11637 · username – The username of the user casting the vote.
11639 · value – The value of the vote being cast.
11641 StorageBackend.update_username(old_username, new_username)
11643 If a user is allowed to change their username this method should
11644 be called so that there is not stagnate data in the storage sys‐
11645 tem.
11646 Parameters
11648 · old_username – The username being changed.
11650 · new_username – What the username is being changed to.
11652 StorageBackend.accept_comment(comment_id)
11654 Called when a moderator accepts a comment. After the method is
11655 called the comment should be displayed to all users.
11656 Parameters
11658 comment_id – The id of the comment being accepted.
11659
11661 These are the applications provided as part of Sphinx.
11662 Core Applications
11664 sphinx-quickstart
11665 Synopsis
11666 sphinx-quickstart
11667 Description
11669 sphinx-quickstart is an interactive tool that asks some questions about
11670 your project and then generates a complete documentation directory and
11671 sample Makefile to be used with sphinx-build(1).
11672 Options
11674 -q, --quiet
11675 Quiet mode that will skip interactive wizard to specify options.
11676 This option requires -p, -a and -v options.
11677 -h, --help, --version
11679 Display usage summary or Sphinx version.
11680 Structure Options
11682 --sep If specified, separate source and build directories.
11684 --dot=DOT
11686 Inside the root directory, two more directories will be created;
11687 “_templates” for custom HTML templates and “_static” for custom
11688 stylesheets and other static files. You can enter another prefix
11689 (such as “.”) to replace the underscore.
11690 Project Basic Options
11692 -p PROJECT, --project=PROJECT
11694 Project name will be set. (see project).
11695 -a AUTHOR, --author=AUTHOR
11697 Author names. (see copyright).
11698 -v VERSION
11700 Version of project. (see version).
11701 -r RELEASE, --release=RELEASE
11703 Release of project. (see release).
11704 -l LANGUAGE, --language=LANGUAGE
11706 Document language. (see language).
11707 --suffix=SUFFIX
11709 Source file suffix. (see source_suffix).
11710 --master=MASTER
11712 Master document name. (see master_doc).
11713 Extension Options
11715 --ext-autodoc
11717 Enable sphinx.ext.autodoc extension.
11718 --ext-doctest
11720 Enable sphinx.ext.doctest extension.
11721 --ext-intersphinx
11723 Enable sphinx.ext.intersphinx extension.
11724 --ext-todo
11726 Enable sphinx.ext.todo extension.
11727 --ext-coverage
11729 Enable sphinx.ext.coverage extension.
11730 --ext-imgmath
11732 Enable sphinx.ext.imgmath extension.
11733 --ext-mathjax
11735 Enable sphinx.ext.mathjax extension.
11736 --ext-ifconfig
11738 Enable sphinx.ext.ifconfig extension.
11739 --ext-viewcode
11741 Enable sphinx.ext.viewcode extension.
11742 --ext-githubpages
11744 Enable sphinx.ext.githubpages extension.
11745 --extensions=EXTENSIONS
11747 Enable arbitrary extensions.
11748 Makefile and Batchfile Creation Options
11750 --use-make-mode (-m), --no-use-make-mode (-M)
11752 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
11753 use, which generates a more concise Makefile/make.bat.
11754 Changed in version 1.5: make-mode is default.
11756 --makefile, --no-makefile
11759 Create (or not create) makefile.
11760 --batchfile, --no-batchfile
11762 Create (or not create) batchfile
11763 Project templating
11765 New in version 1.5: Project templating options for sphinx-quickstart
11767 -t, --templatedir=TEMPLATEDIR
11770 Template directory for template files. You can modify the tem‐
11771 plates of sphinx project files generated by quickstart. Follow‐
11772 ing Jinja2 template files are allowed:
11773 · master_doc.rst_t
11775 · conf.py_t
11777 · Makefile_t
11779 · Makefile.new_t
11781 · make.bat_t
11783 · make.bat.new_t
11785 In detail, please refer the system template files Sphinx pro‐
11787 vides. (sphinx/templates/quickstart)
11788 -d NAME=VALUE
11790 Define a template variable
11791 See also
11793 sphinx-build(1)
11794 sphinx-build
11796 Synopsis
11797 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
11798 Description
11800 sphinx-build generates documentation from the files in <sourcedir> and
11801 places it in the <outputdir>.
11802 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
11804 tings. sphinx-quickstart(1) may be used to generate template files,
11805 including conf.py.
11806 sphinx-build can create documentation in different formats. A format
11808 is selected by specifying the builder name on the command line; it
11809 defaults to HTML. Builders can also perform other tasks related to
11810 documentation processing.
11811 By default, everything that is outdated is built. Output only for
11813 selected files can be built by specifying individual filenames.
11814 For a list of available options, refer to sphinx-build -b.
11816 Options
11818 -b buildername
11819 The most important option: it selects a builder. The most com‐
11820 mon builders are:
11821 html Build HTML pages. This is the default builder.
11823 dirhtml
11825 Build HTML pages, but with a single directory per docu‐
11826 ment. Makes for prettier URLs (no .html) if served from
11827 a webserver.
11828 singlehtml
11830 Build a single HTML with the whole content.
11831 htmlhelp, qthelp, devhelp, epub
11833 Build HTML files with additional information for building
11834 a documentation collection in one of these formats.
11835 applehelp
11837 Build an Apple Help Book. Requires hiutil and codesign,
11838 which are not Open Source and presently only available on
11839 Mac OS X 10.6 and higher.
11840 latex Build LaTeX sources that can be compiled to a PDF docu‐
11842 ment using pdflatex.
11843 man Build manual pages in groff format for UNIX systems.
11845 texinfo
11847 Build Texinfo files that can be processed into Info files
11848 using makeinfo.
11849 text Build plain text files.
11851 gettext
11853 Build gettext-style message catalogs (.pot files).
11854 doctest
11856 Run all doctests in the documentation, if the doctest
11857 extension is enabled.
11858 linkcheck
11860 Check the integrity of all external links.
11861 xml Build Docutils-native XML files.
11863 pseudoxml
11865 Build compact pretty-printed “pseudo-XML” files display‐
11866 ing the internal structure of the intermediate document
11867 trees.
11868 See /usage/builders/index for a list of all builders shipped
11870 with Sphinx. Extensions can add their own builders.
11871 -M buildername
11873 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
11874 vides the same build functionality as a default Makefile or
11875 Make.bat. In addition to all Sphinx /usage/builders/index, the
11876 following build pipelines are available:
11877 latexpdf
11879 Build LaTeX files and run them through pdflatex, or as
11880 per latex_engine setting. If language is set to 'ja',
11881 will use automatically the platex/dvipdfmx latex to PDF
11882 pipeline.
11883 info Build Texinfo files and run them through makeinfo.
11885 IMPORTANT:
11887 Sphinx only recognizes the -M option if it is placed first.
11888 New in version 1.2.1.
11890 -a If given, always write all output files. The default is to only
11893 write output files for new and changed source files. (This may
11894 not apply to all builders.)
11895 -E Don’t use a saved environment (the structure caching all
11897 cross-references), but rebuild it completely. The default is to
11898 only read and parse source files that are new or have changed
11899 since the last run.
11900 -t tag Define the tag tag. This is relevant for only directives that
11902 only include their content if this tag is set.
11903 New in version 0.6.
11905 -d path
11908 Since Sphinx has to read and parse all source files before it
11909 can write an output file, the parsed source files are cached as
11910 “doctree pickles”. Normally, these files are put in a directory
11911 called .doctrees under the build directory; with this option you
11912 can select a different cache directory (the doctrees can be
11913 shared between all builders).
11914 -j N Distribute the build over N processes in parallel, to make
11916 building on multiprocessor machines more effective. Note that
11917 not all parts and not all builders of Sphinx can be paral‐
11918 lelized. If auto argument is given, Sphinx uses the number of
11919 CPUs as N.
11920 New in version 1.2: This option should be considered experimen‐
11922 tal.
11923 Changed in version 1.7: Support auto argument.
11926 -c path
11929 Don’t look for the conf.py in the source directory, but use the
11930 given configuration directory instead. Note that various other
11931 files and paths given by configuration values are expected to be
11932 relative to the configuration directory, so they will have to be
11933 present at this location too.
11934 New in version 0.3.
11936 -C Don’t look for a configuration file; only take options via the
11939 -D option.
11940 New in version 0.5.
11942 -D setting=value
11945 Override a configuration value set in the conf.py file. The
11946 value must be a number, string, list or dictionary value.
11947 For lists, you can separate elements with a comma like this: -D
11949 html_theme_path=path1,path2.
11950 For dictionary values, supply the setting name and key like
11952 this: -D latex_elements.docclass=scrartcl.
11953 For boolean values, use 0 or 1 as the value.
11955 Changed in version 0.6: The value can now be a dictionary value.
11957 Changed in version 1.3: The value can now also be a list value.
11960 -A name=value
11963 Make the name assigned to value in the HTML templates.
11964 New in version 0.5.
11966 -n Run in nit-picky mode. Currently, this generates warnings for
11969 all missing references. See the config value nitpick_ignore for
11970 a way to exclude some references as “known missing”.
11971 -N Do not emit colored output.
11973 -v Increase verbosity (loglevel). This option can be given up to
11975 three times to get more debug logging output. It implies -T.
11976 New in version 1.2.
11978 -q Do not output anything on standard output, only write warnings
11981 and errors to standard error.
11982 -Q Do not output anything on standard output, also suppress warn‐
11984 ings. Only errors are written to standard error.
11985 -w file
11987 Write warnings (and errors) to the given file, in addition to
11988 standard error.
11989 -W Turn warnings into errors. This means that the build stops at
11991 the first warning and sphinx-build exits with exit status 1.
11992 --keep-going
11994 With -W option, keep going processing when getting warnings to
11995 the end of build, and sphinx-build exits with exit status 1.
11996 New in version 1.8.
11998 -T Display the full traceback when an unhandled exception occurs.
12001 Otherwise, only a summary is displayed and the traceback infor‐
12002 mation is saved to a file for further analysis.
12003 New in version 1.2.
12005 -P (Useful for debugging only.) Run the Python debugger, pdb, if
12008 an unhandled exception occurs while building.
12009 -h, --help, --version
12011 Display usage summary or Sphinx version.
12012 New in version 1.2.
12014 You can also give one or more filenames on the command line after the
12017 source and build directories. Sphinx will then try to build only these
12018 output files (and their dependencies).
12019 Environment Variables
12021 The sphinx-build refers following environment variables:
12022 MAKE A path to make command. A command name is also allowed.
12024 sphinx-build uses it to invoke sub-build process on make-mode.
12025 Makefile Options
12027 The Makefile and make.bat files created by sphinx-quickstart usually
12029 run sphinx-build only with the -b and -d options. However, they sup‐
12030 port the following variables to customize behavior:
12031 PAPER This sets the 'papersize' key of latex_elements: i.e. PAPER=a4
12033 sets it to 'a4paper' and PAPER=letter to 'letterpaper'.
12034 NOTE:
12036 Usage of this environment variable got broken at Sphinx 1.5
12037 as a4 or letter ended up as option to LaTeX document in place
12038 of the needed a4paper, resp. letterpaper. Fixed at 1.7.7.
12039 SPHINXBUILD
12041 The command to use instead of sphinx-build.
12042 BUILDDIR
12044 The build directory to use instead of the one chosen in
12045 sphinx-quickstart.
12046 SPHINXOPTS
12048 Additional options for sphinx-build. These options can also be
12049 set via the shortcut variable O (capital ‘o’).
12050 Deprecation Warnings
12052 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
12053 when building a user’s document, some Sphinx extension is using depre‐
12054 cated features. In that case, please report it to author of the exten‐
12055 sion.
12056 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
12058 ronment variable to your environment. For example:
12059 · PYTHONWARNINGS= make html (Linux/Mac)
12061 · export PYTHONWARNINGS= and do make html (Linux/Mac)
12063 · set PYTHONWARNINGS= and do make html (Windows)
12065 · modify your Makefile/make.bat and set the environment variable
12067 See also
12069 sphinx-quickstart(1)
12070 Additional Applications
12072 sphinx-apidoc
12073 Synopsis
12074 sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PAT‐
12075 TERN, …]
12076 Description
12078 sphinx-apidoc is a tool for automatic generation of Sphinx sources
12079 that, using the autodoc extension, document a whole package in the
12080 style of other automatic API documentation tools.
12081 MODULE_PATH is the path to a Python package to document, and OUT‐
12083 PUT_PATH is the directory where the generated sources are placed. Any
12084 EXCLUDE_PATTERNs given are fnmatch-style file and/or directory patterns
12085 that will be excluded from generation.
12086 WARNING:
12088 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
12089 document all found modules. If any modules have side effects on
12090 import, these will be executed by autodoc when sphinx-build is run.
12091 If you document scripts (as opposed to library modules), make sure
12093 their main routine is protected by a if __name__ == '__main__' con‐
12094 dition.
12095 Options
12097 -o <OUTPUT_PATH>
12098 Directory to place the output files. If it does not exist, it is
12099 created.
12100 -f, --force
12102 Force overwriting of any existing generated files.
12103 -l, --follow-links
12105 Follow symbolic links.
12106 -n, --dry-run
12108 Do not create any files.
12109 -s <suffix>
12111 Suffix for the source files generated. Defaults to rst.
12112 -d <MAXDEPTH>
12114 Maximum depth for the generated table of contents file.
12115 --tocfile
12117 Filename for a table of contents file. Defaults to modules.
12118 -T, --no-toc
12120 Do not create a table of contents file. Ignored when --full is
12121 provided.
12122 -F, --full
12124 Generate a full Sphinx project (conf.py, Makefile etc.) using
12125 the same mechanism as sphinx-quickstart.
12126 -e, --separate
12128 Put documentation for each module on its own page.
12129 New in version 1.2.
12131 -E, --no-headings
12134 Do not create headings for the modules/packages. This is useful,
12135 for example, when docstrings already contain headings.
12136 -P, --private
12138 Include “_private” modules.
12139 New in version 1.2.
12141 --implicit-namespaces
12144 By default sphinx-apidoc processes sys.path searching for mod‐
12145 ules only. Python 3.3 introduced PEP 420 implicit namespaces
12146 that allow module path structures such as foo/bar/module.py or
12147 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
12148 not modules).
12149 Interpret paths recursively according to PEP-0420.
12151 -M, --module-first
12153 Put module documentation before submodule documentation.
12154 These options are used when --full is specified:
12156 -a Append module_path to sys.path.
12158 -H <project>
12160 Sets the project name to put in generated files (see project).
12161 -A <author>
12163 Sets the author name(s) to put in generated files (see copy‐
12164 right).
12165 -V <version>
12167 Sets the project version to put in generated files (see ver‐
12168 sion).
12169 -R <release>
12171 Sets the project release to put in generated files (see
12172 release).
12173 Environment
12175 SPHINX_APIDOC_OPTIONS
12176 A comma-separated list of option to append to generated automod‐
12177 ule directives. Defaults to members,undoc-members,show-inheri‐
12178 tance.
12179 See also
12181 sphinx-build(1), sphinx-autogen(1)
12182 sphinx-autogen
12184 Synopsis
12185 sphinx-autogen [options] <sourcefile> …
12186 Description
12188 sphinx-autogen is a tool for automatic generation of Sphinx sources
12189 that, using the autodoc extension, document items included in autosum‐
12190 mary listing(s).
12191 sourcefile is the path to one or more reStructuredText documents con‐
12193 taining autosummary entries with the :toctree:: option set. sourcefile
12194 can be an fnmatch-style pattern.
12195 Options
12197 -o <outputdir>
12198 Directory to place the output file. If it does not exist, it is
12199 created. Defaults to the value passed to the :toctree: option.
12200 -s <suffix>, --suffix <suffix>
12202 Default suffix to use for generated files. Defaults to rst.
12203 -t <templates>, --templates <templates>
12205 Custom template directory. Defaults to None.
12206 -i, --imported-members
12208 Document imported members.
12209 Example
12211 Given the following directory structure:
12212 docs
12214 ├── index.rst
12215 └── ...
12216 foobar
12217 ├── foo
12218 │ └── __init__.py
12219 └── bar
12220 ├── __init__.py
12221 └── baz
12222 └── __init__.py
12223 and assuming docs/index.rst contained the following:
12225 Modules
12227 =======
12228 .. autosummary::
12230 :toctree: modules
12231 foobar.foo
12233 foobar.bar
12234 foobar.bar.baz
12235 If you run the following:
12237 $ PYTHONPATH=. sphinx-autodoc doc/index.rst
12239 then the following stub files will be created in docs:
12241 docs
12243 ├── index.rst
12244 └── modules
12245 ├── foobar.bar.rst
12246 ├── foobar.bar.baz.rst
12247 └── foobar.foo.rst
12248 and each of those files will contain a autodoc directive and some other
12250 information.
12251 See also
12253 sphinx-build(1), sphinx-apidoc(1)
12254
12256 New in version 0.6.
12257 NOTE:
12260 This document provides information about creating your own theme. If
12261 you simply wish to use a pre-existing HTML themes, refer to
12262 /usage/theming.
12263 Sphinx supports changing the appearance of its HTML output via themes.
12265 A theme is a collection of HTML templates, stylesheet(s) and other
12266 static files. Additionally, it has a configuration file which speci‐
12267 fies from which theme to inherit, which highlighting style to use, and
12268 what options exist for customizing the theme’s look and feel.
12269 Themes are meant to be project-unaware, so they can be used for differ‐
12271 ent projects without change.
12272 Creating themes
12274 Themes take the form of either a directory or a zipfile (whose name is
12275 the theme name), containing the following:
12276 · A theme.conf file.
12278 · HTML templates, if needed.
12280 · A static/ directory containing any static files that will be copied
12282 to the output static directory on build. These can be images,
12283 styles, script files.
12284 The theme.conf file is in INI format [1] (readable by the standard
12286 Python ConfigParser module) and has the following structure:
12287 [theme]
12289 inherit = base theme
12290 stylesheet = main CSS name
12291 pygments_style = stylename
12292 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
12293 [options]
12295 variable = default value
12296 · The inherit setting gives the name of a “base theme”, or none. The
12298 base theme will be used to locate missing templates (most themes will
12299 not have to supply most templates if they use basic as the base
12300 theme), its options will be inherited, and all of its static files
12301 will be used as well. If you want to also inherit the stylesheet,
12302 include it via CSS’ @import in your own.
12303 · The stylesheet setting gives the name of a CSS file which will be
12305 referenced in the HTML header. If you need more than one CSS file,
12306 either include one from the other via CSS’ @import, or use a custom
12307 HTML template that adds <link rel="stylesheet"> tags as necessary.
12308 Setting the html_style config value will override this setting.
12309 · The pygments_style setting gives the name of a Pygments style to use
12311 for highlighting. This can be overridden by the user in the pyg‐
12312 ments_style config value.
12313 · The sidebars setting gives the comma separated list of sidebar tem‐
12315 plates for constructing sidebars. This can be overridden by the user
12316 in the html_sidebars config value.
12317 · The options section contains pairs of variable names and default val‐
12319 ues. These options can be overridden by the user in
12320 html_theme_options and are accessible from all templates as
12321 theme_<name>.
12322 New in version 1.7: sidebar settings
12324 Distribute your theme as a Python package
12327 As a way to distribute your theme, you can use Python package. Python
12328 package brings to users easy setting up ways.
12329 To distribute your theme as a Python package, please define an entry
12331 point called sphinx.html_themes in your setup.py file, and write a set‐
12332 up() function to register your themes using add_html_theme() API in it:
12333 # 'setup.py'
12335 setup(
12336 ...
12337 entry_points = {
12338 'sphinx.html_themes': [
12339 'name_of_theme = your_package',
12340 ]
12341 },
12342 ...
12343 )
12344 # 'your_package.py'
12346 from os import path
12347 def setup(app):
12349 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
12350 If your theme package contains two or more themes, please call
12352 add_html_theme() twice or more.
12353 New in version 1.2: ‘sphinx_themes’ entry_points feature.
12355 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
12358 recated.
12359 New in version 1.6: sphinx.html_themes entry_points feature.
12362 Templating
12365 The guide to templating is helpful if you want to write your own tem‐
12366 plates. What is important to keep in mind is the order in which Sphinx
12367 searches for templates:
12368 · First, in the user’s templates_path directories.
12370 · Then, in the selected theme.
12372 · Then, in its base theme, its base’s base theme, etc.
12374 When extending a template in the base theme with the same name, use the
12376 theme name as an explicit directory: {% extends "basic/layout.html" %}.
12377 From a user templates_path template, you can still use the “exclamation
12378 mark” syntax as described in the templating document.
12379 Static templates
12381 Since theme options are meant for the user to configure a theme more
12382 easily, without having to write a custom stylesheet, it is necessary to
12383 be able to template static files as well as HTML files. Therefore,
12384 Sphinx supports so-called “static templates”, like this:
12385 If the name of a file in the static/ directory of a theme (or in the
12387 user’s static path, for that matter) ends with _t, it will be processed
12388 by the template engine. The _t will be left from the final file name.
12389 For example, the classic theme has a file static/classic.css_t which
12390 uses templating to put the color options into the stylesheet. When a
12391 documentation is built with the classic theme, the output directory
12392 will contain a _static/classic.css file where all template tags have
12393 been processed.
12394 [1] It is not an executable Python file, as opposed to conf.py,
12396 because that would pose an unnecessary security risk if themes are
12397 shared.
12398
12400 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
12401 is a text-based engine, and inspired by Django templates, so anyone
12402 having used Django will already be familiar with it. It also has
12403 excellent documentation for those who need to make themselves familiar
12404 with it.
12405 Do I need to use Sphinx’s templates to produce HTML?
12407 No. You have several other options:
12408 · You can write a TemplateBridge subclass that calls your template
12410 engine of choice, and set the template_bridge configuration value
12411 accordingly.
12412 · You can write a custom builder that derives from StandaloneHTML‐
12414 Builder and calls your template engine of choice.
12415 · You can use the PickleHTMLBuilder that produces pickle files with the
12417 page contents, and postprocess them using a custom tool, or use them
12418 in your Web application.
12419 Jinja/Sphinx Templating Primer
12421 The default templating language in Sphinx is Jinja. It’s Django/Smarty
12422 inspired and easy to understand. The most important concept in Jinja
12423 is template inheritance, which means that you can overwrite only spe‐
12424 cific blocks within a template, customizing it while also keeping the
12425 changes at a minimum.
12426 To customize the output of your documentation you can override all the
12428 templates (both the layout templates and the child templates) by adding
12429 files with the same name as the original filename into the template
12430 directory of the structure the Sphinx quickstart generated for you.
12431 Sphinx will look for templates in the folders of templates_path first,
12433 and if it can’t find the template it’s looking for there, it falls back
12434 to the selected theme’s templates.
12435 A template contains variables, which are replaced with values when the
12437 template is evaluated, tags, which control the logic of the template
12438 and blocks which are used for template inheritance.
12439 Sphinx’s basic theme provides base templates with a couple of blocks it
12441 will fill with data. These are located in the themes/basic subdirec‐
12442 tory of the Sphinx installation directory, and used by all builtin
12443 Sphinx themes. Templates with the same name in the templates_path
12444 override templates supplied by the selected theme.
12445 For example, to add a new link to the template area containing related
12447 links all you have to do is to add a new template called layout.html
12448 with the following contents:
12449 {% extends "!layout.html" %}
12451 {% block rootrellink %}
12452 <li><a href="https://project.invalid/">Project Homepage</a> »</li>
12453 {{ super() }}
12454 {% endblock %}
12455 By prefixing the name of the overridden template with an exclamation
12457 mark, Sphinx will load the layout template from the underlying HTML
12458 theme.
12459 Important: If you override a block, call {{ super() }} somewhere to
12461 render the block’s original content in the extended template – unless
12462 you don’t want that content to show up.
12463 Working with the builtin templates
12465 The builtin basic theme supplies the templates that all builtin Sphinx
12466 themes are based on. It has the following elements you can override or
12467 use:
12468 Blocks
12470 The following blocks exist in the layout.html template:
12471 doctype
12473 The doctype of the output format. By default this is XHTML 1.0
12474 Transitional as this is the closest to what Sphinx and Docutils
12475 generate and it’s a good idea not to change it unless you want
12476 to switch to HTML 5 or a different but compatible XHTML doctype.
12477 linktags
12479 This block adds a couple of <link> tags to the head section of
12480 the template.
12481 extrahead
12483 This block is empty by default and can be used to add extra con‐
12484 tents into the <head> tag of the generated HTML file. This is
12485 the right place to add references to JavaScript or extra CSS
12486 files.
12487 relbar1 / relbar2
12489 This block contains the relation bar, the list of related links
12490 (the parent documents on the left, and the links to index, mod‐
12491 ules etc. on the right). relbar1 appears before the document,
12492 relbar2 after the document. By default, both blocks are filled;
12493 to show the relbar only before the document, you would override
12494 relbar2 like this:
12495 {% block relbar2 %}{% endblock %}
12497 rootrellink / relbaritems
12499 Inside the relbar there are three sections: The rootrellink, the
12500 links from the documentation and the custom relbaritems. The
12501 rootrellink is a block that by default contains a list item
12502 pointing to the master document by default, the relbaritems is
12503 an empty block. If you override them to add extra links into
12504 the bar make sure that they are list items and end with the
12505 reldelim1.
12506 document
12508 The contents of the document itself. It contains the block
12509 “body” where the individual content is put by subtemplates like
12510 page.html.
12511 sidebar1 / sidebar2
12513 A possible location for a sidebar. sidebar1 appears before the
12514 document and is empty by default, sidebar2 after the document
12515 and contains the default sidebar. If you want to swap the side‐
12516 bar location override this and call the sidebar helper:
12517 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
12519 {% block sidebar2 %}{% endblock %}
12520 (The sidebar2 location for the sidebar is needed by the sphinx‐
12522 doc.css stylesheet, for example.)
12523 sidebarlogo
12525 The logo location within the sidebar. Override this if you want
12526 to place some content at the top of the sidebar.
12527 footer The block for the footer div. If you want a custom footer or
12529 markup before or after it, override this one.
12530 The following four blocks are only used for pages that do not have
12532 assigned a list of custom sidebars in the html_sidebars config value.
12533 Their use is deprecated in favor of separate sidebar templates, which
12534 can be included via html_sidebars.
12535 sidebartoc
12537 The table of contents within the sidebar.
12538 Deprecated since version 1.0.
12540 sidebarrel
12543 The relation links (previous, next document) within the sidebar.
12544 Deprecated since version 1.0.
12546 sidebarsourcelink
12549 The “Show source” link within the sidebar (normally only shown
12550 if this is enabled by html_show_sourcelink).
12551 Deprecated since version 1.0.
12553 sidebarsearch
12556 The search box within the sidebar. Override this if you want to
12557 place some content at the bottom of the sidebar.
12558 Deprecated since version 1.0.
12560 Configuration Variables
12563 Inside templates you can set a couple of variables used by the layout
12564 template using the {% set %} tag:
12565 reldelim1
12567 The delimiter for the items on the left side of the related bar.
12568 This defaults to ' »' Each item in the related bar ends
12569 with the value of this variable.
12570 reldelim2
12572 The delimiter for the items on the right side of the related
12573 bar. This defaults to ' |'. Each item except of the last one
12574 in the related bar ends with the value of this variable.
12575 Overriding works like this:
12577 {% extends "!layout.html" %}
12579 {% set reldelim1 = ' >' %}
12580 script_files
12582 Add additional script files here, like this:
12583 {% set script_files = script_files + ["_static/myscript.js"] %}
12585 Deprecated since version 1.8.0: Please use .Sphinx.add_js_file()
12587 instead.
12588 Helper Functions
12591 Sphinx provides various Jinja functions as helpers in the template.
12592 You can use them to generate links or output multiply used elements.
12593 pathto(document)
12595 Return the path to a Sphinx document as a URL. Use this to
12596 refer to built documents.
12597 pathto(file, 1)
12599 Return the path to a file which is a filename relative to the
12600 root of the generated output. Use this to refer to static
12601 files.
12602 hasdoc(document)
12604 Check if a document with the name document exists.
12605 sidebar()
12607 Return the rendered sidebar.
12608 relbar()
12610 Return the rendered relation bar.
12611 warning(message)
12613 Emit a warning message.
12614 Global Variables
12616 These global variables are available in every template and are safe to
12617 use. There are more, but most of them are an implementation detail and
12618 might change in the future.
12619 builder
12621 The name of the builder (e.g. html or htmlhelp).
12622 copyright
12624 The value of copyright.
12625 docstitle
12627 The title of the documentation (the value of html_title), except
12628 when the “single-file” builder is used, when it is set to None.
12629 embedded
12631 True if the built HTML is meant to be embedded in some viewing
12632 application that handles navigation, not the web browser, such
12633 as for HTML help or Qt help formats. In this case, the sidebar
12634 is not included.
12635 favicon
12637 The path to the HTML favicon in the static path, or ''.
12638 file_suffix
12640 The value of the builder’s out_suffix attribute, i.e. the file
12641 name extension that the output files will get. For a standard
12642 HTML builder, this is usually .html.
12643 has_source
12645 True if the reST document sources are copied (if
12646 html_copy_source is True).
12647 language
12649 The value of language.
12650 last_updated
12652 The build date.
12653 logo The path to the HTML logo image in the static path, or ''.
12655 master_doc
12657 The value of master_doc, for usage with pathto().
12658 pagename
12660 The “page name” of the current file, i.e. either the document
12661 name if the file is generated from a reST source, or the equiva‐
12662 lent hierarchical name relative to the output directory ([direc‐
12663 tory/]filename_without_extension).
12664 project
12666 The value of project.
12667 release
12669 The value of release.
12670 rellinks
12672 A list of links to put at the left side of the relbar, next to
12673 “next” and “prev”. This usually contains links to the general
12674 index and other indices, such as the Python module index. If
12675 you add something yourself, it must be a tuple (pagename, link
12676 title, accesskey, link text).
12677 shorttitle
12679 The value of html_short_title.
12680 show_source
12682 True if html_show_sourcelink is True.
12683 sphinx_version
12685 The version of Sphinx used to build.
12686 style The name of the main stylesheet, as given by the theme or
12688 html_style.
12689 title The title of the current document, as used in the <title> tag.
12691 use_opensearch
12693 The value of html_use_opensearch.
12694 version
12696 The value of version.
12697 In addition to these values, there are also all theme options available
12699 (prefixed by theme_), as well as the values given by the user in
12700 html_context.
12701 In documents that are created from source files (as opposed to automat‐
12703 ically-generated files like the module index, or documents that already
12704 are in HTML form), these variables are also available:
12705 body A string containing the content of the page in HTML form as pro‐
12707 duced by the HTML builder, before the theme is applied.
12708 display_toc
12710 A boolean that is True if the toc contains more than one entry.
12711 meta Document metadata (a dictionary), see metadata.
12713 metatags
12715 A string containing the page’s HTML meta tags.
12716 next The next document for the navigation. This variable is either
12718 false or has two attributes link and title. The title contains
12719 HTML markup. For example, to generate a link to the next page,
12720 you can use this snippet:
12721 {% if next %}
12723 <a href="{{ next.link|e }}">{{ next.title }}</a>
12724 {% endif %}
12725 page_source_suffix
12727 The suffix of the file that was rendered. Since we support a
12728 list of source_suffix, this will allow you to properly link to
12729 the original source file.
12730 parents
12732 A list of parent documents for navigation, structured like the
12733 next item.
12734 prev Like next, but for the previous page.
12736 sourcename
12738 The name of the copied source file for the current document.
12739 This is only nonempty if the html_copy_source value is True.
12740 This has empty value on creating automatically-generated files.
12741 title The page title.
12743 toc The local table of contents for the current page, rendered as
12745 HTML bullet lists.
12746 toctree
12748 A callable yielding the global TOC tree containing the current
12749 page, rendered as HTML bullet lists. Optional keyword argu‐
12750 ments:
12751 · collapse (True by default): if true, all TOC entries that are
12753 not ancestors of the current page are collapsed
12754 · maxdepth (defaults to the max depth selected in the toctree
12756 directive): the maximum depth of the tree; set it to -1 to
12757 allow unlimited depth
12758 · titles_only (False by default): if true, put only toplevel
12760 document titles in the tree
12761 · includehidden (False by default): if true, the TOC tree will
12763 also contain hidden entries.
12764
12766 The latex target does not benefit from prepared themes.
12767 The latex-options, and particularly among them the latex_elements vari‐
12769 able provides much of the interface for customization.
12770 For some details of the LaTeX/PDF builder command line invocation,
12772 refer to LaTeXBuilder.
12773 Example
12775 Keep in mind that backslashes must be doubled in Python string literals
12776 to avoid interpretation as escape sequences, or use raw strings (as is
12777 done here).
12778 # inside conf.py
12780 latex_engine = 'xelatex'
12781 latex_elements = {
12782 'fontpkg': r'''
12783 \setmainfont{DejaVu Serif}
12784 \setsansfont{DejaVu Sans}
12785 \setmonofont{DejaVu Sans Mono}
12786 ''',
12787 'preamble': r'''
12788 \usepackage[titles]{tocloft}
12789 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
12790 \setlength{\cftchapnumwidth}{0.75cm}
12791 \setlength{\cftsecindent}{\cftchapnumwidth}
12792 \setlength{\cftsecnumwidth}{1.25cm}
12793 ''',
12794 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
12795 'printindex': r'\footnotesize\raggedright\printindex',
12796 }
12797 latex_show_urls = 'footnote'
12798 The latex_elements configuration setting
12800 A dictionary that contains LaTeX snippets overriding those Sphinx usu‐
12801 ally puts into the generated .tex files. Its 'sphinxsetup' key is
12802 described separately.
12803 · Keys that you may want to override include:
12805 'papersize'
12807 Paper size option of the document class ('a4paper' or 'letter‐
12808 paper'), default 'letterpaper'.
12809 'pointsize'
12811 Point size option of the document class ('10pt', '11pt' or
12812 '12pt'), default '10pt'.
12813 'pxunit'
12815 the value of the px when used in image attributes width and
12816 height. The default value is '0.75bp' which achieves 96px=1in
12817 (in TeX 1in = 72bp = 72.27pt.) To obtain for example 100px=1in
12818 use '0.01in' or '0.7227pt' (the latter leads to TeX computing
12819 a more precise value, due to the smaller unit used in the
12820 specification); for 72px=1in, simply use '1bp'; for 90px=1in,
12821 use '0.8bp' or '0.803pt'.
12822 New in version 1.5.
12824 'passoptionstopackages'
12827 A string which will be positioned early in the preamble,
12828 designed to contain \\PassOptionsToPackage{options}{foo} com‐
12829 mands. Default empty.
12830 New in version 1.4.
12832 'babel'
12835 “babel” package inclusion, default '\\usepackage{babel}' (the
12836 suitable document language string is passed as class option,
12837 and english is used if no language.) For Japanese documents,
12838 the default is the empty string.
12839 With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX docu‐
12841 ment to use polyglossia, but one should be aware that current
12842 babel has improved its support for Unicode engines in recent
12843 years and for some languages it may make sense to prefer babel
12844 over polyglossia.
12845 HINT:
12847 After modifiying a core LaTeX key like this one, clean up
12848 the LaTeX build repertory before next PDF build, else
12849 left-over auxiliary files are likely to break the build.
12850 Changed in version 1.5: For latex_engine set to 'xelatex', the
12852 default is '\\usepackage{polyglossia}\n\\setmainlanguage{<lan‐
12853 guage>}'.
12854 Changed in version 1.6: 'lualatex' uses same default setting
12857 as 'xelatex'
12858 Changed in version 1.7.6: For French, xelatex and lualatex
12861 default to using babel, not polyglossia.
12862 'fontpkg'
12865 Font package inclusion, the default is '\\usepackage{times}'
12866 which uses Times for text, Helvetica for sans serif and
12867 Courier for monospace.
12868 Changed in version 1.2: Defaults to '' when the language uses
12870 the Cyrillic script.
12871 Changed in version 2.0: Support for individual Greek and
12874 Cyrillic letters:
12875 · In order to support occasional Cyrillic (физика частиц) or
12877 Greek letters (Σωματιδιακή φυσική) in a document whose lan‐
12878 guage is English or a Latin European one, the default
12879 set-up is enhanced (only for 'pdflatex' engine) to do:
12880 \substitutefont{LGR}{\rmdefault}{cmr}
12882 \substitutefont{LGR}{\sfdefault}{cmss}
12883 \substitutefont{LGR}{\ttdefault}{cmtt}
12884 \substitutefont{X2}{\rmdefault}{cmr}
12885 \substitutefont{X2}{\sfdefault}{cmss}
12886 \substitutefont{X2}{\ttdefault}{cmtt}
12887 but this is activated only under the condition that the
12889 'fontenc' key is configured to load the LGR (Greek) and/or
12890 X2 (Cyrillic) pdflatex-font encodings (if the language is
12891 set to a Cyrillic language, this 'fontpkg' key must be used
12892 as “times” package has no direct support for it; then keep
12893 only LGR lines from the above, if support is needed for
12894 Greek in the text).
12895 The \substitutefont command is from the eponymous LaTeX
12897 package, which is loaded by Sphinx if needed (on Ubuntu
12898 xenial it is part of texlive-latex-extra which is a Sphinx
12899 requirement).
12900 Only if the document actually does contain Unicode Greek
12902 letters (in text) or Cyrillic letters, will the above
12903 default set-up cause additional requirements for the PDF
12904 build. On Ubuntu xenial, texlive-lang-greek,
12905 texlive-lang-cyrillic, and (with the above choice of fonts)
12906 the cm-super (or cm-super-minimal) package.
12907 · For 'xelatex' and 'lualatex', the default is to use the
12909 FreeFont family: this OpenType font family supports both
12910 Cyrillic and Greek scripts and is available as separate
12911 Ubuntu xenial package fonts-freefont-otf, it is not needed
12912 to install the big package texlive-fonts-extra.
12913 · 'platex' (Japanese documents) engine supports individual
12915 Cyrillic and Greek letters with no need of extra user
12916 set-up.
12917 'fncychap'
12920 Inclusion of the “fncychap” package (which makes fancy chapter
12921 titles), default '\\usepackage[Bjarne]{fncychap}' for English
12922 documentation (this option is slightly customized by Sphinx),
12923 '\\usepackage[Sonny]{fncychap}' for internationalized docs
12924 (because the “Bjarne” style uses numbers spelled out in Eng‐
12925 lish). Other “fncychap” styles you can try are “Lenny”,
12926 “Glenn”, “Conny”, “Rejne” and “Bjornstrup”. You can also set
12927 this to '' to disable fncychap.
12928 The default is '' for Japanese documents.
12930 'preamble'
12932 Additional preamble content, default empty. One may move all
12933 needed macros into some file mystyle.tex.txt of the project
12934 source repertory, and get LaTeX to import it at run time:
12935 'preamble': r'\input{mystyle.tex.txt}',
12937 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
12938 'preamble': r'\usepackage{mystyle}',
12939 It is then needed to set appropriately latex_additional_files,
12941 for example:
12942 latex_additional_files = ["mystyle.sty"]
12944 'figure_align'
12946 Latex figure float alignment, default ‘htbp’ (here, top, bot‐
12947 tom, page). Whenever an image doesn’t fit into the current
12948 page, it will be ‘floated’ into the next page but may be pre‐
12949 ceded by any other text. If you don’t like this behavior, use
12950 ‘H’ which will disable floating and position figures strictly
12951 in the order they appear in the source.
12952 New in version 1.3.
12954 'atendofbody'
12957 Additional document content (right before the indices),
12958 default empty.
12959 New in version 1.5.
12961 'footer'
12964 Additional footer content (before the indices), default empty.
12965 Deprecated since version 1.5: Use 'atendofbody' key instead.
12967 · Keys that don’t need to be overridden unless in special cases are:
12970 'extraclassoptions'
12972 The default is the empty string. Example: 'extraclassoptions':
12973 'openany' will allow chapters (for documents of the 'manual'
12974 type) to start on any page.
12975 New in version 1.2.
12977 Changed in version 1.6: Added this documentation.
12980 'maxlistdepth'
12983 LaTeX allows by default at most 6 levels for nesting list and
12984 quote-like environments, with at most 4 enumerated lists, and
12985 4 bullet lists. Setting this key for example to '10' (as a
12986 string) will allow up to 10 nested levels (of all sorts).
12987 Leaving it to the empty string means to obey the LaTeX
12988 default.
12989 WARNING:
12991 · Using this key may prove incompatible with some LaTeX
12993 packages or special document classes which do their own
12994 list customization.
12995 · The key setting is silently ignored if \usepackage{enu‐
12997 mitem} is executed inside the document preamble. Use then
12998 rather the dedicated commands of this LaTeX package.
12999 New in version 1.5.
13001 'inputenc'
13004 “inputenc” package inclusion, defaults to '\\usepack‐
13005 age[utf8]{inputenc}' when using pdflatex. Otherwise empty.
13006 Changed in version 1.4.3: Previously '\\usepackage[utf8]{inpu‐
13008 tenc}' was used for all compilers.
13009 'cmappkg'
13012 “cmap” package inclusion, default '\\usepackage{cmap}'.
13013 New in version 1.2.
13015 'fontenc'
13018 “fontenc” package inclusion, defaults to '\\usepack‐
13019 age[T1]{fontenc}'.
13020 If 'pdflatex' is the latex_engine, one can add LGR for support
13022 of Greek letters in the document, and also X2 (or T2A) for
13023 Cyrillic letters, like this:
13024 r'\usepackage[LGR,X2,T1]{fontenc}'
13026 ATTENTION:
13028 Prior to 2.0, Unicode Greek letters were escaped to use
13029 LaTeX math mark-up. This is not the case anymore, and the
13030 above must be used (only in case of 'pdflatex' engine) if
13031 the source contains such Unicode Greek.
13032 On Ubuntu xenial, packages texlive-lang-greek and cm-super
13034 (for the latter, only if the 'fontpkg' setting is left to
13035 its default) are needed for LGR to work. In place of
13036 cm-super one can install smaller cm-super-minimal, but it
13037 requires the LaTeX document to execute \usepack‐
13038 age[10pt]{type1ec} before loading fontenc. Thus, use this
13039 key with this extra at its start if needed.
13040 Changed in version 1.5: Defaults to '\\usepackage{fontspec}'
13042 when latex_engine is 'xelatex'.
13043 Changed in version 1.6: 'lualatex' uses fontspec per default
13046 like 'xelatex'.
13047 Changed in version 2.0: 'lualatex' executes \defaultfontfea‐
13050 tures[\rmfamily,\sffamily]{} to disable TeX ligatures.
13051 Changed in version 2.0: Detection of LGR, T2A, X2 to trigger
13054 support of occasional Greek or Cyrillic ('pdflatex' only, as
13055 this support is provided natively by 'platex' and only
13056 requires suitable font with 'xelatex'/'lualatex').
13057 'textgreek'
13060 The default ('pdflatex' only) is '\\usepackage{textalpha}',
13061 but only if 'fontenc' was modified by user to include LGR
13062 option. If not, the key value will be forced to be the empty
13063 string.
13064 This is needed for pdfLaTeX to support Unicode input of Greek
13066 letters such as φύσις. Expert users may want to load the tex‐
13067 talpha package with its option normalize-symbols.
13068 HINT:
13070 Unicode Greek (but no further Unicode symbols) in math can
13071 be supported by 'pdflatex' from setting this key to
13072 r'\usepackage{textalpha,alphabeta}'. Then :math:`α`
13073 (U+03B1) will render as \alpha. For wider Unicode support
13074 in math input, see the discussion of latex_engine.
13075 With 'platex' (Japanese), 'xelatex' or 'lualatex', this key
13077 is ignored.
13078 New in version 2.0.
13080 'geometry'
13083 “geometry” package inclusion, the default definition is:
13084 '\\usepackage{geometry}'
13085 with an additional [dvipdfm] for Japanese documents. The
13087 Sphinx LaTeX style file executes:
13088 \PassOptionsToPackage{hmargin=1in,vmargin=1in,margin‐
13089 par=0.5in}{geometry}
13090 which can be customized via corresponding ‘sphinxsetup’
13092 options.
13093 New in version 1.5.
13095 Changed in version 1.5.2: dvipdfm option if latex_engine is
13098 'platex'.
13099 New in version 1.5.3: The ‘sphinxsetup’ keys for the margins.
13102 Changed in version 1.5.3: The location in the LaTeX file has
13105 been moved to after \usepackage{sphinx} and \sphinxsetup{..},
13106 hence also after insertion of 'fontpkg' key. This is in order
13107 to handle the paper layout options in a special way for Japa‐
13108 nese documents: the text width will be set to an integer mul‐
13109 tiple of the zenkaku width, and the text height to an integer
13110 multiple of the baseline. See the hmargin documentation for
13111 more.
13112 'hyperref'
13115 “hyperref” package inclusion; also loads package “hypcap” and
13116 issues \urlstyle{same}. This is done after sphinx.sty file is
13117 loaded and before executing the contents of 'preamble' key.
13118 ATTENTION:
13120 Loading of packages “hyperref” and “hypcap” is mandatory.
13121 New in version 1.5: Previously this was done from inside
13123 sphinx.sty.
13124 'maketitle'
13127 “maketitle” call, default '\\sphinxmaketitle'. Override if you
13128 want to generate a differently styled title page.
13129 HINT:
13131 If the key value is set to r'\newcommand\sphinxbackofti‐
13132 tlepage{<Extra material>}\sphinxmaketitle', then <Extra
13133 material> will be typeset on back of title page ('manual'
13134 docclass only).
13135 Changed in version 1.8.3: Original \maketitle from document
13137 class is not overwritten, hence is re-usable as part of some
13138 custom setting for this key.
13139 New in version 1.8.3: \sphinxbackoftitlepage optional macro.
13142 It can also be defined inside 'preamble' key rather than this
13143 one.
13144 'releasename'
13147 value that prefixes 'release' element on title page, default
13148 'Release'. As for title and author used in the tuples of
13149 latex_documents, it is inserted as LaTeX markup.
13150 'tableofcontents'
13152 “tableofcontents” call, default '\\sphinxtableofcontents' (it
13153 is a wrapper of unmodified \tableofcontents, which may itself
13154 be customized by user loaded packages.) Override if you want
13155 to generate a different table of contents or put content
13156 between the title page and the TOC.
13157 Changed in version 1.5: Previously the meaning of \tableofcon‐
13159 tents itself was modified by Sphinx. This created an incompat‐
13160 ibility with dedicated packages modifying it also such as
13161 “tocloft” or “etoc”.
13162 'transition'
13165 Commands used to display transitions, default
13166 '\n\n\\bigskip\\hrule\\bigskip\n\n'. Override if you want to
13167 display transitions differently.
13168 New in version 1.2.
13170 Changed in version 1.6: Remove unneeded {} after \\hrule.
13173 'printindex'
13176 “printindex” call, the last thing in the file, default
13177 '\\printindex'. Override if you want to generate the index
13178 differently or append some content after the index. For exam‐
13179 ple '\\footnotesize\\raggedright\\printindex' is advisable
13180 when the index is full of long entries.
13181 'fvset'
13183 Customization of fancyvrb LaTeX package. Sphinx does by
13184 default 'fvset': '\\fvset{fontsize=\\small}', to adjust for
13185 the large character width of the monospace font, used in
13186 code-blocks. You may need to modify this if you use custom
13187 fonts.
13188 New in version 1.8.
13190 Changed in version 2.0: Due to new default font choice for
13193 'xelatex' and 'lualatex' (FreeFont), Sphinx does \\fvset{font‐
13194 size=\\small} also with these engines (and not \\fvset{font‐
13195 size=auto}).
13196 · Keys that are set by other options and therefore should not be over‐
13199 ridden are:
13200 'docclass' 'classoptions' 'title' 'release' 'author' 'makeindex'
13202 'sphinxsetup' key
13204 The 'sphinxsetup' key of latex_elements provides a LaTeX-type cus‐
13205 tomization interface:
13206 latex_elements = {
13208 'sphinxsetup': 'key1=value1, key2=value2, ...',
13209 }
13210 It defaults to empty. If non-empty, it will be passed as argument to
13212 the \sphinxsetup macro inside the document preamble, like this:
13213 \usepackage{sphinx}
13215 \sphinxsetup{key1=value1, key2=value2,...}
13216 New in version 1.5.
13218 HINT:
13221 It is possible to insert further uses of the \sphinxsetup LaTeX
13222 macro directly into the body of the document, via the help of the
13223 raw directive. Here is how this present chapter is styled in the
13224 PDF output:
13225 .. raw:: latex
13227 \begingroup
13229 \sphinxsetup{%
13230 verbatimwithframe=false,
13231 VerbatimColor={named}{OldLace},
13232 TitleColor={named}{DarkGoldenrod},
13233 hintBorderColor={named}{LightCoral},
13234 attentionborder=3pt,
13235 attentionBorderColor={named}{Crimson},
13236 attentionBgColor={named}{FloralWhite},
13237 noteborder=2pt,
13238 noteBorderColor={named}{Olive},
13239 cautionborder=3pt,
13240 cautionBorderColor={named}{Cyan},
13241 cautionBgColor={named}{LightCyan}}
13242 at the start of the chapter and:
13244 .. raw:: latex
13246 \endgroup
13248 at its end.
13250 The colors used in the above are provided by the svgnames option of
13252 the “xcolor” package:
13253 latex_elements = {
13255 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
13256 }
13257 LaTeX boolean keys require lowercase true or false values. Spaces
13259 around the commas and equal signs are ignored, spaces inside LaTeX
13260 macros may be significant.
13261 hmargin, vmargin
13263 The dimensions of the horizontal (resp. vertical) margins,
13264 passed as hmargin (resp. vmargin) option to the geometry pack‐
13265 age. The default is 1in, which is equivalent to {1in,1in}. Exam‐
13266 ple:
13267 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
13269 Japanese documents currently accept only the one-dimension for‐
13271 mat for these parameters. The geometry package is then passed
13272 suitable options to get the text width set to an exact multiple
13273 of the zenkaku width, and the text height set to an integer mul‐
13274 tiple of the baselineskip, with the closest fit for the margins.
13275 HINT:
13277 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
13278 use the nomag extra document class option (cf. 'extraclas‐
13279 soptions' key of latex_elements) or so-called TeX “true”
13280 units:
13281 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
13283 New in version 1.5.3.
13285 marginpar
13288 The \marginparwidth LaTeX dimension, defaults to 0.5in. For Ja‐
13289 panese documents, the value is modified to be the closest inte‐
13290 ger multiple of the zenkaku width.
13291 New in version 1.5.3.
13293 verbatimwithframe
13296 default true. Boolean to specify if code-blocks and literal
13297 includes are framed. Setting it to false does not deactivate use
13298 of package “framed”, because it is still in use for the optional
13299 background colour.
13300 verbatimwrapslines
13302 default true. Tells whether long lines in code-block’s contents
13303 should wrap.
13304 literalblockcappos
13306 default t for “top”. Decides the caption position. Alternative
13307 is b (“bottom”).
13308 New in version 1.7.
13310 verbatimhintsturnover
13313 default true. If true, code-blocks display “continued on next
13314 page”, “continued from previous page” hints in case of page‐
13315 breaks.
13316 New in version 1.6.3.
13318 Changed in version 1.7: the default changed from false to true.
13321 verbatimcontinuedalign, verbatimcontinuesalign
13324 default r. Horizontal position relative to the framed contents:
13325 either l (left aligned), r (right aligned) or c (centered).
13326 New in version 1.7.
13328 parsedliteralwraps
13331 default true. Tells whether long lines in parsed-literal’s con‐
13332 tents should wrap.
13333 New in version 1.5.2: set this option value to false to recover
13335 former behaviour.
13336 inlineliteralwraps
13339 default true. Allows linebreaks inside inline literals: but
13340 extra potential break-points (additionally to those allowed by
13341 LaTeX at spaces or for hyphenation) are currently inserted only
13342 after the characters . , ; ? ! /. Due to TeX internals, white
13343 space in the line will be stretched (or shrunk) in order to
13344 accomodate the linebreak.
13345 New in version 1.5: set this option value to false to recover
13347 former behaviour.
13348 verbatimvisiblespace
13351 default \textcolor{red}{\textvisiblespace}. When a long code
13352 line is split, the last space character from the source code
13353 line right before the linebreak location is typeset using this.
13354 verbatimcontinued
13356 A LaTeX macro inserted at start of continuation code lines. Its
13357 (complicated…) default typesets a small red hook pointing to the
13358 right:
13359 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
13361 Changed in version 1.5: The breaking of long code lines was
13363 added at 1.4.2. The default definition of the continuation sym‐
13364 bol was changed at 1.5 to accomodate various font sizes (e.g.
13365 code-blocks can be in footnotes).
13366 TitleColor
13369 default {rgb}{0.126,0.263,0.361}. The colour for titles (as con‐
13370 figured via use of package “titlesec”.)
13371 WARNING:
13373 Colours set via 'sphinxsetup' must obey the syntax of the argument
13374 of the color/xcolor packages \definecolor command.
13375 InnerLinkColor
13377 default {rgb}{0.208,0.374,0.486}. A colour passed to hyperref as
13378 value of linkcolor and citecolor.
13379 OuterLinkColor
13381 default {rgb}{0.216,0.439,0.388}. A colour passed to hyperref as
13382 value of filecolor, menucolor, and urlcolor.
13383 VerbatimColor
13385 default {rgb}{1,1,1}. The background colour for code-blocks. The
13386 default is white.
13387 VerbatimBorderColor
13389 default {rgb}{0,0,0}. The frame color, defaults to black.
13390 VerbatimHighlightColor
13392 default {rgb}{0.878,1,1}. The color for highlighted lines.
13393 New in version 1.6.6.
13395 NOTE:
13398 Starting with this colour key, and for all others coming next, the
13399 actual names declared to “color” or “xcolor” are prefixed with
13400 “sphinx”.
13401 verbatimsep
13403 default \fboxsep. The separation between code lines and the
13404 frame.
13405 verbatimborder
13407 default \fboxrule. The width of the frame around code-blocks.
13408 shadowsep
13410 default 5pt. The separation between contents and frame for
13411 contents and topic boxes.
13412 shadowsize
13414 default 4pt. The width of the lateral “shadow” to the right.
13415 shadowrule
13417 default \fboxrule. The width of the frame around topic boxes.
13418 noteBorderColor, hintBorderColor,
13420 importantBorderColor, tipBorderColor default {rgb}{0,0,0}
13421 (black). The colour for the two horizontal rules used by Sphinx
13422 in LaTeX for styling a note type admonition.
13423 noteborder, hintborder, importantborder, tipborder
13425 default 0.5pt. The width of the two horizontal rules.
13426 warningBorderColor, cautionBorderColor,
13428 attentionBorderColor, dangerBorderColor, errorBorderColor
13429 default {rgb}{0,0,0} (black). The colour for the admonition
13430 frame.
13431 warningBgColor, cautionBgColor,
13433 attentionBgColor, dangerBgColor, errorBgColor default
13434 {rgb}{1,1,1} (white). The background colours for the respective
13435 admonitions.
13436 warningborder, cautionborder,
13438 attentionborder, dangerborder, errorborder default 1pt. The
13439 width of the frame.
13440 AtStartFootnote
13442 default \mbox{ }. LaTeX macros inserted at the start of the
13443 footnote text at bottom of page, after the footnote number.
13444 BeforeFootnote
13446 default \leavevmode\unskip. LaTeX macros inserted before the
13447 footnote mark. The default removes possible space before it
13448 (else, TeX could insert a linebreak there).
13449 New in version 1.5.
13451 HeaderFamily
13454 default \sffamily\bfseries. Sets the font used by headings.
13455 LaTeX macros and environments
13457 Here are some macros from the package file sphinx.sty and class files
13458 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
13459 ing redefinitions. Check the respective files for the defaults.
13460 Macros
13462 · text styling commands:
13463 · \sphinxstrong,
13465 · \sphinxbfcode,
13467 · \sphinxemail,
13469 · \sphinxtablecontinued,
13471 · \sphinxtitleref,
13473 · \sphinxmenuselection,
13475 · \sphinxaccelerator,
13477 · \sphinxcrossref,
13479 · \sphinxtermref,
13481 · \sphinxoptional.
13483 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
13485 possibilities of conflict with LaTeX packages.
13486 · more text styling:
13489 · \sphinxstyleindexentry,
13491 · \sphinxstyleindexextra,
13493 · \sphinxstyleindexpageref,
13495 · \sphinxstyletopictitle,
13497 · \sphinxstylesidebartitle,
13499 · \sphinxstyleothertitle,
13501 · \sphinxstylesidebarsubtitle,
13503 · \sphinxstyletheadfamily,
13505 · \sphinxstyleemphasis,
13507 · \sphinxstyleliteralemphasis,
13509 · \sphinxstylestrong,
13511 · \sphinxstyleliteralstrong,
13513 · \sphinxstyleabbreviation,
13515 · \sphinxstyleliteralintitle,
13517 · \sphinxstylecodecontinued,
13519 · \sphinxstylecodecontinues.
13521 New in version 1.5: these macros were formerly hard-coded as non cus‐
13523 tomizable \texttt, \emph, etc…
13524 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
13527 ily and allows multiple paragraphs in header cells of tables.
13528 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
13531 continues.
13532 · \sphinxtableofcontents: it is a wrapper (defined differently in
13535 sphinxhowto.cls and in sphinxmanual.cls) of standard \tableofcon‐
13536 tents. The macro \sphinxtableofcontentshook is executed during its
13537 expansion right before \tableofcontents itself.
13538 Changed in version 1.5: formerly, the meaning of \tableofcontents was
13540 modified by Sphinx.
13541 Changed in version 2.0: hard-coded redefinitions of \l@section and
13544 \l@subsection formerly done during loading of 'manual' docclass are
13545 now executed later via \sphinxtableofcontentshook. This macro is
13546 also executed by the 'howto' docclass, but defaults to empty with it.
13547 · \sphinxmaketitle: it is defined in the class files sphinxmanual.cls
13550 and sphinxhowto.cls and is used as default setting of 'maketitle'
13551 latex_elements key.
13552 Changed in version 1.8.3: formerly, \maketitle from LaTeX document
13554 class was modified by Sphinx.
13555 · \sphinxbackoftitlepage: for 'manual' docclass, and if it is defined,
13558 it gets executed at end of \sphinxmaketitle, before the final
13559 \clearpage. Use either the 'maketitle' key or the 'preamble' key of
13560 latex_elements to add a custom definition of \sphinxbackoftitlepage.
13561 New in version 1.8.3.
13563 · \sphinxcite: it is a wrapper of standard \cite for citation refer‐
13566 ences.
13567 Environments
13569 · a figure may have an optional legend with arbitrary body elements:
13570 they are rendered in a sphinxlegend environment. The default defini‐
13571 tion issues \small, and ends with \par.
13572 New in version 1.5.6: formerly, the \small was hardcoded in LaTeX
13574 writer and the ending \par was lacking.
13575 · environments associated with admonitions:
13578 · sphinxnote,
13580 · sphinxhint,
13582 · sphinximportant,
13584 · sphinxtip,
13586 · sphinxwarning,
13588 · sphinxcaution,
13590 · sphinxattention,
13592 · sphinxdanger,
13594 · sphinxerror.
13596 They may be \renewenvironment ‘d individually, and must then be
13598 defined with one argument (it is the heading of the notice, for exam‐
13599 ple Warning: for warning directive, if English is the document lan‐
13600 guage). Their default definitions use either the sphinxheavybox (for
13601 the last 5 ones) or the sphinxlightbox environments, configured to
13602 use the parameters (colours, border thickness) specific to each type,
13603 which can be set via 'sphinxsetup' string.
13604 Changed in version 1.5: use of public environment names, separate
13606 customizability of the parameters, such as noteBorderColor, notebor‐
13607 der, warningBgColor, warningBorderColor, warningborder, …
13608 · the contents directive (with :local: option) and the topic directive
13611 are implemented by environment sphinxShadowBox.
13612 New in version 1.4.2: former code refactored into an environment
13614 allowing page breaks.
13615 Changed in version 1.5: options shadowsep, shadowsize, shadowrule.
13618 · the literal blocks (via :: or code-block), are implemented using
13621 sphinxVerbatim environment which is a wrapper of Verbatim environment
13622 from package fancyvrb.sty. It adds the handling of the top caption
13623 and the wrapping of long lines, and a frame which allows pagebreaks.
13624 Inside tables the used environment is sphinxVerbatimintable (it does
13625 not draw a frame, but allows a caption).
13626 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
13628 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
13629 intable is used inside tables.
13630 New in version 1.5: options verbatimwithframe, verbatimwrapslines,
13633 verbatimsep, verbatimborder.
13634 New in version 1.6.6: support for :emphasize-lines: option
13637 New in version 1.6.6: easier customizability of the formatting via
13640 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
13641 · the bibliography uses sphinxthebibliography and the Python Module
13644 index as well as the general index both use sphinxtheindex; these
13645 environments are wrappers of the thebibliography and respectively
13646 theindex environments as provided by the document class (or pack‐
13647 ages).
13648 Changed in version 1.5: formerly, the original environments were mod‐
13650 ified by Sphinx.
13651 Miscellany
13654 · the section, subsection, … headings are set using titlesec’s
13655 \titleformat command.
13656 · for the 'manual' docclass, the chapter headings can be customized
13658 using fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
13659 sphinx.sty has custom re-definitions in case of fncychap option
13660 Bjarne.
13661 Changed in version 1.5: formerly, use of fncychap with other styles
13663 than Bjarne was dysfunctional.
13664 HINT:
13667 As an experimental feature, Sphinx can use user-defined template
13668 file for LaTeX source if you have a file named _tem‐
13669 plates/latex.tex_t in your project.
13670 New in version 1.5: currently all template variables are unstable
13672 and undocumented.
13673 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
13676 can be added to _templates/ to configure some aspects of table ren‐
13677 dering (such as the caption position).
13678 New in version 1.6: currently all template variables are unstable
13680 and undocumented.
13681
13684 Since many projects will need special features in their documentation,
13685 Sphinx is designed to be extensible on several levels.
13686 This is what you can do in an extension: First, you can add new
13688 builders to support new output formats or actions on the parsed docu‐
13689 ments. Then, it is possible to register custom reStructuredText roles
13690 and directives, extending the markup. And finally, there are so-called
13691 “hook points” at strategic places throughout the build process, where
13692 an extension can register a hook and run specialized code.
13693 An extension is simply a Python module. When an extension is loaded,
13695 Sphinx imports this module and executes its setup() function, which in
13696 turn notifies Sphinx of everything the extension offers – see the
13697 extension tutorial for examples.
13698 The configuration file itself can be treated as an extension if it con‐
13700 tains a setup() function. All other extensions to load must be listed
13701 in the extensions configuration value.
13702 Discovery of builders by entry point
13704 New in version 1.6.
13705 Builder extensions can be discovered by means of entry points so that
13708 they do not have to be listed in the extensions configuration value.
13709 Builder extensions should define an entry point in the sphinx.builders
13711 group. The name of the entry point needs to match your builder’s name
13712 attribute, which is the name passed to the sphinx-build -b option. The
13713 entry point value should equal the dotted name of the extension module.
13714 Here is an example of how an entry point for ‘mybuilder’ can be defined
13715 in the extension’s setup.py:
13716 setup(
13718 # ...
13719 entry_points={
13720 'sphinx.builders': [
13721 'mybuilder = my.extension.module',
13722 ],
13723 }
13724 )
13725 Note that it is still necessary to register the builder using
13727 add_builder() in the extension’s setup() function.
13728 Important objects
13730 There are several key objects whose API you will use while writing an
13731 extension. These are:
13732 Application
13734 The application object (usually called app) is an instance of
13735 Sphinx. It controls most high-level functionality, such as the
13736 setup of extensions, event dispatching and producing output
13737 (logging).
13738 If you have the environment object, the application is available
13740 as env.app.
13741 Environment
13743 The build environment object (usually called env) is an instance
13744 of BuildEnvironment. It is responsible for parsing the source
13745 documents, stores all metadata about the document collection and
13746 is serialized to disk after each build.
13747 Its API provides methods to do with access to metadata, resolv‐
13749 ing references, etc. It can also be used by extensions to cache
13750 information that should persist for incremental rebuilds.
13751 If you have the application or builder object, the environment
13753 is available as app.env or builder.env.
13754 Builder
13756 The builder object (usually called builder) is an instance of a
13757 specific subclass of Builder. Each builder class knows how to
13758 convert the parsed documents into an output format, or otherwise
13759 process them (e.g. check external links).
13760 If you have the application object, the builder is available as
13762 app.builder.
13763 Config The config object (usually called config) provides the values of
13765 configuration values set in conf.py as attributes. It is an
13766 instance of Config.
13767 The config is available as app.config or env.config.
13769 To see an example of use of these objects, refer to ../develop‐
13771 ment/tutorials/index.
13772 Build Phases
13774 One thing that is vital in order to understand extension mechanisms is
13775 the way in which a Sphinx project is built: this works in several
13776 phases.
13777 Phase 0: Initialization
13779 In this phase, almost nothing of interest to us happens. The source
13780 directory is searched for source files, and extensions are initial‐
13781 ized. Should a stored build environment exist, it is loaded, other‐
13782 wise a new one is created.
13783 Phase 1: Reading
13785 In Phase 1, all source files (and on subsequent builds, those that
13786 are new or changed) are read and parsed. This is the phase where
13787 directives and roles are encountered by docutils, and the corre‐
13788 sponding code is executed. The output of this phase is a doctree
13789 for each source file; that is a tree of docutils nodes. For docu‐
13790 ment elements that aren’t fully known until all existing files are
13791 read, temporary nodes are created.
13792 There are nodes provided by docutils, which are documented in the
13794 docutils documentation. Additional nodes are provided by Sphinx and
13795 documented here.
13796 During reading, the build environment is updated with all meta- and
13798 cross reference data of the read documents, such as labels, the
13799 names of headings, described Python objects and index entries. This
13800 will later be used to replace the temporary nodes.
13801 The parsed doctrees are stored on the disk, because it is not possi‐
13803 ble to hold all of them in memory.
13804 Phase 2: Consistency checks
13806 Some checking is done to ensure no surprises in the built documents.
13807 Phase 3: Resolving
13809 Now that the metadata and cross-reference data of all existing docu‐
13810 ments is known, all temporary nodes are replaced by nodes that can
13811 be converted into output using components called transforms. For
13812 example, links are created for object references that exist, and
13813 simple literal nodes are created for those that don’t.
13814 Phase 4: Writing
13816 This phase converts the resolved doctrees to the desired output for‐
13817 mat, such as HTML or LaTeX. This happens via a so-called docutils
13818 writer that visits the individual nodes of each doctree and produces
13819 some output in the process.
13820 NOTE:
13822 Some builders deviate from this general build plan, for example, the
13823 builder that checks external links does not need anything more than
13824 the parsed doctrees and therefore does not have phases 2–4.
13825 To see an example of application, refer to ../development/tutori‐
13827 als/todo.
13828 Extension metadata
13830 New in version 1.3.
13831 The setup() function can return a dictionary. This is treated by
13834 Sphinx as metadata of the extension. Metadata keys currently recog‐
13835 nized are:
13836 · 'version': a string that identifies the extension version. It is
13838 used for extension version requirement checking (see needs_exten‐
13839 sions) and informational purposes. If not given, "unknown version"
13840 is substituted.
13841 · 'env_version': an integer that identifies the version of env data
13843 structure if the extension stores any data to environment. It is
13844 used to detect the data structure has been changed from last build.
13845 The extensions have to increment the version when data structure has
13846 changed. If not given, Sphinx considers the extension does not
13847 stores any data to environment.
13848 · 'parallel_read_safe': a boolean that specifies if parallel reading of
13850 source files can be used when the extension is loaded. It defaults
13851 to False, i.e. you have to explicitly specify your extension to be
13852 parallel-read-safe after checking that it is.
13853 · 'parallel_write_safe': a boolean that specifies if parallel writing
13855 of output files can be used when the extension is loaded. Since
13856 extensions usually don’t negatively influence the process, this
13857 defaults to True.
13858 APIs used for writing extensions
13860 Application API
13861 Each Sphinx extension is a Python module with at least a setup() func‐
13862 tion. This function is called at initialization time with one argu‐
13863 ment, the application object representing the Sphinx process.
13864 class sphinx.application.Sphinx
13866 This application object has the public API described in the fol‐
13867 lowing.
13868 Extension setup
13870 These methods are usually called in an extension’s setup() function.
13871 Examples of using the Sphinx extension API can be seen in the
13873 sphinx.ext package.
13874 Sphinx.setup_extension(name)
13876 Import and setup a Sphinx extension module.
13877 Load the extension given by the module name. Use this if your
13879 extension needs the features provided by another extension.
13880 No-op if called twice.
13881 Sphinx.require_sphinx(version)
13883 Check the Sphinx version if requested.
13884 Compare version (which must be a major.minor version string,
13886 e.g. '1.1') with the version of the running Sphinx, and abort
13887 the build when it is too old.
13888 New in version 1.0.
13890 Sphinx.connect(event, callback)
13893 Register callback to be called when event is emitted.
13894 For details on available core events and the arguments of call‐
13896 back functions, please see Sphinx core events.
13897 The method returns a “listener ID” that can be used as an argu‐
13899 ment to disconnect().
13900 Sphinx.disconnect(listener_id)
13902 Unregister callback by listener_id.
13903 Sphinx.add_builder(builder)
13905 Register a new builder.
13906 builder must be a class that inherits from Builder.
13908 Changed in version 1.8: Add override keyword.
13910 Sphinx.add_config_value(name, default, rebuild)
13913 Register a configuration value.
13914 This is necessary for Sphinx to recognize new values and set
13916 default values accordingly. The name should be prefixed with
13917 the extension name, to avoid clashes. The default value can be
13918 any Python object. The string value rebuild must be one of
13919 those values:
13920 · 'env' if a change in the setting only takes effect when a doc‐
13922 ument is parsed – this means that the whole environment must
13923 be rebuilt.
13924 · 'html' if a change in the setting needs a full rebuild of HTML
13926 documents.
13927 · '' if a change in the setting will not need any special
13929 rebuild.
13930 Changed in version 0.6: Changed rebuild from a simple boolean
13932 (equivalent to '' or 'env') to a string. However, booleans are
13933 still accepted and converted internally.
13934 Changed in version 0.4: If the default value is a callable, it
13937 will be called with the config object as its argument in order
13938 to get the default value. This can be used to implement config
13939 values whose default depends on other values.
13940 Sphinx.add_event(name)
13943 Register an event called name.
13944 This is needed to be able to emit it.
13946 Sphinx.set_translator(name, translator_class)
13948 Register or override a Docutils translator class.
13949 This is used to register a custom output translator or to
13951 replace a builtin translator. This allows extensions to use
13952 custom translator and define custom nodes for the translator
13953 (see add_node()).
13954 New in version 1.3.
13956 Changed in version 1.8: Add override keyword.
13959 Sphinx.add_node(node, **kwds)
13962 Register a Docutils node class.
13963 This is necessary for Docutils internals. It may also be used
13965 in the future to validate nodes in the parsed documents.
13966 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
13968 page writers can be given as keyword arguments: the keyword
13969 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
13970 info' or any other supported translators, the value a 2-tuple of
13971 (visit, depart) methods. depart can be None if the visit func‐
13972 tion raises docutils.nodes.SkipNode. Example:
13973 class math(docutils.nodes.Element): pass
13975 def visit_math_html(self, node):
13977 self.body.append(self.starttag(node, 'math'))
13978 def depart_math_html(self, node):
13979 self.body.append('</math>')
13980 app.add_node(math, html=(visit_math_html, depart_math_html))
13982 Obviously, translators for which you don’t specify visitor meth‐
13984 ods will choke on the node when encountered in a document to
13985 translate.
13986 Changed in version 0.5: Added the support for keyword arguments
13988 giving visit functions.
13989 Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
13992 Register a Docutils node class as a numfig target.
13993 Sphinx numbers the node automatically. And then the users can
13995 refer it using numref.
13996 figtype is a type of enumerable nodes. Each figtypes have indi‐
13998 vidual numbering sequences. As a system figtypes, figure, table
13999 and code-block are defined. It is able to add custom nodes to
14000 these default figtypes. It is also able to define new custom
14001 figtype if new figtype is given.
14002 title_getter is a getter function to obtain the title of node.
14004 It takes an instance of the enumerable node, and it must return
14005 its title as string. The title is used to the default title of
14006 references for ref. By default, Sphinx searches docu‐
14007 tils.nodes.caption or docutils.nodes.title from the node as a
14008 title.
14009 Other keyword arguments are used for node visitor functions. See
14011 the Sphinx.add_node() for details.
14012 New in version 1.4.
14014 Sphinx.add_directive(name, func, content, arguments, **options)
14017 Sphinx.add_directive(name, directiveclass)
14019 Register a Docutils directive.
14020 name must be the prospective directive name. There are two pos‐
14022 sible ways to write a directive:
14023 · In the docutils 0.4 style, obj is the directive function.
14025 content, arguments and options are set as attributes on the
14026 function and determine whether the directive has content,
14027 arguments and options, respectively. This style is depre‐
14028 cated.
14029 · In the docutils 0.5 style, obj is the directive class. It
14031 must already have attributes named has_content, required_argu‐
14032 ments, optional_arguments, final_argument_whitespace and
14033 option_spec that correspond to the options for the function
14034 way. See the Docutils docs for details.
14035 The directive class must inherit from the class docu‐
14037 tils.parsers.rst.Directive.
14038 For example, the (already existing) literalinclude directive
14040 would be added like this:
14041 from docutils.parsers.rst import Directive, directives
14043 class LiteralIncludeDirective(Directive):
14045 has_content = True
14046 required_arguments = 1
14047 optional_arguments = 0
14048 final_argument_whitespace = True
14049 option_spec = {
14050 'class': directives.class_option,
14051 'name': directives.unchanged,
14052 }
14053 def run(self):
14055 ...
14056 add_directive('literalinclude', LiteralIncludeDirective)
14058 Changed in version 0.6: Docutils 0.5-style directive classes are
14060 now supported.
14061 Deprecated since version 1.8: Docutils 0.4-style (function
14064 based) directives support is deprecated.
14065 Changed in version 1.8: Add override keyword.
14068 Sphinx.add_role(name, role)
14071 Register a Docutils role.
14072 name must be the role name that occurs in the source, role the
14074 role function. Refer to the Docutils documentation for more
14075 information.
14076 Changed in version 1.8: Add override keyword.
14078 Sphinx.add_generic_role(name, nodeclass)
14081 Register a generic Docutils role.
14082 Register a Docutils role that does nothing but wrap its contents
14084 in the node given by nodeclass.
14085 New in version 0.6.
14087 Changed in version 1.8: Add override keyword.
14090 Sphinx.add_domain(domain)
14093 Register a domain.
14094 Make the given domain (which must be a class; more precisely, a
14096 subclass of Domain) known to Sphinx.
14097 New in version 1.0.
14099 Changed in version 1.8: Add override keyword.
14102 Sphinx.override_domain(domain)
14105 Override a registered domain.
14106 Make the given domain class known to Sphinx, assuming that there
14108 is already a domain with its .name. The new domain must be a
14109 subclass of the existing one.
14110 New in version 1.0.
14112 Deprecated since version 1.8: Integrated to add_domain().
14115 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
14118 **options)
14119 Sphinx.add_directive_to_domain(domain, name, directiveclass)
14121 Register a Docutils directive in a domain.
14122 Like add_directive(), but the directive is added to the domain
14124 named domain.
14125 New in version 1.0.
14127 Changed in version 1.8: Add override keyword.
14130 Sphinx.add_role_to_domain(domain, name, role)
14133 Register a Docutils role in a domain.
14134 Like add_role(), but the role is added to the domain named
14136 domain.
14137 New in version 1.0.
14139 Changed in version 1.8: Add override keyword.
14142 Sphinx.add_index_to_domain(domain, index)
14145 Register a custom index for a domain.
14146 Add a custom index class to the domain named domain. index must
14148 be a subclass of Index.
14149 New in version 1.0.
14151 Changed in version 1.8: Add override keyword.
14154 Sphinx.add_object_type(directivename, rolename, indextemplate='',
14157 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
14158 Register a new object type.
14159 This method is a very convenient way to add a new object type
14161 that can be cross-referenced. It will do this:
14162 · Create a new directive (called directivename) for documenting
14164 an object. It will automatically add index entries if index‐
14165 template is nonempty; if given, it must contain exactly one
14166 instance of %s. See the example below for how the template
14167 will be interpreted.
14168 · Create a new role (called rolename) to cross-reference to
14170 these object descriptions.
14171 · If you provide parse_node, it must be a function that takes a
14173 string and a docutils node, and it must populate the node with
14174 children parsed from the string. It must then return the name
14175 of the item to be used in cross-referencing and index entries.
14176 See the conf.py file in the source for this documentation for
14177 an example.
14178 · The objname (if not given, will default to directivename)
14180 names the type of object. It is used when listing objects,
14181 e.g. in search results.
14182 For example, if you have this call in a custom Sphinx extension:
14184 app.add_object_type('directive', 'dir', 'pair: %s; directive')
14186 you can use this markup in your documents:
14188 .. rst:directive:: function
14190 Document a function.
14192 <...>
14194 See also the :rst:dir:`function` directive.
14196 For the directive, an index entry will be generated as if you
14198 had prepended
14199 .. index:: pair: function; directive
14201 The reference node will be of class literal (so it will be ren‐
14203 dered in a proportional font, as appropriate for code) unless
14204 you give the ref_nodeclass argument, which must be a docutils
14205 node class. Most useful are docutils.nodes.emphasis or docu‐
14206 tils.nodes.strong – you can also use docutils.nodes.generated if
14207 you want no further text decoration. If the text should be
14208 treated as literal (e.g. no smart quote replacement), but not
14209 have typewriter styling, use sphinx.addnodes.literal_emphasis or
14210 sphinx.addnodes.literal_strong.
14211 For the role content, you have the same syntactical possibili‐
14213 ties as for standard Sphinx roles (see xref-syntax).
14214 Changed in version 1.8: Add override keyword.
14216 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
14219 ref_nodeclass=None, objname='')
14220 Register a new crossref object type.
14221 This method is very similar to add_object_type() except that the
14223 directive it generates must be empty, and will produce no out‐
14224 put.
14225 That means that you can add semantic targets to your sources,
14227 and refer to them using custom roles instead of generic ones
14228 (like ref). Example call:
14229 app.add_crossref_type('topic', 'topic', 'single: %s',
14231 docutils.nodes.emphasis)
14232 Example usage:
14234 .. topic:: application API
14236 The application API
14238 -------------------
14239 Some random text here.
14241 See also :topic:`this section <application API>`.
14243 (Of course, the element following the topic directive needn’t be
14245 a section.)
14246 Changed in version 1.8: Add override keyword.
14248 Sphinx.add_transform(transform)
14251 Register a Docutils transform to be applied after parsing.
14252 Add the standard docutils Transform subclass transform to the
14254 list of transforms that are applied after Sphinx parses a reST
14255 document.
14256 priority range categories for Sphinx transforms
14258 ┌─────────┬────────────────────────────┐
14259 │Priority │ Main purpose in Sphinx │
14260 ├─────────┼────────────────────────────┤
14261 │0-99 │ Fix invalid nodes by docu‐ │
14262 │ │ tils. Translate a doctree. │
14263 ├─────────┼────────────────────────────┤
14264 │100-299 │ Preparation │
14265 ├─────────┼────────────────────────────┤
14266 │300-399 │ early │
14267 ├─────────┼────────────────────────────┤
14268 │400-699 │ main │
14269 ├─────────┼────────────────────────────┤
14270 │700-799 │ Post processing. Deadline │
14271 │ │ to modify text and refer‐ │
14272 │ │ encing. │
14273 ├─────────┼────────────────────────────┤
14274 │800-899 │ Collect referencing and │
14275 │ │ referenced nodes. Domain │
14276 │ │ processing. │
14277 ├─────────┼────────────────────────────┤
14278 │900-999 │ Finalize and clean up. │
14279 └─────────┴────────────────────────────┘
14280 refs: Transform Priority Range Categories
14282 Sphinx.add_post_transform(transform)
14284 Register a Docutils transform to be applied before writing.
14285 Add the standard docutils Transform subclass transform to the
14287 list of transforms that are applied before Sphinx writes a docu‐
14288 ment.
14289 Sphinx.add_js_file(filename, **kwargs)
14291 Register a JavaScript file to include in the HTML output.
14292 Add filename to the list of JavaScript files that the default
14294 HTML template will include. The filename must be relative to
14295 the HTML static path , or a full URI with scheme. The keyword
14296 arguments are also accepted for attributes of <script> tag.
14297 Example:
14299 app.add_js_file('example.js')
14301 # => <script src="_static/example.js"></script>
14302 app.add_js_file('example.js', async="async")
14304 # => <script src="_static/example.js" async="async"></script>
14305 New in version 0.5.
14307 Changed in version 1.8: Renamed from app.add_javascript(). And
14310 it allows keyword arguments as attributes of script tag.
14311 Sphinx.add_css_file(filename, **kwargs)
14314 Register a stylesheet to include in the HTML output.
14315 Add filename to the list of CSS files that the default HTML tem‐
14317 plate will include. The filename must be relative to the HTML
14318 static path, or a full URI with scheme. The keyword arguments
14319 are also accepted for attributes of <link> tag.
14320 Example:
14322 app.add_css_file('custom.css')
14324 # => <link rel="stylesheet" href="_static/custom.css" type="text/css" />
14325 app.add_css_file('print.css', media='print')
14327 # => <link rel="stylesheet" href="_static/print.css"
14328 # type="text/css" media="print" />
14329 app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
14331 # => <link rel="alternate stylesheet" href="_static/fancy.css"
14332 # type="text/css" title="fancy" />
14333 New in version 1.0.
14335 Changed in version 1.6: Optional alternate and/or title
14338 attributes can be supplied with the alternate (of boolean type)
14339 and title (a string) arguments. The default is no title and
14340 alternate = False. For more information, refer to the
14341 documentation.
14342 Changed in version 1.8: Renamed from app.add_stylesheet(). And
14345 it allows keyword arguments as attributes of link tag.
14346 Sphinx.add_latex_package(packagename, options=None)
14349 Register a package to include in the LaTeX source code.
14350 Add packagename to the list of packages that LaTeX source code
14352 will include. If you provide options, it will be taken to usep‐
14353 ackage declaration.
14354 app.add_latex_package('mypackage')
14356 # => \usepackage{mypackage}
14357 app.add_latex_package('mypackage', 'foo,bar')
14358 # => \usepackage[foo,bar]{mypackage}
14359 New in version 1.3.
14361 Sphinx.add_lexer(alias, lexer)
14364 Register a new lexer for source code.
14365 Use lexer to highlight code blocks with the given language
14367 alias.
14368 New in version 0.6.
14370 Changed in version 2.1: Take a lexer class as an argument. An
14373 instance of lexers are still supported until Sphinx-3.x.
14374 Sphinx.add_autodocumenter(cls)
14377 Register a new documenter class for the autodoc extension.
14378 Add cls as a new documenter class for the sphinx.ext.autodoc
14380 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
14381 menter. This allows to auto-document new types of objects. See
14382 the source of the autodoc module for examples on how to subclass
14383 Documenter.
14384 Todo
14386 Add real docs for Documenter and subclassing
14387 New in version 0.6.
14389 Sphinx.add_autodoc_attrgetter(type, getter)
14392 Register a new getattr-like function for the autodoc extension.
14393 Add getter, which must be a function with an interface compati‐
14395 ble to the getattr() builtin, as the autodoc attribute getter
14396 for objects that are instances of typ. All cases where autodoc
14397 needs to get an attribute of a type are then handled by this
14398 function instead of getattr().
14399 New in version 0.6.
14401 Sphinx.add_search_language(cls)
14404 Register a new language for the HTML search index.
14405 Add cls, which must be a subclass of sphinx.search.Search‐
14407 Language, as a support language for building the HTML full-text
14408 search index. The class must have a lang attribute that indi‐
14409 cates the language it should be used for. See html_search_lan‐
14410 guage.
14411 New in version 1.1.
14413 Sphinx.add_source_suffix(suffix, filetype)
14416 Register a suffix of source files.
14417 Same as source_suffix. The users can override this using the
14419 setting.
14420 New in version 1.8.
14422 Sphinx.add_source_parser(parser)
14425 Register a parser class.
14426 New in version 1.4.
14428 Changed in version 1.8: suffix argument is deprecated. It only
14431 accepts parser argument. Use add_source_suffix() API to regis‐
14432 ter suffix instead.
14433 Changed in version 1.8: Add override keyword.
14436 Sphinx.add_env_collector(collector)
14439 Register an environment collector class.
14440 Refer to collector-api.
14442 New in version 1.6.
14444 Sphinx.add_html_theme(name, theme_path)
14447 Register a HTML Theme.
14448 The name is a name of theme, and path is a full path to the
14450 theme (refs: distribute-your-theme).
14451 New in version 1.6.
14453 Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
14456 Register a math renderer for HTML.
14457 The name is a name of math renderer. Both inline_renderers and
14459 block_renderers are used as visitor functions for the HTML
14460 writer: the former for inline math node (nodes.math), the latter
14461 for block math node (nodes.math_block). Regarding visitor func‐
14462 tions, see add_node() for details.
14463 New in version 1.8.
14465 Sphinx.add_message_catalog(catalog, locale_dir)
14468 Register a message catalog.
14469 The catalog is a name of catalog, and locale_dir is a base path
14471 of message catalog. For more details, see
14472 sphinx.locale.get_translation().
14473 New in version 1.8.
14475 Sphinx.is_parallel_allowed(typ)
14478 Check parallel processing is allowed or not.
14479 typ is a type of processing; 'read' or 'write'.
14481 exception sphinx.application.ExtensionError
14483 All these methods raise this exception if something went wrong
14484 with the extension API.
14485 Emitting events
14487 class sphinx.application.Sphinx
14488 emit(event, *arguments)
14490 Emit event and pass arguments to the callback functions.
14491 Return the return values of all callbacks as a list. Do
14493 not emit core Sphinx events in extensions!
14494 emit_firstresult(event, *arguments)
14496 Emit event and pass arguments to the callback functions.
14497 Return the result of the first callback that doesn’t
14499 return None.
14500 New in version 0.5.
14502 Sphinx runtime information
14505 The application object also provides runtime information as attributes.
14506 Sphinx.project
14508 Target project. See Project.
14509 Sphinx.srcdir
14511 Source directory.
14512 Sphinx.confdir
14514 Directory containing conf.py.
14515 Sphinx.doctreedir
14517 Directory for storing pickled doctrees.
14518 Sphinx.outdir
14520 Directory for storing built document.
14521 Sphinx core events
14523 These events are known to the core. The arguments shown are given to
14524 the registered event handlers. Use Sphinx.connect() in an extension’s
14525 setup function (note that conf.py can also have a setup function) to
14526 connect handlers to the events. Example:
14527 def source_read_handler(app, docname, source):
14529 print('do something here...')
14530 def setup(app):
14532 app.connect('source-read', source_read_handler)
14533 builder-inited(app)
14535 Emitted when the builder object has been created. It is avail‐
14536 able as app.builder.
14537 config-inited(app, config)
14539 Emitted when the config object has been initialized.
14540 New in version 1.8.
14542 env-get-outdated(app, env, added, changed, removed)
14545 Emitted when the environment determines which source files have
14546 changed and should be re-read. added, changed and removed are
14547 sets of docnames that the environment has determined. You can
14548 return a list of docnames to re-read in addition to these.
14549 New in version 1.1.
14551 env-purge-doc(app, env, docname)
14554 Emitted when all traces of a source file should be cleaned from
14555 the environment, that is, if the source file is removed or
14556 before it is freshly read. This is for extensions that keep
14557 their own caches in attributes of the environment.
14558 For example, there is a cache of all modules on the environment.
14560 When a source file has been changed, the cache’s entries for the
14561 file are cleared, since the module declarations could have been
14562 removed from the file.
14563 New in version 0.5.
14565 env-before-read-docs(app, env, docnames)
14568 Emitted after the environment has determined the list of all
14569 added and changed files and just before it reads them. It
14570 allows extension authors to reorder the list of docnames
14571 (inplace) before processing, or add more docnames that Sphinx
14572 did not consider changed (but never add any docnames that are
14573 not in env.found_docs).
14574 You can also remove document names; do this with caution since
14576 it will make Sphinx treat changed files as unchanged.
14577 New in version 1.3.
14579 source-read(app, docname, source)
14582 Emitted when a source file has been read. The source argument
14583 is a list whose single element is the contents of the source
14584 file. You can process the contents and replace this item to
14585 implement source-level transformations.
14586 For example, if you want to use $ signs to delimit inline math,
14588 like in LaTeX, you can use a regular expression to replace $...$
14589 by :math:`...`.
14590 New in version 0.5.
14592 doctree-read(app, doctree)
14595 Emitted when a doctree has been parsed and read by the environ‐
14596 ment, and is about to be pickled. The doctree can be modified
14597 in-place.
14598 missing-reference(app, env, node, contnode)
14600 Emitted when a cross-reference to a Python module or object can‐
14601 not be resolved. If the event handler can resolve the refer‐
14602 ence, it should return a new docutils node to be inserted in the
14603 document tree in place of the node node. Usually this node is a
14604 reference node containing contnode as a child.
14605 Parameters
14607 · env – The build environment (app.builder.env).
14609 · node – The pending_xref node to be resolved. Its
14611 attributes reftype, reftarget, modname and classname
14612 attributes determine the type and target of the refer‐
14613 ence.
14614 · contnode – The node that carries the text and format‐
14616 ting inside the future reference and should be a child
14617 of the returned reference node.
14618 New in version 0.5.
14620 doctree-resolved(app, doctree, docname)
14623 Emitted when a doctree has been “resolved” by the environment,
14624 that is, all references have been resolved and TOCs have been
14625 inserted. The doctree can be modified in place.
14626 Here is the place to replace custom nodes that don’t have visi‐
14628 tor methods in the writers, so that they don’t cause errors when
14629 the writers encounter them.
14630 env-merge-info(app, env, docnames, other)
14632 This event is only emitted when parallel reading of documents is
14633 enabled. It is emitted once for every subprocess that has read
14634 some documents.
14635 You must handle this event in an extension that stores data in
14637 the environment in a custom location. Otherwise the environment
14638 in the main process will not be aware of the information stored
14639 in the subprocess.
14640 other is the environment object from the subprocess, env is the
14642 environment from the main process. docnames is a set of docu‐
14643 ment names that have been read in the subprocess.
14644 For a sample of how to deal with this event, look at the stan‐
14646 dard sphinx.ext.todo extension. The implementation is often
14647 similar to that of env-purge-doc, only that information is not
14648 removed, but added to the main environment from the other envi‐
14649 ronment.
14650 New in version 1.3.
14652 env-updated(app, env)
14655 Emitted when the update() method of the build environment has
14656 completed, that is, the environment and all doctrees are now
14657 up-to-date.
14658 You can return an iterable of docnames from the handler. These
14660 documents will then be considered updated, and will be
14661 (re-)written during the writing phase.
14662 New in version 0.5.
14664 Changed in version 1.3: The handlers’ return value is now used.
14667 env-check-consistency(app, env)
14670 Emitted when Consistency checks phase. You can check consis‐
14671 tency of metadata for whole of documents.
14672 New in version 1.6: As a experimental event
14674 html-collect-pages(app)
14677 Emitted when the HTML builder is starting to write non-document
14678 pages. You can add pages to write by returning an iterable from
14679 this event consisting of (pagename, context, templatename).
14680 New in version 1.0.
14682 html-page-context(app, pagename, templatename, context, doctree)
14685 Emitted when the HTML builder has created a context dictionary
14686 to render a template with – this can be used to add custom ele‐
14687 ments to the context.
14688 The pagename argument is the canonical name of the page being
14690 rendered, that is, without .html suffix and using slashes as
14691 path separators. The templatename is the name of the template
14692 to render, this will be 'page.html' for all pages from reST doc‐
14693 uments.
14694 The context argument is a dictionary of values that are given to
14696 the template engine to render the page and can be modified to
14697 include custom values. Keys must be strings.
14698 The doctree argument will be a doctree when the page is created
14700 from a reST documents; it will be None when the page is created
14701 from an HTML template alone.
14702 You can return a string from the handler, it will then replace
14704 'page.html' as the HTML template for this page.
14705 New in version 0.4.
14707 Changed in version 1.3: The return value can now specify a tem‐
14710 plate name.
14711 build-finished(app, exception)
14714 Emitted when a build has finished, before Sphinx exits, usually
14715 used for cleanup. This event is emitted even when the build
14716 process raised an exception, given as the exception argument.
14717 The exception is reraised in the application after the event
14718 handlers have run. If the build process raised no exception,
14719 exception will be None. This allows to customize cleanup
14720 actions depending on the exception status.
14721 New in version 0.5.
14723 Checking the Sphinx version
14726 Use this to adapt your extension to API changes in Sphinx.
14727 sphinx.version_info = (2, 1, 2, 'final', 0)
14729 Version info for better programmatic use.
14730 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
14732 would be (1, 2, 1, 'beta', 3). The fourth element can be one of:
14733 alpha, beta, rc, final. final always has 0 as the last element.
14734 New in version 1.2: Before version 1.2, check the string
14736 sphinx.__version__.
14737 The Config object
14740 class sphinx.config.Config(*args)
14741 Configuration file abstraction.
14742 The config object makes the values of all config values avail‐
14744 able as attributes.
14745 It is exposed via the sphinx.application.Application.config and
14747 sphinx.environment.Environment.config attributes. For example,
14748 to get the value of language, use either app.config.language or
14749 env.config.language.
14750 The template bridge
14752 class sphinx.application.TemplateBridge
14753 This class defines the interface for a “template bridge”, that
14754 is, a class that renders templates given a template name and a
14755 context.
14756 init(builder, theme=None, dirs=None)
14758 Called by the builder to initialize the template system.
14759 builder is the builder object; you’ll probably want to
14761 look at the value of builder.config.templates_path.
14762 theme is a sphinx.theming.Theme object or None; in the
14764 latter case, dirs can be list of fixed directories to
14765 look for templates.
14766 newest_template_mtime()
14768 Called by the builder to determine if output files are
14769 outdated because of template changes. Return the mtime
14770 of the newest template file that was changed. The
14771 default implementation returns 0.
14772 render(template, context)
14774 Called by the builder to render a template given as a
14775 filename with a specified context (a Python dictionary).
14776 render_string(template, context)
14778 Called by the builder to render a template given as a
14779 string with a specified context (a Python dictionary).
14780 Exceptions
14782 exception sphinx.errors.SphinxError
14783 Base class for Sphinx errors.
14784 This is the base class for “nice” exceptions. When such an
14786 exception is raised, Sphinx will abort the build and present the
14787 exception category and message to the user.
14788 Extensions are encouraged to derive from this exception for
14790 their custom errors.
14791 Exceptions not derived from SphinxError are treated as unex‐
14793 pected and shown to the user with a part of the traceback (and
14794 the full traceback saved in a temporary file).
14795 category
14797 Description of the exception “category”, used in convert‐
14798 ing the exception to a string (“category: message”).
14799 Should be set accordingly in subclasses.
14800 exception sphinx.errors.ConfigError
14802 Configuration error.
14803 exception sphinx.errors.ExtensionError(message, orig_exc=None)
14805 Extension error.
14806 exception sphinx.errors.ThemeError
14808 Theme error.
14809 exception sphinx.errors.VersionRequirementError
14811 Incompatible Sphinx version error.
14812 Project API
14814 class sphinx.project.Project(srcdir, source_suffix)
14815 A project is source code set of Sphinx document.
14816 discover(exclude_paths=[])
14818 Find all document files in the source directory and put
14819 them in docnames.
14820 doc2path(docname, basedir=True)
14822 Return the filename for the document name.
14823 If basedir is True, return as an absolute path. Else,
14825 return as a relative path to the source directory.
14826 path2doc(filename)
14828 Return the docname for the filename if the file is docu‐
14829 ment.
14830 filename should be absolute or relative to the source
14832 directory.
14833 restore(other)
14835 Take over a result of last build.
14836 docnames = None
14838 The name of documents belongs to this project.
14839 source_suffix = None
14841 source_suffix. Same as source_suffix.
14842 srcdir = None
14844 Source directory.
14845 Build environment API
14847 class sphinx.environment.BuildEnvironment
14848 Attributes
14849 app Reference to the Sphinx (application) object.
14851 config Reference to the Config object.
14853 project
14855 Target project. See Project.
14856 srcdir Source directory.
14858 doctreedir
14860 Directory for storing pickled doctrees.
14861 events An EventManager object.
14863 found_docs
14865 A set of all existing docnames.
14866 metadata
14868 Dictionary mapping docnames to “metadata” (see metadata).
14869 titles Dictionary mapping docnames to the docutils node for
14871 their main title.
14872 docname
14874 Returns the docname of the document currently being
14875 parsed.
14876 Utility methods
14878 doc2path(docname, base=True, suffix=None)
14880 Return the filename for the document name.
14881 If base is True, return absolute path under self.srcdir.
14883 If base is None, return relative path to self.srcdir. If
14884 base is a path string, return absolute path under that.
14885 If suffix is not None, add it instead of con‐
14886 fig.source_suffix.
14887 relfn2path(filename, docname=None)
14889 Return paths to a file referenced from a document, rela‐
14890 tive to documentation root and absolute.
14891 In the input “filename”, absolute filenames are taken as
14893 relative to the source dir, while relative filenames are
14894 relative to the dir of the containing document.
14895 note_dependency(filename)
14897 Add filename as a dependency of the current document.
14898 This means that the document will be rebuilt if this file
14900 changes.
14901 filename should be absolute or relative to the source
14903 directory.
14904 new_serialno(category='')
14906 Return a serial number, e.g. for index entry targets.
14907 The number is guaranteed to be unique in the current doc‐
14909 ument.
14910 note_reread()
14912 Add the current document to the list of documents that
14913 will automatically be re-read at the next build.
14914 Builder API
14916 Todo
14917 Expand this.
14918 class sphinx.builders.Builder
14920 This is the base class for all builders.
14921 These attributes should be set on builder classes:
14923 name = ''
14925 The builder’s name, for the -b command line option.
14926 format = ''
14928 The builder’s output format, or ‘’ if no document output
14929 is produced.
14930 epilog = ''
14932 The message emitted upon successful build completion.
14933 This can be a printf-style template string with the fol‐
14934 lowing keys: outdir, project
14935 supported_image_types = []
14937 The list of MIME types of image formats supported by the
14938 builder. Image files are searched in the order in which
14939 they appear here.
14940 supported_remote_images = False
14942 The builder supports remote images or not.
14943 supported_data_uri_images = False
14945 The builder supports data URIs or not.
14946 default_translator_class = None
14948 default translator class for the builder. This can be
14949 overridden by app.set_translator().
14950 These methods are predefined and will be called from the appli‐
14952 cation:
14953 get_relative_uri(from_, to, typ=None)
14955 Return a relative URI between two source filenames.
14956 May raise environment.NoUri if there’s no way to return a
14958 sensible URI.
14959 build_all()
14961 Build all source files.
14962 build_specific(filenames)
14964 Only rebuild as much as needed for changes in the file‐
14965 names.
14966 build_update()
14968 Only rebuild what was changed or added since last build.
14969 build(docnames, summary=None, method='update')
14971 Main build method.
14972 First updates the environment, and then calls write().
14974 These methods can be overridden in concrete builder classes:
14976 init() Load necessary templates and perform initialization. The
14978 default implementation does nothing.
14979 get_outdated_docs()
14981 Return an iterable of output files that are outdated, or
14982 a string describing what an update build will build.
14983 If the builder does not output individual files corre‐
14985 sponding to source files, return a string here. If it
14986 does, return an iterable of those files that need to be
14987 written.
14988 get_target_uri(docname, typ=None)
14990 Return the target URI for a document name.
14991 typ can be used to qualify the link characteristic for
14993 individual builders.
14994 prepare_writing(docnames)
14996 A place where you can add logic before write_doc() is run
14997 write_doc(docname, doctree)
14999 Where you actually write something to the filesystem.
15000 finish()
15002 Finish the building process.
15003 The default implementation does nothing.
15005 Attributes
15007 events An EventManager object.
15009 Environment Collector API
15011 class sphinx.environment.collectors.EnvironmentCollector
15012 An EnvironmentCollector is a specific data collector from each
15013 document.
15014 It gathers data and stores BuildEnvironment as a database.
15016 Examples of specific data would be images, download files, sec‐
15017 tion titles, metadatas, index entries and toctrees, etc.
15018 clear_doc(app, env, docname)
15020 Remove specified data of a document.
15021 This method is called on the removal of the document.
15023 get_outdated_docs(app, env, added, changed, removed)
15025 Return a list of docnames to re-read.
15026 This methods is called before reading the documents.
15028 get_updated_docs(app, env)
15030 Return a list of docnames to re-read.
15031 This methods is called after reading the whole of docu‐
15033 ments (experimental).
15034 merge_other(app, env, docnames, other)
15036 Merge in specified data regarding docnames from a differ‐
15037 ent BuildEnvironment object which coming from a subpro‐
15038 cess in parallel builds.
15039 process_doc(app, doctree)
15041 Process a document and gather specific data from it.
15042 This method is called after the document is read.
15044 Docutils markup API
15046 This section describes the API for adding ReST markup elements (roles
15047 and directives).
15048 Roles
15050 Directives
15051 Directives are handled by classes derived from docu‐
15052 tils.parsers.rst.Directive. They have to be registered by an extension
15053 using Sphinx.add_directive() or Sphinx.add_directive_to_domain().
15054 class docutils.parsers.rst.Directive
15056 The markup syntax of the new directive is determined by the fol‐
15057 low five class attributes:
15058 required_arguments = 0
15060 Number of required directive arguments.
15061 optional_arguments = 0
15063 Number of optional arguments after the required argu‐
15064 ments.
15065 final_argument_whitespace = False
15067 May the final argument contain whitespace?
15068 option_spec = None
15070 Mapping of option names to validator functions.
15071 Option validator functions take a single parameter, the
15073 option argument (or None if not given), and should vali‐
15074 date it or convert it to the proper form. They raise
15075 ValueError or TypeError to indicate failure.
15076 There are several predefined and possibly useful valida‐
15078 tors in the docutils.parsers.rst.directives module.
15079 has_content = False
15081 May the directive have content?
15082 New directives must implement the run() method:
15084 run() This method must process the directive arguments, options
15086 and content, and return a list of Docutils/Sphinx nodes
15087 that will be inserted into the document tree at the point
15088 where the directive was encountered.
15089 Instance attributes that are always set on the directive are:
15091 name The directive name (useful when registering the same
15093 directive class under multiple names).
15094 arguments
15096 The arguments given to the directive, as a list.
15097 options
15099 The options given to the directive, as a dictionary map‐
15100 ping option names to validated/converted values.
15101 content
15103 The directive content, if given, as a ViewList.
15104 lineno The absolute line number on which the directive appeared.
15106 This is not always a useful value; use srcline instead.
15107 content_offset
15109 Internal offset of the directive content. Used when
15110 calling nested_parse (see below).
15111 block_text
15113 The string containing the entire directive.
15114 state
15116 state_machine
15118 The state and state machine which controls the parsing.
15119 Used for nested_parse.
15120 ViewLists
15122 Docutils represents document source lines in a class docutils.statema‐
15123 chine.ViewList. This is a list with extended functionality – for one,
15124 slicing creates views of the original list, and also the list contains
15125 information about the source line numbers.
15126 The Directive.content attribute is a ViewList. If you generate content
15128 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
15129 tant for content generation are the following points:
15130 · The constructor takes a list of strings (lines) and a source (docu‐
15132 ment) name.
15133 · The .append() method takes a line and a source name as well.
15135 Parsing directive content as ReST
15137 Many directives will contain more markup that must be parsed. To do
15138 this, use one of the following APIs from the Directive.run() method:
15139 · self.state.nested_parse
15141 · sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
15143 the parsed content.
15144 Both APIs parse the content into a given node. They are used like this:
15146 node = docutils.nodes.paragraph()
15148 # either
15149 nested_parse_with_titles(self.state, self.result, node)
15150 # or
15151 self.state.nested_parse(self.result, 0, node)
15152 NOTE:
15154 sphinx.util.docutils.switch_source_input() allows to change a target
15155 file during nested_parse. It is useful to mixed contents. For
15156 example, sphinx. ext.autodoc uses it to parse docstrings:
15157 from sphinx.util.docutils import switch_source_input
15159 # Switch source_input between parsing content.
15161 # Inside this context, all parsing errors and warnings are reported as
15162 # happened in new source_input (in this case, ``self.result``).
15163 with switch_source_input(self.state, self.result):
15164 node = docutils.nodes.paragraph()
15165 self.state.nested_parse(self.result, 0, node)
15166 Deprecated since version 1.7: Until Sphinx-1.6,
15168 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
15169 now, it is replaced by switch_source_input().
15170 If you don’t need the wrapping node, you can use any concrete node type
15173 and return node.children from the Directive.
15174 SEE ALSO:
15176 Creating directives HOWTO of the Docutils documentation
15177 Domain API
15179 class sphinx.domains.Domain(env)
15180 A Domain is meant to be a group of “object” description direc‐
15181 tives for objects of a similar nature, and corresponding roles
15182 to create references to them. Examples would be Python modules,
15183 classes, functions etc., elements of a templating language,
15184 Sphinx roles and directives, etc.
15185 Each domain has a separate storage for information about exist‐
15187 ing objects and how to reference them in self.data, which must
15188 be a dictionary. It also must implement several functions that
15189 expose the object information in a uniform way to parts of
15190 Sphinx that allow the user to reference or search for objects in
15191 a domain-agnostic way.
15192 About self.data: since all object and cross-referencing informa‐
15194 tion is stored on a BuildEnvironment instance, the domain.data
15195 object is also stored in the env.domaindata dict under the key
15196 domain.name. Before the build process starts, every active
15197 domain is instantiated and given the environment object; the
15198 domaindata dict must then either be nonexistent or a dictionary
15199 whose ‘version’ key is equal to the domain class’ data_version
15200 attribute. Otherwise, OSError is raised and the pickled envi‐
15201 ronment is discarded.
15202 add_object_type(name, objtype)
15204 Add an object type.
15205 check_consistency()
15207 Do consistency checks (experimental).
15208 clear_doc(docname)
15210 Remove traces of a document in the domain-specific inven‐
15211 tories.
15212 directive(name)
15214 Return a directive adapter class that always gives the
15215 registered directive its full name (‘domain:name’) as
15216 self.name.
15217 get_enumerable_node_type(node)
15219 Get type of enumerable nodes (experimental).
15220 get_full_qualified_name(node)
15222 Return full qualified name for given node.
15223 get_objects()
15225 Return an iterable of “object descriptions”.
15226 Object descriptions are tuples with six items:
15228 name Fully qualified name.
15230 dispname
15232 Name to display when searching/linking.
15233 type Object type, a key in self.object_types.
15235 docname
15237 The document where it is to be found.
15238 anchor The anchor name for the object.
15240 priority
15242 How “important” the object is (determines place‐
15243 ment in search results). One of:
15244 1 Default priority (placed before full-text
15246 matches).
15247 0 Object is important (placed before
15249 default-priority objects).
15250 2 Object is unimportant (placed after
15252 full-text matches).
15253 -1 Object should not show up in search at all.
15255 get_type_name(type, primary=False)
15257 Return full name for given ObjType.
15258 merge_domaindata(docnames, otherdata)
15260 Merge in data regarding docnames from a different domain‐
15261 data inventory (coming from a subprocess in parallel
15262 builds).
15263 process_doc(env, docname, document)
15265 Process a document after it is read by the environment.
15266 process_field_xref(pnode)
15268 Process a pending xref created in a doc field. For exam‐
15269 ple, attach information about the current scope.
15270 resolve_any_xref(env, fromdocname, builder, target, node, contn‐
15272 ode)
15273 Resolve the pending_xref node with the given target.
15274 The reference comes from an “any” or similar role, which
15276 means that we don’t know the type. Otherwise, the argu‐
15277 ments are the same as for resolve_xref().
15278 The method must return a list (potentially empty) of
15280 tuples ('domain:role', newnode), where 'domain:role' is
15281 the name of a role that could have created the same ref‐
15282 erence, e.g. 'py:func'. newnode is what resolve_xref()
15283 would return.
15284 New in version 1.3.
15286 resolve_xref(env, fromdocname, builder, typ, target, node, con‐
15289 tnode)
15290 Resolve the pending_xref node with the given typ and tar‐
15291 get.
15292 This method should return a new node, to replace the xref
15294 node, containing the contnode which is the markup content
15295 of the cross-reference.
15296 If no resolution can be found, None can be returned; the
15298 xref node will then given to the missing-reference event,
15299 and if that yields no resolution, replaced by contnode.
15300 The method can also raise sphinx.environment.NoUri to
15302 suppress the missing-reference event being emitted.
15303 role(name)
15305 Return a role adapter function that always gives the reg‐
15306 istered role its full name (‘domain:name’) as the first
15307 argument.
15308 dangling_warnings = {}
15310 role name -> a warning message if reference is missing
15311 data = None
15313 data value
15314 data_version = 0
15316 data version, bump this when the format of self.data
15317 changes
15318 directives = {}
15320 directive name -> directive class
15321 enumerable_nodes = {}
15323 node_class -> (enum_node_type, title_getter)
15324 indices = []
15326 a list of Index subclasses
15327 initial_data = {}
15329 data value for a fresh environment
15330 label = ''
15332 domain label: longer, more descriptive (used in messages)
15333 name = ''
15335 domain name: should be short, but unique
15336 object_types = {}
15338 type (usually directive) name -> ObjType instance
15339 roles = {}
15341 role name -> role callable
15342 class sphinx.domains.ObjType(lname, *roles, **attrs)
15344 An ObjType is the description for a type of object that a domain
15345 can document. In the object_types attribute of Domain sub‐
15346 classes, object type names are mapped to instances of this
15347 class.
15348 Constructor arguments:
15350 · lname: localized name of the type (do not include domain name)
15352 · roles: all the roles that can refer to an object of this type
15354 · attrs: object attributes – currently only “searchprio” is
15356 known, which defines the object’s priority in the full-text
15357 search index, see Domain.get_objects().
15358 class sphinx.domains.Index(domain)
15360 An Index is the description for a domain-specific index. To add
15361 an index to a domain, subclass Index, overriding the three name
15362 attributes:
15363 · name is an identifier used for generating file names.
15365 · localname is the section title for the index.
15367 · shortname is a short name for the index, for use in the rela‐
15369 tion bar in HTML output. Can be empty to disable entries in
15370 the relation bar.
15371 and providing a generate() method. Then, add the index class to
15373 your domain’s indices list. Extensions can add indices to
15374 existing domains using add_index_to_domain().
15375 generate(docnames=None)
15377 Get entries for the index.
15378 If docnames is given, restrict to entries referring to
15380 these docnames.
15381 The return value is a tuple of (content, collapse):
15383 collapse
15385 A boolean that determines if sub-entries should
15386 start collapsed (for output formats that support
15387 collapsing sub-entries).
15388 content:
15390 A sequence of (letter, entries) tuples, where let‐
15391 ter is the “heading” for the given entries, usu‐
15392 ally the starting letter, and entries is a
15393 sequence of single entries. Each entry is a
15394 sequence [name, subtype, docname, anchor, extra,
15395 qualifier, descr]. The items in this sequence have
15396 the following meaning:
15397 name The name of the index entry to be dis‐
15399 played.
15400 subtype
15402 The sub-entry related type. One of:
15403 0 A normal entry.
15405 1 An entry with sub-entries.
15407 2 A sub-entry.
15409 docname
15411 docname where the entry is located.
15412 anchor Anchor for the entry within docname
15414 extra Extra info for the entry.
15416 qualifier
15418 Qualifier for the description.
15419 descr Description for the entry.
15421 Qualifier and description are not rendered for some out‐
15423 put formats such as LaTeX.
15424 Parser API
15426 The docutils documentation describes parsers as follows:
15427 The Parser analyzes the input document and creates a node tree rep‐
15428 resentation.
15429 In Sphinx, the parser modules works as same as docutils. The parsers
15431 are registered to Sphinx by extensions using Application APIs;
15432 Sphinx.add_source_suffix() and Sphinx.add_source_parser().
15433 The source suffix is a mapping from file suffix to file type. For
15435 example, .rst file is mapped to 'restructuredtext' type. Sphinx uses
15436 the file type to looking for parsers from registered list. On search‐
15437 ing, Sphinx refers to the Parser.supported attribute and picks up a
15438 parser which contains the file type in the attribute.
15439 The users can override the source suffix mappings using source_suffix
15441 like following:
15442 # a mapping from file suffix to file types
15444 source_suffix = {
15445 '.rst': 'restructuredtext',
15446 '.md': 'markdown',
15447 }
15448 You should indicate file types your parser supports. This will allow
15450 users to configure their settings appropriately.
15451 class sphinx.parsers.Parser
15453 A base class of source parsers. The additional parsers should
15454 inherit this class instead of docutils.parsers.Parser. Compared
15455 with docutils.parsers.Parser, this class improves accessibility
15456 to Sphinx APIs.
15457 The subclasses can access following objects and functions:
15459 self.app
15461 The application object (sphinx.application.Sphinx)
15462 self.config
15464 The config object (sphinx.config.Config)
15465 self.env
15467 The environment object (sphinx.environment.BuildEnviron‐
15468 ment)
15469 self.warn()
15471 Emit a warning. (Same as sphinx.applica‐
15472 tion.Sphinx.warn())
15473 self.info()
15475 Emit a informational message. (Same as sphinx.applica‐
15476 tion.Sphinx.info())
15477 Deprecated since version 1.6: warn() and info() is deprecated.
15479 Use sphinx.util.logging instead.
15480 Doctree node classes added by Sphinx
15483 Nodes for domain-specific object descriptions
15484 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
15485 Node for object descriptions.
15486 This node is similar to a “definition list” with one definition.
15488 It contains one or more desc_signature and a desc_content.
15489 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
15491 **attributes)
15492 Node for object signatures.
15493 The “term” part of the custom Sphinx definition list.
15495 As default the signature is a single line signature, but set
15497 is_multiline = True to describe a multi-line signature. In that
15498 case all child nodes must be desc_signature_line nodes.
15499 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
15501 dren, **attributes)
15502 Node for a line in a multi-line object signatures.
15503 It should only be used in a desc_signature with is_multiline
15505 set. Set add_permalink = True for the line that should get the
15506 permalink.
15507 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
15509 **attributes)
15510 Node for additional name parts (module name, class name).
15511 class sphinx.addnodes.desc_type(rawsource='', text='', *children,
15513 **attributes)
15514 Node for return types or object type names.
15515 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
15517 **attributes)
15518 Node for a “returns” annotation (a la -> in Python).
15519 class sphinx.addnodes.desc_name(rawsource='', text='', *children,
15521 **attributes)
15522 Node for the main object name.
15523 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
15525 dren, **attributes)
15526 Node for a general parameter list.
15527 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
15529 **attributes)
15530 Node for a single parameter.
15531 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
15533 **attributes)
15534 Node for marking optional parts of the parameter list.
15535 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
15537 **attributes)
15538 Node for signature annotations (not Python 3-style annotations).
15539 class sphinx.addnodes.desc_content(rawsource='', *children,
15541 **attributes)
15542 Node for object description content.
15543 This is the “definition” part of the custom Sphinx definition
15545 list.
15546 New admonition-like constructs
15548 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
15549 **attributes)
15550 Node for version change entries.
15551 Currently used for “versionadded”, “versionchanged” and “depre‐
15553 cated” directives.
15554 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
15556 Custom “see also” admonition.
15557 Other paragraph-level nodes
15559 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
15560 dren, **attributes)
15561 Node for a compact paragraph (which never makes a <p> node).
15562 New inline nodes
15564 class sphinx.addnodes.index(rawsource='', text='', *children,
15565 **attributes)
15566 Node for index entries.
15567 This node is created by the index directive and has one
15569 attribute, entries. Its value is a list of 5-tuples of (entry‐
15570 type, entryname, target, ignored, key).
15571 entrytype is one of “single”, “pair”, “double”, “triple”.
15573 key is categorization characters (usually a single character)
15575 for general index page. For the details of this, please see
15576 also: glossary and issue #2320.
15577 class sphinx.addnodes.pending_xref(rawsource='', *children,
15579 **attributes)
15580 Node for cross-references that cannot be resolved without com‐
15581 plete information about all documents.
15582 These nodes are resolved before writing output, in BuildEnviron‐
15584 ment.resolve_references.
15585 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
15587 dren, **attributes)
15588 Node that behaves like emphasis, but further text processors are
15589 not applied (e.g. smartypants for HTML output).
15590 class sphinx.addnodes.abbreviation(rawsource='', text='', *children,
15592 **attributes)
15593 Node for abbreviations with explanations.
15594 Deprecated since version 2.0.
15596 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
15599 dren, **attributes)
15600 Node for download references, similar to pending_xref.
15601 Special nodes
15603 class sphinx.addnodes.only(rawsource='', *children, **attributes)
15604 Node for “only” directives (conditional inclusion based on
15605 tags).
15606 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
15608 Node for meta directive – same as docutils’ standard meta node,
15609 but pickleable.
15610 class sphinx.addnodes.highlightlang(rawsource='', *children,
15612 **attributes)
15613 Inserted to set the highlight language and line number options
15614 for subsequent code blocks.
15615 You should not need to generate the nodes below in extensions.
15617 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
15619 Node to insert a glossary.
15620 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
15622 Node for inserting a “TOC tree”.
15623 class sphinx.addnodes.start_of_file(rawsource='', *children,
15625 **attributes)
15626 Node to mark start of a new file, used in the LaTeX builder
15627 only.
15628 class sphinx.addnodes.productionlist(rawsource='', *children,
15630 **attributes)
15631 Node for grammar production lists.
15632 Contains production nodes.
15634 class sphinx.addnodes.production(rawsource='', text='', *children,
15636 **attributes)
15637 Node for a single grammar production rule.
15638 Logging API
15640 sphinx.util.logging.getLogger(name)
15641 Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
15642 Sphinx logger always uses sphinx.* namespace to be independent
15644 from settings of root logger. It ensures logging is consistent
15645 even if a third-party extension or imported application resets
15646 logger settings.
15647 Example usage:
15649 >>> from sphinx.util import logging
15651 >>> logger = logging.getLogger(__name__)
15652 >>> logger.info('Hello, this is an extension!')
15653 Hello, this is an extension!
15654 class sphinx.util.logging.SphinxLoggerAdapter(logging.LoggerAdapter)
15656 LoggerAdapter allowing type and subtype keywords.
15657 error(msg, *args, **kwargs)
15659 critical(msg, *args, **kwargs)
15661 warning(msg, *args, **kwargs)
15663 Logs a message on this logger with the specified level.
15664 Basically, the arguments are as with python’s logging
15665 module.
15666 In addition, Sphinx logger supports following keyword
15668 arguments:
15669 type, *subtype*
15671 Categories of warning logs. It is used to sup‐
15672 press warnings by suppress_warnings setting.
15673 location
15675 Where the warning happened. It is used to include
15676 the path and line number in each log. It allows
15677 docname, tuple of docname and line number and
15678 nodes:
15679 logger = sphinx.util.logging.getLogger(__name__)
15681 logger.warning('Warning happened!', location='index')
15682 logger.warning('Warning happened!', location=('chapter1/index', 10))
15683 logger.warning('Warning happened!', location=some_node)
15684 color The color of logs. By default, error level logs
15686 are colored as "darkred", critical level ones is
15687 not colored, and warning level ones are colored as
15688 "red".
15689 log(level, msg, *args, **kwargs)
15691 info(msg, *args, **kwargs)
15693 verbose(msg, *args, **kwargs)
15695 debug(msg, *args, **kwargs)
15697 Logs a message to this logger with the specified level.
15698 Basically, the arguments are as with python’s logging
15699 module.
15700 In addition, Sphinx logger supports following keyword
15702 arguments:
15703 nonl If true, the logger does not fold lines at the end
15705 of the log message. The default is False.
15706 location
15708 Where the message emitted. For more detail, see
15709 SphinxLoggerAdapter.warning().
15710 color The color of logs. By default, info and verbose
15712 level logs are not colored, and debug level ones
15713 are colored as "darkgray".
15714 sphinx.util.logging.pending_logging()
15716 Contextmanager to pend logging all logs temporary.
15717 For example:
15719 >>> with pending_logging():
15721 >>> logger.warning('Warning message!') # not flushed yet
15722 >>> some_long_process()
15723 >>>
15724 Warning message! # the warning is flushed here
15725 sphinx.util.logging.pending_warnings()
15727 Contextmanager to pend logging warnings temporary.
15728 Similar to pending_logging().
15730 sphinx.util.logging.prefixed_warnings()
15732 Prepend prefix to all records for a while.
15733 For example:
15735 >>> with prefixed_warnings("prefix:"):
15737 >>> logger.warning('Warning message!') # => prefix: Warning message!
15738 New in version 2.0.
15740 i18n API
15743 sphinx.locale.init(locale_dirs, language, catalog='sphinx', names‐
15744 pace='general')
15745 Look for message catalogs in locale_dirs and ensure that there
15746 is at least a NullTranslations catalog set in translators. If
15747 called multiple times or if several .mo files are found, their
15748 contents are merged together (thus making init reentrant).
15749 sphinx.locale.init_console(locale_dir, catalog)
15751 Initialize locale for console.
15752 New in version 1.8.
15754 sphinx.locale.get_translation(catalog, namespace='general')
15757 Get a translation function based on the catalog and namespace.
15758 The extension can use this API to translate the messages on the
15760 extension:
15761 import os
15763 from sphinx.locale import get_translation
15764 MESSAGE_CATALOG_NAME = 'myextension' # name of *.pot, *.po and *.mo files
15766 _ = get_translation(MESSAGE_CATALOG_NAME)
15767 text = _('Hello Sphinx!')
15768 def setup(app):
15771 package_dir = path.abspath(path.dirname(__file__))
15772 locale_dir = os.path.join(package_dir, 'locales')
15773 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
15774 With this code, sphinx searches a message catalog from ${pack‐
15776 age_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The
15777 language is used for the searching.
15778 New in version 1.8.
15780 sphinx.locale._(message, *args)
15783 Translation function for messages on documentation (menu,
15784 labels, themes and so on). This function follows language set‐
15785 ting.
15786 sphinx.locale.__(message, *args)
15788 Translation function for console messages This function follows
15789 locale setting (LC_ALL, LC_MESSAGES and so on).
15790 Extension internationalization (i18n) and localization (l10n) using i18n
15792 API
15793 New in version 1.8.
15794 An extension may naturally come with message translations. This is
15797 briefly summarized in sphinx.locale.get_translation() help.
15798 In practice, you have to:
15800 1. Choose a name for your message catalog, which must be unique. Usu‐
15802 ally the name of your extension is used for the name of message cat‐
15803 alog.
15804 2. Mark in your extension sources all messages as translatable, via
15806 sphinx.locale.get_translation() function, usually renamed _(), e.g.:
15807 src/__init__.py
15809 from sphinx.locale import get_translation
15811 MESSAGE_CATALOG_NAME = 'myextension'
15813 _ = get_translation(MESSAGE_CATALOG_NAME)
15814 translated_text = _('Hello Sphinx!')
15816 1. Set up your extension to be aware of its dedicated translations:
15818 src/__init__.py
15820 def setup(app):
15822 package_dir = path.abspath(path.dirname(__file__))
15823 locale_dir = os.path.join(package_dir, 'locales')
15824 app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
15825 1. Generate message catalog template *.pot file, usually in locale/
15827 source directory, for example via Babel:
15828 $ pybabel extract --output=src/locale/myextension.pot src/
15830 2. Create message catalogs (*.po) for each language which your exten‐
15832 sion will provide localization, for example via Babel:
15833 $ pybabel init --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale --locale=fr_FR
15835 3. Translate message catalogs for each language manually
15837 4. Compile message catalogs into *.mo files, for example via Babel:
15839 $ pybabel compile --directory=src/locale --domain=myextension
15841 5. Ensure that message catalog files are distributed when your package
15843 will be installed, by adding equivalent line in your extension MANI‐
15844 FEST.in:
15845 MANIFEST.in
15847 recursive-include src *.pot *.po *.mo
15849 When the messages on your extension has been changed, you need to also
15851 update message catalog template and message catalogs, for example via
15852 Babel:
15853 $ pybabel extract --output=src/locale/myextension.pot src/
15855 $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
15856 Utilities
15858 Sphinx provides utility classes and functions to develop extensions.
15859 Base classes for components
15861 These base classes are useful to allow your extensions to obtain Sphinx
15862 components (e.g. Config, BuildEnvironment and so on) easily.
15863 NOTE:
15865 The subclasses of them might not work with bare docutils because
15866 they are strongly coupled with Sphinx.
15867 class sphinx.transforms.SphinxTransform(document, startnode=None)
15869 A base class of Transforms.
15870 Compared with docutils.transforms.Transform, this class improves
15872 accessibility to Sphinx APIs.
15873 property app
15875 Reference to the Sphinx object.
15876 property config
15878 Reference to the Config object.
15879 property env
15881 Reference to the BuildEnvironment object.
15882 class sphinx.transforms.post_transforms.SphinxPostTransform(document,
15884 startnode=None)
15885 A base class of post-transforms.
15886 Post transforms are invoked to modify the document to restruc‐
15888 ture it for outputting. They do resolving references, convert
15889 images, special transformation for each output formats and so
15890 on. This class helps to implement these post transforms.
15891 apply(**kwargs)
15893 Override to apply the transform to the document tree.
15894 is_supported()
15896 Check this transform working for current builder.
15897 run(**kwargs)
15899 main method of post transforms.
15900 Subclasses should override this method instead of
15902 apply().
15903 class sphinx.util.docutils.SphinxDirective(name, arguments, options,
15905 content, lineno, content_offset, block_text, state, state_machine)
15906 A base class for Sphinx directives.
15907 This class provides helper methods for Sphinx directives.
15909 NOTE:
15911 The subclasses of this class might not work with docutils.
15912 This class is strongly coupled with Sphinx.
15913 set_source_info(node)
15915 Set source and line number to the node.
15916 property config
15918 Reference to the Config object.
15919 property env
15921 Reference to the BuildEnvironment object.
15922 class sphinx.util.docutils.SphinxRole
15924 A base class for Sphinx roles.
15925 This class provides helper methods for Sphinx roles.
15927 NOTE:
15929 The subclasses of this class might not work with docutils.
15930 This class is strongly coupled with Sphinx.
15931 property config
15933 Reference to the Config object.
15934 content = None
15936 A list of strings, the directive content for customiza‐
15937 tion
15938 property env
15940 Reference to the BuildEnvironment object.
15941 inliner = None
15943 The docutils.parsers.rst.states.Inliner object.
15944 lineno = None
15946 The line number where the interpreted text begins.
15947 name = None
15949 The role name actually used in the document.
15950 options = None
15952 A dictionary of directive options for customization
15953 rawtext = None
15955 A string containing the entire interpreted text input.
15956 text = None
15958 The interpreted text content.
15959 class sphinx.util.docutils.ReferenceRole
15961 A base class for reference roles.
15962 The reference roles can accpet link title <target> style as a
15964 text for the role. The parsed result; link title and target
15965 will be stored to self.title and self.target.
15966 has_explicit_title = None
15968 A boolean indicates the role has explicit title or not.
15969 target = None
15971 The link target for the interpreted text.
15972 title = None
15974 The link title for the interpreted text.
15975 class sphinx.transforms.post_transforms.images.ImageConverter(*args,
15977 **kwargs)
15978 A base class for image converters.
15979 An image converter is kind of Docutils transform module. It is
15981 used to convert image files which does not supported by builder
15982 to appropriate format for that builder.
15983 For example, LaTeX builder supports PDF, PNG and JPEG as image
15985 formats. However it does not support SVG images. For such
15986 case, to use image converters allows to embed these unsupported
15987 images into the document. One of image converters;
15988 sphinx.ext.imgconverter can convert a SVG image to PNG format
15989 using Imagemagick internally.
15990 There are three steps to make your custom image converter:
15992 1. Make a subclass of ImageConverter class
15994 2. Override conversion_rules, is_available() and convert()
15996 3. Register your image converter to Sphinx using
15998 Sphinx.add_post_transform()
15999 convert(_from, _to)
16001 Convert a image file to expected format.
16002 _from is a path for source image file, and _to is a path
16004 for destination file.
16005 is_available()
16007 Return the image converter is available or not.
16008 conversion_rules = []
16010 A conversion rules the image converter supports. It is
16011 represented as a list of pair of source image format
16012 (mimetype) and destination one:
16013 conversion_rules = [
16015 ('image/svg+xml', 'image/png'),
16016 ('image/gif', 'image/png'),
16017 ('application/pdf', 'image/png'),
16018 ]
16019 Utility components
16021 class sphinx.events.EventManager(app=None)
16022 Event manager for Sphinx.
16023 add(name)
16025 Register a custom Sphinx event.
16026 connect(name, callback)
16028 Connect a handler to specific event.
16029 disconnect(listener_id)
16031 Disconnect a handler.
16032 emit(name, *args)
16034 Emit a Sphinx event.
16035 emit_firstresult(name, *args)
16037 Emit a Sphinx event and returns first result.
16038 This returns the result of the first handler that doesn’t
16040 return None.
16041 Deprecated APIs
16043 On developing Sphinx, we are always careful to the compatibility of our
16044 APIs. But, sometimes, the change of interface are needed for some rea‐
16045 sons. In such cases, we’ve marked them as deprecated. And they are
16046 kept during the two major versions (for more details, please see depre‐
16047 cation-policy).
16048 The following is a list of deprecated interfaces.
16050 deprecated APIs
16052┌─────────────────────────────────────────────────────┬────────────┬───────────┬───────────────────────────────────────┐
16053│Target │ Deprecated │ (will be) │ Alternatives │
16054│ │ │ Removed │ │
16055├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16056│sphinx.builders.latex.LaTeXBuilder.apply_trans‐ │ 2.1 │ 4.0 │ N/A │
16057│forms() │ │ │ │
16058├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16059│sphinx.builders._epub_base.EpubBuilder.esc() │ 2.1 │ 4.0 │ html.escape() │
16060├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16061│sphinx.directives.Acks │ 2.1 │ 4.0 │ sphinx.direc‐ │
16062│ │ │ │ tives.other.Acks │
16063├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16064│sphinx.directives.Author │ 2.1 │ 4.0 │ sphinx.direc‐ │
16065│ │ │ │ tives.other.Author │
16066├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16067│sphinx.directives.Centered │ 2.1 │ 4.0 │ sphinx.direc‐ │
16068│ │ │ │ tives.other.Cen‐ │
16069│ │ │ │ tered │
16070├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16071│sphinx.directives.Class │ 2.1 │ 4.0 │ sphinx.direc‐ │
16072│ │ │ │ tives.other.Class │
16073├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16074│sphinx.directives.CodeBlock │ 2.1 │ 4.0 │ sphinx.direc‐ │
16075│ │ │ │ tives.code.Code‐ │
16076│ │ │ │ Block │
16077├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16078│sphinx.directives.Figure │ 2.1 │ 4.0 │ sphinx.direc‐ │
16079│ │ │ │ tives.patches.Fig‐ │
16080│ │ │ │ ure │
16081├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16082│sphinx.directives.HList │ 2.1 │ 4.0 │ sphinx.direc‐ │
16083│ │ │ │ tives.other.HList │
16084├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16085│sphinx.directives.Highlight │ 2.1 │ 4.0 │ sphinx.direc‐ │
16086│ │ │ │ tives.code.High‐ │
16087│ │ │ │ light │
16088├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16089│sphinx.directives.Include │ 2.1 │ 4.0 │ sphinx.direc‐ │
16090│ │ │ │ tives.other.Include │
16091├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16092│sphinx.directives.Index │ 2.1 │ 4.0 │ sphinx.direc‐ │
16093│ │ │ │ tives.other.Index │
16094├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16095│sphinx.directives.LiteralInclude │ 2.1 │ 4.0 │ sphinx.direc‐ │
16096│ │ │ │ tives.code.Literal‐ │
16097│ │ │ │ Include │
16098├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16099│sphinx.directives.Meta │ 2.1 │ 4.0 │ sphinx.direc‐ │
16100│ │ │ │ tives.patches.Meta │
16101├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16102│sphinx.directives.Only │ 2.1 │ 4.0 │ sphinx.direc‐ │
16103│ │ │ │ tives.other.Only │
16104├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16105│sphinx.directives.SeeAlso │ 2.1 │ 4.0 │ sphinx.direc‐ │
16106│ │ │ │ tives.other.SeeAlso │
16107├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16108│sphinx.directives.TabularColumns │ 2.1 │ 4.0 │ sphinx.direc‐ │
16109│ │ │ │ tives.other.Tabu‐ │
16110│ │ │ │ larColumns │
16111├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16112│sphinx.directives.TocTree │ 2.1 │ 4.0 │ sphinx.direc‐ │
16113│ │ │ │ tives.other.TocTree │
16114├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16115│sphinx.directives.VersionChange │ 2.1 │ 4.0 │ sphinx.direc‐ │
16116│ │ │ │ tives.other.Ver‐ │
16117│ │ │ │ sionChange │
16118├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16119│sphinx.domains.python.PyClassmember │ 2.1 │ 4.0 │ sphinx.domains.python.PyAt‐ │
16120│ │ │ │ tribute, │
16121│ │ │ │ sphinx.domains.python.PyMethod, │
16122│ │ │ │ sphinx.domains.python.PyClass‐ │
16123│ │ │ │ Method, │
16124│ │ │ │ sphinx.domains.python.PyOb‐ │
16125│ │ │ │ ject and │
16126│ │ │ │ sphinx.domains.python.PyStat‐ │
16127│ │ │ │ icMethod │
16128└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16129│sphinx.domains.python.PyModulelevel │ 2.1 │ 4.0 │ sphinx.domains.python.PyFunc‐ │
16135│ │ │ │ tion, │
16136│ │ │ │ sphinx.domains.python.PyObject │
16137│ │ │ │ and │
16138│ │ │ │ sphinx.domains.python.PyVari‐ │
16139│ │ │ │ able │
16140├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16141│sphinx.domains.std.StandardDo‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16142│main._resolve_citation_xref() │ │ │ tionDomain.resolve_xref() │
16143├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16144│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16145│tions() │ │ │ tionDomain.note_citation() │
16146├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16147│sphinx.domains.std.StandardDomain.note_cita‐ │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16148│tion_refs() │ │ │ tionDomain.note_citation_refer‐ │
16149│ │ │ │ ence() │
16150├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16151│sphinx.domains.std.StandardDomain.note_labels() │ 2.1 │ 4.0 │ sphinx.domains.std.StandardDo‐ │
16152│ │ │ │ main.process_doc() │
16153├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16154│sphinx.environment.NoUri │ 2.1 │ 4.0 │ sphinx.errors.NoUri │
16155├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16156│sphinx.ext.apidoc.format_directive() │ 2.1 │ 4.0 │ N/A │
16157├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16158│sphinx.ext.apidoc.format_heading() │ 2.1 │ 4.0 │ N/A │
16159├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16160│sphinx.ext.apidoc.makename() │ 2.1 │ 4.0 │ sphinx.ext.apidoc.module_join() │
16161├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16162│sphinx.ext.autodoc.importer.MockFinder │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
16163│ │ │ │ Finder │
16164├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16165│sphinx.ext.autodoc.importer.MockLoader │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.Mock‐ │
16166│ │ │ │ Loader │
16167├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16168│sphinx.ext.autodoc.importer.mock() │ 2.1 │ 4.0 │ sphinx.ext.autodoc.mock.mock() │
16169├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16170│sphinx.ext.autosummary.autolink_role() │ 2.1 │ 4.0 │ sphinx.ext.autosummary.AutoLink │
16171├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16172│sphinx.ext.imgmath.DOC_BODY │ 2.1 │ 4.0 │ N/A │
16173├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16174│sphinx.ext.imgmath.DOC_BODY_PREVIEW │ 2.1 │ 4.0 │ N/A │
16175├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16176│sphinx.ext.imgmath.DOC_HEAD │ 2.1 │ 4.0 │ N/A │
16177├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16178│sphinx.transforms.CitationReferences │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16179│ │ │ │ tionReferenceTransform │
16180├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16181│sphinx.transforms.SmartQuotesSkipper │ 2.1 │ 4.0 │ sphinx.domains.citation.Cita‐ │
16182│ │ │ │ tionDefinitionTransform │
16183├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16184│sphinx.util.docfields.DocFieldTransformer.pre‐ │ 2.1 │ 4.0 │ sphinx.directives.ObjectDe‐ │
16185│process_fieldtypes() │ │ │ scription.get_field_type_map() │
16186├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16187│sphinx.util.node.find_source_node() │ 2.1 │ 4.0 │ sphinx.util.node.get_node_source() │
16188├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16189│sphinx.util.i18n.find_catalog() │ 2.1 │ 4.0 │ sphinx.util.i18n.doc‐ │
16190│ │ │ │ name_to_domain() │
16191├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16192│sphinx.util.i18n.find_catalog_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
16193├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16194│sphinx.util.i18n.find_catalog_source_files() │ 2.1 │ 4.0 │ sphinx.util.i18n.CatalogRepository │
16195├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16196│encoding argument of autodoc.Docu‐ │ 2.0 │ 4.0 │ N/A │
16197│menter.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
16198│tureMixin.get_doc(), autodoc.DocstringSigna‐ │ │ │ │
16199│tureMixin._find_signature(), and autodoc.Class‐ │ │ │ │
16200│Documenter.get_doc() │ │ │ │
16201├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16202│arguments of EpubBuilder.build_mimetype(), │ 2.0 │ 4.0 │ N/A │
16203│EpubBuilder.build_container(), Epub‐ │ │ │ │
16204│Builder.build_content(), Epub‐ │ │ │ │
16205│Builder.build_toc() and Epub‐ │ │ │ │
16206│Builder.build_epub() │ │ │ │
16207├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16208│arguments of Epub3Builder.build_naviga‐ │ 2.0 │ 4.0 │ N/A │
16209│tion_doc() │ │ │ │
16210├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16211│nodetype argument of sphinx.search.WordCollec‐ │ 2.0 │ 4.0 │ N/A │
16212│tor.is_meta_keywords() │ │ │ │
16213├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16214│suffix argument of BuildEnvironment.doc2path() │ 2.0 │ 4.0 │ N/A │
16215├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16216│string style base argument of BuildEnviron‐ │ 2.0 │ 4.0 │ os.path.join() │
16217│ment.doc2path() │ │ │ │
16218├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16219│sphinx.addnodes.abbreviation │ 2.0 │ 4.0 │ docutils.nodes.abbreviation │
16220├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16221│sphinx.builders.applehelp │ 2.0 │ 4.0 │ sphinxcontrib.applehelp │
16222├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16223│sphinx.builders.devhelp │ 2.0 │ 4.0 │ sphinxcontrib.devhelp │
16224├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16225│sphinx.builders.epub3.Epub3Builder.vali‐ │ 2.0 │ 4.0 │ sphinx.builders.epub3.vali‐ │
16226│date_config_value() │ │ │ date_config_values() │
16227├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16228│sphinx.builders.html.JSONHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16229│ │ │ │ inghtml.JSONHTMLBuilder │
16230├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16231│sphinx.builders.html.PickleHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16232│ │ │ │ inghtml.PickleHTMLBuilder │
16233├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16234│sphinx.builders.html.SerializingHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16235│ │ │ │ inghtml.SerializingHTMLBuilder │
16236├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16237│sphinx.builders.html.SingleFileHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.singlehtml.Single‐ │
16238│ │ │ │ FileHTMLBuilder │
16239├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16240│sphinx.builders.html.WebHTMLBuilder │ 2.0 │ 4.0 │ sphinx.builders.serializ‐ │
16241│ │ │ │ inghtml.PickleHTMLBuilder │
16242├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16243│sphinx.builders.htmlhelp │ 2.0 │ 4.0 │ sphinxcontrib.htmlhelp │
16244├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16245│sphinx.builders.htmlhelp.HTMLHelp‐ │ 2.0 │ 4.0 │ open() │
16246│Builder.open_file() │ │ │ │
16247├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16248│sphinx.builders.qthelp │ 2.0 │ 4.0 │ sphinxcontrib.qthelp │
16249├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16250│sphinx.cmd.quickstart.term_decode() │ 2.0 │ 4.0 │ N/A │
16251├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16252│sphinx.cmd.quickstart.TERM_ENCODING │ 2.0 │ 4.0 │ sys.stdin.encoding │
16253└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16254│sphinx.config.check_unicode() │ 2.0 │ 4.0 │ N/A │
16257├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16258│sphinx.config.string_classes │ 2.0 │ 4.0 │ [str] │
16259├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16260│sphinx.domains.cpp.DefinitionError.description │ 2.0 │ 4.0 │ str(exc) │
16261├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16262│sphinx.domains.cpp.NoOldIdError.description │ 2.0 │ 4.0 │ str(exc) │
16263├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16264│sphinx.domains.cpp.UnsupportedMultiCharacter‐ │ 2.0 │ 4.0 │ str(exc) │
16265│CharLiteral.decoded │ │ │ │
16266├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16267│sphinx.ext.autosummary.Autosummary.warn() │ 2.0 │ 4.0 │ N/A │
16268├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16269│sphinx.ext.autosummary.Autosummary.genopt │ 2.0 │ 4.0 │ N/A │
16270├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16271│sphinx.ext.autosummary.Autosummary.warnings │ 2.0 │ 4.0 │ N/A │
16272├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16273│sphinx.ext.autosummary.Autosummary.result │ 2.0 │ 4.0 │ N/A │
16274├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16275│sphinx.ext.doctest.doctest_encode() │ 2.0 │ 4.0 │ N/A │
16276├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16277│sphinx.ext.jsmath │ 2.0 │ 4.0 │ sphinxcontrib.jsmath │
16278├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16279│sphinx.roles.abbr_role() │ 2.0 │ 4.0 │ sphinx.roles.Abbreviation │
16280├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16281│sphinx.roles.emph_literal_role() │ 2.0 │ 4.0 │ sphinx.roles.EmphasizedLiteral │
16282├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16283│sphinx.roles.menusel_role() │ 2.0 │ 4.0 │ sphinx.roles.GUILabel or │
16284│ │ │ │ sphinx.roles.MenuSelection │
16285├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16286│sphinx.roles.index_role() │ 2.0 │ 4.0 │ sphinx.roles.Index │
16287├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16288│sphinx.roles.indexmarkup_role() │ 2.0 │ 4.0 │ sphinx.roles.PEP or │
16289│ │ │ │ sphinx.roles.RFC │
16290├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16291│sphinx.testing.util.remove_unicode_literal() │ 2.0 │ 4.0 │ N/A │
16292├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16293│sphinx.util.attrdict │ 2.0 │ 4.0 │ N/A │
16294├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16295│sphinx.util.force_decode() │ 2.0 │ 4.0 │ N/A │
16296├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16297│sphinx.util.get_matching_docs() │ 2.0 │ 4.0 │ sphinx.util.get_matching_files() │
16298├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16299│sphinx.util.inspect.Parameter │ 2.0 │ 3.0 │ N/A │
16300├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16301│sphinx.util.jsonimpl │ 2.0 │ 4.0 │ sphinxcontrib.serializ‐ │
16302│ │ │ │ inghtml.jsonimpl │
16303├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16304│sphinx.util.osutil.EEXIST │ 2.0 │ 4.0 │ errno.EEXIST or FileExistsError │
16305├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16306│sphinx.util.osutil.EINVAL │ 2.0 │ 4.0 │ errno.EINVAL │
16307├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16308│sphinx.util.osutil.ENOENT │ 2.0 │ 4.0 │ errno.ENOENT or FileNotFoundError │
16309├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16310│sphinx.util.osutil.EPIPE │ 2.0 │ 4.0 │ errno.ENOENT or BrokenPipeError │
16311├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16312│sphinx.util.osutil.walk() │ 2.0 │ 4.0 │ os.walk() │
16313├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16314│sphinx.util.pycompat.NoneType │ 2.0 │ 4.0 │ sphinx.util.typing.NoneType │
16315├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16316│sphinx.util.pycompat.TextIOWrapper │ 2.0 │ 4.0 │ io.TextIOWrapper │
16317├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16318│sphinx.util.pycompat.UnicodeMixin │ 2.0 │ 4.0 │ N/A │
16319├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16320│sphinx.util.pycompat.htmlescape() │ 2.0 │ 4.0 │ html.escape() │
16321├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16322│sphinx.util.pycompat.indent() │ 2.0 │ 4.0 │ textwrap.indent() │
16323├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16324│sphinx.util.pycompat.sys_encoding │ 2.0 │ 4.0 │ sys.getdefaultencoding() │
16325├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16326│sphinx.util.pycompat.terminal_safe() │ 2.0 │ 4.0 │ sphinx.util.console.termi‐ │
16327│ │ │ │ nal_safe() │
16328├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16329│sphinx.util.pycompat.u │ 2.0 │ 4.0 │ N/A │
16330├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16331│sphinx.util.PeekableIterator │ 2.0 │ 4.0 │ N/A │
16332├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16333│Omitting the filename argument in an overrid‐ │ 2.0 │ 4.0 │ IndexBuilder.feed(docname, file‐ │
16334│dent IndexBuilder.feed() method. │ │ │ name, title, doctree) │
16335├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16336│sphinx.writers.latex.ExtBabel │ 2.0 │ 4.0 │ sphinx.builders.latex.util.ExtBa‐ │
16337│ │ │ │ bel │
16338├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16339│sphinx.writers.latex.LaTeXTranslator.babel_def‐ │ 2.0 │ 4.0 │ N/A │
16340│macro() │ │ │ │
16341├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16342│sphinx.application.Sphinx._setting_up_extension │ 2.0 │ 3.0 │ N/A │
16343├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16344│The importer argument of │ 2.0 │ 3.0 │ N/A │
16345│sphinx.ext.autodoc.importer._MockModule │ │ │ │
16346├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16347│sphinx.ext.autodoc.importer._MockImporter │ 2.0 │ 3.0 │ N/A │
16348├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16349│sphinx.io.SphinxBaseFileInput │ 2.0 │ 3.0 │ N/A │
16350├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16351│sphinx.io.SphinxFileInput.supported │ 2.0 │ 3.0 │ N/A │
16352├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16353│sphinx.io.SphinxRSTFileInput │ 2.0 │ 3.0 │ N/A │
16354├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16355│sphinx.registry.SphinxComponentReg‐ │ 2.0 │ 3.0 │ N/A │
16356│istry.add_source_input() │ │ │ │
16357├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16358│sphinx.writers.latex.LaTeXTransla‐ │ 2.0 │ 3.0 │ N/A │
16359│tor._make_visit_admonition() │ │ │ │
16360├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16361│sphinx.writers.latex.LaTeXTranslator.col‐ │ 2.0 │ 4.0 │ N/A │
16362│lect_footnotes() │ │ │ │
16363├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16364│sphinx.writers.texinfo.TexinfoTransla‐ │ 2.0 │ 3.0 │ N/A │
16365│tor._make_visit_admonition() │ │ │ │
16366├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16367│sphinx.writers.text.TextTransla‐ │ 2.0 │ 3.0 │ N/A │
16368│tor._make_depart_admonition() │ │ │ │
16369├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16370│sphinx.writers.latex.LaTeXTranslator.gener‐ │ 2.0 │ 4.0 │ N/A │
16371│ate_numfig_format() │ │ │ │
16372├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16373│highlightlang │ 1.8 │ 4.0 │ highlight │
16374├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16375│add_stylesheet() │ 1.8 │ 4.0 │ add_css_file() │
16376└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16377│add_javascript() │ 1.8 │ 4.0 │ add_js_file() │
16379├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16380│autodoc_default_flags │ 1.8 │ 4.0 │ autodoc_default_options │
16381├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16382│content arguments of │ 1.8 │ 3.0 │ N/A │
16383│sphinx.util.image.guess_mimetype() │ │ │ │
16384├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16385│gettext_compact arguments of │ 1.8 │ 3.0 │ N/A │
16386│sphinx.util.i18n.find_catalog_source_files() │ │ │ │
16387├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16388│sphinx.io.SphinxI18nReader.set_lineno_for_reporter() │ 1.8 │ 3.0 │ N/A │
16389├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16390│sphinx.io.SphinxI18nReader.line │ 1.8 │ 3.0 │ N/A │
16391├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16392│sphinx.directives.other.VersionChanges │ 1.8 │ 3.0 │ sphinx.domains.changeset.Version‐ │
16393│ │ │ │ Changes │
16394├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16395│sphinx.highlighting.PygmentsBridge.unhighlight() │ 1.8 │ 3.0 │ N/A │
16396├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16397│trim_doctest_flags arguments of sphinx.highlight‐ │ 1.8 │ 3.0 │ N/A │
16398│ing.PygmentsBridge │ │ │ │
16399├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16400│sphinx.ext.mathbase │ 1.8 │ 3.0 │ N/A │
16401├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16402│sphinx.ext.mathbase.MathDomain │ 1.8 │ 3.0 │ sphinx.domains.math.MathDomain │
16403├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16404│sphinx.ext.mathbase.MathDirective │ 1.8 │ 3.0 │ sphinx.directives.patches.MathDi‐ │
16405│ │ │ │ rective │
16406├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16407│sphinx.ext.mathbase.math_role() │ 1.8 │ 3.0 │ docu‐ │
16408│ │ │ │ tils.parsers.rst.roles.math_role() │
16409├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16410│sphinx.ext.mathbase.setup_math() │ 1.8 │ 3.0 │ add_html_math_renderer() │
16411├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16412│sphinx.ext.mathbase.is_in_section_title() │ 1.8 │ 3.0 │ N/A │
16413├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16414│sphinx.ext.mathbase.get_node_equation_number() │ 1.8 │ 3.0 │ sphinx.util.math.get_node_equa‐ │
16415│ │ │ │ tion_number() │
16416├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16417│sphinx.ext.mathbase.wrap_displaymath() │ 1.8 │ 3.0 │ sphinx.util.math.wrap_display‐ │
16418│ │ │ │ math() │
16419├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16420│sphinx.ext.mathbase.math (node) │ 1.8 │ 3.0 │ docutils.nodes.math │
16421├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16422│sphinx.ext.mathbase.displaymath (node) │ 1.8 │ 3.0 │ docutils.nodes.math_block │
16423├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16424│sphinx.ext.mathbase.eqref (node) │ 1.8 │ 3.0 │ sphinx.builders.latex.nodes.math_ref‐ │
16425│ │ │ │ erence │
16426├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16427│viewcode_import (config value) │ 1.8 │ 3.0 │ viewcode_follow_imported_members │
16428├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16429│sphinx.writers.latex.Table.caption_footnotetexts │ 1.8 │ 3.0 │ N/A │
16430├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16431│sphinx.writers.latex.Table.header_footnotetexts │ 1.8 │ 3.0 │ N/A │
16432├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16433│sphinx.writers.latex.LaTeXTranslator.footnotestack │ 1.8 │ 3.0 │ N/A │
16434├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16435│sphinx.writers.latex.LaTeXTranslator.in_con‐ │ 1.8 │ 3.0 │ N/A │
16436│tainer_literal_block │ │ │ │
16437├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16438│sphinx.writers.latex.LaTeXTranslator.next_sec‐ │ 1.8 │ 3.0 │ N/A │
16439│tion_ids │ │ │ │
16440├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16441│sphinx.writers.latex.LaTeXTranslator.next_hyper‐ │ 1.8 │ 3.0 │ N/A │
16442│link_ids │ │ │ │
16443├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16444│sphinx.writers.latex.LaTeXTranslator.restrict_foot‐ │ 1.8 │ 3.0 │ N/A │
16445│note() │ │ │ │
16446├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16447│sphinx.writers.latex.LaTeXTranslator.unre‐ │ 1.8 │ 3.0 │ N/A │
16448│strict_footnote() │ │ │ │
16449├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16450│sphinx.writers.latex.LaTeXTranslator.push_hyper‐ │ 1.8 │ 3.0 │ N/A │
16451│link_ids() │ │ │ │
16452├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16453│sphinx.writers.latex.LaTeXTranslator.pop_hyper‐ │ 1.8 │ 3.0 │ N/A │
16454│link_ids() │ │ │ │
16455├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16456│sphinx.writers.latex.LaTeXTranslator.bibitems │ 1.8 │ 3.0 │ N/A │
16457├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16458│sphinx.writers.latex.LaTeXTranslator.hlsettingstack │ 1.8 │ 3.0 │ N/A │
16459├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16460│sphinx.writers.latex.ExtBabel.get_shorthandoff() │ 1.8 │ 3.0 │ N/A │
16461├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16462│sphinx.writers.html.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
16463├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16464│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16465│lang_base() │ │ │ │
16466├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16467│sphinx.writers.html.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16468│langopts() │ │ │ │
16469├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16470│sphinx.writers.html.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
16471│nenothreshold() │ │ │ │
16472├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16473│sphinx.writers.html5.HTMLTranslator.highlightlang() │ 1.8 │ 3.0 │ N/A │
16474├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16475│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16476│lang_base() │ │ │ │
16477├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16478│sphinx.writers.html5.HTMLTranslator.highlight‐ │ 1.8 │ 3.0 │ N/A │
16479│langopts() │ │ │ │
16480├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16481│sphinx.writers.html5.HTMLTranslator.highlightli‐ │ 1.8 │ 3.0 │ N/A │
16482│nenothreshold() │ │ │ │
16483├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16484│sphinx.writers.latex.LaTeXTransla‐ │ 1.8 │ 3.0 │ Nothing │
16485│tor.check_latex_elements() │ │ │ │
16486├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16487│sphinx.application.CONFIG_FILENAME │ 1.8 │ 3.0 │ sphinx.config.CONFIG_FILENAME │
16488├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16489│Config.check_unicode() │ 1.8 │ 3.0 │ sphinx.config.check_unicode() │
16490├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16491│Config.check_types() │ 1.8 │ 3.0 │ sphinx.config.check_confval_types() │
16492├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16493│dirname, filename and tags arguments of Con‐ │ 1.8 │ 3.0 │ Config.read() │
16494│fig.__init__() │ │ │ │
16495├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16496│The value of html_search_options │ 1.8 │ 3.0 │ see html_search_options │
16497└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16498│sphinx.versioning.prepare() │ 1.8 │ 3.0 │ sphinx.versioning.UIDTransform │
16501├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16502│Sphinx.override_domain() │ 1.8 │ 3.0 │ add_domain() │
16503├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16504│Sphinx.import_object() │ 1.8 │ 3.0 │ sphinx.util.import_object() │
16505├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16506│suffix argument of add_source_parser() │ 1.8 │ 3.0 │ add_source_suffix() │
16507├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16508│BuildEnvironment.load() │ 1.8 │ 3.0 │ pickle.load() │
16509├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16510│BuildEnvironment.loads() │ 1.8 │ 3.0 │ pickle.loads() │
16511├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16512│BuildEnvironment.frompickle() │ 1.8 │ 3.0 │ pickle.load() │
16513├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16514│BuildEnvironment.dump() │ 1.8 │ 3.0 │ pickle.dump() │
16515├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16516│BuildEnvironment.dumps() │ 1.8 │ 3.0 │ pickle.dumps() │
16517├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16518│BuildEnvironment.topickle() │ 1.8 │ 3.0 │ pickle.dump() │
16519├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16520│BuildEnvironment._nitpick_ignore │ 1.8 │ 3.0 │ nitpick_ignore │
16521├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16522│BuildEnvironment.versionchanges │ 1.8 │ 3.0 │ N/A │
16523├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16524│BuildEnvironment.update() │ 1.8 │ 3.0 │ Builder.read() │
16525├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16526│BuildEnvironment.read_doc() │ 1.8 │ 3.0 │ Builder.read_doc() │
16527├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16528│BuildEnvironment._read_serial() │ 1.8 │ 3.0 │ Builder.read() │
16529├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16530│BuildEnvironment._read_parallel() │ 1.8 │ 3.0 │ Builder.read() │
16531├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16532│BuildEnvironment.write_doctree() │ 1.8 │ 3.0 │ Builder.write_doctree() │
16533├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16534│BuildEnvironment.note_versionchange() │ 1.8 │ 3.0 │ ChangesDomain.note_changeset() │
16535├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16536│warn() (template helper function) │ 1.8 │ 3.0 │ warning() │
16537├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16538│source_parsers │ 1.8 │ 3.0 │ add_source_parser() │
16539├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16540│sphinx.util.docutils.directive_helper() │ 1.8 │ 3.0 │ Directive class of docutils │
16541├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16542│sphinx.cmdline │ 1.8 │ 3.0 │ sphinx.cmd.build │
16543├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16544│sphinx.make_mode │ 1.8 │ 3.0 │ sphinx.cmd.make_mode │
16545├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16546│sphinx.locale.l_() │ 1.8 │ 3.0 │ sphinx.locale._() │
16547├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16548│sphinx.locale.lazy_gettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
16549├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16550│sphinx.locale.mygettext() │ 1.8 │ 3.0 │ sphinx.locale._() │
16551├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16552│sphinx.util.copy_static_entry() │ 1.5 │ 3.0 │ sphinx.util.fileutil.copy_asset() │
16553├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16554│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
16555├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16556│sphinx.ext.intersphinx.debug() │ 1.7 │ 2.0 │ sphinx.ext.intersphinx.inspect_main() │
16557├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16558│sphinx.ext.autodoc.format_annotation() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
16559├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16560│sphinx.ext.autodoc.formatargspec() │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
16561├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16562│sphinx.ext.autodoc.AutodocReporter │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
16563│ │ │ │ tils.switch_source_input() │
16564├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16565│sphinx.ext.autodoc.add_documenter() │ 1.7 │ 2.0 │ add_autodocumenter() │
16566├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16567│sphinx.ext.autodoc.AutoDirective._register │ 1.7 │ 2.0 │ add_autodocumenter() │
16568├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16569│AutoDirective._special_attrgetters │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
16570├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16571│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
16572├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16573│BuildEnvironment.set_warnfunc() │ 1.6 │ 2.0 │ logging-api │
16574├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16575│BuildEnvironment.note_toctree() │ 1.6 │ 2.0 │ Toctree.note() (in sphinx.environ‐ │
16576│ │ │ │ ment.adapters.toctree) │
16577├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16578│BuildEnvironment.get_toc_for() │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
16579│ │ │ │ sphinx.environment.adapters.toctree) │
16580├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16581│BuildEnvironment.get_toctree_for() │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
16582│ │ │ │ sphinx.environment.adapters.toctree) │
16583├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16584│BuildEnvironment.create_index() │ 1.6 │ 2.0 │ IndexEntries.create_index() (in │
16585│ │ │ │ sphinx.environment.adapters.indexen‐ │
16586│ │ │ │ tries) │
16587├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16588│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
16589├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16590│StandaloneHTMLBuilder.css_files │ 1.6 │ 2.0 │ add_stylesheet() │
16591├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16592│document.settings.gettext_compact │ 1.8 │ 1.8 │ gettext_compact │
16593├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16594│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
16595├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16596│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_iterator() │
16597├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16598│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
16599│ │ │ │ tive_helper() │
16600├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16601│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Directive │
16602├─────────────────────────────────────────────────────┼────────────┼───────────┼───────────────────────────────────────┤
16603│sphinx.util.compat.docutils_version │ 1.6 │ 1.7 │ sphinx.util.docutils.__version_info__ │
16604└─────────────────────────────────────────────────────┴────────────┴───────────┴───────────────────────────────────────┘
16605 NOTE:
16607 On deprecating on public APIs (internal functions and classes), we
16608 also follow the policy as much as possible.
16609
16611 Refer to the following tutorials to get started with extension develop‐
16612 ment.
16613 Developing a “Hello world” extension
16615 The objective of this tutorial is to create a very basic extension that
16616 adds a new directive. This directive will output a paragraph containing
16617 “hello world”.
16618 Only basic information is provided in this tutorial. For more informa‐
16620 tion, refer to the other tutorials that go into more details.
16621 WARNING:
16623 For this extension, you will need some basic understanding of
16624 docutils and Python.
16625 Overview
16627 We want the extension to add the following to Sphinx:
16628 · A helloworld directive, that will simply output the text “hello
16630 world”.
16631 Prerequisites
16633 We will not be distributing this plugin via PyPI and will instead
16634 include it as part of an existing project. This means you will need to
16635 use an existing project or create a new one using sphinx-quickstart.
16636 We assume you are using separate source (source) and build (build)
16638 folders. Your extension file could be in any folder of your project. In
16639 our case, let’s do the following:
16640 1. Create an _ext folder in source
16642 2. Create a new Python file in the _ext folder called helloworld.py
16644 Here is an example of the folder structure you might obtain:
16646 └── source
16648 ├── _ext
16649 │ └── helloworld.py
16650 ├── _static
16651 ├── conf.py
16652 ├── somefolder
16653 ├── index.rst
16654 ├── somefile.rst
16655 └── someotherfile.rst
16656 Writing the extension
16658 Open helloworld.py and paste the following code in it:
16659 from docutils import nodes
16661 from docutils.parsers.rst import Directive
16662 class HelloWorld(Directive):
16665 def run(self):
16667 paragraph_node = nodes.paragraph(text='Hello World!')
16668 return [paragraph_node]
16669 def setup(app):
16672 app.add_directive("helloworld", HelloWorld)
16673 return {
16675 'version': '0.1',
16676 'parallel_read_safe': True,
16677 'parallel_write_safe': True,
16678 }
16679 Some essential things are happening in this example, and you will see
16682 them for all directives.
16683 The directive class
16685 Our new directive is declared in the HelloWorld class.
16687 class HelloWorld(Directive):
16689 def run(self):
16691 paragraph_node = nodes.paragraph(text='Hello World!')
16692 return [paragraph_node]
16693 This class extends the docutils’ Directive class. All extensions that
16696 create directives should extend this class.
16697 SEE ALSO:
16699 The docutils documentation on creating directives
16700 This class contains a run method. This method is a requirement and it
16702 is part of every directive. It contains the main logic of the direc‐
16703 tive and it returns a list of docutils nodes to be processed by Sphinx.
16704 These nodes are docutils’ way of representing the content of a docu‐
16705 ment. There are many types of nodes available: text, paragraph, refer‐
16706 ence, table, etc.
16707 SEE ALSO:
16709 The docutils documentation on nodes
16710 The nodes.paragraph class creates a new paragraph node. A paragraph
16712 node typically contains some text that we can set during instantiation
16713 using the text parameter.
16714 The setup function
16716 This function is a requirement. We use it to plug our new directive
16718 into Sphinx.
16719 def setup(app):
16721 app.add_directive("helloworld", HelloWorld)
16722 return {
16724 'version': '0.1',
16725 'parallel_read_safe': True,
16726 'parallel_write_safe': True,
16727 }
16728 The simplest thing you can do it call the add_directive() method, which
16731 is what we’ve done here. For this particular call, the first argument
16732 is the name of the directive itself as used in a reST file. In this
16733 case, we would use helloworld. For example:
16734 Some intro text here...
16736 .. helloworld::
16738 Some more text here...
16740 We also return the extension metadata that indicates the version of our
16742 extension, along with the fact that it is safe to use the extension for
16743 both parallel reading and writing.
16744 Using the extension
16746 The extension has to be declared in your conf.py file to make Sphinx
16747 aware of it. There are two steps necessary here:
16748 1. Add the _ext directory to the Python path using sys.path.append.
16750 This should be placed at the top of the file.
16751 2. Update or create the extensions list and add the extension file name
16753 to the list
16754 For example:
16756 import os
16758 import sys
16759 sys.path.append(os.path.abspath("./_ext"))
16761 extensions = ['helloworld']
16763 TIP:
16765 We’re not distributing this extension as a Python package, we need
16766 to modify the Python path so Sphinx can find our extension. This is
16767 why we need the call to sys.path.append.
16768 You can now use the extension in a file. For example:
16770 Some intro text here...
16772 .. helloworld::
16774 Some more text here...
16776 The sample above would generate:
16778 Some intro text here...
16780 Hello World!
16782 Some more text here...
16784 Further reading
16786 This is the very basic principle of an extension that creates a new
16787 directive.
16788 For a more advanced example, refer to todo.
16790 Developing a “TODO” extension
16792 The objective of this tutorial is to create a more comprehensive exten‐
16793 sion than that created in helloworld. Whereas that guide just covered
16794 writing a custom directive, this guide adds multiple directives, along
16795 with custom nodes, additional config values and custom event handlers.
16796 To this end, we will cover a todo extension that adds capabilities to
16797 include todo entries in the documentation, and to collect these in a
16798 central place. This is similar the sphinxext.todo extension distributed
16799 with Sphinx.
16800 Overview
16802 NOTE:
16803 To understand the design of this extension, refer to impor‐
16804 tant-objects and build-phases.
16805 We want the extension to add the following to Sphinx:
16807 · A todo directive, containing some content that is marked with “TODO”
16809 and only shown in the output if a new config value is set. Todo
16810 entries should not be in the output by default.
16811 · A todolist directive that creates a list of all todo entries through‐
16813 out the documentation.
16814 For that, we will need to add the following elements to Sphinx:
16816 · New directives, called todo and todolist.
16818 · New document tree nodes to represent these directives, conventionally
16820 also called todo and todolist. We wouldn’t need new nodes if the new
16821 directives only produced some content representable by existing
16822 nodes.
16823 · A new config value todo_include_todos (config value names should
16825 start with the extension name, in order to stay unique) that controls
16826 whether todo entries make it into the output.
16827 · New event handlers: one for the doctree-resolved event, to replace
16829 the todo and todolist nodes, and one for env-purge-doc (the reason
16830 for that will be covered later).
16831 Prerequisites
16833 As with helloworld, we will not be distributing this plugin via PyPI so
16834 once again we need a Sphinx project to call this from. You can use an
16835 existing project or create a new one using sphinx-quickstart.
16836 We assume you are using separate source (source) and build (build)
16838 folders. Your extension file could be in any folder of your project. In
16839 our case, let’s do the following:
16840 1. Create an _ext folder in source
16842 2. Create a new Python file in the _ext folder called todo.py
16844 Here is an example of the folder structure you might obtain:
16846 └── source
16848 ├── _ext
16849 │ └── todo.py
16850 ├── _static
16851 ├── conf.py
16852 ├── somefolder
16853 ├── index.rst
16854 ├── somefile.rst
16855 └── someotherfile.rst
16856 Writing the extension
16858 Open todo.py and paste the following code in it, all of which we will
16859 explain in detail shortly:
16860 from docutils import nodes
16862 from docutils.parsers.rst import Directive
16863 from sphinx.locale import _
16865 from sphinx.util.docutils import SphinxDirective
16866 class todo(nodes.Admonition, nodes.Element):
16869 pass
16870 class todolist(nodes.General, nodes.Element):
16873 pass
16874 def visit_todo_node(self, node):
16877 self.visit_admonition(node)
16878 def depart_todo_node(self, node):
16881 self.depart_admonition(node)
16882 class TodolistDirective(Directive):
16885 def run(self):
16887 return [todolist('')]
16888 class TodoDirective(SphinxDirective):
16891 # this enables content in the directive
16893 has_content = True
16894 def run(self):
16896 targetid = 'todo-%d' % self.env.new_serialno('todo')
16897 targetnode = nodes.target('', '', ids=[targetid])
16898 todo_node = todo('\n'.join(self.content))
16900 todo_node += nodes.title(_('Todo'), _('Todo'))
16901 self.state.nested_parse(self.content, self.content_offset, todo_node)
16902 if not hasattr(self.env, 'todo_all_todos'):
16904 self.env.todo_all_todos = []
16905 self.env.todo_all_todos.append({
16907 'docname': self.env.docname,
16908 'lineno': self.lineno,
16909 'todo': todo_node.deepcopy(),
16910 'target': targetnode,
16911 })
16912 return [targetnode, todo_node]
16914 def purge_todos(app, env, docname):
16917 if not hasattr(env, 'todo_all_todos'):
16918 return
16919 env.todo_all_todos = [todo for todo in env.todo_all_todos
16921 if todo['docname'] != docname]
16922 def process_todo_nodes(app, doctree, fromdocname):
16925 if not app.config.todo_include_todos:
16926 for node in doctree.traverse(todo):
16927 node.parent.remove(node)
16928 # Replace all todolist nodes with a list of the collected todos.
16930 # Augment each todo with a backlink to the original location.
16931 env = app.builder.env
16932 for node in doctree.traverse(todolist):
16934 if not app.config.todo_include_todos:
16935 node.replace_self([])
16936 continue
16937 content = []
16939 for todo_info in env.todo_all_todos:
16941 para = nodes.paragraph()
16942 filename = env.doc2path(todo_info['docname'], base=None)
16943 description = (
16944 _('(The original entry is located in %s, line %d and can be found ') %
16945 (filename, todo_info['lineno']))
16946 para += nodes.Text(description, description)
16947 # Create a reference
16949 newnode = nodes.reference('', '')
16950 innernode = nodes.emphasis(_('here'), _('here'))
16951 newnode['refdocname'] = todo_info['docname']
16952 newnode['refuri'] = app.builder.get_relative_uri(
16953 fromdocname, todo_info['docname'])
16954 newnode['refuri'] += '#' + todo_info['target']['refid']
16955 newnode.append(innernode)
16956 para += newnode
16957 para += nodes.Text('.)', '.)')
16958 # Insert into the todolist
16960 content.append(todo_info['todo'])
16961 content.append(para)
16962 node.replace_self(content)
16964 def setup(app):
16967 app.add_config_value('todo_include_todos', False, 'html')
16968 app.add_node(todolist)
16970 app.add_node(todo,
16971 html=(visit_todo_node, depart_todo_node),
16972 latex=(visit_todo_node, depart_todo_node),
16973 text=(visit_todo_node, depart_todo_node))
16974 app.add_directive('todo', TodoDirective)
16976 app.add_directive('todolist', TodolistDirective)
16977 app.connect('doctree-resolved', process_todo_nodes)
16978 app.connect('env-purge-doc', purge_todos)
16979 return {
16981 'version': '0.1',
16982 'parallel_read_safe': True,
16983 'parallel_write_safe': True,
16984 }
16985 This is far more extensive extension than the one detailed in hel‐
16988 loworld, however, we will will look at each piece step-by-step to
16989 explain what’s happening.
16990 The node classes
16992 Let’s start with the node classes:
16994 class todo(nodes.Admonition, nodes.Element):
16996 pass
16997 class todolist(nodes.General, nodes.Element):
17000 pass
17001 def visit_todo_node(self, node):
17004 self.visit_admonition(node)
17005 def depart_todo_node(self, node):
17008 self.depart_admonition(node)
17009 Node classes usually don’t have to do anything except inherit from the
17012 standard docutils classes defined in docutils.nodes. todo inherits
17013 from Admonition because it should be handled like a note or warning,
17014 todolist is just a “general” node.
17015 NOTE:
17017 Many extensions will not have to create their own node classes and
17018 work fine with the nodes already provided by docutils and Sphinx.
17019 The directive classes
17021 A directive class is a class deriving usually from docu‐
17023 tils.parsers.rst.Directive. The directive interface is also covered in
17024 detail in the docutils documentation; the important thing is that the
17025 class should have attributes that configure the allowed markup, and a
17026 run method that returns a list of nodes.
17027 Looking first at the TodolistDirective directive:
17029 class TodolistDirective(Directive):
17031 def run(self):
17033 return [todolist('')]
17034 It’s very simple, creating and returning an instance of our todolist
17037 node class. The TodolistDirective directive itself has neither content
17038 nor arguments that need to be handled. That brings us to the TodoDirec‐
17039 tive directive:
17040 class TodoDirective(SphinxDirective):
17042 # this enables content in the directive
17044 has_content = True
17045 def run(self):
17047 targetid = 'todo-%d' % self.env.new_serialno('todo')
17048 targetnode = nodes.target('', '', ids=[targetid])
17049 todo_node = todo('\n'.join(self.content))
17051 todo_node += nodes.title(_('Todo'), _('Todo'))
17052 self.state.nested_parse(self.content, self.content_offset, todo_node)
17053 if not hasattr(self.env, 'todo_all_todos'):
17055 self.env.todo_all_todos = []
17056 self.env.todo_all_todos.append({
17058 'docname': self.env.docname,
17059 'lineno': self.lineno,
17060 'todo': todo_node.deepcopy(),
17061 'target': targetnode,
17062 })
17063 return [targetnode, todo_node]
17065 Several important things are covered here. First, as you can see, we’re
17068 now subclassing the SphinxDirective helper class instead of the usual
17069 Directive class. This gives us access to the build environment instance
17070 using the self.env property. Without this, we’d have to use the rather
17071 convoluted self.state.document.settings.env. Then, to act as a link
17072 target (from TodolistDirective), the TodoDirective directive needs to
17073 return a target node in addition to the todo node. The target ID (in
17074 HTML, this will be the anchor name) is generated by using env.new_seri‐
17075 alno which returns a new unique integer on each call and therefore
17076 leads to unique target names. The target node is instantiated without
17077 any text (the first two arguments).
17078 On creating admonition node, the content body of the directive are
17080 parsed using self.state.nested_parse. The first argument gives the
17081 content body, and the second one gives content offset. The third argu‐
17082 ment gives the parent node of parsed result, in our case the todo node.
17083 Following this, the todo node is added to the environment. This is
17084 needed to be able to create a list of all todo entries throughout the
17085 documentation, in the place where the author puts a todolist directive.
17086 For this case, the environment attribute todo_all_todos is used (again,
17087 the name should be unique, so it is prefixed by the extension name).
17088 It does not exist when a new environment is created, so the directive
17089 must check and create it if necessary. Various information about the
17090 todo entry’s location are stored along with a copy of the node.
17091 In the last line, the nodes that should be put into the doctree are
17093 returned: the target node and the admonition node.
17094 The node structure that the directive returns looks like this:
17096 +--------------------+
17098 | target node |
17099 +--------------------+
17100 +--------------------+
17101 | todo node |
17102 +--------------------+
17103 \__+--------------------+
17104 | admonition title |
17105 +--------------------+
17106 | paragraph |
17107 +--------------------+
17108 | ... |
17109 +--------------------+
17110 The event handlers
17112 Event handlers are one of Sphinx’s most powerful features, providing a
17114 way to do hook into any part of the documentation process. There are
17115 many events provided by Sphinx itself, as detailed in the API guide,
17116 and we’re going to use a subset of them here.
17117 Let’s look at the event handlers used in the above example. First, the
17119 one for the env-purge-doc event:
17120 def purge_todos(app, env, docname):
17122 if not hasattr(env, 'todo_all_todos'):
17123 return
17124 env.todo_all_todos = [todo for todo in env.todo_all_todos
17126 if todo['docname'] != docname]
17127 Since we store information from source files in the environment, which
17130 is persistent, it may become out of date when the source file changes.
17131 Therefore, before each source file is read, the environment’s records
17132 of it are cleared, and the env-purge-doc event gives extensions a
17133 chance to do the same. Here we clear out all todos whose docname
17134 matches the given one from the todo_all_todos list. If there are todos
17135 left in the document, they will be added again during parsing.
17136 The other handler belongs to the doctree-resolved event:
17138 def process_todo_nodes(app, doctree, fromdocname):
17140 if not app.config.todo_include_todos:
17141 for node in doctree.traverse(todo):
17142 node.parent.remove(node)
17143 # Replace all todolist nodes with a list of the collected todos.
17145 # Augment each todo with a backlink to the original location.
17146 env = app.builder.env
17147 for node in doctree.traverse(todolist):
17149 if not app.config.todo_include_todos:
17150 node.replace_self([])
17151 continue
17152 content = []
17154 for todo_info in env.todo_all_todos:
17156 para = nodes.paragraph()
17157 filename = env.doc2path(todo_info['docname'], base=None)
17158 description = (
17159 _('(The original entry is located in %s, line %d and can be found ') %
17160 (filename, todo_info['lineno']))
17161 para += nodes.Text(description, description)
17162 # Create a reference
17164 newnode = nodes.reference('', '')
17165 innernode = nodes.emphasis(_('here'), _('here'))
17166 newnode['refdocname'] = todo_info['docname']
17167 newnode['refuri'] = app.builder.get_relative_uri(
17168 fromdocname, todo_info['docname'])
17169 newnode['refuri'] += '#' + todo_info['target']['refid']
17170 newnode.append(innernode)
17171 para += newnode
17172 para += nodes.Text('.)', '.)')
17173 # Insert into the todolist
17175 content.append(todo_info['todo'])
17176 content.append(para)
17177 node.replace_self(content)
17179 The doctree-resolved event is emitted at the end of phase 3 (resolving)
17182 and allows custom resolving to be done. The handler we have written for
17183 this event is a bit more involved. If the todo_include_todos config
17184 value (which we’ll describe shortly) is false, all todo and todolist
17185 nodes are removed from the documents. If not, todo nodes just stay
17186 where and how they are. todolist nodes are replaced by a list of todo
17187 entries, complete with backlinks to the location where they come from.
17188 The list items are composed of the nodes from the todo entry and docu‐
17189 tils nodes created on the fly: a paragraph for each entry, containing
17190 text that gives the location, and a link (reference node containing an
17191 italic node) with the backreference. The reference URI is built by
17192 sphinx.builders.Builder.get_relative_uri`() which creates a suitable
17193 URI depending on the used builder, and appending the todo node’s (the
17194 target’s) ID as the anchor name.
17195 The setup function
17197 As noted previously, the setup function is a requirement and is used to
17199 plug directives into Sphinx. However, we also use it to hook up the
17200 other parts of our extension. Let’s look at our setup function:
17201 def setup(app):
17203 app.add_config_value('todo_include_todos', False, 'html')
17204 app.add_node(todolist)
17206 app.add_node(todo,
17207 html=(visit_todo_node, depart_todo_node),
17208 latex=(visit_todo_node, depart_todo_node),
17209 text=(visit_todo_node, depart_todo_node))
17210 app.add_directive('todo', TodoDirective)
17212 app.add_directive('todolist', TodolistDirective)
17213 app.connect('doctree-resolved', process_todo_nodes)
17214 app.connect('env-purge-doc', purge_todos)
17215 return {
17217 'version': '0.1',
17218 'parallel_read_safe': True,
17219 'parallel_write_safe': True,
17220 }
17221 The calls in this function refer to the classes and functions we added
17224 earlier. What the individual calls do is the following:
17225 · add_config_value() lets Sphinx know that it should recognize the new
17227 config value todo_include_todos, whose default value should be False
17228 (this also tells Sphinx that it is a boolean value).
17229 If the third argument was 'html', HTML documents would be full
17231 rebuild if the config value changed its value. This is needed for
17232 config values that influence reading (build phase 1 (reading)).
17233 · add_node() adds a new node class to the build system. It also can
17235 specify visitor functions for each supported output format. These
17236 visitor functions are needed when the new nodes stay until phase 4
17237 (writing). Since the todolist node is always replaced in phase 3
17238 (resolving), it doesn’t need any.
17239 · add_directive() adds a new directive, given by name and class.
17241 · Finally, connect() adds an event handler to the event whose name is
17243 given by the first argument. The event handler function is called
17244 with several arguments which are documented with the event.
17245 With this, our extension is complete.
17247 Using the extension
17249 As before, we need to enable the extension by declaring it in our
17250 conf.py file. There are two steps necessary here:
17251 1. Add the _ext directory to the Python path using sys.path.append.
17253 This should be placed at the top of the file.
17254 2. Update or create the extensions list and add the extension file name
17256 to the list
17257 In addition, we may wish to set the todo_include_todos config value. As
17259 noted above, this defaults to False but we can set it explicitly.
17260 For example:
17262 import os
17264 import sys
17265 sys.path.append(os.path.abspath("./_ext"))
17267 extensions = ['todo']
17269 todo_include_todos = False
17271 You can now use the extension throughout your project. For example:
17273 index.rst
17275 Hello, world
17277 ============
17278 .. toctree::
17280 somefile.rst
17281 someotherfile.rst
17282 Hello world. Below is the list of TODOs.
17284 .. todolist::
17286 somefile.rst
17288 foo
17290 ===
17291 Some intro text here...
17293 .. todo:: Fix this
17295 someotherfile.rst
17297 bar
17299 ===
17300 Some more text here...
17302 .. todo:: Fix that
17304 Because we have configured todo_include_todos to False, we won’t actu‐
17306 ally see anything rendered for the todo and todolist directives. How‐
17307 ever, if we toggle this to true, we will see the output described pre‐
17308 viously.
17309 Further reading
17311 For more information, refer to the docutils documentation and
17312 /extdev/index.
17313 Developing a “recipe” extension
17315 The objective of this tutorial is to illustrate roles, directives and
17316 domains. Once complete, we will be able to use this extension to
17317 describe a recipe and reference that recipe from elsewhere in our docu‐
17318 mentation.
17319 NOTE:
17321 This tutorial is based on a guide first published on opensource.com
17322 and is provided here with the original author’s permission.
17323 Overview
17325 We want the extension to add the following to Sphinx:
17326 · A recipe directive, containing some content describing the recipe
17328 steps, along with a :contains: option highlighting the main ingredi‐
17329 ents of the recipe.
17330 · A ref role, which provides a cross-reference to the recipe itself.
17332 · A recipe domain, which allows us to tie together the above role and
17334 domain, along with things like indices.
17335 For that, we will need to add the following elements to Sphinx:
17337 · A new directive called recipe
17339 · New indexes to allow us to reference ingredient and recipes
17341 · A new domain called recipe, which will contain the recipe directive
17343 and ref role
17344 Prerequisites
17346 We need the same setup as in the previous extensions. This time, we
17347 will be putting out extension in a file called recipe.py.
17348 Here is an example of the folder structure you might obtain:
17350 └── source
17352 ├── _ext
17353 │ └── recipe.py
17354 ├── conf.py
17355 └── index.rst
17356 Writing the extension
17358 Open recipe.py and paste the following code in it, all of which we will
17359 explain in detail shortly:
17360 from collections import defaultdict
17362 from docutils.parsers.rst import directives
17364 from sphinx import addnodes
17366 from sphinx.directives import ObjectDescription
17367 from sphinx.domains import Domain
17368 from sphinx.domains import Index
17369 from sphinx.roles import XRefRole
17370 from sphinx.util.nodes import make_refnode
17371 class RecipeDirective(ObjectDescription):
17374 """A custom directive that describes a recipe."""
17375 has_content = True
17377 required_arguments = 1
17378 option_spec = {
17379 'contains': directives.unchanged_required,
17380 }
17381 def handle_signature(self, sig, signode):
17383 signode += addnodes.desc_name(text=sig)
17384 return sig
17385 def add_target_and_index(self, name_cls, sig, signode):
17387 signode['ids'].append('recipe' + '-' + sig)
17388 if 'noindex' not in self.options:
17389 ingredients = [
17390 x.strip() for x in self.options.get('contains').split(',')]
17391 recipes = self.env.get_domain('recipe')
17393 recipes.add_recipe(sig, ingredients)
17394 class IngredientIndex(Index):
17397 """A custom index that creates an ingredient matrix."""
17398 name = 'ingredient'
17400 localname = 'Ingredient Index'
17401 shortname = 'Ingredient'
17402 def generate(self, docnames=None):
17404 content = defaultdict(list)
17405 recipes = {name: (dispname, typ, docname, anchor)
17407 for name, dispname, typ, docname, anchor, _
17408 in self.domain.get_objects()}
17409 recipe_ingredients = self.domain.data['recipe_ingredients']
17410 ingredient_recipes = defaultdict(list)
17411 # flip from recipe_ingredients to ingredient_recipes
17413 for recipe_name, ingredients in recipe_ingredients.items():
17414 for ingredient in ingredients:
17415 ingredient_recipes[ingredient].append(recipe_name)
17416 # convert the mapping of ingredient to recipes to produce the expected
17418 # output, shown below, using the ingredient name as a key to group
17419 #
17420 # name, subtype, docname, anchor, extra, qualifier, description
17421 for ingredient, recipe_names in ingredient_recipes.items():
17422 for recipe_name in recipe_names:
17423 dispname, typ, docname, anchor = recipes[recipe_name]
17424 content[ingredient].append(
17425 (dispname, 0, docname, anchor, docname, '', typ))
17426 # convert the dict to the sorted list of tuples expected
17428 content = sorted(content.items())
17429 return content, True
17431 class RecipeIndex(Index):
17434 """A custom index that creates an recipe matrix."""
17435 name = 'recipe'
17437 localname = 'Recipe Index'
17438 shortname = 'Recipe'
17439 def generate(self, docnames=None):
17441 content = defaultdict(list)
17442 # sort the list of recipes in alphabetical order
17444 recipes = self.domain.get_objects()
17445 recipes = sorted(recipes, key=lambda recipe: recipe[0])
17446 # generate the expected output, shown below, from the above using the
17448 # first letter of the recipe as a key to group thing
17449 #
17450 # name, subtype, docname, anchor, extra, qualifier, description
17451 for name, dispname, typ, docname, anchor, _ in recipes:
17452 content[dispname[0].lower()].append(
17453 (dispname, 0, docname, anchor, docname, '', typ))
17454 # convert the dict to the sorted list of tuples expected
17456 content = sorted(content.items())
17457 return content, True
17459 class RecipeDomain(Domain):
17462 name = 'recipe'
17464 label = 'Recipe Sample'
17465 roles = {
17466 'ref': XRefRole()
17467 }
17468 directives = {
17469 'recipe': RecipeDirective,
17470 }
17471 indices = {
17472 RecipeIndex,
17473 IngredientIndex
17474 }
17475 initial_data = {
17476 'recipes': [], # object list
17477 'recipe_ingredients': {}, # name -> object
17478 }
17479 def get_full_qualified_name(self, node):
17481 return '{}.{}'.format('recipe', node.arguments[0])
17482 def get_objects(self):
17484 for obj in self.data['recipes']:
17485 yield(obj)
17486 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
17488 contnode):
17489 match = [(docname, anchor)
17490 for name, sig, typ, docname, anchor, prio
17491 in self.get_objects() if sig == target]
17492 if len(match) > 0:
17494 todocname = match[0][0]
17495 targ = match[0][1]
17496 return make_refnode(builder, fromdocname, todocname, targ,
17498 contnode, targ)
17499 else:
17500 print('Awww, found nothing')
17501 return None
17502 def add_recipe(self, signature, ingredients):
17504 """Add a new recipe to the domain."""
17505 name = '{}.{}'.format('recipe', signature)
17506 anchor = 'recipe-{}'.format(signature)
17507 self.data['recipe_ingredients'][name] = ingredients
17509 # name, dispname, type, docname, anchor, priority
17510 self.data['recipes'].append(
17511 (name, signature, 'Recipe', self.env.docname, anchor, 0))
17512 def setup(app):
17515 app.add_domain(RecipeDomain)
17516 return {
17518 'version': '0.1',
17519 'parallel_read_safe': True,
17520 'parallel_write_safe': True,
17521 }
17522 Let’s look at each piece of this extension step-by-step to explain
17525 what’s going on.
17526 The directive class
17528 The first thing to examine is the RecipeDirective directive:
17530 required_arguments = 1
17532 option_spec = {
17533 'contains': directives.unchanged_required,
17534 }
17535 def handle_signature(self, sig, signode):
17537 signode += addnodes.desc_name(text=sig)
17538 return sig
17539 def add_target_and_index(self, name_cls, sig, signode):
17541 signode['ids'].append('recipe' + '-' + sig)
17542 if 'noindex' not in self.options:
17543 ingredients = [
17544 x.strip() for x in self.options.get('contains').split(',')]
17545 recipes = self.env.get_domain('recipe')
17547 recipes.add_recipe(sig, ingredients)
17548 class IngredientIndex(Index):
17551 """A custom index that creates an ingredient matrix."""
17552 Unlike helloworld and todo, this directive doesn’t derive from docu‐
17555 tils.parsers.rst.Directive and doesn’t define a run method. Instead,
17556 it derives from sphinx.directives.ObjectDescription and defines han‐
17557 dle_signature and add_target_and_index methods. This is because Object‐
17558 Description is a special-purpose directive that’s intended for describ‐
17559 ing things like classes, functions, or, in our case, recipes. More
17560 specifically, handle_signature implements parsing the signature of the
17561 directive and passes on the object’s name and type to its superclass,
17562 while add_taget_and_index adds a target (to link to) and an entry to
17563 the index for this node.
17564 We also see that this directive defines has_content, required_arguments
17566 and option_spec. Unlike the TodoDirective directive added in the previ‐
17567 ous tutorial, this directive takes a single argument, the recipe name,
17568 and an option, contains, in addition to the nested reStructuredText in
17569 the body.
17570 The index classes
17572 Todo
17574 Add brief overview of indices
17575 localname = 'Ingredient Index'
17577 shortname = 'Ingredient'
17578 def generate(self, docnames=None):
17580 content = defaultdict(list)
17581 recipes = {name: (dispname, typ, docname, anchor)
17583 for name, dispname, typ, docname, anchor, _
17584 in self.domain.get_objects()}
17585 recipe_ingredients = self.domain.data['recipe_ingredients']
17586 ingredient_recipes = defaultdict(list)
17587 # flip from recipe_ingredients to ingredient_recipes
17589 for recipe_name, ingredients in recipe_ingredients.items():
17590 for ingredient in ingredients:
17591 ingredient_recipes[ingredient].append(recipe_name)
17592 # convert the mapping of ingredient to recipes to produce the expected
17594 # output, shown below, using the ingredient name as a key to group
17595 #
17596 # name, subtype, docname, anchor, extra, qualifier, description
17597 for ingredient, recipe_names in ingredient_recipes.items():
17598 for recipe_name in recipe_names:
17599 dispname, typ, docname, anchor = recipes[recipe_name]
17600 content[ingredient].append(
17601 (dispname, 0, docname, anchor, docname, '', typ))
17602 # convert the dict to the sorted list of tuples expected
17604 content = sorted(content.items())
17605 return content, True
17607 class RecipeIndex(Index):
17610 """A custom index that creates an recipe matrix."""
17611 name = 'recipe'
17613 localname = 'Recipe Index'
17614 shortname = 'Recipe'
17615 def generate(self, docnames=None):
17617 content = defaultdict(list)
17618 # sort the list of recipes in alphabetical order
17620 recipes = self.domain.get_objects()
17621 recipes = sorted(recipes, key=lambda recipe: recipe[0])
17622 # generate the expected output, shown below, from the above using the
17624 # first letter of the recipe as a key to group thing
17625 #
17626 # name, subtype, docname, anchor, extra, qualifier, description
17627 for name, dispname, typ, docname, anchor, _ in recipes:
17628 content[dispname[0].lower()].append(
17629 (dispname, 0, docname, anchor, docname, '', typ))
17630 # convert the dict to the sorted list of tuples expected
17632 content = sorted(content.items())
17633 return content, True
17635 class RecipeDomain(Domain):
17638 Both IngredientIndex and RecipeIndex are derived from Index. They
17642 implement custom logic to generate a tuple of values that define the
17643 index. Note that RecipeIndex is a simple index that has only one entry.
17644 Extending it to cover more object types is not yet part of the code.
17645 Both indices use the method Index.generate() to do their work. This
17647 method combines the information from our domain, sorts it, and returns
17648 it in a list structure that will be accepted by Sphinx. This might look
17649 complicated but all it really is is a list of tuples like ('tomato',
17650 'TomatoSoup', 'test', 'rec-TomatoSoup',...). Refer to the domain API
17651 guide for more information on this API.
17652 The domain
17654 A Sphinx domain is a specialized container that ties together roles,
17656 directives, and indices, among other things. Let’s look at the domain
17657 we’re creating here.
17658 roles = {
17660 'ref': XRefRole()
17661 }
17662 directives = {
17663 'recipe': RecipeDirective,
17664 }
17665 indices = {
17666 RecipeIndex,
17667 IngredientIndex
17668 }
17669 initial_data = {
17670 'recipes': [], # object list
17671 'recipe_ingredients': {}, # name -> object
17672 }
17673 def get_full_qualified_name(self, node):
17675 return '{}.{}'.format('recipe', node.arguments[0])
17676 def get_objects(self):
17678 for obj in self.data['recipes']:
17679 yield(obj)
17680 def resolve_xref(self, env, fromdocname, builder, typ, target, node,
17682 contnode):
17683 match = [(docname, anchor)
17684 for name, sig, typ, docname, anchor, prio
17685 in self.get_objects() if sig == target]
17686 if len(match) > 0:
17688 todocname = match[0][0]
17689 targ = match[0][1]
17690 return make_refnode(builder, fromdocname, todocname, targ,
17692 contnode, targ)
17693 else:
17694 print('Awww, found nothing')
17695 return None
17696 def add_recipe(self, signature, ingredients):
17698 """Add a new recipe to the domain."""
17699 name = '{}.{}'.format('recipe', signature)
17700 anchor = 'recipe-{}'.format(signature)
17701 self.data['recipe_ingredients'][name] = ingredients
17703 # name, dispname, type, docname, anchor, priority
17704 self.data['recipes'].append(
17705 (name, signature, 'Recipe', self.env.docname, anchor, 0))
17706 def setup(app):
17709 app.add_domain(RecipeDomain)
17710 There are some interesting things to note about this recipe domain and
17713 domains in general. Firstly, we actually register our directives, roles
17714 and indices here, via the directives, roles and indices attributes,
17715 rather than via calls later on in setup. We can also note that we
17716 aren’t actually defining a custom role and are instead reusing the
17717 sphinx.roles.XRefRole role and defining the
17718 sphinx.domains.Domain.resolve_xref method. This method takes two argu‐
17719 ments, typ and target, which refer to the cross-reference type and its
17720 target name. We’ll use target to resolve our destination from our
17721 domain’s recipes because we currently have only one type of node.
17722 Moving on, we can see that we’ve defined initial_data. The values
17724 defined in initial_data will be copied to env.domaindata[domain_name]
17725 as the initial data of the domain, and domain instances can access it
17726 via self.data. We see that we have defined two items in initial_data:
17727 recipes and recipe2ingredient. These contain a list of all objects
17728 defined (i.e. all recipes) and a hash that maps a canonical ingredient
17729 name to the list of objects. The way we name objects is common across
17730 our extension and is defined in the get_full_qualified_name method. For
17731 each object created, the canonical name is recipe.<recipename>, where
17732 <recipename> is the name the documentation writer gives the object (a
17733 recipe). This enables the extension to use different object types that
17734 share the same name. Having a canonical name and central place for our
17735 objects is a huge advantage. Both our indices and our cross-referencing
17736 code use this feature.
17737 The setup function
17739 As always, the setup function is a requirement and is used to hook the
17741 various parts of our extension into Sphinx. Let’s look at the setup
17742 function for this extension.
17743 'version': '0.1',
17745 'parallel_read_safe': True,
17746 'parallel_write_safe': True,
17747 }
17748 This looks a little different to what we’re used to seeing. There are
17751 no calls to add_directive() or even add_role(). Instead, we have a sin‐
17752 gle call to add_domain() followed by some initialization of the stan‐
17753 dard domain. This is because we had already registered our directives,
17754 roles and indexes as part of the directive itself.
17755 Using the extension
17757 You can now use the extension throughout your project. For example:
17758 index.rst
17760 Joe's Recipes
17762 =============
17763 Below are a collection of my favourite recipes. I highly recommend the
17765 :recipe:ref:`TomatoSoup` recipe in particular!
17766 .. toctree::
17768 tomato-soup
17770 tomato-soup.rst
17772 The recipe contains `tomato` and `cilantro`.
17774 .. recipe:recipe:: TomatoSoup
17776 :contains: tomato cilantro salt pepper
17777 This recipe is a tasty tomato soup, combine all ingredients
17779 and cook.
17780 The important things to note are the use of the :recipe:ref: role to
17782 cross-reference the recipe actually defined elsewhere (using the
17783 :recipe:recipe: directive.
17784 Further reading
17786 For more information, refer to the docutils documentation and
17787 /extdev/index.
17788
17790 This is a list of Frequently Asked Questions about Sphinx. Feel free
17791 to suggest new entries!
17792 How do I…
17794 … create PDF files without LaTeX?
17795 rinohtype provides a PDF builder that can be used as a drop-in
17796 replacement for the LaTeX builder.
17797 … get section numbers?
17799 They are automatic in LaTeX output; for HTML, give a :numbered:
17800 option to the toctree directive where you want to start number‐
17801 ing.
17802 … customize the look of the built HTML files?
17804 Use themes, see /usage/theming.
17805 … add global substitutions or includes?
17807 Add them in the rst_prolog or rst_epilog config value.
17808 … display the whole TOC tree in the sidebar?
17810 Use the toctree callable in a custom layout template, probably
17811 in the sidebartoc block.
17812 … write my own extension?
17814 See the /development/tutorials/index.
17815 … convert from my existing docs using MoinMoin markup?
17817 The easiest way is to convert to xhtml, then convert xhtml to
17818 reST. You’ll still need to mark up classes and such, but the
17819 headings and code examples come through cleanly.
17820 For many more extensions and other contributed stuff, see the
17822 sphinx-contrib repository.
17823 Using Sphinx with…
17825 Read the Docs
17826 https://readthedocs.org is a documentation hosting service based
17827 around Sphinx. They will host sphinx documentation, along with
17828 supporting a number of other features including version support,
17829 PDF generation, and more. The Getting Started guide is a good
17830 place to start.
17831 Epydoc There’s a third-party extension providing an api role which
17833 refers to Epydoc’s API docs for a given identifier.
17834 Doxygen
17836 Michael Jones is developing a reST/Sphinx bridge to doxygen
17837 called breathe.
17838 SCons Glenn Hutchings has written a SCons build script to build Sphinx
17840 documentation; it is hosted here:
17841 https://bitbucket.org/zondo/sphinx-scons
17842 PyPI Jannis Leidel wrote a setuptools command that automatically
17844 uploads Sphinx documentation to the PyPI package documentation
17845 area at https://pythonhosted.org/.
17846 GitHub Pages
17848 Directories starting with underscores are ignored by default
17849 which breaks static files in Sphinx. GitHub’s preprocessor can
17850 be disabled to support Sphinx HTML output properly.
17851 MediaWiki
17853 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
17854 project by Kevin Dunn.
17855 Google Analytics
17857 You can use a custom layout.html template, like this:
17858 {% extends "!layout.html" %}
17860 {%- block extrahead %}
17862 {{ super() }}
17863 <script type="text/javascript">
17864 var _gaq = _gaq || [];
17865 _gaq.push(['_setAccount', 'XXX account number XXX']);
17866 _gaq.push(['_trackPageview']);
17867 </script>
17868 {% endblock %}
17869 {% block footer %}
17871 {{ super() }}
17872 <div class="footer">This page uses <a href="https://analytics.google.com/">
17873 Google Analytics</a> to collect statistics. You can disable it by blocking
17874 the JavaScript coming from www.google-analytics.com.
17875 <script type="text/javascript">
17876 (function() {
17877 var ga = document.createElement('script');
17878 ga.src = ('https:' == document.location.protocol ?
17879 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
17880 ga.setAttribute('async', 'true');
17881 document.documentElement.firstChild.appendChild(ga);
17882 })();
17883 </script>
17884 </div>
17885 {% endblock %}
17886 Google Search
17888 To replace Sphinx’s built-in search function with Google Search,
17889 proceed as follows:
17890 1. Go to https://cse.google.com/cse/all to create the Google
17892 Search code snippet.
17893 2. Copy the code snippet and paste it into _templates/search‐
17895 box.html in your Sphinx project:
17896 <div>
17898 <h3>{{ _('Quick search') }}</h3>
17899 <script>
17900 (function() {
17901 var cx = '......';
17902 var gcse = document.createElement('script');
17903 gcse.type = 'text/javascript';
17904 gcse.async = true;
17905 gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
17906 var s = document.getElementsByTagName('script')[0];
17907 s.parentNode.insertBefore(gcse, s);
17908 })();
17909 </script>
17910 <gcse:search></gcse:search>
17911 </div>
17912 3. Add searchbox.html to the html_sidebars configuration value.
17914 Epub info
17916 The following list gives some hints for the creation of epub files:
17917 · Split the text into several files. The longer the individual HTML
17919 files are, the longer it takes the ebook reader to render them. In
17920 extreme cases, the rendering can take up to one minute.
17921 · Try to minimize the markup. This also pays in rendering time.
17923 · For some readers you can use embedded or external fonts using the CSS
17925 @font-face directive. This is extremely useful for code listings
17926 which are often cut at the right margin. The default Courier font
17927 (or variant) is quite wide and you can only display up to 60 charac‐
17928 ters on a line. If you replace it with a narrower font, you can get
17929 more characters on a line. You may even use FontForge and create
17930 narrow variants of some free font. In my case I get up to 70 charac‐
17931 ters on a line.
17932 You may have to experiment a little until you get reasonable results.
17934 · Test the created epubs. You can use several alternatives. The ones I
17936 am aware of are Epubcheck, Calibre, FBreader (although it does not
17937 render the CSS), and Bookworm. For Bookworm, you can download the
17938 source from https://code.google.com/archive/p/threepress and run your
17939 own local server.
17940 · Large floating divs are not displayed properly. If they cover more
17942 than one page, the div is only shown on the first page. In that case
17943 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
17944 tory to your local _static/ directory and remove the float settings.
17945 · Files that are inserted outside of the toctree directive must be man‐
17947 ually included. This sometimes applies to appendixes, e.g. the glos‐
17948 sary or the indices. You can add them with the epub_post_files
17949 option.
17950 · The handling of the epub cover page differs from the reStructuredText
17952 procedure which automatically resolves image paths and puts the
17953 images into the _images directory. For the epub cover page put the
17954 image in the html_static_path directory and reference it with its
17955 full path in the epub_cover config option.
17956 · kindlegen command can convert from epub3 resulting file to .mobi file
17958 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
17959 lowing command:
17960 $ make epub
17962 $ kindlegen _build/epub/yourdoc.epub
17963 The kindlegen command doesn’t accept documents that have section
17965 titles surrounding toctree directive:
17966 Section Title
17968 =============
17969 .. toctree::
17971 subdocument
17973 Section After Toc Tree
17975 ======================
17976 kindlegen assumes all documents order in line, but the resulting doc‐
17978 ument has complicated order for kindlegen:
17979 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
17981 If you get the following error, fix your document structure:
17983 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
17985 Error(prcgen):E24001: The table of content could not be built.
17986 Texinfo info
17988 There are two main programs for reading Info files, info and GNU Emacs.
17989 The info program has less features but is available in most Unix envi‐
17990 ronments and can be quickly accessed from the terminal. Emacs provides
17991 better font and color display and supports extensive customization (of
17992 course).
17993 Displaying Links
17995 One noticeable problem you may encounter with the generated Info files
17996 is how references are displayed. If you read the source of an Info
17997 file, a reference to this section would look like:
17998 * note Displaying Links: target-id
18000 In the stand-alone reader, info, references are displayed just as they
18002 appear in the source. Emacs, on the other-hand, will by default
18003 replace *note: with see and hide the target-id. For example:
18004 Displaying Links
18005 The exact behavior of how Emacs displays references is dependent on the
18007 variable Info-hide-note-references. If set to the value of hide, Emacs
18008 will hide both the *note: part and the target-id. This is generally
18009 the best way to view Sphinx-based documents since they often make fre‐
18010 quent use of links and do not take this limitation into account. How‐
18011 ever, changing this variable affects how all Info documents are dis‐
18012 played and most do take this behavior into account.
18013 If you want Emacs to display Info files produced by Sphinx using the
18015 value hide for Info-hide-note-references and the default value for all
18016 other Info files, try adding the following Emacs Lisp code to your
18017 start-up file, ~/.emacs.d/init.el.
18018 (defadvice info-insert-file-contents (after
18020 sphinx-info-insert-file-contents
18021 activate)
18022 "Hack to make `Info-hide-note-references' buffer-local and
18023 automatically set to `hide' iff it can be determined that this file
18024 was created from a Texinfo file generated by Docutils or Sphinx."
18025 (set (make-local-variable 'Info-hide-note-references)
18026 (default-value 'Info-hide-note-references))
18027 (save-excursion
18028 (save-restriction
18029 (widen) (goto-char (point-min))
18030 (when (re-search-forward
18031 "^Generated by \\(Sphinx\\|Docutils\\)"
18032 (save-excursion (search-forward "\x1f" nil t)) t)
18033 (set (make-local-variable 'Info-hide-note-references)
18034 'hide)))))
18035 Notes
18037 The following notes may be helpful if you want to create Texinfo files:
18038 · Each section corresponds to a different node in the Info file.
18040 · Colons (:) cannot be properly escaped in menu entries and xrefs.
18042 They will be replaced with semicolons (;).
18043 · Links to external Info files can be created using the somewhat offi‐
18045 cial URI scheme info. For example:
18046 info:Texinfo#makeinfo_options
18048 · Inline markup
18050 The standard formatting for *strong* and _emphasis_ can result in
18052 ambiguous output when used to markup parameter names and other val‐
18053 ues. Since this is a fairly common practice, the default formatting
18054 has been changed so that emphasis and strong are now displayed like
18055 `literal's.
18056 The standard formatting can be re-enabled by adding the following to
18058 your conf.py:
18059 texinfo_elements = {'preamble': """
18061 @definfoenclose strong,*,*
18062 @definfoenclose emph,_,_
18063 """}
18064
18066 builder
18067 A class (inheriting from Builder) that takes parsed documents
18068 and performs an action on them. Normally, builders translate
18069 the documents to an output format, but it is also possible to
18070 use the builder builders that e.g. check for broken links in the
18071 documentation, or build coverage information.
18072 See /usage/builders/index for an overview over Sphinx’s built-in
18074 builders.
18075 configuration directory
18077 The directory containing conf.py. By default, this is the same
18078 as the source directory, but can be set differently with the -c
18079 command-line option.
18080 directive
18082 A reStructuredText markup element that allows marking a block of
18083 content with special meaning. Directives are supplied not only
18084 by docutils, but Sphinx and custom extensions can add their own.
18085 The basic directive syntax looks like this:
18086 .. directivename:: argument ...
18088 :option: value
18089 Content of the directive.
18091 See rst-directives for more information.
18093 document name
18095 Since reST source files can have different extensions (some peo‐
18096 ple like .txt, some like .rst – the extension can be configured
18097 with source_suffix) and different OSes have different path sepa‐
18098 rators, Sphinx abstracts them: document names are always rela‐
18099 tive to the source directory, the extension is stripped, and
18100 path separators are converted to slashes. All values, parame‐
18101 ters and such referring to “documents” expect such document
18102 names.
18103 Examples for document names are index, library/zipfile, or ref‐
18105 erence/datamodel/types. Note that there is no leading or trail‐
18106 ing slash.
18107 domain A domain is a collection of markup (reStructuredText directives
18109 and roles) to describe and link to objects belonging together,
18110 e.g. elements of a programming language. Directive and role
18111 names in a domain have names like domain:name, e.g. py:function.
18112 Having domains means that there are no naming problems when one
18114 set of documentation wants to refer to e.g. C++ and Python
18115 classes. It also means that extensions that support the docu‐
18116 mentation of whole new languages are much easier to write.
18117 For more information, refer to /usage/restructuredtext/domains.
18119 environment
18121 A structure where information about all documents under the root
18122 is saved, and used for cross-referencing. The environment is
18123 pickled after the parsing stage, so that successive runs only
18124 need to read and parse new and changed documents.
18125 extension
18127 A custom role, directive or other aspect of Sphinx that allows
18128 users to modify any aspect of the build process within Sphinx.
18129 For more information, refer to /usage/extensions/index.
18131 master document
18133 The document that contains the root toctree directive.
18134 object The basic building block of Sphinx documentation. Every “object
18136 directive” (e.g. function or object) creates such a block; and
18137 most objects can be cross-referenced to.
18138 RemoveInSphinxXXXWarning
18140 The feature which is warned will be removed in Sphinx-XXX ver‐
18141 sion. It usually caused from Sphinx extensions which is using
18142 deprecated. See also when-deprecation-warnings-are-displayed.
18143 role A reStructuredText markup element that allows marking a piece of
18145 text. Like directives, roles are extensible. The basic syntax
18146 looks like this: :rolename:`content`. See rst-inline-markup for
18147 details.
18148 source directory
18150 The directory which, including its subdirectories, contains all
18151 source files for one Sphinx project.
18152 reStructuredText
18154 An easy-to-read, what-you-see-is-what-you-get plaintext markup
18155 syntax and parser system.
18156
18158 Abstract
18159 This document describes the development process of Sphinx, a documenta‐
18160 tion system used by developers to document systems used by other devel‐
18161 opers to develop other systems that may also be documented using
18162 Sphinx.
18163 · Bug Reports and Feature Requests
18165 · Contributing to Sphinx
18167 · Getting Started
18169 · Core Developers
18171 · Locale updates
18173 · Coding Guide
18175 · Debugging Tips
18177 · Branch Model
18179 · Deprecating a feature
18181 · Deprecation policy
18183 · Unit Testing
18185 The Sphinx source code is managed using Git and is hosted on GitHub.
18187 git clone git://github.com/sphinx-doc/sphinx
18188 Community
18190 sphinx-users <sphinx-users@googlegroups.com>
18192 Mailing list for user support.
18193 sphinx-dev <sphinx-dev@googlegroups.com>
18195 Mailing list for development related discussions.
18196 #sphinx-doc on irc.freenode.net
18198 IRC channel for development questions and user support.
18199 Bug Reports and Feature Requests
18201 If you have encountered a problem with Sphinx or have an idea for a new
18202 feature, please submit it to the issue tracker on GitHub or discuss it
18203 on the sphinx-dev mailing list.
18204 For bug reports, please include the output produced during the build
18206 process and also the log file Sphinx creates after it encounters an
18207 unhandled exception. The location of this file should be shown towards
18208 the end of the error message.
18209 Including or providing a link to the source files involved may help us
18211 fix the issue. If possible, try to create a minimal project that pro‐
18212 duces the error and post that instead.
18213 Contributing to Sphinx
18215 The recommended way for new contributors to submit code to Sphinx is to
18216 fork the repository on GitHub and then submit a pull request after com‐
18217 mitting the changes. The pull request will then need to be approved by
18218 one of the core developers before it is merged into the main reposi‐
18219 tory.
18220 1. Check for open issues or open a fresh issue to start a discussion
18222 around a feature idea or a bug.
18223 2. If you feel uncomfortable or uncertain about an issue or your
18225 changes, feel free to email the sphinx-dev mailing list.
18226 3. Fork the repository on GitHub to start making your changes to the
18228 master branch for next MAJOR version, or X.Y branch for next MINOR
18229 version (see Branch Model).
18230 4. Write a test which shows that the bug was fixed or that the feature
18232 works as expected.
18233 5. Send a pull request and bug the maintainer until it gets merged and
18235 published. Make sure to add yourself to AUTHORS and the change to
18236 CHANGES.
18237 Getting Started
18239 These are the basic steps needed to start developing on Sphinx.
18240 1. Create an account on GitHub.
18242 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
18244 GitHub interface.
18245 3. Clone the forked repository to your machine.
18247 git clone https://github.com/USERNAME/sphinx
18249 cd sphinx
18250 4. Checkout the appropriate branch.
18252 Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/
18254 ).
18255 For changes that preserves backwards-compatibility of API and fea‐
18257 tures, they should be included in the next MINOR release, use the
18258 X.Y branch.
18259 git checkout X.Y
18261 For incompatible or other substantial changes that should wait
18263 until the next MAJOR release, use the master branch.
18264 For urgent release, a new PATCH branch must be branched from the
18266 newest release tag (see Branch Model for detail).
18267 5. Setup a virtual environment.
18269 This is not necessary for unit testing, thanks to tox, but it is
18271 necessary if you wish to run sphinx-build locally or run unit tests
18272 without the help of tox.
18273 virtualenv ~/.venv
18275 . ~/.venv/bin/activate
18276 pip install -e .
18277 6. Create a new working branch. Choose any name you like.
18279 git checkout -b feature-xyz
18281 7. Hack, hack, hack.
18283 For tips on working with the code, see the Coding Guide.
18285 8. Test, test, test.
18287 Testing is best done through tox, which provides a number of tar‐
18289 gets and allows testing against multiple different Python environ‐
18290 ments:
18291 · To list all possible targets:
18293 tox -av
18295 · To run unit tests for a specific Python version, such as 3.6:
18297 tox -e py36
18299 · To run unit tests for a specific Python version and turn on dep‐
18301 recation warnings on so they’re shown in the test output:
18302 PYTHONWARNINGS=all tox -e py36
18304 · To run code style and type checks:
18306 tox -e mypy
18308 tox -e flake8
18309 · Arguments to pytest can be passed via tox, e.g. in order to run a
18311 particular test:
18312 tox -e py36 tests/test_module.py::test_new_feature
18314 · To build the documentation:
18316 tox -e docs
18318 · To build the documentation in multiple formats:
18320 tox -e docs -- -b html,latexpdf
18322 · To run JavaScript tests with Karma, execute the following com‐
18324 mands (requires Node.js):
18325 npm install
18327 npm run test
18328 You can also test by installing dependencies in your local environ‐
18330 ment.
18331 pip install .[test]
18333 New unit tests should be included in the tests directory where nec‐
18335 essary:
18336 · For bug fixes, first add a test that fails without your changes
18338 and passes after they are applied.
18339 · Tests that need a sphinx-build run should be integrated in one of
18341 the existing test modules if possible. New tests that to
18342 @with_app and then build_all for a few assertions are not good
18343 since the test suite should not take more than a minute to run.
18344 9. Please add a bullet point to CHANGES if the fix or feature is not
18346 trivial (small doc updates, typo fixes). Then commit:
18347 git commit -m '#42: Add useful new feature that does this.'
18349 GitHub recognizes certain phrases that can be used to automatically
18351 update the issue tracker.
18352 For example:
18354 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
18356 would close issue #42.
18358 10. Push changes in the branch to your forked repository on GitHub.
18360 git push origin feature-xyz
18362 11. Submit a pull request from your branch to the respective branch
18364 (master or X.Y).
18365 12. Wait for a core developer to review your changes.
18367 Core Developers
18369 The core developers of Sphinx have write access to the main repository.
18370 They can commit changes, accept/reject pull requests, and manage items
18371 on the issue tracker.
18372 You do not need to be a core developer or have write access to be
18374 involved in the development of Sphinx. You can submit patches or cre‐
18375 ate pull requests from forked repositories and have a core developer
18376 add the changes for you.
18377 The following are some general guidelines for core developers:
18379 · Questionable or extensive changes should be submitted as a pull
18381 request instead of being committed directly to the main repository.
18382 The pull request should be reviewed by another core developer before
18383 it is merged.
18384 · Trivial changes can be committed directly but be sure to keep the
18386 repository in a good working state and that all tests pass before
18387 pushing your changes.
18388 · When committing code written by someone else, please attribute the
18390 original author in the commit message and any relevant CHANGES entry.
18391 Locale updates
18393 The parts of messages in Sphinx that go into builds are translated into
18394 several locales. The translations are kept as gettext .po files trans‐
18395 lated from the master template sphinx/locale/sphinx.pot.
18396 Sphinx uses Babel to extract messages and maintain the catalog files.
18398 It is integrated in setup.py:
18399 · Use python setup.py extract_messages to update the .pot template.
18401 · Use python setup.py update_catalog to update all existing language
18403 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
18404 the template file.
18405 · Use python setup.py compile_catalog to compile the .po files to
18407 binary .mo files and .js files.
18408 When an updated .po file is submitted, run compile_catalog to commit
18410 both the source and the compiled catalogs.
18411 When a new locale is submitted, add a new directory with the ISO 639-1
18413 language identifier and put sphinx.po in there. Don’t forget to update
18414 the possible values for language in doc/usage/configuration.rst.
18415 The Sphinx core messages can also be translated on Transifex. There
18417 exists a client tool named tx in the Python package “transifex_client”,
18418 which can be used to pull translations in .po format from Transifex.
18419 To do this, go to sphinx/locale and then run tx pull -f -l LANG where
18420 LANG is an existing language identifier. It is good practice to run
18421 python setup.py update_catalog afterwards to make sure the .po file has
18422 the canonical Babel formatting.
18423 Coding Guide
18425 · Try to use the same code style as used in the rest of the project.
18426 See the Pocoo Styleguide for more information.
18427 · For non-trivial changes, please update the CHANGES file. If your
18429 changes alter existing behavior, please document this.
18430 · New features should be documented. Include examples and use cases
18432 where appropriate. If possible, include a sample that is displayed
18433 in the generated output.
18434 · When adding a new configuration variable, be sure to document it and
18436 update sphinx/cmd/quickstart.py if it’s important enough.
18437 · Add appropriate unit tests.
18439 Debugging Tips
18441 · Delete the build cache before building documents if you make changes
18442 in the code by running the command make clean or using the
18443 sphinx-build -E option.
18444 · Use the sphinx-build -P option to run pdb on exceptions.
18446 · Use node.pformat() and node.asdom().toxml() to generate a printable
18448 representation of the document structure.
18449 · Set the configuration variable keep_warnings to True so warnings will
18451 be displayed in the generated output.
18452 · Set the configuration variable nitpicky to True so that Sphinx will
18454 complain about references without a known target.
18455 · Set the debugging options in the Docutils configuration file.
18457 · JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
18459 are generated by this modified snowballcode generator. Generated JSX
18460 files are in this repository. You can get the resulting JavaScript
18461 files using the following command:
18462 npm install
18464 node_modules/.bin/grunt build # -> dest/*.global.js
18465 Branch Model
18467 Sphinx project uses following branches for developing that conforms to
18468 Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
18469 master Development for MAJOR version. All changes including incompati‐
18471 ble behaviors and public API updates are allowed.
18472 X.Y Where X.Y is the MAJOR.MINOR release. Used to maintain current
18474 MINOR release. All changes are allowed if the change preserves
18475 backwards-compatibility of API and features.
18476 Only the most recent MAJOR.MINOR branch is currently retained.
18478 When a new MAJOR version is released, the old MAJOR.MINOR branch
18479 will be deleted and replaced by an equivalent tag.
18480 X.Y.Z Where X.Y.Z is the MAJOR.MINOR.PATCH release. Only back‐
18482 wards-compatible bug fixes are allowed. In Sphinx project, PATCH
18483 version is used for urgent bug fix.
18484 MAJOR.MINOR.PATCH branch will be branched from the v prefixed
18486 release tag (ex. make 2.3.1 that branched from v2.3.0) when a
18487 urgent release is needed. When new PATCH version is released,
18488 the branch will be deleted and replaced by an equivalent tag
18489 (ex. v2.3.1).
18490 Deprecating a feature
18492 There are a couple reasons that code in Sphinx might be deprecated:
18493 · If a feature has been improved or modified in a backwards-incompati‐
18495 ble way, the old feature or behavior will be deprecated.
18496 · Sometimes Sphinx will include a backport of a Python library that’s
18498 not included in a version of Python that Sphinx currently supports.
18499 When Sphinx no longer needs to support the older version of Python
18500 that doesn’t include the library, the library will be deprecated in
18501 Sphinx.
18502 As the Deprecation policy describes, the first release of Sphinx that
18504 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
18505 (where XX is the Sphinx version where the feature will be removed) when
18506 the deprecated feature is invoked. Assuming we have good test coverage,
18507 these warnings are converted to errors when running the test suite with
18508 warnings enabled:
18509 pytest -Wall
18511 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
18513 silence any warnings generated when running the tests.
18514 Deprecation policy
18516 MAJOR and MINOR releases may deprecate certain features from previous
18517 releases. If a feature is deprecated in a release A.x, it will continue
18518 to work in all A.x.x versions (for all versions of x). It will continue
18519 to work in all B.x.x versions but raise deprecation warnings. Depre‐
18520 cated features will be removed at the C.0.0. It means the deprecated
18521 feature will work during 2 MAJOR releases at least.
18522 So, for example, if we decided to start the deprecation of a function
18524 in Sphinx 2.x:
18525 · Sphinx 2.x will contain a backwards-compatible replica of the func‐
18527 tion which will raise a RemovedInSphinx40Warning.
18528 · Sphinx 3.x will still contain the backwards-compatible replica.
18530 · Sphinx 4.0 will remove the feature outright.
18532 The warnings are displayed by default. You can turn off display of
18534 these warnings with:
18535 · PYTHONWARNINGS= make html (Linux/Mac)
18537 · export PYTHONWARNINGS= and do make html (Linux/Mac)
18539 · set PYTHONWARNINGS= and do make html (Windows)
18541 Unit Testing
18543 Sphinx has been tested with pytest runner. Sphinx developers write unit
18544 tests using pytest notation. Utility functions and pytest fixtures for
18545 testing are provided in sphinx.testing. If you are a developer of
18546 Sphinx extensions, you can write unit tests with using pytest. At this
18547 time, sphinx.testing will help your test implementation.
18548 How to use pytest fixtures that are provided by sphinx.testing? You
18550 can require 'sphinx.testing.fixtures' in your test modules or con‐
18551 ftest.py files like this:
18552 pytest_plugins = 'sphinx.testing.fixtures'
18554 If you want to know more detailed usage, please refer to tests/con‐
18556 ftest.py and other test_*.py files under tests directory.
18557 NOTE:
18559 Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
18560 New in version 1.6: sphinx.testing as a experimental.
18562 New in version 1.8: Sphinx also runs JavaScript tests.
18565
18568 Release 2.1.2 (released Jun 19, 2019)
18569 Bugs fixed
18570 · #6497: custom lexers fails highlighting when syntax error
18571 · #6478, #6488: info field lists are incorrectly recognized
18573 Release 2.1.1 (released Jun 10, 2019)
18575 Incompatible changes
18576 · #6447: autodoc: Stop to generate document for undocumented module
18577 variables
18578 Bugs fixed
18580 · #6442: LaTeX: admonitions of note type can get separated from immedi‐
18581 ately preceding section title by pagebreak
18582 · #6448: autodoc: crashed when autodocumenting classes with __slots__ =
18584 None
18585 · #6451: autodoc: generates docs for “optional import”ed modules as
18587 variables
18588 · #6452: autosummary: crashed when generating document of properties
18590 · #6455: napoleon: docstrings for properties are not processed
18592 · #6436: napoleon: “Unknown target name” error if variable name ends
18594 with underscore
18595 · #6440: apidoc: missing blank lines between modules
18597 Release 2.1.0 (released Jun 02, 2019)
18599 Incompatible changes
18600 · Ignore filenames without file extension given to Builder.build_spe‐
18601 cific() API directly
18602 · #6230: The anchor of term in glossary directive is changed if it is
18604 consisted by non-ASCII characters
18605 · #4550: html: Centering tables by default using CSS
18607 · #6239: latex: xelatex and xeCJK are used for Chinese documents by
18609 default
18610 · Sphinx.add_lexer() now takes a Lexer class instead of instance. An
18612 instance of lexers are still supported until Sphinx-3.x.
18613 Deprecated
18615 · sphinx.builders.latex.LaTeXBuilder.apply_transforms()
18616 · sphinx.builders._epub_base.EpubBuilder.esc()
18618 · sphinx.directives.Acks
18620 · sphinx.directives.Author
18622 · sphinx.directives.Centered
18624 · sphinx.directives.Class
18626 · sphinx.directives.CodeBlock
18628 · sphinx.directives.Figure
18630 · sphinx.directives.HList
18632 · sphinx.directives.Highlight
18634 · sphinx.directives.Include
18636 · sphinx.directives.Index
18638 · sphinx.directives.LiteralInclude
18640 · sphinx.directives.Meta
18642 · sphinx.directives.Only
18644 · sphinx.directives.SeeAlso
18646 · sphinx.directives.TabularColumns
18648 · sphinx.directives.TocTree
18650 · sphinx.directives.VersionChange
18652 · sphinx.domains.python.PyClassmember
18654 · sphinx.domains.python.PyModulelevel
18656 · sphinx.domains.std.StandardDomain._resolve_citation_xref()
18658 · sphinx.domains.std.StandardDomain.note_citations()
18660 · sphinx.domains.std.StandardDomain.note_citation_refs()
18662 · sphinx.domains.std.StandardDomain.note_labels()
18664 · sphinx.environment.NoUri
18666 · sphinx.ext.apidoc.format_directive()
18668 · sphinx.ext.apidoc.format_heading()
18670 · sphinx.ext.apidoc.makename()
18672 · sphinx.ext.autodoc.importer.MockFinder
18674 · sphinx.ext.autodoc.importer.MockLoader
18676 · sphinx.ext.autodoc.importer.mock()
18678 · sphinx.ext.autosummary.autolink_role()
18680 · sphinx.ext.imgmath.DOC_BODY
18682 · sphinx.ext.imgmath.DOC_BODY_PREVIEW
18684 · sphinx.ext.imgmath.DOC_HEAD
18686 · sphinx.transforms.CitationReferences
18688 · sphinx.transforms.SmartQuotesSkipper
18690 · sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()
18692 · sphinx.util.node.find_source_node()
18694 · sphinx.util.i18n.find_catalog()
18696 · sphinx.util.i18n.find_catalog_files()
18698 · sphinx.util.i18n.find_catalog_source_files()
18700 For more details, see deprecation APIs list.
18702 Features added
18704 · Add a helper class sphinx.transforms.post_transforms.SphinxPostTrans‐
18705 form
18706 · Add helper methods
18708 · PythonDomain.note_module()
18710 · PythonDomain.note_object()
18712 · SphinxDirective.set_source_info()
18714 · #6180: Support --keep-going with BuildDoc setup command
18716 · math directive now supports :class: option
18718 · todo: todo directive now supports :name: option
18720 · Enable override via environment of SPHINXOPTS and SPHINXBUILD Make‐
18722 file variables (refs: #6232, #6303)
18723 · #6287: autodoc: Unable to document bound instance methods exported as
18725 module functions
18726 · #6289: autodoc: autodoc_default_options now supports imported-members
18728 option
18729 · #4777: autodoc: Support coroutine
18731 · #744: autodoc: Support abstractmethod
18733 · #6325: autodoc: Support attributes in __slots__. For dict-style
18735 __slots__, autodoc considers values as a docstring of the attribute
18736 · #6361: autodoc: Add autodoc_typehints to suppress typehints from sig‐
18738 nature
18739 · #1063: autodoc: automodule directive now handles undocumented module
18741 level variables
18742 · #6212 autosummary: Add autosummary_imported_members to display
18744 imported members on autosummary
18745 · #6271: make clean is catastrophically broken if building into ‘.’
18747 · #6363: Support %O% environment variable in make.bat
18749 · #4777: py domain: Add :async: option to py:function directive
18751 · py domain: Add new options to py:method directive
18753 · :abstractmethod:
18755 · :async:
18757 · :classmethod:
18759 · :property:
18761 · :staticmethod:
18763 · rst domain: Add directive:option directive to describe the option for
18765 directive
18766 · #6306: html: Add a label to search form for accessability purposes
18768 · #4390: html: Consistent and semantic CSS for signatures
18770 · #6358: The rawsource property of production nodes now contains the
18772 full production rule
18773 · #6373: autosectionlabel: Allow suppression of warnings
18775 · coverage: Support a new coverage_ignore_pyobjects option
18777 · #6239: latex: Support to build Chinese documents
18779 Bugs fixed
18781 · #6230: Inappropriate node_id has been generated by glossary directive
18782 if term is consisted by non-ASCII characters
18783 · #6213: ifconfig: contents after headings are not shown
18785 · commented term in glossary directive is wrongly recognized
18787 · #6299: rst domain: rst:directive directive generates waste space
18789 · #6379: py domain: Module index (py-modindex.html) has duplicate
18791 titles
18792 · #6331: man: invalid output when doctest follows rubric
18794 · #6351: “Hyperlink target is not referenced” message is shown even if
18796 referenced
18797 · #6165: autodoc: tab_width setting of docutils has been ignored
18799 · #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5
18801 · #6311: autosummary: autosummary table gets confused by complex type
18803 hints
18804 · #6350: autosummary: confused by an argument having some kind of
18806 default value
18807 · Generated Makefiles lack a final EOL (refs: #6232)
18809 · #6375: extlinks: Cannot escape angle brackets in link caption
18811 · #6378: linkcheck: Send commonly used User-Agent
18813 · #6387: html search: failed to search document with haiku and scrolls
18815 themes
18816 · #6408: html search: Fix the ranking of search results
18818 · #6406: Wrong year is returned for SOURCE_DATE_EPOCH
18820 · #6402: image directive crashes by unknown image format
18822 · #6286: C++, allow 8 and 9 in hexadecimal integer literals.
18824 · #6305: Fix the string in quickstart for ‘path’ argument of parser
18826 · LaTeX: Figures in admonitions produced errors (refs: #6364)
18828 Release 2.0.1 (released Apr 08, 2019)
18830 Bugs fixed
18831 · LaTeX: some system labels are not translated
18832 · RemovedInSphinx30Warning is marked as pending
18834 · deprecation warnings are not emitted
18836 · sphinx.application.CONFIG_FILENAME
18838 · sphinx.builders.htmlhelp
18840 · viewcode_import
18842 · #6208: C++, properly parse full xrefs that happen to have a short
18844 xref as prefix
18845 · #6220, #6225: napoleon: AttributeError is raised for raised section
18847 having references
18848 · #6245: circular import error on importing SerializingHTMLBuilder
18850 · #6243: LaTeX: ‘releasename’ setting for latex_elements is ignored
18852 · #6244: html: Search function is broken with 3rd party themes
18854 · #6263: html: HTML5Translator crashed with invalid field node
18856 · #6262: html theme: The style of field lists has changed in bizstyle
18858 theme
18859 Release 2.0.0 (released Mar 29, 2019)
18861 Dependencies
18862 2.0.0b1
18863 · LaTeX builder now depends on TeX Live 2015 or above.
18865 · LaTeX builder (with 'pdflatex' latex_engine) will process Unicode
18867 Greek letters in text (not in math mark-up) via the text font and
18868 will not escape them to math mark-up. See the discussion of the
18869 'fontenc' key of latex_elements; such (optional) support for Greek
18870 adds, for example on Ubuntu xenial, the texlive-lang-greek and (if
18871 default font set-up is not modified) cm-super(-minimal) as additional
18872 Sphinx LaTeX requirements.
18873 · LaTeX builder with latex_engine set to 'xelatex' or to 'lualatex'
18875 requires (by default) the FreeFont fonts, which in Ubuntu xenial are
18876 provided by package fonts-freefont-otf, and e.g. in Fedora 29 via
18877 package texlive-gnu-freefont.
18878 · requests 2.5.0 or above
18880 · The six package is no longer a dependency
18882 · The sphinxcontrib-websupport package is no longer a dependency
18884 · Some packages are separated to sub packages:
18886 · sphinxcontrib.applehelp
18888 · sphinxcontrib.devhelp
18890 · sphinxcontrib.htmlhelp
18892 · sphinxcontrib.jsmath
18894 · sphinxcontrib.serializinghtml
18896 · sphinxcontrib.qthelp
18898 Incompatible changes
18900 2.0.0b1
18901 · Drop python 2.7 and 3.4 support
18903 · Drop docutils 0.11 support
18905 · Drop features and APIs deprecated in 1.7.x
18907 · The default setting for master_doc is changed to 'index' which has
18909 been longly used as default of sphinx-quickstart.
18910 · LaTeX: Move message resources to sphinxmessage.sty
18912 · LaTeX: Stop using \captions<lang> macro for some labels
18914 · LaTeX: for 'xelatex' and 'lualatex', use the FreeFont OpenType fonts
18916 as default choice (refs: #5645)
18917 · LaTeX: 'xelatex' and 'lualatex' now use \small in code-blocks (due to
18919 FreeMono character width) like 'pdflatex' already did (due to Courier
18920 character width). You may need to adjust this via latex_elements
18921 'fvset' key, in case of usage of some other OpenType fonts (refs:
18922 #5768)
18923 · LaTeX: Greek letters in text are not escaped to math mode mark-up,
18925 and they will use the text font not the math font. The LGR font
18926 encoding must be added to the 'fontenc' key of latex_elements for
18927 this to work (only if it is needed by the document, of course).
18928 · LaTeX: setting the language to 'en' triggered Sonny option of fncy‐
18930 chap, now it is Bjarne to match case of no language specified.
18931 (refs: #5772)
18932 · #5770: doctest: Follow highlight_language on highlighting doctest
18934 block. As a result, they are highlighted as python3 by default.
18935 · The order of argument for HTMLTranslator, HTML5Translator and Manual‐
18937 PageTranslator are changed
18938 · LaTeX: hard-coded redefinitions of \l@section and \l@subsection for‐
18940 merly done during loading of 'manual' docclass get executed later, at
18941 time of \sphinxtableofcontents. This means that custom user defini‐
18942 tions from LaTeX preamble now get overwritten. Use \sphinxtableof‐
18943 contentshook to insert custom user definitions. See latex-macros.
18944 · quickstart: Simplify generated conf.py
18946 · #4148: quickstart: some questions are removed. They are still able
18948 to specify via command line options
18949 · websupport: unbundled from sphinx core. Please use sphinxcontrib-web‐
18951 support
18952 · C++, the visibility of base classes is now always rendered as present
18954 in the input. That is, private is now shown, where it was ellided
18955 before.
18956 · LaTeX: graphics inclusion of oversized images rescales to not exceed
18958 the text width and height, even if width and/or height option were
18959 used. (refs: #5956)
18960 · epub: epub_title defaults to the project option
18962 · #4550: All tables and figures without align option are displayed to
18964 center
18965 · #4587: html: Output HTML5 by default
18967 2.0.0b2
18969 · texinfo: image files are copied into name-figure directory
18971 Deprecated
18973 2.0.0b1
18974 · Support for evaluating Python 2 syntax is deprecated. This includes
18976 configuration files which should be converted to Python 3.
18977 · The arguments of EpubBuilder.build_mimetype(), EpubBuilder.build_con‐
18979 tainer(), EpubBuilder.bulid_content(), EpubBuilder.build_toc() and
18980 EpubBuilder.build_epub()
18981 · The arguments of Epub3Builder.build_navigation_doc()
18983 · The config variables
18985 · html_experimental_html5_writer
18987 · The encoding argument of autodoc.Documenter.get_doc(), autodoc.Doc‐
18989 stringSignatureMixin.get_doc(), autodoc.DocstringSigna‐
18990 tureMixin._find_signature(), and autodoc.ClassDocumenter.get_doc()
18991 are deprecated.
18992 · The importer argument of sphinx.ext.autodoc.importer._MockModule
18994 · The nodetype argument of sphinx.search.WordCollector. is_meta_key‐
18996 words()
18997 · The suffix argument of env.doc2path() is deprecated.
18999 · The string style base argument of env.doc2path() is deprecated.
19001 · The fallback to allow omitting the filename argument from an overrid‐
19003 den IndexBuilder.feed() method is deprecated.
19004 · sphinx.addnodes.abbreviation
19006 · sphinx.application.Sphinx._setting_up_extension
19008 · sphinx.builders.epub3.Epub3Builder.validate_config_value()
19010 · sphinx.builders.html.SingleFileHTMLBuilder
19012 · sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()
19014 · sphinx.cmd.quickstart.term_decode()
19016 · sphinx.cmd.quickstart.TERM_ENCODING
19018 · sphinx.config.check_unicode()
19020 · sphinx.config.string_classes
19022 · sphinx.domains.cpp.DefinitionError.description
19024 · sphinx.domains.cpp.NoOldIdError.description
19026 · sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded
19028 · sphinx.ext.autodoc.importer._MockImporter
19030 · sphinx.ext.autosummary.Autosummary.warn()
19032 · sphinx.ext.autosummary.Autosummary.genopt
19034 · sphinx.ext.autosummary.Autosummary.warnings
19036 · sphinx.ext.autosummary.Autosummary.result
19038 · sphinx.ext.doctest.doctest_encode()
19040 · sphinx.io.SphinxBaseFileInput
19042 · sphinx.io.SphinxFileInput.supported
19044 · sphinx.io.SphinxRSTFileInput
19046 · sphinx.registry.SphinxComponentRegistry.add_source_input()
19048 · sphinx.roles.abbr_role()
19050 · sphinx.roles.emph_literal_role()
19052 · sphinx.roles.menusel_role()
19054 · sphinx.roles.index_role()
19056 · sphinx.roles.indexmarkup_role()
19058 · sphinx.testing.util.remove_unicode_literal()
19060 · sphinx.util.attrdict
19062 · sphinx.util.force_decode()
19064 · sphinx.util.get_matching_docs()
19066 · sphinx.util.inspect.Parameter
19068 · sphinx.util.jsonimpl
19070 · sphinx.util.osutil.EEXIST
19072 · sphinx.util.osutil.EINVAL
19074 · sphinx.util.osutil.ENOENT
19076 · sphinx.util.osutil.EPIPE
19078 · sphinx.util.osutil.walk()
19080 · sphinx.util.PeekableIterator
19082 · sphinx.util.pycompat.NoneType
19084 · sphinx.util.pycompat.TextIOWrapper
19086 · sphinx.util.pycompat.UnicodeMixin
19088 · sphinx.util.pycompat.htmlescape
19090 · sphinx.util.pycompat.indent
19092 · sphinx.util.pycompat.sys_encoding
19094 · sphinx.util.pycompat.terminal_safe()
19096 · sphinx.util.pycompat.u
19098 · sphinx.writers.latex.ExtBabel
19100 · sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()
19102 · sphinx.writers.latex.LaTeXTranslator.babel_defmacro()
19104 · sphinx.writers.latex.LaTeXTranslator.collect_footnotes()
19106 · sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()
19108 · sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()
19110 · sphinx.writers.text.TextTranslator._make_depart_admonition()
19112 · template variables for LaTeX template
19114 · logo
19116 · numfig_format
19118 · pageautorefname
19120 · translatablestrings
19122 For more details, see deprecation APIs list.
19124 Features added
19126 2.0.0b1
19127 · #1618: The search results preview of generated HTML documentation is
19129 reader-friendlier: instead of showing the snippets as raw reStruc‐
19130 turedText markup, Sphinx now renders the corresponding HTML. This
19131 means the Sphinx extension Sphinx: pretty search results is no longer
19132 necessary. Note that changes to the search function of your custom
19133 or 3rd-party HTML template might overwrite this improvement.
19134 · #4182: autodoc: Support suppress_warnings
19136 · #5533: autodoc: autodoc_default_options supports member-order
19138 · #5394: autodoc: Display readable names in type annotations for mocked
19140 objects
19141 · #5459: autodoc: autodoc_default_options accepts True as a value
19143 · #1148: autodoc: Add autodecorator directive for decorators
19145 · #5635: autosummary: Add autosummary_mock_imports to mock external
19147 libraries on importing targets
19148 · #4018: htmlhelp: Add htmlhelp_file_suffix and htmlhelp_link_suffix
19150 · #5559: text: Support complex tables (colspan and rowspan)
19152 · LaTeX: support rendering (not in math, yet) of Greek and Cyrillic
19154 Unicode letters in non-Cyrillic document even with 'pdflatex' as
19155 latex_engine (refs: #5645)
19156 · #5660: The versionadded, versionchanged and deprecated directives are
19158 now generated with their own specific CSS classes (added, changed and
19159 deprecated, respectively) in addition to the generic versionmodified
19160 class.
19161 · #5841: apidoc: Add –extensions option to sphinx-apidoc
19163 · #4981: C++, added an alias directive for inserting lists of declara‐
19165 tions, that references existing declarations (e.g., for making a syn‐
19166 opsis).
19167 · C++: add cpp:struct to complement cpp:class.
19169 · #1341 the HTML search considers words that contain a search term of
19171 length three or longer a match.
19172 · #4611: epub: Show warning for duplicated ToC entries
19174 · #1851: Allow to omit an argument for code-block directive. If omit‐
19176 ted, it follows highlight or highlight_language
19177 · #4587: html: Add html4_writer to use old HTML4 writer
19179 · #6016: HTML search: A placeholder for the search summary prevents
19181 search result links from changing their position when the search ter‐
19182 minates. This makes navigating search results easier.
19183 · #5196: linkcheck also checks remote images exist
19185 · #5924: githubpages: create CNAME file for custom domains when
19187 html_baseurl set
19188 · #4261: autosectionlabel: restrict the labeled sections by new config
19190 value; autosectionlabel_maxdepth
19191 Bugs fixed
19193 2.0.0b1
19194 · #1682: LaTeX: writer should not translate Greek unicode, but use
19196 textgreek package
19197 · #5247: LaTeX: PDF does not build with default font config for Russian
19199 language and 'xelatex' or 'lualatex' as latex_engine (refs: #5251)
19200 · #5248: LaTeX: Greek letters in section titles disappear from PDF
19202 bookmarks
19203 · #5249: LaTeX: Unicode Greek letters in math directive break PDF build
19205 (fix requires extra set-up, see latex_elements 'textgreek' key and/or
19206 latex_engine setting)
19207 · #5772: LaTeX: should the Bjarne style of fncychap be used for English
19209 also if passed as language option?
19210 · #5179: LaTeX: (lualatex only) escaping of > by \textgreater{} is not
19212 enough as \textgreater{}\textgreater{} applies TeX-ligature
19213 · LaTeX: project name is not escaped if latex_documents omitted
19215 · LaTeX: authors are not shown if latex_documents omitted
19217 · HTML: Invalid HTML5 file is generated for a glossary having multiple
19219 terms for one description (refs: #4611)
19220 · QtHelp: OS dependent path separator is used in .qhp file
19222 · HTML search: search always returns nothing when multiple search terms
19224 are used and one term is shorter than three characters
19225 2.0.0b2
19227 · #6096: html: Anchor links are not added to figures
19229 · #3620: html: Defer searchindex.js rather than loading it via ajax
19231 · #6113: html: Table cells and list items have large margins
19233 · #5508: linenothreshold option for highlight directive was ignored
19235 · texinfo: make install-info causes syntax error
19237 · texinfo: make install-info fails on macOS
19239 · #3079: texinfo: image files are not copied on make install-info
19241 · #5391: A cross reference in heading is rendered as literal
19243 · #5946: C++, fix cpp:alias problems in LaTeX (and singlehtml)
19245 · #6147: classes attribute of citation_reference node is lost
19247 · AssertionError is raised when custom citation_reference node having
19249 classes attribute refers missing citation (refs: #6147)
19250 · #2155: Support code directive
19252 · C++, fix parsing of braced initializers.
19254 · #6172: AttributeError is raised for old styled index nodes
19256 · #4872: inheritance_diagram: correctly describe behavior of parts
19258 option in docs, allow negative values.
19259 · #6178: i18n: Captions missing in translations for hidden TOCs
19261 2.0.0 final
19263 · #6196: py domain: unexpected prefix is generated
19265 Testing
19267 2.0.0b1
19268 · Stop to use SPHINX_TEST_TEMPDIR envvar
19270 2.0.0b2
19272 · Add a helper function: sphinx.testing.restructuredtext.parse()
19274 Release 1.8.5 (released Mar 10, 2019)
19276 Bugs fixed
19277 · LaTeX: Remove extraneous space after author names on PDF title page
19278 (refs: #6004)
19279 · #6026: LaTeX: A cross reference to definition list does not work
19281 · #6046: LaTeX: TypeError is raised when invalid latex_elements given
19283 · #6067: LaTeX: images having a target are concatenated to next line
19285 · #6067: LaTeX: images having a target are not aligned even if speci‐
19287 fied
19288 · #6149: LaTeX: :index: role in titles causes Use of \@icentercr
19290 doesn't match its definition error on latexpdf build
19291 · #6019: imgconverter: Including multipage PDF fails
19293 · #6047: autodoc: autofunction emits a warning for method objects
19295 · #6028: graphviz: Ensure the graphviz filenames are reproducible
19297 · #6068: doctest: skipif option may remove the code block from documen‐
19299 tation
19300 · #6136: :name: option for math directive causes a crash
19302 · #6139: intersphinx: ValueError on failure reporting
19304 · #6135: changes: Fix UnboundLocalError when any module found
19306 · #3859: manpage: code-block captions are not displayed correctly
19308 Release 1.8.4 (released Feb 03, 2019)
19310 Bugs fixed
19311 · #3707: latex: no bold checkmark (✔) available.
19312 · #5605: with the documentation language set to Chinese, English words
19314 could not be searched.
19315 · #5889: LaTeX: user numfig_format is stripped of spaces and may cause
19317 build failure
19318 · C++, fix hyperlinks for declarations involving east cv-qualifiers.
19320 · #5755: C++, fix duplicate declaration error on function templates
19322 with constraints in the return type.
19323 · C++, parse unary right fold expressions and binary fold expressions.
19325 · pycode could not handle egg files on windows
19327 · #5928: KeyError: ‘DOCUTILSCONFIG’ when running build
19329 · #5936: LaTeX: PDF build broken by inclusion of image taller than page
19331 height in an admonition
19332 · #5231: “make html” does not read and build “po” files in “locale” dir
19334 · #5954: :scale: image option may break PDF build if image in an admo‐
19336 nition
19337 · #5966: mathjax has not been loaded on incremental build
19339 · #5960: LaTeX: modified PDF layout since September 2018 TeXLive update
19341 of parskip.sty
19342 · #5948: LaTeX: duplicated labels are generated for sections
19344 · #5958: versionadded directive causes crash with Python 3.5.0
19346 · #5995: autodoc: autodoc_mock_imports conflict with metaclass on
19348 Python 3.7
19349 · #5871: texinfo: a section title . is not allowed
19351 Release 1.8.3 (released Dec 26, 2018)
19353 Features added
19354 · LaTeX: it is possible to insert custom material to appear on back of
19355 title page, see discussion of 'maketitle' key of latex_elements
19356 ('manual' docclass only)
19357 Bugs fixed
19359 · #5725: mathjax: Use CDN URL for “latest” version by default
19360 · #5460: html search does not work with some 3rd party themes
19362 · #5520: LaTeX, caption package incompatibility since Sphinx 1.6
19364 · #5614: autodoc: incremental build is broken when builtin modules are
19366 imported
19367 · #5627: qthelp: index.html missing in QtHelp
19369 · #5659: linkcheck: crashes for a hyperlink containing multibyte char‐
19371 acter
19372 · #5754: DOC: Fix some mistakes in /latex
19374 · #5810: LaTeX: sphinxVerbatim requires explicit “hllines” set-up since
19376 1.6.6 (refs: #1238)
19377 · #5636: C++, fix parsing of floating point literals.
19379 · #5496 (again): C++, fix assertion in partial builds with duplicates.
19381 · #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty
19383 · #1956: Default conf.py is not PEP8-compliant
19385 · #5849: LaTeX: document class \maketitle is overwritten with no possi‐
19387 bility to use original meaning in place of Sphinx custom one
19388 · #5834: apidoc: wrong help for --tocfile
19390 · #5800: todo: crashed if todo is defined in TextElement
19392 · #5846: htmlhelp: convert hex escaping to decimal escaping in
19394 .hhc/.hhk files
19395 · htmlhelp: broken .hhk file generated when title contains a double
19397 quote
19398 Release 1.8.2 (released Nov 11, 2018)
19400 Incompatible changes
19401 · #5497: Do not include MathJax.js and jsmath.js unless it is really
19402 needed
19403 Features added
19405 · #5471: Show appropriate deprecation warnings
19406 Bugs fixed
19408 · #5490: latex: enumerated list causes a crash with recommonmark
19409 · #5492: sphinx-build fails to build docs w/ Python < 3.5.2
19411 · #3704: latex: wrong \label positioning for figures with a legend
19413 · #5496: C++, fix assertion when a symbol is declared more than twice.
19415 · #5493: gettext: crashed with broken template
19417 · #5495: csv-table directive with file option in included file is bro‐
19419 ken (refs: #4821)
19420 · #5498: autodoc: unable to find type hints for a functools.partial
19422 · #5480: autodoc: unable to find type hints for unresolvable Forward
19424 references
19425 · #5419: incompatible math_block node has been generated
19427 · #5548: Fix ensuredir() in case of pre-existing file
19429 · #5549: graphviz Correctly deal with non-existing static dir
19431 · #3002: i18n: multiple footnote_references referring same footnote
19433 cause duplicated node_ids
19434 · #5563: latex: footnote_references generated by extension causes a
19436 LaTeX builder crash
19437 · #5561: make all-pdf fails with old xindy version
19439 · #5557: quickstart: –no-batchfile isn’t honored
19441 · #3080: texinfo: multiline rubrics are broken
19443 · #3080: texinfo: multiline citations are broken
19445 Release 1.8.1 (released Sep 22, 2018)
19447 Incompatible changes
19448 · LaTeX \pagestyle commands have been moved to the LaTeX template. No
19449 changes in PDF, except possibly if \sphinxtableofcontents, which con‐
19450 tained them, had been customized in conf.py. (refs: #5455)
19451 Bugs fixed
19453 · #5418: Incorrect default path for sphinx-build -d/doctrees files
19454 · #5421: autodoc emits deprecation warning for autodoc_default_flags
19456 · #5422: lambda object causes PicklingError on storing environment
19458 · #5417: Sphinx fails to build with syntax error in Python 2.7.5
19460 · #4911: add latexpdf to make.bat for non make-mode
19462 · #5436: Autodoc does not work with enum subclasses with proper‐
19464 ties/methods
19465 · #5437: autodoc: crashed on modules importing eggs
19467 · #5433: latex: ImportError: cannot import name ‘DEFAULT_SETTINGS’
19469 · #5431: autodoc: autofunction emits a warning for callable objects
19471 · #5457: Fix TypeError in error message when override is prohibited
19473 · #5453: PDF builds of ‘howto’ documents have no page numbers
19475 · #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0
19477 · #5454: latex: Index has disappeared from PDF for Japanese documents
19479 · #5432: py domain: :type: field can’t process :term: references
19481 · #5426: py domain: TypeError has been raised for class attribute
19483 Release 1.8.0 (released Sep 13, 2018)
19485 Dependencies
19486 1.8.0b1
19487 · LaTeX: latex_use_xindy, if True (default for xelatex/lualatex),
19489 instructs make latexpdf to use xindy for general index. Make sure
19490 your LaTeX distribution includes it. (refs: #5134)
19491 · LaTeX: latexmk is required for make latexpdf on Windows
19493 Incompatible changes
19495 1.8.0b2
19496 · #5282: html theme: refer pygments_style settings of HTML themes pref‐
19498 erentially
19499 · The URL of download files are changed
19501 · #5127: quickstart: Makefile and make.bat are not overwritten if
19503 exists
19504 1.8.0b1
19506 · #5156: the sphinx.ext.graphviz: extension runs `dot in the directory
19508 of the document being built instead of in the root directory of the
19509 documentation.
19510 · #4460: extensions which stores any data to environment should return
19512 the version of its env data structure as metadata. In detail, please
19513 see ext-metadata.
19514 · Sphinx expects source parser modules to have supported file formats
19516 as Parser.supported attribute
19517 · The default value of epub_author and epub_publisher are changed from
19519 'unknown' to the value of author. This is same as a conf.py file
19520 sphinx-build generates.
19521 · The gettext_compact attribute is removed from document.settings
19523 object. Please use config.gettext_compact instead.
19524 · The processing order on reading phase is changed. smart_quotes,
19526 sphinx domains, doctree-read event and versioning doctrees are
19527 invoked earlier than so far. For more details, please read a
19528 description of Sphinx.add_transform()
19529 · #4827: All substitution_definition nodes are removed from doctree on
19531 reading phase
19532 · docutils.conf in $HOME or /etc directories are ignored. Only docu‐
19534 tils.conf from confdir is obeyed.
19535 · #789: :samp: role supports to escape curly braces with backslash
19537 · #4811: The files under html_static_path are excluded from source
19539 files.
19540 · latex: Use \sphinxcite for citation references instead \hyperref
19542 · The config value viewcode_import is renamed to viewcode_fol‐
19544 low_imported_members (refs: #4035)
19545 · #1857: latex: latex_show_pagerefs does not add pagerefs for citations
19547 · #4648: latex: Now “rubric” elements are rendered as unnumbered sec‐
19549 tion title
19550 · #4983: html: The anchor for productionlist tokens has been changed
19552 · Modifying a template variable script_files in templates is allowed
19554 now. Please use app.add_js_file() instead.
19555 · #5072: Save environment object also with only new documents
19557 · #5035: qthelp builder allows dashes in qthelp_namespace
19559 · LaTeX: with lualatex or xelatex use by default xindy as UTF-8 able
19561 replacement of makeindex (refs: #5134). After upgrading Sphinx,
19562 please clean latex build repertory of existing project before new
19563 build.
19564 · #5163: html: hlist items are now aligned to top
19566 · highlightlang directive is processed on resolving phase
19568 · #4000: LaTeX: template changed. Following elements moved to it:
19570 · \begin{document}
19572 · shorthandoff variable
19574 · maketitle variable
19576 · tableofcontents variable
19578 Deprecated
19580 1.8.0b2
19581 · sphinx.io.SphinxI18nReader.set_lineno_for_reporter() is deprecated
19583 · sphinx.io.SphinxI18nReader.line is deprecated
19585 · sphinx.util.i18n.find_catalog_source_file() has changed; the get‐
19587 text_compact argument has been deprecated
19588 · #5403: sphinx.util.images.guess_mimetype() has changed; the content
19590 argument has been deprecated
19591 1.8.0b1
19593 · source_parsers is deprecated
19595 · autodoc_default_flags is deprecated
19597 · quickstart: --epub option becomes default, so it is deprecated
19599 · Drop function based directive support. For now, Sphinx only supports
19601 class based directives (see Directive)
19602 · sphinx.util.docutils.directive_helper() is deprecated
19604 · sphinx.cmdline is deprecated
19606 · sphinx.make_mode is deprecated
19608 · sphinx.locale.l_() is deprecated
19610 · #2157: helper function warn() for HTML themes is deprecated
19612 · app.override_domain() is deprecated
19614 · app.add_stylesheet() is deprecated
19616 · app.add_javascript() is deprecated
19618 · app.import_object() is deprecated
19620 · app.add_source_parser() has changed; the suffix argument has been
19622 deprecated
19623 · sphinx.versioning.prepare() is deprecated
19625 · Config.__init__() has changed; the dirname, filename and tags argu‐
19627 ment has been deprecated
19628 · Config.check_types() is deprecated
19630 · Config.check_unicode() is deprecated
19632 · sphinx.application.CONFIG_FILENAME is deprecated
19634 · highlightlang directive is deprecated
19636 · BuildEnvironment.load() is deprecated
19638 · BuildEnvironment.loads() is deprecated
19640 · BuildEnvironment.frompickle() is deprecated
19642 · env.read_doc() is deprecated
19644 · env.update() is deprecated
19646 · env._read_serial() is deprecated
19648 · env._read_parallel() is deprecated
19650 · env.write_doctree() is deprecated
19652 · env._nitpick_ignore is deprecated
19654 · env.versionchanges is deprecated
19656 · env.dump() is deprecated
19658 · env.dumps() is deprecated
19660 · env.topickle() is deprecated
19662 · env.note_versionchange() is deprecated
19664 · sphinx.writers.latex.Table.caption_footnotetexts is deprecated
19666 · sphinx.writers.latex.Table.header_footnotetexts is deprecated
19668 · sphinx.writers.latex.LaTeXTranslator.footnotestack is deprecated
19670 · sphinx.writers.latex.LaTeXTranslator.in_container_literal_block is
19672 deprecated
19673 · sphinx.writers.latex.LaTeXTranslator.next_section_ids is deprecated
19675 · sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids is deprecated
19677 · sphinx.writers.latex.LaTeXTranslator.restrict_footnote() is depre‐
19679 cated
19680 · sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote() is depre‐
19682 cated
19683 · sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids() is depre‐
19685 cated
19686 · sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids() is depre‐
19688 cated
19689 · sphinx.writers.latex.LaTeXTranslator.check_latex_elements() is depre‐
19691 cated
19692 · sphinx.writers.latex.LaTeXTranslator.bibitems is deprecated
19694 · sphinx.writers.latex.LaTeXTranslator.hlsettingstack is deprecated
19696 · sphinx.writers.latex.ExtBabel.get_shorthandoff() is deprecated
19698 · sphinx.writers.html.HTMLTranslator.highlightlang is deprecated
19700 · sphinx.writers.html.HTMLTranslator.highlightlang_base is deprecated
19702 · sphinx.writers.html.HTMLTranslator.highlightlangopts is deprecated
19704 · sphinx.writers.html.HTMLTranslator.highlightlinenothreshold is depre‐
19706 cated
19707 · sphinx.writers.html5.HTMLTranslator.highlightlang is deprecated
19709 · sphinx.writers.html5.HTMLTranslator.highlightlang_base is deprecated
19711 · sphinx.writers.html5.HTMLTranslator.highlightlangopts is deprecated
19713 · sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold is dep‐
19715 recated
19716 · sphinx.ext.mathbase extension is deprecated
19718 · sphinx.ext.mathbase.math node is deprecated
19720 · sphinx.ext.mathbase.displaymath node is deprecated
19722 · sphinx.ext.mathbase.eqref node is deprecated
19724 · sphinx.ext.mathbase.is_in_section_title() is deprecated
19726 · sphinx.ext.mathbase.MathDomain is deprecated
19728 · sphinx.ext.mathbase.MathDirective is deprecated
19730 · sphinx.ext.mathbase.math_role is deprecated
19732 · sphinx.ext.mathbase.setup_math() is deprecated
19734 · sphinx.directives.other.VersionChanges is deprecated
19736 · sphinx.highlighting.PygmentsBridge.unhighlight() is deprecated
19738 · sphinx.ext.mathbase.get_node_equation_number() is deprecated
19740 · sphinx.ext.mathbase.wrap_displaymath() is deprecated
19742 · The trim_doctest_flags argument of sphinx.highlighting.PygmentsBridge
19744 is deprecated
19745 For more details, see deprecation APIs list
19747 Features added
19749 1.8.0b2
19750 · #5388: Ensure frozen object descriptions are reproducible
19752 · #5362: apidoc: Add --tocfile option to change the filename of ToC
19754 1.8.0b1
19756 · Add config-inited event
19758 · Add sphinx.config.Any to represent the config value accepts any type
19760 of value
19761 · source_suffix allows a mapping fileext to file types
19763 · Add author as a configuration value
19765 · #2852: imgconverter: Support to convert GIF to PNG
19767 · sphinx-build command supports i18n console output
19769 · Add app.add_message_catalog() and sphinx.locale.get_translations() to
19771 support translation for 3rd party extensions
19772 · helper function warning() for HTML themes is added
19774 · Add Domain.enumerable_nodes to manage own enumerable nodes for
19776 domains (experimental)
19777 · Add a new keyword argument override to Application APIs
19779 · LaTeX: new key 'fvset' for latex_elements. For XeLaTeX/LuaLaTeX its
19781 default sets fanvyvrb to use normal, not small, fontsize in
19782 code-blocks (refs: #4793)
19783 · Add html_css_files and epub_css_files for adding CSS files from con‐
19785 figuration
19786 · Add html_js_files for adding JS files from configuration
19788 · #4834: Ensure set object descriptions are reproducible.
19790 · #4828: Allow to override numfig_format partially. Full definition is
19792 not needed.
19793 · Improve warning messages during including (refs: #4818)
19795 · LaTeX: separate customizability of guilabel and menuselection (refs:
19797 #4830)
19798 · Add Config.read() classmethod to create a new config object from con‐
19800 figuration file
19801 · #4866: Wrap graphviz diagrams in <div> tag
19803 · viewcode: Add viewcode-find-source and viewcode-follow-imported to
19805 load source code without loading
19806 · #4785: napoleon: Add strings to translation file for localisation
19808 · #4927: Display a warning when invalid values are passed to
19810 linenothreshold option of highlight directive
19811 · C++:
19813 · Add a cpp:texpr role as a sibling to cpp:expr.
19815 · Add support for unions.
19817 · #3593, #2683: add support for anonymous entities using names star‐
19819 ing with @.
19820 · #5147: add support for (most) character literals.
19822 · Cross-referencing entities inside primary templates is supported,
19824 and now properly documented.
19825 · #1552: add new cross-referencing format for cpp:any and cpp:func
19827 roles, for referencing specific function overloads.
19828 · #3606: MathJax should be loaded with async attribute
19830 · html: Output canonical_url metadata if html_baseurl set (refs: #4193)
19832 · #5029: autosummary: expose inherited_members to template
19834 · #3784: mathjax: Add mathjax_options to give options to script tag for
19836 mathjax
19837 · #4362: latex: Don’t overwrite .tex file if document not changed
19839 · #1431: latex: Add alphanumeric enumerated list support
19841 · Add latex_use_xindy for UTF-8 savvy indexing, defaults to True if
19843 latex_engine is 'xelatex' or 'lualatex'. (refs: #5134, #5192, #5212)
19844 · #4976: SphinxLoggerAdapter.info() now supports location parameter
19846 · #5122: setuptools: support nitpicky option
19848 · #2820: autoclass directive supports nested class
19850 · Add app.add_html_math_renderer() to register a math renderer for HTML
19852 · Apply trim_doctest_flags to all builders (cf. text, manpages)
19854 · #5140: linkcheck: Add better Accept header to HTTP client
19856 · #4614: sphinx-build: Add --keep-going option to show all warnings
19858 · Add math:numref role to refer equations (Same as eq)
19860 · quickstart: epub builder is enabled by default
19862 · #5246: Add singlehtml_sidebars to configure sidebars for singlehtml
19864 builder
19865 · #5273: doctest: Skip doctest conditionally
19867 · #5306: autodoc: emit a warning for invalid typehints
19869 · #4075, #5215: autodoc: Add autodoc_default_options which accepts
19871 option values as dict
19872 Bugs fixed
19874 1.8.0b2
19875 · html: search box overrides to other elements if scrolled
19877 · i18n: warnings for translation catalogs have wrong line numbers
19879 (refs: #5321)
19880 · #5325: latex: cross references has been broken by multiply labeled
19882 objects
19883 · C++, fixes for symbol addition and lookup. Lookup should no longer
19885 break in partial builds. See also #5337.
19886 · #5348: download reference to remote file is not displayed
19888 · #5282: html theme: pygments_style of theme was overridden by conf.py
19890 by default
19891 · #4379: toctree shows confusing warning when document is excluded
19893 · #2401: autodoc: :members: causes :special-members: not to be shown
19895 · autodoc: ImportError is replaced by AttributeError for deeper module
19897 · #2720, #4034: Incorrect links with :download:, duplicate names, and
19899 parallel builds
19900 · #5290: autodoc: failed to analyze source code in egg package
19902 · #5399: Sphinx crashes if unknown po file exists
19904 1.8.0b1
19906 · i18n: message catalogs were reset on each initialization
19908 · #4850: latex: footnote inside footnote was not rendered
19910 · #4945: i18n: fix lang_COUNTRY not fallback correctly for
19912 IndexBuilder. Thanks to Shengjing Zhu.
19913 · #4983: productionlist directive generates invalid IDs for the tokens
19915 · #5132: lualatex: PDF build fails if indexed word starts with Unicode
19917 character
19918 · #5133: latex: index headings “Symbols” and “Numbers” not internation‐
19920 alized
19921 · #5114: sphinx-build: Handle errors on scanning documents
19923 · epub: spine has been broken when “self” is listed on toctree (refs:
19925 #4611)
19926 · #344: autosummary does not understand docstring of module level
19928 attributes
19929 · #5191: C++, prevent nested declarations in functions to avoid lookup
19931 problems.
19932 · #5126: C++, add missing isPack method for certain template parameter
19934 types.
19935 · #5187: C++, parse attributes on declarators as well.
19937 · C++, parse delete expressions and basic new expressions as well.
19939 · #5002: graphviz: SVGs do not adapt to the column width
19941 Features removed
19943 1.8.0b1
19944 · sphinx.ext.pngmath extension
19946 Documentation
19948 1.8.0b1
19949 · #5083: Fix wrong make.bat option for internationalization.
19951 · #5115: napoleon: add admonitions added by #4613 to the docs.
19953 Release 1.7.9 (released Sep 05, 2018)
19955 Features added
19956 · #5359: Make generated texinfo files reproducible by sorting the
19957 anchors
19958 Bugs fixed
19960 · #5361: crashed on incremental build if document uses include direc‐
19961 tive
19962 Release 1.7.8 (released Aug 29, 2018)
19964 Incompatible changes
19965 · The type of env.included has been changed to dict of set
19966 Bugs fixed
19968 · #5320: intersphinx: crashed if invalid url given
19969 · #5326: manpage: crashed when invalid docname is specified as
19971 man_pages
19972 · #5322: autodoc: Any typehint causes formatting error
19974 · #5327: “document isn’t included in any toctree” warning on rebuild
19976 with generated files
19977 · #5335: quickstart: escape sequence has been displayed with MacPorts’
19979 python
19980 Release 1.7.7 (released Aug 19, 2018)
19982 Bugs fixed
19983 · #5198: document not in toctree warning when including files only for
19984 parallel builds
19985 · LaTeX: reduce “Token not allowed in a PDF string” hyperref warnings
19987 in latex console output (refs: #5236)
19988 · LaTeX: suppress “remreset Warning: The remreset package is obsolete”
19990 in latex console output with recent LaTeX (refs: #5237)
19991 · #5234: PDF output: usage of PAPER environment variable is broken
19993 since Sphinx 1.5
19994 · LaTeX: fix the latex_engine documentation regarding Latin Modern font
19996 with XeLaTeX/LuaLateX (refs: #5251)
19997 · #5280: autodoc: Fix wrong type annotations for complex typing
19999 · autodoc: Optional types are wrongly rendered
20001 · #5291: autodoc crashed by ForwardRef types
20003 · #5211: autodoc: No docs generated for functools.partial functions
20005 · #5306: autodoc: getargspec() raises NameError for invalid typehints
20007 · #5298: imgmath: math_number_all causes equations to have two numbers
20009 in html
20010 · #5294: sphinx-quickstart blank prompts in PowerShell
20012 Release 1.7.6 (released Jul 17, 2018)
20014 Bugs fixed
20015 · #5037: LaTeX \sphinxupquote{} breaks in Russian
20016 · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
20018 · #5016: crashed when recommonmark.AutoStrictify is enabled
20020 · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
20022 · #5009: latex: a label for table is vanished if table does not have a
20024 caption
20025 · #5048: crashed with numbered toctree
20027 · #2410: C, render empty argument lists for macros.
20029 · C++, fix lookup of full template specializations with no template
20031 arguments.
20032 · #4667: C++, fix assertion on missing references in global scope when
20034 using intersphinx. Thanks to Alan M. Carroll.
20035 · #5019: autodoc: crashed by Form Feed Character
20037 · #5032: autodoc: loses the first staticmethod parameter for old styled
20039 classes
20040 · #5036: quickstart: Typing Ctrl-U clears the whole of line
20042 · #5066: html: “relations” sidebar is not shown by default
20044 · #5091: latex: curly braces in index entries are not handled correctly
20046 · #5070: epub: Wrong internal href fragment links
20048 · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
20050 · #4272: PDF builds of French projects have issues with XeTeX
20052 · #5076: napoleon raises RuntimeError with python 3.7
20054 · #5125: sphinx-build: Interface of sphinx:main() has changed
20056 · sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
20058 given argument
20059 · #5146: autosummary: warning is emitted when the first line of doc‐
20061 string ends with literal notation
20062 · autosummary: warnings of autosummary indicates wrong location (refs:
20064 #5146)
20065 · #5143: autodoc: crashed on inspecting dict like object which does not
20067 support sorting
20068 · #5139: autodoc: Enum argument missing if it shares value with another
20070 · #4946: py domain: rtype field could not handle “None” as a type
20072 · #5176: LaTeX: indexing of terms containing @, !, or " fails
20074 · #5161: html: crashes if copying static files are failed
20076 · #5167: autodoc: Fix formatting type annotations for tuples with more
20078 than two arguments
20079 · #3329: i18n: crashed by auto-symbol footnote references
20081 · #5158: autosummary: module summary has been broken when it starts
20083 with heading
20084 Release 1.7.5 (released May 29, 2018)
20086 Bugs fixed
20087 · #4924: html search: Upper characters problem in any other languages
20088 · #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
20090 tains a module starting with underscore
20091 · #4863, #4938, #4939: i18n doesn’t handle correctly node.title as used
20093 for contents, topic, admonition, table and section.
20094 · #4913: i18n: literal blocks in bullet list are not translated
20096 · #4962: C++, raised TypeError on duplicate declaration.
20098 · #4825: C++, properly parse expr roles and give better error messages
20100 when (escaped) line breaks are present.
20101 · C++, properly use desc_addname nodes for prefixes of names.
20103 · C++, parse pack expansions in function calls.
20105 · #4915, #4916: links on search page are broken when using dirhtml
20107 builder
20108 · #4969: autodoc: constructor method should not have return annotation
20110 · latex: deeply nested enumerated list which is beginning with non-1
20112 causes LaTeX engine crashed
20113 · #4978: latex: shorthandoff is not set up for Brazil locale
20115 · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
20117 · #4946: py domain: type field could not handle “None” as a type
20119 · #4979: latex: Incorrect escaping of curly braces in index entries
20121 · #4956: autodoc: Failed to extract document from a subclass of the
20123 class on mocked module
20124 · #4973: latex: glossary directive adds whitespace to each item
20126 · #4980: latex: Explicit labels on code blocks are duplicated
20128 · #4919: node.asdom() crashes if toctree has :numbered: option
20130 · #4914: autodoc: Parsing error when using dataclasses without default
20132 values
20133 · #4931: autodoc: crashed when handler for autodoc-skip-member raises
20135 an error
20136 · #4931: autodoc: crashed when subclass of mocked class are processed
20138 by napoleon module
20139 · #5007: sphinx-build crashes when error log contains a “%” character
20141 Release 1.7.4 (released Apr 25, 2018)
20143 Bugs fixed
20144 · #4885, #4887: domains: Crashed with duplicated objects
20145 · #4889: latex: sphinx.writers.latex causes recursive import
20147 Release 1.7.3 (released Apr 23, 2018)
20149 Bugs fixed
20150 · #4769: autodoc loses the first staticmethod parameter
20151 · #4790: autosummary: too wide two column tables in PDF builds
20153 · #4795: Latex customization via _templates/longtable.tex_t is broken
20155 · #4789: imgconverter: confused by convert.exe of Windows
20157 · #4783: On windows, Sphinx crashed when drives of srcdir and outdir
20159 are different
20160 · #4812: autodoc ignores type annotated variables
20162 · #4817: wrong URLs on warning messages
20164 · #4784: latex: latex_show_urls assigns incorrect footnote numbers if
20166 hyperlinks exists inside substitutions
20167 · #4837: latex with class memoir Error: Font command \sf is not sup‐
20169 ported
20170 · #4803: latex: too slow in proportion to number of auto numbered foot‐
20172 notes
20173 · #4838: htmlhelp: The entries in .hhp file is not ordered
20175 · toctree directive tries to glob for URL having query_string
20177 · #4871: html search: Upper characters problem in German
20179 · #4717: latex: Compilation for German docs failed with LuaLaTeX and
20181 XeLaTeX
20182 · #4459: duplicated labels detector does not work well in parallel
20184 build
20185 · #4878: Crashed with extension which returns invalid metadata
20187 Release 1.7.2 (released Mar 21, 2018)
20189 Incompatible changes
20190 · #4520: apidoc: folders with an empty __init__.py are no longer
20191 excluded from TOC
20192 Bugs fixed
20194 · #4669: sphinx.build_main and sphinx.make_main throw NameError
20195 · #4685: autosummary emits meaningless warnings
20197 · autodoc: crashed when invalid options given
20199 · pydomain: always strip parenthesis if empty (refs: #1042)
20201 · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
20203 · #4701: viewcode: Misplaced <div> in viewcode html output
20205 · #4444: Don’t require numfig to use :numref: on sections
20207 · #4727: Option clash for package textcomp
20209 · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
20211 · #4716: Generation PDF file with TexLive on Windows, file not found
20213 error
20214 · #4574: vertical space before equation in latex
20216 · #4720: message when an image is mismatched for builder is not clear
20218 · #4655, #4684: Incomplete localization strings in Polish and Chinese
20220 · #2286: Sphinx crashes when error is happens in rendering HTML pages
20222 · #4688: Error to download remote images having long URL
20224 · #4754: sphinx/pycode/__init__.py raises AttributeError
20226 · #1435: qthelp builder should htmlescape keywords
20228 · epub: Fix docTitle elements of toc.ncx is not escaped
20230 · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
20232 · #4767: html: search highlighting breaks mathjax equations
20234 Release 1.7.1 (released Feb 23, 2018)
20236 Deprecated
20237 · #4623: sphinx.build_main() is deprecated.
20238 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
20240 has been changed (Since 1.7.0)
20241 · #4664: sphinx.ext.intersphinx.debug() is deprecated.
20243 For more details, see deprecation APIs list
20245 Bugs fixed
20247 · #4608: epub: Invalid meta tag is generated
20248 · #4260: autodoc: keyword only argument separator is not disappeared if
20250 it is appeared at top of the argument list
20251 · #4622: epub: epub_scheme does not effect to content.opf
20253 · #4627: graphviz: Fit graphviz images to page
20255 · #4617: quickstart: PROJECT_DIR argument is required
20257 · #4623: sphinx.build_main no longer exists in 1.7.0
20259 · #4615: The argument of sphinx.build has been changed in 1.7.0
20261 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
20263 has been changed
20264 · #4630: Have order on msgids in sphinx.pot deterministic
20266 · #4563: autosummary: Incorrect end of line punctuation detection
20268 · #4577: Enumerated sublists with explicit start with wrong number
20270 · #4641: A external link in TOC cannot contain “?” with :glob: option
20272 · C++, add missing parsing of explicit casts and typeid in expression
20274 parsing.
20275 · C++, add missing parsing of this in expression parsing.
20277 · #4655: Fix incomplete localization strings in Polish
20279 · #4653: Fix error reporting for parameterless ImportErrors
20281 · #4664: Reading objects.inv fails again
20283 · #4662: any refs with term targets crash when an ambiguity is encoun‐
20285 tered
20286 Release 1.7.0 (released Feb 12, 2018)
20288 Dependencies
20289 1.7.0b1
20290 · Add packaging package
20292 Incompatible changes
20294 1.7.0b1
20295 · #3668: The arguments has changed of main functions for each command
20297 · #3893: Unknown html_theme_options throw warnings instead of errors
20299 · #3927: Python parameter/variable types should match classes, not all
20301 objects
20302 · #3962: sphinx-apidoc now recognizes given directory as an implicit
20304 namespace package when --implicit-namespaces option given, not subdi‐
20305 rectories of given directory.
20306 · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
20308 · #4226: apidoc: Generate new style makefile (make-mode)
20310 · #4274: sphinx-build returns 2 as an exit code on argument error
20312 · #4389: output directory will be created after loading extensions
20314 · autodoc does not generate warnings messages to the generated document
20316 even if keep_warnings is True. They are only emitted to stderr.
20317 · shebang line is removed from generated conf.py
20319 · #2557: autodoc: autodoc_mock_imports only mocks specified modules
20321 with their descendants. It does not mock their ancestors. If you
20322 want to mock them, please specify the name of ancestors explicitly.
20323 · #3620: html theme: move DOCUMENTATION_OPTIONS to independent
20325 JavaScript file (refs: #4295)
20326 · #4246: Limit width of text body for all themes. Configurable via
20328 theme options body_min_width and body_max_width.
20329 · #4771: apidoc: The exclude_patterns arguments are ignored if they are
20331 placed just after command line options
20332 1.7.0b2
20334 · #4467: html theme: Rename csss block to css
20336 Deprecated
20338 1.7.0b1
20339 · using a string value for html_sidebars is deprecated and only list
20341 values will be accepted at 2.0.
20342 · format_annotation() and formatargspec() is deprecated. Please use
20344 sphinx.util.inspect.Signature instead.
20345 · sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
20347 tils. switch_source_input() and now deprecated. It will be removed
20348 in Sphinx-2.0.
20349 · sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
20351 now deprecated. Please use app.add_autodocumenter() instead.
20352 · AutoDirective._special_attrgetters is now deprecated. Please use
20354 app.add_autodoc_attrgetter() instead.
20355 Features added
20357 1.7.0b1
20358 · C++, handle decltype(auto).
20360 · #2406: C++, add proper parsing of expressions, including linking of
20362 identifiers.
20363 · C++, add a cpp:expr role for inserting inline C++ expressions or
20365 types.
20366 · C++, support explicit member instantiations with shorthand template
20368 prefix
20369 · C++, make function parameters linkable, like template params.
20371 · #3638: Allow to change a label of reference to equation using
20373 math_eqref_format
20374 · Now suppress_warnings accepts following configurations:
20376 · ref.python (ref: #3866)
20378 · #3872: Add latex key to configure literal blocks caption position in
20380 PDF output (refs #3792, #1723)
20381 · In case of missing docstring try to retrieve doc from base classes
20383 (ref: #3140)
20384 · #4023: Clarify error message when any role has more than one target.
20386 · #3973: epub: allow to override build date
20388 · #3972: epub: Sort manifest entries by filename
20390 · #4052: viewcode: Sort before highlighting module code
20392 · #1448: qthelp: Add new config value; qthelp_namespace
20394 · #4140: html themes: Make body tag inheritable
20396 · #4168: improve zh search with jieba
20398 · HTML themes can set up default sidebars through theme.conf
20400 · #3160: html: Use <kdb> to represent :kbd: role
20402 · #4212: autosummary: catch all exceptions when importing modules
20404 · #4166: Add math_numfig for equation numbering by section (refs:
20406 #3991, #4080). Thanks to Oliver Jahn.
20407 · #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
20409 code-blocks
20410 · #947: autodoc now supports ignore-module-all to ignore a module’s
20412 __all__
20413 · #4332: Let LaTeX obey math_numfig for equation numbering
20415 · #4093: sphinx-build creates empty directories for unknown tar‐
20417 gets/builders
20418 · Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
20420 sion to limit the scope of inheritance graphs.
20421 · #4183: doctest: :pyversion: option also follows PEP-440 specification
20423 · #4235: html: Add manpages_url to make manpage roles to hyperlinks
20425 · #3570: autodoc: Do not display ‘typing.’ module for type hints
20427 · #4354: sphinx-build now emits finish message. Builders can modify it
20429 through Builder.epilog attribute
20430 · #4245: html themes: Add language to javascript vars list
20432 · #4079: html: Add notranslate class to each code-blocks, literals and
20434 maths to let Google Translate know they are not translatable
20435 · #4137: doctest: doctest block is always highlighted as python console
20437 (pycon)
20438 · #4137: doctest: testcode block is always highlighted as python
20440 · #3998: text: Assign section numbers by default. You can control it
20442 using text_add_secnumbers and text_secnumber_suffix
20443 1.7.0b2
20445 · #4271: sphinx-build supports an option called -j auto to adjust num‐
20447 bers of processes automatically.
20448 · Napoleon: added option to specify custom section tags.
20450 Features removed
20452 1.7.0b1
20453 · Configuration variables
20455 · html_use_smartypants
20457 · latex_keep_old_macro_names
20459 · latex_elements[‘footer’]
20461 · utility methods of sphinx.application.Sphinx class
20463 · buildername (property)
20465 · _display_chunk()
20467 · old_status_iterator()
20469 · status_iterator()
20471 · _directive_helper()
20473 · utility methods of sphinx.environment.BuildEnvironment class
20475 · currmodule (property)
20477 · currclass (property)
20479 · epub2 builder
20481 · prefix and colorfunc parameter for warn()
20483 · sphinx.util.compat module
20485 · sphinx.util.nodes.process_only_nodes()
20487 · LaTeX environment notice, use sphinxadmonition instead
20489 · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
20491 · C++, support of function concepts. Thanks to mickk-on-cpp.
20493 · Not used and previously not documented LaTeX macros \shortversion and
20495 \setshortversion
20496 Bugs fixed
20498 1.7.0b1
20499 · #3882: Update the order of files for HTMLHelp and QTHelp
20501 · #3962: sphinx-apidoc does not recognize implicit namespace packages
20503 correctly
20504 · #4094: C++, allow empty template argument lists.
20506 · C++, also hyperlink types in the name of declarations with qualified
20508 names.
20509 · C++, do not add index entries for declarations inside concepts.
20511 · C++, support the template disambiguator for dependent names.
20513 · #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
20515 from the one of figures and tables
20516 · #4330: PDF ‘howto’ documents have an incoherent default LaTeX
20518 tocdepth counter setting
20519 · #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
20521 Thanks to Joel Nothman.
20522 · #4081: Warnings and errors colored the same when building
20524 · latex: Do not display ‘Release’ label if release is not set
20526 1.7.0b2
20528 · #4415: autodoc classifies inherited classmethods as regular methods
20530 · #4415: autodoc classifies inherited staticmethods as regular methods
20532 · #4472: DOCUMENTATION_OPTIONS is not defined
20534 · #4491: autodoc: prefer _MockImporter over other importers in
20536 sys.meta_path
20537 · #4490: autodoc: type annotation is broken with python 3.7.0a4+
20539 · utils package is no longer installed
20541 · #3952: apidoc: module header is too escaped
20543 · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
20545 · #4493: recommonmark raises AttributeError if AutoStructify enabled
20547 · #4209: intersphinx: In link title, “v” should be optional if target
20549 has no version
20550 · #4230: slowdown in writing pages with sphinx 1.6
20552 · #4522: epub: document is not rebuilt even if config changed
20554 1.7.0b3
20556 · #4019: inheritance_diagram AttributeError stopping make process
20558 · #4531: autosummary: methods are not treated as attributes
20560 · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
20562 · #4539: autodoc emits warnings for partialmethods
20564 · #4223: doctest: failing tests reported in wrong file, at wrong line
20566 · i18n: message catalogs are not compiled if specific filenames are
20568 given for sphinx-build as arguments (refs: #4560)
20569 · #4027: sphinx.ext.autosectionlabel now expects labels to be the same
20571 as they are in the raw source; no smart quotes, nothig fancy.
20572 · #4581: apidoc: Excluded modules still included
20574 Testing
20576 1.7.0b1
20577 · Add support for docutils 0.14
20579 · Add tests for the sphinx.ext.inheritance_diagram extension.
20581 Release 1.6.7 (released Feb 04, 2018)
20583 Bugs fixed
20584 · #1922: html search: Upper characters problem in French
20585 · #4412: Updated jQuery version from 3.1.0 to 3.2.1
20587 · #4438: math: math with labels with whitespace cause html error
20589 · #2437: make full reference for classes, aliased with “alias of”
20591 · #4434: pure numbers as link targets produce warning
20593 · #4477: Build fails after building specific files
20595 · #4449: apidoc: include “empty” packages that contain modules
20597 · #3917: citation labels are transformed to ellipsis
20599 · #4501: graphviz: epub3 validation error caused if graph is not click‐
20601 able
20602 · #4514: graphviz: workaround for wrong map ID which graphviz generates
20604 · #4525: autosectionlabel does not support parallel build
20606 · #3953: Do not raise warning when there is a working intersphinx
20608 inventory
20609 · #4487: math: ValueError is raised on parallel build. Thanks to
20611 jschueller.
20612 · #2372: autosummary: invalid signatures are shown for type annotated
20614 functions
20615 · #3942: html: table is not aligned to center even if :align: center
20617 Release 1.6.6 (released Jan 08, 2018)
20619 Features added
20620 · #4181: autodoc: Sort dictionary keys when possible
20621 · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
20623 · Easier customizability of LaTeX macros involved in rendering of
20625 code-blocks
20626 · Show traceback if conf.py raises an exception (refs: #4369)
20628 · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
20630 · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
20632 Bugs fixed
20634 · #4334: sphinx-apidoc: Don’t generate references to non-existing files
20635 in TOC
20636 · #4206: latex: reST label between paragraphs loses paragraph break
20638 · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
20640 · #4221: napoleon depends on autodoc, but users need to load it manu‐
20642 ally
20643 · #2298: automodule fails to document a class attribute
20645 · #4099: C++: properly link class reference to class from inside con‐
20647 structor
20648 · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
20650 · #4249: PDF output: Pygments error highlighting increases line spacing
20652 in code blocks
20653 · #1238: Support :emphasize-lines: in PDF output
20655 · #4279: Sphinx crashes with pickling error when run with multiple pro‐
20657 cesses and remote image
20658 · #1421: Respect the quiet flag in sphinx-quickstart
20660 · #4281: Race conditions when creating output directory
20662 · #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
20664 generates \chapter commands
20665 · #4214: Two todolist directives break sphinx-1.6.5
20667 · Fix links to external option docs with intersphinx (refs: #3769)
20669 · #4091: Private members not documented without :undoc-members:
20671 Release 1.6.5 (released Oct 23, 2017)
20673 Features added
20674 · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
20675 · #4112: Don’t override the smart_quotes setting if it was already set
20677 · #4125: Display reference texts of original and translated passages on
20679 i18n warning message
20680 · #4147: Include the exception when logging PO/MO file read/write
20682 Bugs fixed
20684 · #4085: Failed PDF build from image in parsed-literal using :align:
20685 option
20686 · #4100: Remove debug print from autodoc extension
20688 · #3987: Changing theme from alabaster causes HTML build to fail
20690 · #4096: C++, don’t crash when using the wrong role type. Thanks to
20692 mitya57.
20693 · #4070, #4111: crashes when the warning message contains format
20695 strings (again)
20696 · #4108: Search word highlighting breaks SVG images
20698 · #3692: Unable to build HTML if writing .buildinfo failed
20700 · #4152: HTML writer crashes if a field list is placed on top of the
20702 document
20703 · #4063: Sphinx crashes when labeling directive .. todolist::
20705 · #4134: [doc] docutils.conf is not documented explicitly
20707 · #4169: Chinese language doesn’t trigger Chinese search automatically
20709 · #1020: ext.todo todolist not linking to the page in pdflatex
20711 · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
20713 · #3739: :module: option is ignored at content of pyobjects
20715 · #4149: Documentation: Help choosing latex_engine
20717 · #4090: [doc] latex_additional_files with extra LaTeX macros should
20719 not use .tex extension
20720 · Failed to convert reST parser error to warning (refs: #4132)
20722 Release 1.6.4 (released Sep 26, 2017)
20724 Features added
20725 · #3926: Add autodoc_warningiserror to suppress the behavior of -W
20726 option during importing target modules on autodoc
20727 Bugs fixed
20729 · #3924: docname lost after dynamically parsing RST in extension
20730 · #3946: Typo in sphinx.sty (this was a bug with no effect in default
20732 context)
20733 ·
20735 pep and :rfc: does not supports default-role directive (refs:
20737 #3960)
20738 · #3960: default_role = ‘guilabel’ not functioning
20740 · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
20742 dows.
20743 · #4026: nature: Fix macOS Safari scrollbar color
20745 · #3877: Fix for C++ multiline signatures.
20747 · #4006: Fix crash on parallel build
20749 · #3969: private instance attributes causes AttributeError
20751 · #4041: C++, remove extra name linking in function pointers.
20753 · #4038: C, add missing documentation of member role.
20755 · #4044: An empty multicolumn cell causes extra row height in PDF out‐
20757 put
20758 · #4049: Fix typo in output of sphinx-build -h
20760 · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
20762 · Avoid indent after index entries in latex (refs: #4066)
20764 · #4070: crashes when the warning message contains format strings
20766 · #4067: Return non-zero exit status when make subprocess fails
20768 · #4055: graphviz: the :align: option does not work for SVG output
20770 · #4055: graphviz: the :align: center option does not work for latex
20772 output
20773 · #4051: warn() function for HTML theme outputs ‘None’ string
20775 Release 1.6.3 (released Jul 02, 2017)
20777 Features added
20778 · latex: hint that code-block continues on next page (refs: #3764,
20779 #3792)
20780 Bugs fixed
20782 · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
20783 · #3829: sphinx-quickstart template is incomplete regarding use of
20785 alabaster
20786 · #3772: ‘str object’ has no attribute ‘filename’
20788 · Emit wrong warnings if citation label includes hyphens (refs: #3565)
20790 · #3858: Some warnings are not colored when using –color option
20792 · #3775: Remove unwanted whitespace in default template
20794 · #3835: sphinx.ext.imgmath fails to convert SVG images if project
20796 directory name contains spaces
20797 · #3850: Fix color handling in make mode’s help command
20799 · #3865: use of self.env.warn in sphinx extension fails
20801 · #3824: production lists apply smart quotes transform since Sphinx
20803 1.6.1
20804 · latex: fix \sphinxbfcode swallows initial space of argument
20806 · #3878: Quotes in auto-documented class attributes should be straight
20808 quotes in PDF output
20809 · #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
20811 tical whitespace
20812 · #3885: duplicated footnotes raises IndexError
20814 · #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
20816 pat.Directive
20817 · #3874: Bogus warnings for “citation not referenced” for cross-file
20819 citations
20820 · #3860: Don’t download images when builders not supported images
20822 · #3860: Remote image URIs without filename break builders not sup‐
20824 ported remote images
20825 · #3833: command line messages are translated unintentionally with lan‐
20827 guage setting.
20828 · #3840: make checking epub_uid strict
20830 · #3851, #3706: Fix about box drawing characters for PDF output
20832 · #3900: autosummary could not find methods
20834 · #3902: Emit error if latex_documents contains non-unicode string in
20836 py2
20837 Release 1.6.2 (released May 28, 2017)
20839 Incompatible changes
20840 · #3789: Do not require typing module for python>=3.5
20841 Bugs fixed
20843 · #3754: HTML builder crashes if HTML theme appends own stylesheets
20844 · #3756: epub: Entity ‘mdash’ not defined
20846 · #3758: Sphinx crashed if logs are emitted in conf.py
20848 · #3755: incorrectly warns about dedent with literalinclude
20850 · #3742: RTD PDF builds of Sphinx own docs are missing an index entry
20852 in the bookmarks and table of contents. This is
20853 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
20854 extra LaTeX code in Sphinx’s own conf.py
20855 · #3770: Build fails when a “code-block” has the option emphasize-lines
20857 and the number indicated is higher than the number of lines
20858 · #3774: Incremental HTML building broken when using citations
20860 · #3763: got epubcheck validations error if epub_cover is set
20862 · #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
20864 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
20865 · #3796: env.resolve_references() crashes when non-document node given
20867 · #3803: Sphinx crashes with invalid PO files
20869 · #3791: PDF “continued on next page” for long tables isn’t interna‐
20871 tionalized
20872 · #3788: smartquotes emits warnings for unsupported languages
20874 · #3807: latex Makefile for make latexpdf is only for unixen
20876 · #3781: double hyphens in option directive are compiled as endashes
20878 · #3817: latex builder raises AttributeError
20880 Release 1.6.1 (released May 16, 2017)
20882 Dependencies
20883 1.6b1
20884 · (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
20886 ages (Feb. 2014) and earlier tex installations may not be fully com‐
20887 pliant, particularly regarding Unicode engines xelatex and lualatex
20888 · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
20890 X (refs: #3082)
20891 Incompatible changes
20893 1.6b1
20894 · #1061, #2336, #3235: Now generation of autosummary doesn’t contain
20896 imported members by default. Thanks to Luc Saffre.
20897 · LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
20899 graphics has the custom code to fit image to available width if over‐
20900 sized.
20901 · The subclasses of sphinx.domains.Index should override generate()
20903 method. The default implementation raises NotImplementedError
20904 · LaTeX positioned long tables horizontally centered, and short ones
20906 flushed left (no text flow around table.) The position now defaults
20907 to center in both cases, and it will obey Docutils 0.13 :align:
20908 option (refs #3415, #3377)
20909 · option directive also allows all punctuations for the option name
20911 (refs: #3366)
20912 · #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
20914 tive (refs #3412)
20915 · literalinclude directive does not allow the combination of :diff:
20917 option and other options (refs: #3416)
20918 · LuaLaTeX engine uses fontspec like XeLaTeX. It is advised
20920 latex_engine = 'lualatex' be used only on up-to-date TeX installs
20921 (refs #3070, #3466)
20922 · latex_keep_old_macro_names default value has been changed from True
20924 to False. This means that some LaTeX macros for styling are by
20925 default defined only with \sphinx.. prefixed names. (refs: #3429)
20926 · Footer “Continued on next page” of LaTeX longtable’s now not framed
20928 (refs: #3497)
20929 · #3529: The arguments of BuildEnvironment.__init__ is changed
20931 · #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
20933 only)
20934 · #3558: Emit warnings if footnotes and citations are not referenced.
20936 The warnings can be suppressed by suppress_warnings.
20937 · latex made available (non documented) colour macros from a file dis‐
20939 tributed with pdftex engine for Plain TeX. This is removed in order
20940 to provide better support for multiple TeX engines. Only interface
20941 from color or xcolor packages should be used by extensions of Sphinx
20942 latex writer. (refs #3550)
20943 · Builder.env is not filled at instantiation
20945 · #3594: LaTeX: single raw directive has been considered as block level
20947 element
20948 · #3639: If html_experimental_html5_writer is available, epub builder
20950 use it by default.
20951 · Sphinx.add_source_parser() raises an error if duplicated
20953 1.6b2
20955 · #3345: Replace the custom smartypants code with Docutils’
20957 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at
20958 Docutils.
20959 1.6b3
20961 · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
20963 · LaTeX package multirow is not used and not loaded by Sphinx anymore
20965 · Add line numbers to citation data in std domain
20967 1.6 final
20969 · LaTeX package threeparttable is not used and not loaded by Sphinx
20971 anymore (refs #3686, #3532, #3377)
20972 Features removed
20974 · Configuration variables
20975 · epub3_contributor
20977 · epub3_description
20979 · epub3_page_progression_direction
20981 · html_translator_class
20983 · html_use_modindex
20985 · latex_font_size
20987 · latex_paper_size
20989 · latex_preamble
20991 · latex_use_modindex
20993 · latex_use_parts
20995 · termsep node
20997 · defindex.html template
20999 · LDML format support in today, today_fmt and html_last_updated_fmt
21001 · :inline: option for the directives of sphinx.ext.graphviz extension
21003 · sphinx.ext.pngmath extension
21005 · sphinx.util.compat.make_admonition()
21007 Features added
21009 1.6b1
21010 · #3136: Add :name: option to the directives in sphinx.ext.graphviz
21012 · #2336: Add imported_members option to sphinx-autogen command to docu‐
21014 ment imported members.
21015 · C++, add :tparam-line-spec: option to templated declarations. When
21017 specified, each template parameter will be rendered on a separate
21018 line.
21019 · #3359: Allow sphinx.js in a user locale dir to override sphinx.js
21021 from Sphinx
21022 · #3303: Add :pyversion: option to the doctest directive.
21024 · #3378: (latex) support for :widths: option of table directives (refs:
21026 #3379, #3381)
21027 · #3402: Allow to suppress “download file not readable” warnings using
21029 suppress_warnings.
21030 · #3377: latex: Add support for Docutils 0.13 :align: option for tables
21032 (but does not implement text flow around table).
21033 · latex: footnotes from inside tables are hyperlinked (except from cap‐
21035 tions or headers) (refs: #3422)
21036 · Emit warning if over dedent has detected on literalinclude directive
21038 (refs: #3416)
21039 · Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
21041 and polyglossia). (refs: #3070, #3466)
21042 · Make 'extraclassoptions' key of latex_elements public (refs #3480)
21044 · #3463: Add warning messages for required EPUB3 metadata. Add default
21046 value to epub_description to avoid warning like other settings.
21047 · #3476: setuptools: Support multiple builders
21049 · latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
21051 quotes… as do normal cells (refs: #3435)
21052 · HTML builder uses experimental HTML5 writer if html_experimen‐
21054 tal_html5_writer is True and docutils 0.13 or later is installed.
21055 · LaTeX macros to customize space before and after tables in PDF output
21057 (refs #3504)
21058 · #3348: Show decorators in literalinclude and viewcode directives
21060 · #3108: Show warning if :start-at: and other literalinclude options
21062 does not match to the text
21063 · #3609: Allow to suppress “duplicate citation” warnings using sup‐
21065 press_warnings
21066 · #2803: Discovery of builders by entry point
21068 · #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
21070 stylesheets
21071 · #3589: Support remote images on non-HTML builders
21073 · #3589: Support images in Data URI on non-HTML builders
21075 · #2961: improve autodoc_mock_imports. Now the config value only
21077 requires to declare the top-level modules that should be mocked.
21078 Thanks to Robin Jarry.
21079 · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
21081 ture calculation. Thanks to Nathaniel J. Smith.
21082 · #3641: Epub theme supports HTML structures that are generated by
21084 HTML5 writer.
21085 · #3644 autodoc uses inspect instead of checking types. Thanks to
21087 Jeroen Demeyer.
21088 · Add a new extension; sphinx.ext.imgconverter. It converts images in
21090 the document to appropriate format for builders
21091 · latex: Use templates to render tables (refs #3389, 2a37b0e)
21093 1.6b2
21095 · LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass
21097 options to latexmk when executing make latexpdf (refs #3695, #3720)
21098 · Add a new event env-check-consistency to check consistency to exten‐
21100 sions
21101 · Add Domain.check_consistency() to check consistency
21103 Bugs fixed
21105 1.6b1
21106 · literalinclude directive expands tabs after dedent-ing (refs: #3416)
21108 · #1574: Paragraphs in table cell doesn’t work in Latex output
21110 · #3288: Table with merged headers not wrapping text
21112 · #3491: Inconsistent vertical space around table and longtable in PDF
21114 · #3506: Depart functions for all admonitions in HTML writer now prop‐
21116 erly pass node to depart_admonition.
21117 · #2693: Sphinx latex style file wrongly inhibits colours for section
21119 headings for latex+dvi(ps,pdf,pdfmx)
21120 · C++, properly look up any references.
21122 · #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
21124 with gzip
21125 · #3551: PDF information dictionary is lacking author and title data
21127 · #3351: intersphinx does not refers context like py:module, py:class
21129 and so on.
21130 · Fail to load template file if the parent template is archived
21132 1.6b2
21134 · #3661: sphinx-build crashes on parallel build
21136 · #3669: gettext builder fails with “ValueError: substring not found”
21138 · #3660: Sphinx always depends on sphinxcontrib-websupport and its
21140 dependencies
21141 · #3472: smart quotes getting wrong in latex (at least with list of
21143 strings via autoattribute) (refs: #3345, #3666)
21144 1.6b3
21146 · #3588: No compact (p tag) html output in the i18n document build even
21148 when html_compact_lists is True.
21149 · The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using
21151 latexmk) aborted earlier in case of LaTeX errors than was the case
21152 with 1.5 series, due to hard-coded usage of --halt-on-error option
21153 (refs #3695)
21154 · #3683: sphinx.websupport module is not provided by default
21156 · #3683: Failed to build document if builder.css_file.insert() is
21158 called
21159 · #3714: viewcode extension not taking highlight_code='none' in account
21161 · #3698: Moving :doc: to std domain broke backwards compatibility
21163 · #3633: misdetect unreferenced citations
21165 1.6 final
21167 · LaTeX tables do not allow multiple paragraphs in a header cell
21169 · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
21171 · #3532: Figure or literal block captions in cells of short tables
21173 cause havoc in PDF output
21174 · Fix: in PDF captions of tables are rendered differently whether table
21176 is of longtable class or not (refs #3686)
21177 · #3725: Todo looks different from note in LaTeX output
21179 · #3479: stub-columns have no effect in LaTeX output
21181 · #3738: Nonsensical code in theming.py
21183 · #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
21185 options -pdfxe and -pdflua
21186 Deprecated
21188 1.6b1
21189 · sphinx.util.compat.Directive class is now deprecated. Please use
21191 instead docutils.parsers.rst.Directive
21192 · sphinx.util.compat.docutils_version is now deprecated
21194 · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
21196 deprecated. Please use sphinx.util.logging (logging-api) instead.
21197 · #3318: notice is now deprecated as LaTeX environment name and will be
21199 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
21200 instead (as Sphinx does since 1.5.)
21201 · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
21203 recated. Please use sphinx.util:status_iterator() instead.
21204 · Sphinx._directive_helper() is deprecated. Please use
21206 sphinx.util.docutils.directive_helper() instead.
21207 · BuildEnvironment.set_warnfunc() is now deprecated
21209 · Following methods of BuildEnvironment is now deprecated.
21211 · BuildEnvironment.note_toctree()
21213 · BuildEnvironment.get_toc_for()
21215 · BuildEnvironment.get_toctree_for()
21217 · BuildEnvironment.create_index()
21219 Please use sphinx.environment.adapters modules instead.
21221 · latex package footnote is not loaded anymore by its bundled replace‐
21223 ment footnotehyper-sphinx. The redefined macros keep the same names
21224 as in the original package.
21225 · #3429: deprecate config setting latex_keep_old_macro_names. It will
21227 be removed at 1.7, and already its default value has changed from
21228 True to False.
21229 · #3221: epub2 builder is deprecated
21231 · #3254: sphinx.websupport is now separated into independent package;
21233 sphinxcontrib-websupport. sphinx.websupport will be removed in
21234 Sphinx-2.0.
21235 · #3628: sphinx_themes entry_point is deprecated. Please use
21237 sphinx.html_themes instead.
21238 1.6b2
21240 · #3662: builder.css_files is deprecated. Please use add_stylesheet()
21242 API instead.
21243 1.6 final
21245 · LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
21247 1.7. Please move customization into new macro \sphinxstyletheadfam‐
21248 ily.
21249 Testing
21251 1.6 final
21252 · #3458: Add sphinx.testing (experimental)
21254 Release 1.6 (unreleased)
21256 · not released (because of package script error)
21257 Release 1.5.6 (released May 15, 2017)
21259 Bugs fixed
21260 · #3614: Sphinx crashes with requests-2.5.0
21261 · #3618: autodoc crashes with tupled arguments
21263 · #3664: No space after the bullet in items of a latex list produced by
21265 Sphinx
21266 · #3657: EPUB builder crashes if a document starting with genindex
21268 exists
21269 · #3588: No compact (p tag) html output in the i18n document build even
21271 when html_compact_lists is True.
21272 · #3685: AttributeError when using 3rd party domains
21274 · #3702: LaTeX writer styles figure legends with a hard-coded \small
21276 · #3708: LaTeX writer allows irc scheme
21278 · #3717: Stop enforcing that favicon’s must be .ico
21280 · #3731, #3732: Protect isenumclass predicate against non-class argu‐
21282 ments
21283 · #3320: Warning about reference target not being found for container
21285 types
21286 · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
21288 Release 1.5.5 (released Apr 03, 2017)
21290 Bugs fixed
21291 · #3597: python domain raises UnboundLocalError if invalid name given
21292 · #3599: Move to new MathJax CDN
21294 Release 1.5.4 (released Apr 02, 2017)
21296 Features added
21297 · #3470: Make genindex support all kinds of letters, not only Latin
21298 ones
21299 Bugs fixed
21301 · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
21302 to failed PDF build
21303 · EPUB file has duplicated nav.xhtml link in content.opf except first
21305 time build
21306 · #3488: objects.inv has broken when release or version contain return
21308 code
21309 · #2073, #3443, #3490: gettext builder that writes pot files unless the
21311 content are same without creation date. Thanks to Yoshiki Shibukawa.
21312 · #3487: intersphinx: failed to refer options
21314 · #3496: latex longtable’s last column may be much wider than its con‐
21316 tents
21317 · #3507: wrong quotes in latex output for productionlist directive
21319 · #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
21321 links rendered as code
21322 · #2665, #2607: Link names in C++ docfields, and make it possible for
21324 other domains.
21325 · #3542: C++, fix parsing error of non-type template argument with tem‐
21327 plate.
21328 · #3065, #3520: python domain fails to recognize nested class
21330 · #3575: Problems with pdflatex in a Turkish document built with sphinx
21332 has reappeared (refs #2997, #2397)
21333 · #3577: Fix intersphinx debug tool
21335 · A LaTeX command such as \\large inserted in the title items of
21337 latex_documents causes failed PDF build (refs #3551, #3567)
21338 Release 1.5.3 (released Feb 26, 2017)
21340 Features added
21341 · Support requests-2.0.0 (experimental) (refs: #3367)
21342 · (latex) PDF page margin dimensions may be customized (refs: #3387)
21344 · literalinclude directive allows combination of :pyobject: and :lines:
21346 options (refs: #3416)
21347 · #3400: make-mode doesn’t use subprocess on building docs
21349 Bugs fixed
21351 · #3370: the caption of code-block is not picked up for translation
21352 · LaTeX: release is not escaped (refs: #3362)
21354 · #3364: sphinx-quickstart prompts overflow on Console with 80 chars
21356 width
21357 · since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
21359 (refs: #3383)
21360 · #3392: 'releasename' in latex_elements is not working
21362 · #3356: Page layout for Japanese 'manual' docclass has a shorter text
21364 area
21365 · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
21367 wrong PDF page dimensions
21368 · #3399: quickstart: conf.py was not overwritten by template
21370 · #3366: option directive does not allow punctuations
21372 · #3410: return code in release breaks html search
21374 · #3427: autodoc: memory addresses are not stripped on Windows
21376 · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
21378 · #3349: Result of IndexBuilder.load() is broken
21380 · #3450:   is appeared in EPUB docs
21382 · #3418: Search button is misaligned in nature and pyramid theme
21384 · #3421: Could not translate a caption of tables
21386 · #3552: linkcheck raises UnboundLocalError
21388 Release 1.5.2 (released Jan 22, 2017)
21390 Incompatible changes
21391 · Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
21392 #3310)
21393 Features added
21395 · #3241: emit latex warning if buggy titlesec (ref #3210)
21396 · #3194: Refer the $MAKE environment variable to determine make command
21398 · Emit warning for nested numbered toctrees (refs: #3142)
21400 · #978: intersphinx_mapping also allows a list as a parameter
21402 · #3340: (LaTeX) long lines in parsed-literal are wrapped like in
21404 code-block, inline math and footnotes are fully functional.
21405 Bugs fixed
21407 · #3246: xapian search adapter crashes
21408 · #3253: In Py2 environment, building another locale with a non-cap‐
21410 tioned toctree produces None captions
21411 · #185: References to section title including raw node has broken
21413 · #3255: In Py3.4 environment, autodoc doesn’t support documentation
21415 for attributes of Enum class correctly.
21416 · #3261: latex_use_parts makes sphinx crash
21418 · The warning type misc.highlighting_failure does not work
21420 · #3294: add_latex_package() make crashes non-LaTeX builders
21422 · The caption of table are rendered as invalid HTML (refs: #3287)
21424 · #3268: Sphinx crashes with requests package from Debian jessie
21426 · #3284: Sphinx crashes on parallel build with an extension which
21428 raises unserializable exception
21429 · #3315: Bibliography crashes on latex build with docclass ‘memoir’
21431 · #3328: Could not refer rubric implicitly
21433 · #3329: emit warnings if po file is invalid and can’t read it. Also
21435 writing mo
21436 · #3337: Ugly rendering of definition list term’s classifier
21438 · #3335: gettext does not extract field_name of a field in a field_list
21440 · #2952: C++, fix refs to operator() functions.
21442 · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
21444 eral LaTeX output (ref #3342)
21445 · LaTeX writer: leave " character inside parsed-literal as is (ref
21447 #3341)
21448 · #3234: intersphinx failed for encoded inventories
21450 · #3158: too much space after captions in PDF output
21452 · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
21454 if with hyphen
21455 · LaTeX crash if the filename of an image inserted in parsed-literal
21457 via a substitution contains an hyphen (ref #3340)
21458 · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
21460 #3340)
21461 · Inline math in parsed-literal is not rendered well by LaTeX (ref
21463 #3340)
21464 · #3308: Parsed-literals don’t wrap very long lines with pdf builder
21466 (ref #3340)
21467 · #3295: Could not import extension sphinx.builders.linkcheck
21469 · #3285: autosummary: asterisks are escaped twice
21471 · LaTeX, pass dvipdfm option to geometry package for Japanese documents
21473 (ref #3363)
21474 · Fix parselinenos() could not parse left half open range (cf. “-4”)
21476 Release 1.5.1 (released Dec 13, 2016)
21478 Features added
21479 · #3214: Allow to suppress “unknown mimetype” warnings from epub
21480 builder using suppress_warnings.
21481 Bugs fixed
21483 · #3195: Can not build in parallel
21484 · #3198: AttributeError is raised when toctree has ‘self’
21486 · #3211: Remove untranslated sphinx locale catalogs (it was covered by
21488 untranslated it_IT)
21489 · #3212: HTML Builders crashes with docutils-0.13
21491 · #3207: more latex problems with references inside parsed-literal
21493 directive (\DUrole)
21494 · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
21496 · #3220: KeyError when having a duplicate citation
21498 · #3200: LaTeX: xref inside desc_name not allowed
21500 · #3228: build_sphinx command crashes when missing dependency
21502 · #2469: Ignore updates of catalog files for gettext builder. Thanks to
21504 Hiroshi Ohkubo.
21505 · #3183: Randomized jump box order in generated index page.
21507 Release 1.5 (released Dec 5, 2016)
21509 Incompatible changes
21510 1.5a1
21511 · latex, package fancybox is not any longer a dependency of sphinx.sty
21513 · Use 'locales' as a default value of locale_dirs
21515 · latex, package ifthen is not any longer a dependency of sphinx.sty
21517 · latex, style file does not modify fancyvrb’s Verbatim (also available
21519 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
21520 per.
21521 · latex, package newfloat is not used (and not included) anymore (ref
21523 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
21524 · latex, literal blocks in tables do not use OriginalVerbatim but
21526 sphinxVerbatimintable which handles captions and wraps lines (ref
21527 #2704).
21528 · latex, replace pt by TeX equivalent bp if found in width or height
21530 attribute of an image.
21531 · latex, if width or height attribute of an image is given with no
21533 unit, use px rather than ignore it.
21534 · latex: Separate stylesheets of pygments to independent .sty file
21536 · #2454: The filename of sourcelink is now changed. The value of
21538 html_sourcelink_suffix will be appended to the original filename
21539 (like index.rst.txt).
21540 · sphinx.util.copy_static_entry() is now deprecated. Use
21542 sphinx.util.fileutil.copy_asset() instead.
21543 · sphinx.util.osutil.filecopy() skips copying if the file has not been
21545 changed (ref: #2510, #2753)
21546 · Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
21548 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
21549 #2773)
21550 · QtHelpBuilder doesn’t generate search page (ref: #2352)
21552 · QtHelpBuilder uses nonav theme instead of default one to improve
21554 readability.
21555 · latex: To provide good default settings to Japanese documents, Sphinx
21557 uses jreport and jsbook as docclass if language is ja.
21558 · sphinx-quickstart now allows a project version is empty
21560 · Fix :download: role on epub/qthelp builder. They ignore the role
21562 because they don’t support it.
21563 · sphinx.ext.viewcode doesn’t work on epub building by default. view‐
21565 code_enable_epub option
21566 · sphinx.ext.viewcode disabled on singlehtml builder.
21568 · Use make-mode of sphinx-quickstart by default. To disable this, use
21570 -M option
21571 · Fix genindex.html, Sphinx’s document template, link address to itself
21573 to satisfy xhtml standard.
21574 · Use epub3 builder by default. And the old epub builder is renamed to
21576 epub2.
21577 · Fix epub and epub3 builders that contained links to genindex even if
21579 epub_use_index = False.
21580 · html_translator_class is now deprecated. Use Sphinx.set_translator()
21582 API instead.
21583 · Drop python 2.6 and 3.3 support
21585 · Drop epub3 builder’s epub3_page_progression_direction option (use
21587 epub3_writing_mode).
21588 · #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
21590 body']
21591 1.5a2
21593 · #2983: Rename epub3_description and epub3_contributor to
21595 epub_description and epub_contributor.
21596 · Remove themes/basic/defindex.html; no longer used
21598 · Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
21600 chap
21601 · #2435: Slim down quickstarted conf.py
21603 · The sphinx.sty latex package does not load itself “hyperref”, as this
21605 is done later in the preamble of the latex output via 'hyperref' key.
21606 · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
21608 lary. The non-modified package is used.
21609 · #3057: By default, footnote marks in latex PDF output are not pre‐
21611 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
21612 tomization if needed.
21613 · LaTeX target requires that option hyperfootnotes of package hyperref
21615 be left unchanged to its default (i.e. true) (refs: #3022)
21616 1.5 final
21618 · #2986: themes/basic/defindex.html is now deprecated
21620 · Emit warnings that will be deprecated in Sphinx 1.6 by default.
21622 Users can change the behavior by setting the environment variable
21623 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
21624 · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
21626 Deprecated
21628 These features are removed in Sphinx-1.6:
21629 · LDML format support in i18n feature
21631 · sphinx.addnodes.termsep
21633 · Some functions and classes in sphinx.util.pycompat: zip_longest,
21635 product, all, any, next, open, class_types, base_exception, relpath,
21636 StringIO, BytesIO. Please use the standard library version instead;
21637 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
21639 played, please refer when-deprecation-warnings-are-displayed.
21640 Features added
21642 1.5a1
21643 · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
21645 · Add :caption: option for sphinx.ext.inheritance_diagram.
21647 · #2471: Add config variable for default doctest flags.
21649 · Convert linkcheck builder to requests for better encoding handling
21651 · #2463, #2516: Add keywords of “meta” directive to search index
21653 · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
21655 · #2575: Now sphinx.ext.graphviz allows :align: option
21657 · Show warnings if unknown key is specified to latex_elements
21659 · Show warnings if no domains match with primary_domain (ref: #2001)
21661 · C++, show warnings when the kind of role is misleading for the kind
21663 of target it refers to (e.g., using the class role for a function).
21664 · latex, writer abstracts more of text styling into customizable
21666 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
21667 rather than \emph (which may be in use elsewhere or in an added LaTeX
21668 package). See list at end of sphinx.sty (ref: #2686)
21669 · latex, public names for environments and parameters used by note,
21671 warning, and other admonition types, allowing full customizability
21672 from the 'preamble' key or an input file (ref: feature request #2674,
21673 #2685)
21674 · latex, better computes column widths of some tables (as a result,
21676 there will be slight changes as tables now correctly fill the line
21677 width; ref: #2708)
21678 · latex, sphinxVerbatim environment is more easily customizable (ref:
21680 #2704). In addition to already existing VerbatimColor and Verbatim‐
21681 BorderColor:
21682 · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
21684 · booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
21686 slines.
21687 · latex, captions for literal blocks inside tables are handled, and
21689 long code lines wrapped to fit table cell (ref: #2704)
21690 · #2597: Show warning messages as darkred
21692 · latex, allow image dimensions using px unit (default is 96px=1in)
21694 · Show warnings if invalid dimension units found
21696 · #2650: Add --pdb option to setup.py command
21698 · latex, make the use of \small for code listings customizable (ref
21700 #2721)
21701 · #2663: Add --warning-is-error option to setup.py command
21703 · Show warnings if deprecated latex options are used
21705 · Add sphinx.config.ENUM to check the config values is in candidates
21707 · math: Add hyperlink marker to each equations in HTML output
21709 · Add new theme nonav that doesn’t include any navigation links. This
21711 is for any help generator like qthelp.
21712 · #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings
21714 enabled. Also, it emits an additional event named todo-defined to
21715 handle the TODO entries in 3rd party extensions.
21716 · Python domain signature parser now uses the xref mixin for ‘excep‐
21718 tions’, allowing exception classes to be autolinked.
21719 · #2513: Add latex_engine to switch the LaTeX engine by conf.py
21721 · #2682: C++, basic support for attributes (C++11 style and GNU style).
21723 The new configuration variables ‘cpp_id_attributes’ and
21724 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
21725 · #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
21727 removing prefixes from the index text of C++ objects.
21728 · C++, added concept directive. Thanks to mickk-on-cpp.
21730 · C++, added support for template introduction syntax. Thanks to
21732 mickk-on-cpp.
21733 · #2725: latex builder: allow to use user-defined template file (exper‐
21735 imental)
21736 · apidoc now avoids invalidating cached files by not writing to files
21738 whose content doesn’t change. This can lead to significant perfor‐
21739 mance wins if apidoc is run frequently.
21740 · #2851: sphinx.ext.math emits missing-reference event if equation not
21742 found
21743 · #1210: eqref role now supports cross reference
21745 · #2892: Added -a (--append-syspath) option to sphinx-apidoc
21747 · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
21749 · #646: option directive support ‘.’ character as a part of options
21751 · Add document about kindlegen and fix document structure for it.
21753 · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
21755 · #2926: EPUB3 builder supports vertical mode (epub3_writing_mode
21757 option)
21758 · #2695: build_sphinx subcommand for setuptools handles exceptions as
21760 same as sphinx-build does
21761 · #326: numref role can also refer sections
21763 · #2916: numref role can also refer caption as an its linktext
21765 1.5a2
21767 · #3008: linkcheck builder ignores self-signed certificate URL
21769 · #3020: new 'geometry' key to latex_elements whose default uses LaTeX
21771 style file geometry.sty to set page layout
21772 · #2843: Add :start-at: and :end-at: options to literalinclude direc‐
21774 tive
21775 · #2527: Add :reversed: option to toctree directive
21777 · Add -t and -d option to sphinx-quickstart to support templating gen‐
21779 erated sphinx project.
21780 · #3028: Add {path} and {basename} to the format of figure_lan‐
21782 guage_filename
21783 · new 'hyperref' key in the latex_elements dictionary (ref #3030)
21785 · #3022: Allow code-blocks in footnotes for LaTeX PDF output
21787 1.5b1
21789 · #2513: A better default settings for XeLaTeX
21791 · #3096: 'maxlistdepth' key to work around LaTeX list limitations
21793 · #3060: autodoc supports documentation for attributes of Enum class.
21795 Now autodoc render just the value of Enum attributes instead of Enum
21796 attribute representation.
21797 · Add --extensions to sphinx-quickstart to support enable arbitrary
21799 extensions from command line (ref: #2904)
21800 · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
21802 · #3071: Autodoc: Allow mocked module decorators to pass-through func‐
21804 tions unchanged
21805 · #2495: linkcheck: Allow skipping anchor checking using
21807 linkcheck_anchors_ignore
21808 · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
21810 · #3116: allow word wrap in PDF output for inline literals (ref #3110)
21812 · #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
21814 Nick Coghlan.
21815 · #3121: add inlineliteralwraps option to control if inline literal
21817 word-wraps in latex
21818 1.5 final
21820 · #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
21822 servers in linkcheck and intersphinx
21823 · #2215: make.bat generated by sphinx-quickstart can be called from
21825 another dir. Thanks to Timotheus Kampik.
21826 · #3185: Add new warning type misc.highlighting_failure
21828 Bugs fixed
21830 1.5a1
21831 · #2707: (latex) the column width is badly computed for tabular
21833 · #2799: Sphinx installs roles and directives automatically on import‐
21835 ing sphinx module. Now Sphinx installs them on running application.
21836 · sphinx.ext.autodoc crashes if target code imports * from mock modules
21838 by autodoc_mock_imports.
21839 · #1953: Sphinx.add_node does not add handlers the translator installed
21841 by html_translator_class
21842 · #1797: text builder inserts blank line on top
21844 · #2894: quickstart main() doesn’t use argv argument
21846 · #2874: gettext builder could not extract all text under the only
21848 directives
21849 · #2485: autosummary crashes with multiple source_suffix values
21851 · #1734: Could not translate the caption of toctree directive
21853 · Could not translate the content of meta directive (ref: #1734)
21855 · #2550: external links are opened in help viewer
21857 · #2687: Running Sphinx multiple times produces ‘already registered’
21859 warnings
21860 1.5a2
21862 · #2810: Problems with pdflatex in an Italian document
21864 · Use latex_elements.papersize to specify papersize of LaTeX in Make‐
21866 file
21867 · #2988: linkcheck: retry with GET request if denied HEAD request
21869 · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
21871 itly” error if linkcheck_anchors enabled
21872 · #3004: Invalid link types “top” and “up” are used
21874 · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
21876 · #3000: option directive generates invalid HTML anchors
21878 · #2984: Invalid HTML has been generated if html_split_index enabled
21880 · #2986: themes/basic/defindex.html should be changed for html5
21882 friendly
21883 · #2987: Invalid HTML has been generated if multiple IDs are assigned
21885 to a list
21886 · #2891: HTML search does not provide all the results
21888 · #1986: Title in PDF Output
21890 · #147: Problem with latex chapter style
21892 · #3018: LaTeX problem with page layout dimensions and chapter titles
21894 · Fix an issue with \pysigline in LaTeX style file (ref #3023)
21896 · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
21898 · #3031: incompatibility with LaTeX package tocloft
21900 · #3003: literal blocks in footnotes are not supported by Latex
21902 · #3047: spacing before footnote in pdf output is not coherent and
21904 allows breaks
21905 · #3045: HTML search index creator should ignore “raw” content if now
21907 html
21908 · #3039: English stemmer returns wrong word if the word is capitalized
21910 · Fix make-mode Makefile template (ref #3056, #2936)
21912 1.5b1
21914 · #2432: Fix unwanted * between varargs and keyword only args. Thanks
21916 to Alex Grönholm.
21917 · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
21919 panese documents since PR#3030)
21920 · Better rendering of multiline signatures in html.
21922 · #777: LaTeX output “too deeply nested” (ref #3096)
21924 · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
21926 #3059)
21927 · #3019: LaTeX fails on description of C function with arguments (ref
21929 #3083)
21930 · fix latex inline literals where < > - gobbled a space
21932 1.5 final
21934 · #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
21936 tains one \addto\captions...
21937 · #3123: user 'babel' key setting is not obeyed anymore
21939 · #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
21941 Opera
21942 · #3085: keep current directory after breaking build documentation.
21944 Thanks to Timotheus Kampik.
21945 · #3181: pLaTeX crashes with a section contains endash
21947 · #3180: latex: add stretch/shrink between successive singleline or
21949 multipleline cpp signatures (ref #3072)
21950 · #3128: globing images does not support .svgz file
21952 · #3015: fix a broken test on Windows.
21954 · #1843: Fix documentation of descriptor classes that have a custom
21956 metaclass. Thanks to Erik Bray.
21957 · #3190: util.split_docinfo fails to parse multi-line field bodies
21959 · #3024, #3037: In Python3, application.Sphinx._log crushed when the
21961 log message cannot be encoded into console encoding.
21962 Testing
21964 · To simplify, sphinx uses external mock package even if unittest.mock
21965 exists.
21966 Release 1.4.9 (released Nov 23, 2016)
21968 Bugs fixed
21969 · #2936: Fix doc/Makefile that can’t build man because doc/man exists
21970 · #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
21972 directives results in warning / error
21973 · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
21975 · #3074: add_source_parser() crashes in debug mode
21977 · #3135: sphinx.ext.autodoc crashes with plain Callable
21979 · #3150: Fix query word splitter in JavaScript. It behaves as same as
21981 Python’s regular expression.
21982 · #3093: gettext build broken on substituted images.
21984 · #3093: gettext build broken on image node under note directive.
21986 · imgmath: crashes on showing error messages if image generation failed
21988 · #3117: LaTeX writer crashes if admonition is placed before first sec‐
21990 tion title
21991 · #3164: Change search order of sphinx.ext.inheritance_diagram
21993 Release 1.4.8 (released Oct 1, 2016)
21995 Bugs fixed
21996 · #2996: The wheel package of Sphinx got crash with ImportError
21997 Release 1.4.7 (released Oct 1, 2016)
21999 Bugs fixed
22000 · #2890: Quickstart should return an error consistently on all error
22001 conditions
22002 · #2870: flatten genindex columns’ heights.
22004 · #2856: Search on generated HTML site doesn’t find some symbols
22006 · #2882: Fall back to a GET request on 403 status in linkcheck
22008 · #2902: jsdump.loads fails to load search index if keywords starts
22010 with underscore
22011 · #2900: Fix epub content.opf: add auto generated orphan files to
22013 spine.
22014 · #2899: Fix hasdoc() function in Jinja2 template. It will detect
22016 genindex, search also.
22017 · #2901: Fix epub result: skip creating links from image tags to origi‐
22019 nal image files.
22020 · #2917: inline code is hyphenated on HTML
22022 · #1462: autosummary warns for namedtuple with attribute with trailing
22024 underscore
22025 · Could not reference equations if :nowrap: option specified
22027 · #2873: code-block overflow in latex (due to commas)
22029 · #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
22031 relative paths are used in intersphinx_mapping
22032 · #2931: code-block directive with same :caption: causes warning of
22034 duplicate target. Now code-block and literalinclude does not define
22035 hyperlink target using its caption automatically.
22036 · #2962: latex: missing label of longtable
22038 · #2968: autodoc: show-inheritance option breaks docstrings
22040 Release 1.4.6 (released Aug 20, 2016)
22042 Incompatible changes
22043 · #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
22044 six-1.5 or later
22045 Bugs fixed
22047 · applehelp: Sphinx crashes if hiutil or codesign commands not found
22048 · Fix make clean abort issue when build dir contains regular files like
22050 DS_Store.
22051 · Reduce epubcheck warnings/errors:
22053 · Fix DOCTYPE to html5
22055 · Change extension from .html to .xhtml.
22057 · Disable search page on epub results
22059 · #2778: Fix autodoc crashes if obj.__dict__ is a property method and
22061 raises exception
22062 · Fix duplicated toc in epub3 output.
22064 · #2775: Fix failing linkcheck with servers not supporting identity
22066 encoding
22067 · #2833: Fix formatting instance annotations in ext.autodoc.
22069 · #1911: -D option of sphinx-build does not override the extensions
22071 variable
22072 · #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the
22074 inventory is given
22075 · parsing errors for caption of code-blocks are displayed in document
22077 (ref: #2845)
22078 · #2846: singlehtml builder does not include figure numbers
22080 · #2816: Fix data from builds cluttering the Domain.initial_data class
22082 attributes
22083 Release 1.4.5 (released Jul 13, 2016)
22085 Incompatible changes
22086 · latex, inclusion of non-inline images from image directive resulted
22087 in non-coherent whitespaces depending on original image width; new
22088 behaviour by necessity differs from earlier one in some cases. (ref:
22089 #2672)
22090 · latex, use of \includegraphics to refer to Sphinx custom variant is
22092 deprecated; in future it will revert to original LaTeX macro, custom
22093 one already has alternative name \sphinxincludegraphics.
22094 Features added
22096 · new config option latex_keep_old_macro_names, defaults to True. If
22097 False, lets macros (for text styling) be defined only with
22098 \sphinx-prefixed names
22099 · latex writer allows user customization of “shadowed” boxes (topics),
22101 via three length variables.
22102 · woff-format web font files now supported by the epub builder.
22104 Bugs fixed
22106 · jsdump fix for python 3: fixes the HTML search on python > 3
22107 · #2676: (latex) Error with verbatim text in captions since Sphinx
22109 1.4.4
22110 · #2629: memoir class crashes LaTeX. Fixed by
22112 latex_keep_old_macro_names=False (ref 2675)
22113 · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
22115 · #2679: float package needed for 'figure_align': 'H' latex option
22117 · #2671: image directive may lead to inconsistent spacing in pdf
22119 · #2705: toctree generates empty bullet_list if :titlesonly: specified
22121 · #2479: sphinx.ext.viewcode uses python2 highlighter by default
22123 · #2700: HtmlHelp builder has hard coded index.html
22125 · latex, since 1.4.4 inline literal text is followed by spurious space
22127 · #2722: C++, fix id generation for var/member declarations to include
22129 namespaces.
22130 · latex, images (from image directive) in lists or quoted blocks did
22132 not obey indentation (fixed together with #2671)
22133 · #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
22135 warnings
22136 · #2731: sphinx.ext.autodoc does not access propertymethods which
22138 raises any exceptions
22139 · #2666: C++, properly look up nested names involving constructors.
22141 · #2579: Could not refer a label including both spaces and colons via
22143 sphinx.ext.intersphinx
22144 · #2718: Sphinx crashes if the document file is not readable
22146 · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
22148 · #2723: extra spaces in latex pdf output from multirow cell
22150 · #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
22152 page
22153 · #2667: latex crashes if resized images appeared in section title
22155 · #2763: (html) Provide default value for required alt attribute for
22157 image tags of SVG source, required to validate and now consistent w/
22158 other formats.
22159 Release 1.4.4 (released Jun 12, 2016)
22161 Bugs fixed
22162 · #2630: latex: sphinx.sty notice environment formatting problem
22163 · #2632: Warning directives fail in quote environment latex build
22165 · #2633: Sphinx crashes with old styled indices
22167 · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
22169 · #2622: Latex produces empty pages after title and table of contents
22171 · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
22173 · Let LaTeX use straight quotes also in inline code (ref #2627)
22175 · #2351: latex crashes if enumerated lists are placed on footnotes
22177 · #2646: latex crashes if math contains twice empty lines
22179 · #2480: sphinx.ext.autodoc: memory addresses were shown
22181 · latex: allow code-blocks appearing inside lists and quotes at maximal
22183 nesting depth (ref #777, #2624, #2651)
22184 · #2635: Latex code directives produce inconsistent frames based on
22186 viewing resolution
22187 · #2639: Sphinx now bundles iftex.sty
22189 · Failed to build PDF with framed.sty 0.95
22191 · Sphinx now bundles needspace.sty
22193 Release 1.4.3 (released Jun 5, 2016)
22195 Bugs fixed
22196 · #2530: got “Counter too large” error on building PDF if large num‐
22197 bered footnotes existed in admonitions
22198 · width option of figure directive does not work if align option speci‐
22200 fied at same time (ref: #2595)
22201 · #2590: The inputenc package breaks compiling under lualatex and xela‐
22203 tex
22204 · #2540: date on latex front page use different font
22206 · Suppress “document isn’t included in any toctree” warning if the doc‐
22208 ument is included (ref: #2603)
22209 · #2614: Some tables in PDF output will end up shifted if user sets non
22211 zero parindent in preamble
22212 · #2602: URL redirection breaks the hyperlinks generated by
22214 sphinx.ext.intersphinx
22215 · #2613: Show warnings if merged extensions are loaded
22217 · #2619: make sure amstext LaTeX package always loaded (ref: d657225,
22219 488ee52, 9d82cad and #2615)
22220 · #2593: latex crashes if any figures in the table
22222 Release 1.4.2 (released May 29, 2016)
22224 Features added
22225 · Now suppress_warnings accepts following configurations (ref: #2451,
22226 #2466):
22227 · app.add_node
22229 · app.add_directive
22231 · app.add_role
22233 · app.add_generic_role
22235 · app.add_source_parser
22237 · image.data_uri
22239 · image.nonlocal_uri
22241 · #2453: LaTeX writer allows page breaks in topic contents; and their
22243 horizontal extent now fits in the line width (with shadow in margin).
22244 Also warning-type admonitions allow page breaks and their vertical
22245 spacing has been made more coherent with the one for hint-type
22246 notices (ref #2446).
22247 · #2459: the framing of literal code-blocks in LaTeX output (and not
22249 only the code lines themselves) obey the indentation in lists or
22250 quoted blocks.
22251 · #2343: the long source lines in code-blocks are wrapped (without mod‐
22253 ifying the line numbering) in LaTeX output (ref #1534, #2304).
22254 Bugs fixed
22256 · #2370: the equations are slightly misaligned in LaTeX writer
22257 · #1817, #2077: suppress pep8 warnings on conf.py generated by
22259 sphinx-quickstart
22260 · #2407: building docs crash if document includes large data image URIs
22262 · #2436: Sphinx does not check version by needs_sphinx if loading
22264 extensions failed
22265 · #2397: Setup shorthandoff for Turkish documents
22267 · #2447: VerbatimBorderColor wrongly used also for captions of PDF
22269 · #2456: C++, fix crash related to document merging (e.g., singlehtml
22271 and Latex builders).
22272 · #2446: latex(pdf) sets local tables of contents (or more generally
22274 topic nodes) in unbreakable boxes, causes overflow at bottom
22275 · #2476: Omit MathJax markers if :nowrap: is given
22277 · #2465: latex builder fails in case no caption option is provided to
22279 toctree directive
22280 · Sphinx crashes if self referenced toctree found
22282 · #2481: spelling mistake for mecab search splitter. Thanks to Naoki
22284 Sato.
22285 · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
22287 · intersphinx fails if mapping URL contains any port
22289 · #2088: intersphinx crashes if the mapping URL requires basic auth
22291 · #2304: auto line breaks in latexpdf codeblocks
22293 · #1534: Word wrap long lines in Latex verbatim blocks
22295 · #2460: too much white space on top of captioned literal blocks in PDF
22297 output
22298 · Show error reason when multiple math extensions are loaded (ref:
22300 #2499)
22301 · #2483: any figure number was not assigned if figure title contains
22303 only non text objects
22304 · #2501: Unicode subscript numbers are normalized in LaTeX
22306 · #2492: Figure directive with :figwidth: generates incorrect
22308 Latex-code
22309 · The caption of figure is always put on center even if :align: was
22311 specified
22312 · #2526: LaTeX writer crashes if the section having only images
22314 · #2522: Sphinx touches mo files under installed directory that caused
22316 permission error.
22317 · #2536: C++, fix crash when an immediately nested scope has the same
22319 name as the current scope.
22320 · #2555: Fix crash on any-references with unicode.
22322 · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
22324 · #2521: generated Makefile causes BSD make crashed if sphinx-build not
22326 found
22327 · #2470: typing backport package causes autodoc errors with python 2.7
22329 · sphinx.ext.intersphinx crashes if non-string value is used for key of
22331 intersphinx_mapping
22332 · #2518: intersphinx_mapping disallows non alphanumeric keys
22334 · #2558: unpack error on devhelp builder
22336 · #2561: Info builder crashes when a footnote contains a link
22338 · #2565: The descriptions of objects generated by sphinx.ext.autosum‐
22340 mary overflow lines at LaTeX writer
22341 · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
22343 · #2445: rst_prolog and rst_epilog affect to non reST sources
22345 · #2576: sphinx.ext.imgmath crashes if subprocess raises error
22347 · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
22349 · #2556: Xapian search does not work with Python 3
22351 · #2581: The search doesn’t work if language=”es” (Spanish)
22353 · #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
22355 writer
22356 · #2383: The generated footnote by latex_show_urls overflows lines
22358 · #2497, #2552: The label of search button does not fit for the button
22360 itself
22361 Release 1.4.1 (released Apr 12, 2016)
22363 Incompatible changes
22364 · The default format of today_fmt and html_last_updated_fmt is back to
22365 strftime format again. Locale Date Markup Language is also supported
22366 for backward compatibility until Sphinx-1.5.
22367 Translations
22369 · Added Welsh translation, thanks to Geraint Palmer.
22370 · Added Greek translation, thanks to Stelios Vitalis.
22372 · Added Esperanto translation, thanks to Dinu Gherman.
22374 · Added Hindi translation, thanks to Purnank H. Ghumalia.
22376 · Added Romanian translation, thanks to Razvan Stefanescu.
22378 Bugs fixed
22380 · C++, added support for extern and thread_local.
22381 · C++, type declarations are now using the prefixes typedef, using, and
22383 type, depending on the style of declaration.
22384 · #2413: C++, fix crash on duplicate declarations
22386 · #2394: Sphinx crashes when html_last_updated_fmt is invalid
22388 · #2408: dummy builder not available in Makefile and make.bat
22390 · #2412: hyperlink targets are broken in LaTeX builder
22392 · figure directive crashes if non paragraph item is given as caption
22394 · #2418: time formats no longer allowed in today_fmt
22396 · #2395: Sphinx crashes if unicode character in image filename
22398 · #2396: “too many values to unpack” in genindex-single
22400 · #2405: numref link in PDF jumps to the wrong location
22402 · #2414: missing number in PDF hyperlinks to code listings
22404 · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
22406 Release 1.4 (released Mar 28, 2016)
22408 Incompatible changes
22409 · Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
22410 Stemmer to accelerate stemming.
22411 · sphinx_rtd_theme has become optional. Please install it manually.
22413 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
22414 · #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
22416 It enables to take title of roles as an argument of custom macros.
22417 · #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns
22419 default values in conf.py that will be provided on sphinx-quickstart.
22420 · #2027, #2208: The html_title accepts string values only. And The None
22422 value cannot be accepted.
22423 · sphinx.ext.graphviz: show graph image in inline by default
22425 · #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
22427 node instead of sphinx.addnodes.literal_emphasis node.
22428 · #2022: html_extra_path also copies dotfiles in the extra directory,
22430 and refers to exclude_patterns to exclude extra files and directo‐
22431 ries.
22432 · #2300: enhance autoclass:: to use the docstring of __new__ if
22434 __init__ method’s is missing of empty
22435 · #2251: Previously, under glossary directives, multiple terms for one
22437 definition are converted into single term node and the each terms in
22438 the term node are separated by termsep node. In new implementation,
22439 each terms are converted into individual term nodes and termsep node
22440 is removed. By this change, output layout of every builders are
22441 changed a bit.
22442 · The default highlight language is now Python 3. This means that
22444 source code is highlighted as Python 3 (which is mostly a superset of
22445 Python 2), and no parsing is attempted to distinguish valid code. To
22446 get the old behavior back, add highlight_language = "python" to
22447 conf.py.
22448 · Locale Date Markup Language like "MMMM dd, YYYY" is default format
22450 for today_fmt and html_last_updated_fmt. However strftime format
22451 like "%B %d, %Y" is also supported for backward compatibility until
22452 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
22453 · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
22455 ing instead.
22456 · #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
22458 writer.
22459 · #1498: manpage writer: don’t make whole of item in definition list
22461 bold if it includes strong node.
22462 · #582: Remove hint message from quick search box for html output.
22464 · #2378: Sphinx now bundles newfloat.sty
22466 Features added
22468 · #2092: add todo directive support in napoleon package.
22469 · #1962: when adding directives, roles or nodes from an extension, warn
22471 if such an element is already present (built-in or added by another
22472 extension).
22473 · #1909: Add “doc” references to Intersphinx inventories.
22475 · C++ type alias support (e.g., .. type:: T = int).
22477 · C++ template support for classes, functions, type aliases, and vari‐
22479 ables (#1729, #1314).
22480 · C++, added new scope management directives namespace-push and names‐
22482 pace-pop.
22483 · #1970: Keyboard shortcuts to navigate Next and Previous topics
22485 · Intersphinx: Added support for fetching Intersphinx inventories with
22487 URLs using HTTP basic auth.
22488 · C++, added support for template parameter in function info field
22490 lists.
22491 · C++, added support for pointers to member (function).
22493 · #2113: Allow :class: option to code-block directive.
22495 · #2192: Imgmath (pngmath with svg support).
22497 · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
22499 · #1906: Use xcolor over color for fcolorbox where available for LaTeX
22501 output.
22502 · #2216: Texinputs makefile improvements.
22504 · #2170: Support for Chinese language search index.
22506 · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
22508 · #1030: Make page reference names for latex_show_pagerefs translatable
22510 · #2162: Add Sphinx.add_source_parser() to add source_suffix and
22512 source_parsers from extension
22513 · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
22515 · #656: Add graphviz_dot option to graphviz directives to switch the
22517 dot command
22518 · #1939: Added the dummy builder: syntax check without output.
22520 · #2230: Add math_number_all option to number all displayed math in
22522 math extensions
22523 · #2235: needs_sphinx supports micro version comparison
22525 · #2282: Add “language” attribute to html tag in the “basic” theme
22527 · #1779: Add EPUB 3 builder
22529 · #1751: Add todo_link_only to avoid file path and line indication on
22531 todolist. Thanks to Francesco Montesano.
22532 · #2199: Use imagesize package to obtain size of images.
22534 · #1099: Add configurable retries to the linkcheck builder. Thanks to
22536 Alex Gaynor. Also don’t check anchors starting with !.
22537 · #2300: enhance autoclass:: to use the docstring of __new__ if
22539 __init__ method’s is missing of empty
22540 · #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
22542 numfig feature
22543 · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
22545 erence sections using its title. Thanks to Tadhg O’Higgins.
22546 · #1854: Allow to choose Janome for Japanese splitter.
22548 · #1853: support custom text splitter on html search with lan‐
22550 guage='ja'.
22551 · #2320: classifier of glossary terms can be used for index entries
22553 grouping key The classifier also be used for translation. See also
22554 glossary-directive.
22555 · #2308: Define \tablecontinued macro to redefine the style of contin‐
22557 ued label for longtables.
22558 · Select an image by similarity if multiple images are globbed by ..
22560 image:: filename.*
22561 · #1921: Support figure substitutions by language and figure_lan‐
22563 guage_filename
22564 · #2245: Add latex_elements["passoptionstopackages"] option to call
22566 PassOptionsToPackages in early stage of preambles.
22567 · #2340: Math extension: support alignment of multiple equations for
22569 MathJax.
22570 · #2338: Define \titleref macro to redefine the style of title-refer‐
22572 ence roles.
22573 · Define \menuselection and \accelerator macros to redefine the style
22575 of menuselection roles.
22576 · Define \crossref macro to redefine the style of references
22578 · #2301: Texts in the classic html theme should be hyphenated.
22580 · #2355: Define \termref macro to redefine the style of term roles.
22582 · Add suppress_warnings to suppress arbitrary warning message (experi‐
22584 mental)
22585 · #2229: Fix no warning is given for unknown options
22587 · #2327: Add latex_toplevel_sectioning to switch the top level section‐
22589 ing of LaTeX document.
22590 Bugs fixed
22592 · #1913: C++, fix assert bug for enumerators in next-to-global and
22593 global scope.
22594 · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
22596 · C++, add missing support for ‘friend’ functions.
22598 · C++, add missing support for virtual base classes (thanks to Rapptz).
22600 · C++, add support for final classes.
22602 · C++, fix parsing of types prefixed with ‘enum’.
22604 · #2023: Dutch search support uses Danish stemming info.
22606 · C++, add support for user-defined literals.
22608 · #1804: Now html output wraps overflowed long-line-text in the side‐
22610 bar. Thanks to Hassen ben tanfous.
22611 · #2183: Fix porterstemmer causes make json to fail.
22613 · #1899: Ensure list is sent to OptParse.
22615 · #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
22617 package option).
22618 · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
22620 · Fix broken LaTeX code is generated if unknown language is given
22622 · #1944: Fix rst_prolog breaks file-wide metadata
22624 · #2074: make gettext should use canonical relative paths for .pot.
22626 Thanks to anatoly techtonik.
22627 · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
22629 · #2251: Line breaks in .rst files are transferred to .pot files in a
22631 wrong way.
22632 · #794: Fix date formatting in latex output is not localized
22634 · Remove image/gif from supported_image_types of LaTeX writer (#2272)
22636 · Fix ValueError is raised if LANGUAGE is empty string
22638 · Fix unpack warning is shown when the directives generated from
22640 Sphinx.add_crossref_type is used
22641 · The default highlight language is now default. This means that
22643 source code is highlighted as Python 3 (which is mostly a superset of
22644 Python 2) if possible. To get the old behavior back, add high‐
22645 light_language = "python" to conf.py.
22646 · #2329: Refresh environment forcedly if source directory has changed.
22648 · #2331: Fix code-blocks are filled by block in dvi; remove xcdraw
22650 option from xcolor package
22651 · Fix the confval type checker emits warnings if unicode is given to
22653 confvals which expects string value
22654 · #2360: Fix numref in LaTeX output is broken
22656 · #2361: Fix additional paragraphs inside the “compound” directive are
22658 indented
22659 · #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
22661 sion.
22662 · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
22664 · #2368: Ignore emacs lock files like .#foo.rst by default.
22666 · #2262: literal_block and its caption has been separated by pagebreak
22668 in LaTeX output.
22669 · #2319: Fix table counter is overridden by code-block’s in LaTeX.
22671 Thanks to jfbu.
22672 · Fix unpack warning if combined with 3rd party domain extensions.
22674 · #1153: Fix figures in sidebar causes latex build error.
22676 · #2358: Fix user-preamble could not override the tocdepth definition.
22678 · #2358: Reduce tocdepth if part or chapter is used for top_section‐
22680 level
22681 · #2351: Fix footnote spacing
22683 · #2363: Fix toctree() in templates generates broken links in Single‐
22685 HTMLBuilder.
22686 · #2366: Fix empty hyperref is generated on toctree in HTML builder.
22688 Documentation
22690 · #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
22691 mecke.
22692 Release 1.3.6 (released Feb 29, 2016)
22694 Features added
22695 · #1873, #1876, #2278: Add page_source_suffix html context variable.
22696 This should be introduced with source_parsers feature. Thanks for
22697 Eric Holscher.
22698 Bugs fixed
22700 · #2265: Fix babel is used in spite of disabling it on latex_elements
22701 · #2295: Avoid mutating dictionary errors while enumerating members in
22703 autodoc with Python 3
22704 · #2291: Fix pdflatex “Counter too large” error from footnotes inside
22706 tables of contents
22707 · #2292: Fix some footnotes disappear from LaTeX output
22709 · #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
22711 feature should support parsers that specified source_parsers.
22712 · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
22714 of math fonts
22715 · #2324: Print a hint how to increase the recursion limit when it is
22717 hit.
22718 · #1565, #2229: Revert new warning; the new warning will be triggered
22720 from version 1.4 on.
22721 · #2329: Refresh environment forcedly if source directory has changed.
22723 · #2019: Fix the domain objects in search result are not escaped
22725 Release 1.3.5 (released Jan 24, 2016)
22727 Bugs fixed
22728 · Fix line numbers was not shown on warnings in LaTeX and texinfo
22729 builders
22730 · Fix filenames were not shown on warnings of citations
22732 · Fix line numbers was not shown on warnings in LaTeX and texinfo
22734 builders
22735 · Fix line numbers was not shown on warnings of indices
22737 · #2026: Fix LaTeX builder raises error if parsed-literal includes
22739 links
22740 · #2243: Ignore strange docstring types for classes, do not crash
22742 · #2247: Fix #2205 breaks make html for definition list with classi‐
22744 fiers that contains regular-expression like string
22745 · #1565: Sphinx will now emit a warning that highlighting was skipped
22747 if the syntax is incorrect for code-block, literalinclude and so on.
22748 · #2211: Fix paragraphs in table cell doesn’t work in Latex output
22750 · #2253: :pyobject: option of literalinclude directive can’t detect
22752 indented body block when the block starts with blank or comment
22753 lines.
22754 · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
22756 · Fix warning message for :numref: if target is in orphaned doc (ref:
22758 #2244)
22759 Release 1.3.4 (released Jan 12, 2016)
22761 Bugs fixed
22762 · #2134: Fix figure caption with reference causes latex build error
22763 · #2094: Fix rubric with reference not working in Latex
22765 · #2147: Fix literalinclude code in latex does not break in pages
22767 · #1833: Fix email addresses is showed again if latex_show_urls is not
22769 None
22770 · #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
22772 svg
22773 · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
22775 · #1237: Fix footnotes not working in definition list in LaTeX
22777 · #2168: Fix raw directive does not work for text writer
22779 · #2171: Fix cannot linkcheck url with unicode
22781 · #2182: LaTeX: support image file names with more than 1 dots
22783 · #2189: Fix previous sibling link for first file in subdirectory uses
22785 last file, not intended previous from root toctree
22786 · #2003: Fix decode error under python2 (only) when make linkcheck is
22788 run
22789 · #2186: Fix LaTeX output of mathbb in math
22791 · #1480, #2188: LaTeX: Support math in section titles
22793 · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
22795 Bug
22796 · #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
22798 non-ascii characters
22799 · #2193: Fix shutil.SameFileError if source directory and destination
22801 directory are same
22802 · #2178: Fix unparsable C++ cross-reference when referencing a function
22804 with :cpp:any:
22805 · #2206: Fix Sphinx latex doc build failed due to a footnotes
22807 · #2201: Fix wrong table caption for tables with over 30 rows
22809 · #2213: Set <blockquote> in the classic theme to fit with <p>
22811 · #1815: Fix linkcheck does not raise an exception if warniserror set
22813 to true and link is broken
22814 · #2197: Fix slightly cryptic error message for missing index.rst file
22816 · #1894: Unlisted phony targets in quickstart Makefile
22818 · #2125: Fix unifies behavior of collapsed fields (GroupedField and
22820 TypedField)
22821 · #1408: Check latex_logo validity before copying
22823 · #771: Fix latex output doesn’t set tocdepth
22825 · #1820: On Windows, console coloring is broken with colorama version
22827 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
22828 · #2072: Fix footnotes in chapter-titles do not appear in PDF output
22830 · #1580: Fix paragraphs in longtable don’t work in Latex output
22832 · #1366: Fix centered image not centered in latex
22834 · #1860: Fix man page using :samp: with braces - font doesn’t reset
22836 · #1610: Sphinx crashes in Japanese indexing in some systems
22838 · Fix Sphinx crashes if mecab initialization failed
22840 · #2160: Fix broken TOC of PDFs if section includes an image
22842 · #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty.
22844 Thanks to jfbu.
22845 · #2198,#2205: make gettext generate broken msgid for definition lists.
22847 · #2062: Escape characters in doctests are treated incorrectly with
22849 Python 2.
22850 · #2225: Fix if the option does not begin with dash, linking is not
22852 performed
22853 · #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
22855 mathjax)
22856 · #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
22858 extensions doesn’t support resolve_any_xref and resolve_xref returns
22859 problematic node instead of None. sphinxcontrib-httpdomain is one of
22860 them.
22861 · #2229: Fix no warning is given for unknown options
22863 Release 1.3.3 (released Dec 2, 2015)
22865 Bugs fixed
22866 · #2177: Fix parallel hangs
22867 · #2012: Fix exception occurred if numfig_format is invalid
22869 · #2142: Provide non-minified JS code in sphinx/search/non-mini‐
22871 fied-js/*.js for source distribution on PyPI.
22872 · #2148: Error while building devhelp target with non-ASCII document.
22874 Release 1.3.2 (released Nov 29, 2015)
22876 Features added
22877 · #1935: Make “numfig_format” overridable in latex_elements.
22878 Bugs fixed
22880 · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
22881 dows environment.
22882 · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
22884 patibility
22885 · #1788: graphviz extension raises exception when caption option is
22887 present.
22888 · #1789: :pyobject: option of literalinclude directive includes follow‐
22890 ing lines after class definitions
22891 · #1790: literalinclude strips empty lines at the head and tail
22893 · #1802: load plugin themes automatically when theme.conf use it as
22895 ‘inherit’. Thanks to Takayuki Hirai.
22896 · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
22898 find base theme.
22899 · #1834: compatibility for docutils-0.13: handle_io_errors keyword
22901 argument for docutils.io.FileInput cause TypeError.
22902 · #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
22904 error. Now ‘.’ is converted to absolute path automatically.
22905 · Fix a crash when setting up extensions which do not support metadata.
22907 · #1784: Provide non-minified JS code in sphinx/search/non-mini‐
22909 fied-js/*.js
22910 · #1822, #1892: Fix regression for #1061. autosummary can’t generate
22912 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
22913 · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
22915 Takayuki Hirai.
22916 · #1780, #1866: “make text” shows “class” keyword twice. Thanks to
22918 Takayuki Hirai.
22919 · #1871: Fix for LaTeX output of tables with one column and multirows.
22921 · Work around the lack of the HTMLParserError exception in Python 3.5.
22923 · #1949: Use safe_getattr in the coverage builder to avoid aborting
22925 with descriptors that have custom behavior.
22926 · #1915: Do not generate smart quotes in doc field type annotations.
22928 · #1796: On py3, automated .mo building caused UnicodeDecodeError.
22930 · #1923: Use babel features only if the babel latex element is
22932 nonempty.
22933 · #1942: Fix a KeyError in websupport.
22935 · #1903: Fix strange id generation for glossary terms.
22937 · make text will crush if a definition list item has more than 1 clas‐
22939 sifiers as: term : classifier1 : classifier2.
22940 · #1855: make gettext generates broken po file for definition lists
22942 with classifier.
22943 · #1869: Fix problems when dealing with files containing non-ASCII
22945 characters. Thanks to Marvin Schmidt.
22946 · #1798: Fix building LaTeX with references in titles.
22948 · #1725: On py2 environment, doctest with using non-ASCII characters
22950 causes 'ascii' codec can't decode byte exception.
22951 · #1540: Fix RuntimeError with circular referenced toctree
22953 · #1983: i18n translation feature breaks references which uses section
22955 name.
22956 · #1990: Use caption of toctree to title of tableofcontents in LaTeX
22958 · #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
22960 LaTeX builder
22961 · #1994: More supporting non-standard parser (like recommonmark parser)
22963 for Translation and WebSupport feature. Now node.rawsource is fall
22964 backed to node.astext() during docutils transforming.
22965 · #1989: “make blahblah” on Windows indicate help messages for
22967 sphinx-build every time. It was caused by wrong make.bat that gener‐
22968 ated by Sphinx-1.3.0/1.3.1.
22969 · On Py2 environment, conf.py that is generated by sphinx-quickstart
22971 should have u prefixed config value for ‘version’ and ‘release’.
22972 · #2102: On Windows + Py3, using |today| and non-ASCII date format will
22974 raise UnicodeEncodeError.
22975 · #1974: UnboundLocalError: local variable ‘domain’ referenced before
22977 assignment when using any role and sphinx.ext.intersphinx in same
22978 time.
22979 · #2121: multiple words search doesn’t find pages when words across on
22981 the page title and the page content.
22982 · #1884, #1885: plug-in html themes cannot inherit another plug-in
22984 theme. Thanks to Suzumizaki.
22985 · #1818: sphinx.ext.todo directive generates broken html class
22987 attribute as ‘admonition-‘ when language is specified with non-ASCII
22988 linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive
22989 can use :class: option.
22990 · #2140: Fix footnotes in table has broken in LaTeX
22992 · #2127: MecabBinder for html searching feature doesn’t work with
22994 Python 3. Thanks to Tomoko Uchida.
22995 Release 1.3.1 (released Mar 17, 2015)
22997 Bugs fixed
22998 · #1769: allows generating quickstart files/dirs for destination dir
22999 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
23000 rou.
23001 · #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
23003 option argument.
23004 · #1766: the message “least Python 2.6 to run” is at best misleading.
23006 · #1772: cross reference in docstrings like :param .write: breaks
23008 building.
23009 · #1770, #1774: literalinclude with empty file occurs exception. Thanks
23011 to Takayuki Hirai.
23012 · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
23014 · #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
23016 sion.
23017 · #1771: automated .mo building doesn’t work properly.
23019 · #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
23021 Jens Hedegaard Nielsen.
23022 · #1781: Setting html_domain_indices to a list raises a type check
23024 warnings.
23025 Release 1.3 (released Mar 10, 2015)
23027 Incompatible changes
23028 · Roles ref, term and menusel now don’t generate emphasis nodes any‐
23029 more. If you want to keep italic style, adapt your stylesheet.
23030 · Role numref uses %s as special character to indicate position of fig‐
23032 ure numbers instead # symbol.
23033 Features added
23035 · Add convenience directives and roles to the C++ domain: directive
23036 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
23037 ber, and role any for cross-reference to any C++ declaraction. #1577,
23038 #1744
23039 · The source_suffix config value can now be a list of multiple suf‐
23041 fixes.
23042 · Add the ability to specify source parsers by source suffix with the
23044 source_parsers config value.
23045 · #1675: A new builder, AppleHelpBuilder, has been added that builds
23047 Apple Help Books.
23048 Bugs fixed
23050 · 1.3b3 change breaks a previous gettext output that contains dupli‐
23051 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
23052 · #1745: latex builder cause maximum recursion depth exceeded when a
23054 footnote has a footnote mark itself.
23055 · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
23057 · #1658, #1750: No link created (and warning given) if option does not
23059 begin with -, / or +. Thanks to Takayuki Hirai.
23060 · #1753: C++, added missing support for more complex declarations.
23062 · #1700: Add :caption: option for toctree.
23064 · #1742: :name: option is provided for toctree, code-block and literal‐
23066 include directives.
23067 · #1756: Incorrect section titles in search that was introduced from
23069 1.3b3.
23070 · #1746: C++, fixed name lookup procedure, and added missing lookups in
23072 declarations.
23073 · #1765: C++, fix old id generation to use fully qualified names.
23075 Documentation
23077 · #1651: Add vartype field description for python domain.
23078 Release 1.3b3 (released Feb 24, 2015)
23080 Incompatible changes
23081 · Dependency requirement updates: docutils 0.11, Pygments 2.0
23082 · The gettext_enables config value has been renamed to gettext_addi‐
23084 tional_targets.
23085 · #1735: Use https://docs.python.org/ instead of http protocol. It was
23087 used for sphinx.ext.intersphinx and some documentation.
23088 Features added
23090 · #1346: Add new default theme;
23091 · Add ‘alabaster’ theme.
23093 · Add ‘sphinx_rtd_theme’ theme.
23095 · The ‘default’ html theme has been renamed to ‘classic’. ‘default’
23097 is still available, however it will emit notice a recommendation
23098 that using new ‘alabaster’ theme.
23099 · Added highlight_options configuration value.
23101 · The language config value is now available in the HTML templates.
23103 · The env-updated event can now return a value, which is interpreted as
23105 an iterable of additional docnames that need to be rewritten.
23106 · #772: Support for scoped and unscoped enums in C++. Enumerators in
23108 unscoped enums are injected into the parent scope in addition to the
23109 enum scope.
23110 · Add todo_include_todos config option to quickstart conf file, handled
23112 as described in documentation.
23113 · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
23115 nav-item-0, 1, 2…).
23116 · New option sphinx-quickstart --use-make-mode for generating Makefile
23118 that use sphinx-build make-mode.
23119 · #1235: i18n: several node can be translated if it is set to get‐
23121 text_additional_targets in conf.py. Supported nodes are:
23122 · ‘literal-block’
23124 · ‘doctest-block’
23126 · ‘raw’
23128 · ‘image’
23130 · #1227: Add html_scaled_image_link config option to conf.py, to con‐
23132 trol scaled image link.
23133 Bugs fixed
23135 · LaTeX writer now generates correct markup for cells spanning multiple
23136 rows.
23137 · #1674: Do not crash if a module’s __all__ is not a list of strings.
23139 · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
23141 · On windows, make-mode didn’t work on Win32 platform if sphinx was
23143 invoked as python sphinx-build.py.
23144 · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
23146 · #1690: toctrees with glob option now can also contain entries for
23148 single documents with explicit title.
23149 · #1591: html search results for C++ elements now has correct interpage
23151 links.
23152 · bizstyle theme: nested long title pages make long breadcrumb that
23154 breaks page layout.
23155 · bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
23157 browser (iPhone5s safari).
23158 · #1722: restore toctree() template function behavior that was changed
23160 at 1.3b1.
23161 · #1732: i18n: localized table caption raises exception.
23163 · #1718: :numref: does not work with capital letters in the label
23165 · #1630: resolve CSS conflicts, div.container css target for literal
23167 block wrapper now renamed to div.literal-block-wrapper.
23168 · sphinx.util.pycompat has been restored in its backwards-compatibil‐
23170 ity; slated for removal in Sphinx 1.4.
23171 · #1719: LaTeX writer does not respect numref_format option in captions
23173 Release 1.3b2 (released Dec 5, 2014)
23175 Incompatible changes
23176 · update bundled ez_setup.py for setuptools-7.0 that requires Python
23177 2.6 or later.
23178 Features added
23180 · #1597: Added possibility to return a new template name from
23181 html-page-context.
23182 · PR#314, #1150: Configuration values are now checked for their type.
23184 A warning is raised if the configured and the default value do not
23185 have the same type and do not share a common non-trivial base class.
23186 Bugs fixed
23188 · PR#311: sphinx-quickstart does not work on python 3.4.
23189 · Fix autodoc_docstring_signature not working with signatures in class
23191 docstrings.
23192 · Rebuilding cause crash unexpectedly when source files were added.
23194 · #1607: Fix a crash when building latexpdf with “howto” class
23196 · #1251: Fix again. Sections which depth are lower than :tocdepth:
23198 should not be shown on localtoc sidebar.
23199 · make-mode didn’t work on Win32 platform if sphinx was installed by
23201 wheel package.
23202 Release 1.3b1 (released Oct 10, 2014)
23204 Incompatible changes
23205 · Dropped support for Python 2.5, 3.1 and 3.2.
23206 · Dropped support for docutils versions up to 0.9.
23208 · Removed the sphinx.ext.oldcmarkup extension.
23210 · The deprecated config values exclude_trees, exclude_dirnames and
23212 unused_docs have been removed.
23213 · A new node, sphinx.addnodes.literal_strong, has been added, for text
23215 that should appear literally (i.e. no smart quotes) in strong font.
23216 Custom writers will have to be adapted to handle this node.
23217 · PR#269, #1476: replace <tt> tag by <code>. User customized
23219 stylesheets should be updated If the css contain some styles for tt>
23220 tag. Thanks to Takeshi Komiya.
23221 · #1543: templates_path is automatically added to exclude_patterns to
23223 avoid reading autosummary rst templates in the templates directory.
23224 · Custom domains should implement the new Domain.resolve_any_xref
23226 method to make the any role work properly.
23227 · gettext builder: gettext doesn’t emit uuid information to generated
23229 pot files by default. Please set True to gettext_uuid to emit uuid
23230 information. Additionally, if the python-levenshtein 3rd-party pack‐
23231 age is installed, it will improve the calculation time.
23232 · gettext builder: disable extracting/apply ‘index’ node by default.
23234 Please set ‘index’ to gettext_enables to enable extracting index
23235 entries.
23236 · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
23238 Features added
23240 · Add support for Python 3.4.
23241 · Add support for docutils 0.12
23243 · Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
23245 string support.
23246 · Added support for parallel reading (parsing) of source files with the
23248 sphinx-build -j option. Third-party extensions will need to be
23249 checked for compatibility and may need to be adapted if they store
23250 information in the build environment object. See env-merge-info.
23251 · Added the any role that can be used to find a cross-reference of any
23253 type in any domain. Custom domains should implement the new
23254 Domain.resolve_any_xref method to make this work properly.
23255 · Exception logs now contain the last 10 messages emitted by Sphinx.
23257 · Added support for extension versions (a string returned by setup(),
23259 these can be shown in the traceback log files). Version requirements
23260 for extensions can be specified in projects using the new
23261 needs_extensions config value.
23262 · Changing the default role within a document with the default-role
23264 directive is now supported.
23265 · PR#214: Added stemming support for 14 languages, so that the built-in
23267 document search can now handle these. Thanks to Shibukawa Yoshiki.
23268 · PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
23270 tables and code-blocks. This feature is configured with numfig, num‐
23271 fig_secnum_depth and numfig_format. Also numref role is available.
23272 Thanks to Takeshi Komiya.
23273 · PR#202: Allow “.” and “~” prefixed references in :param: doc fields
23275 for Python.
23276 · PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
23278 nal modules that need not be present when autodocumenting.
23279 · #925: Allow list-typed config values to be provided on the command
23281 line, like -D key=val1,val2.
23282 · #668: Allow line numbering of code-block and literalinclude direc‐
23284 tives to start at an arbitrary line number, with a new lineno-start
23285 option.
23286 · PR#172, PR#266: The code-block and literalinclude directives now can
23288 have a caption option that shows a filename before the code in the
23289 output. Thanks to Nasimul Haque, Takeshi Komiya.
23290 · Prompt for the document language in sphinx-quickstart.
23292 · PR#217: Added config values to suppress UUID and location information
23294 in generated gettext catalogs.
23295 · PR#236, #1456: apidoc: Add a -M option to put module documentation
23297 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
23298 · #1434: Provide non-minified JS files for jquery.js and underscore.js
23300 to clarify the source of the minified files.
23301 · PR#252, #1291: Windows color console support. Thanks to meu31.
23303 · PR#255: When generating latex references, also insert latex tar‐
23305 get/anchor for the ids defined on the node. Thanks to Olivier
23306 Heurtier.
23307 · PR#229: Allow registration of other translators. Thanks to Russell
23309 Sim.
23310 · Add app.set_translator() API to register or override a Docutils
23312 translator class like html_translator_class.
23313 · PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
23315 Richard Wall and WAKAYAMA shirou.
23316 · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
23318 · Automatically compile *.mo files from *.po files when get‐
23320 text_auto_build is True (default) and *.po is newer than *.mo file.
23321 · #623: sphinx.ext.viewcode supports imported function/class aliases.
23323 · PR#275: sphinx.ext.intersphinx supports multiple target for the
23325 inventory. Thanks to Brigitta Sipocz.
23326 · PR#261: Added the env-before-read-docs event that can be connected to
23328 modify the order of documents before they are read by the environ‐
23329 ment.
23330 · #1284: Program options documented with option can now start with +.
23332 · PR#291: The caption of code-block is recognized as a title of ref
23334 target. Thanks to Takeshi Komiya.
23335 · PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
23337 · #1344: add gettext_enables to enable extracting ‘index’ to gettext
23339 catalog output / applying translation catalog to generated documenta‐
23340 tion.
23341 · PR#301, #1583: Allow the line numbering of the directive literalin‐
23343 clude to match that of the included file, using a new lineno-match
23344 option. Thanks to Jeppe Pihl.
23345 · PR#299: add various options to sphinx-quickstart. Quiet mode option
23347 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
23348 · #1623: Return types specified with :rtype: are now turned into links
23350 if possible.
23351 Bugs fixed
23353 · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
23354 · #1568: Fix a crash when a “centered” directive contains a reference.
23356 · Now sphinx.ext.autodoc works with python-2.5 again.
23358 · #1563: add_search_language() raises AssertionError for correct type
23360 of argument. Thanks to rikoman.
23361 · #1174: Fix smart quotes being applied inside roles like program or
23363 makevar.
23364 · PR#235: comment db schema of websupport lacked a length of the
23366 node_id field. Thanks to solos.
23367 · #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
23369 “variadic templates” declarations. Thanks to Victor Zverovich.
23370 · #1459,PR#244: Fix default mathjax js path point to http:// that cause
23372 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
23373 · PR#157: autodoc remove spurious signatures from @property decorated
23375 attributes. Thanks to David Ham.
23376 · PR#159: Add coverage targets to quickstart generated Makefile and
23378 make.bat. Thanks to Matthias Troffaes.
23379 · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
23381 data, sub section number that is larger depth than :tocdepth: is
23382 shrunk.
23383 · PR#260: Encode underscore in citation labels for latex export. Thanks
23385 to Lennart Fricke.
23386 · PR#264: Fix could not resolve xref for figure node with :name:
23388 option. Thanks to Takeshi Komiya.
23389 · PR#265: Fix could not capture caption of graphviz node by xref.
23391 Thanks to Takeshi Komiya.
23392 · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
23394 Andersen.
23395 · Hyperlinks to all found nested names and template arguments
23397 (#1103).
23398 · Support for function types everywhere, e.g., in std::func‐
23400 tion<bool(int, int)> (#1013).
23401 · Support for virtual functions.
23403 · Changed interpretation of function arguments to following standard
23405 prototype declarations, i.e., void f(arg) means that arg is the
23406 type of the argument, instead of it being the name.
23407 · Updated tests.
23409 · Updated documentation with elaborate description of what declara‐
23411 tions are supported and how the namespace declarations influence
23412 declaration and cross-reference lookup.
23413 · Index names may be different now. Elements are indexed by their
23415 fully qualified name. It should be rather easy to change this be‐
23416 haviour and potentially index by namespaces/classes as well.
23417 · PR#258, #939: Add dedent option for code-block and literalinclude.
23419 Thanks to Zafar Siddiqui.
23420 · PR#268: Fix numbering section does not work at singlehtml mode. It
23422 still ad-hoc fix because there is a issue that section IDs are con‐
23423 flicted. Thanks to Takeshi Komiya.
23424 · PR#273, #1536: Fix RuntimeError with numbered circular toctree.
23426 Thanks to Takeshi Komiya.
23427 · PR#274: Set its URL as a default title value if URL appears in toc‐
23429 tree. Thanks to Takeshi Komiya.
23430 · PR#276, #1381: rfc and pep roles support custom link text. Thanks to
23432 Takeshi Komiya.
23433 · PR#277, #1513: highlights for function pointers in argument list of
23435 c:function. Thanks to Takeshi Komiya.
23436 · PR#278: Fix section entries were shown twice if toctree has been put
23438 under only directive. Thanks to Takeshi Komiya.
23439 · #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
23441 py3).
23442 · PR#294: On LaTeX builder, wrap float environment on writing lit‐
23444 eral_block to avoid separation of caption and body. Thanks to Takeshi
23445 Komiya.
23446 · PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
23448 directory. Thanks to Peter Suter.
23449 · PR#297, #1571: Add imgpath property to all builders. It make easier
23451 to develop builder extensions. Thanks to Takeshi Komiya.
23452 · #1584: Point to master doc in HTML “top” link.
23454 · #1585: Autosummary of modules broken in Sphinx-1.2.3.
23456 · #1610: Sphinx cause AttributeError when MeCab search option is
23458 enabled and python-mecab is not installed.
23459 · #1674: Do not crash if a module’s __all__ is not a list of strings.
23461 · #1673: Fix crashes with nitpick_ignore and :doc: references.
23463 · #1686: ifconfig directive doesn’t care about default config values.
23465 · #1642: Fix only one search result appearing in Chrome.
23467 Documentation
23469 · Add clarification about the syntax of tags. (doc/markup/misc.rst)
23470 Release 1.2.3 (released Sep 1, 2014)
23472 Features added
23473 · #1518: sphinx-apidoc command now has a --version option to show ver‐
23474 sion information and exit
23475 · New locales: Hebrew, European Portuguese, Vietnamese.
23477 Bugs fixed
23479 · #636: Keep straight single quotes in literal blocks in the LaTeX
23480 build.
23481 · #1419: Generated i18n sphinx.js files are missing message catalog
23483 entries from ‘.js_t’ and ‘.html’. The issue was introduced from
23484 Sphinx-1.1
23485 · #1363: Fix i18n: missing python domain’s cross-references with cur‐
23487 rentmodule directive or currentclass directive.
23488 · #1444: autosummary does not create the description from attributes
23490 docstring.
23491 · #1457: In python3 environment, make linkcheck cause “Can’t convert
23493 ‘bytes’ object to str implicitly” error when link target url has a
23494 hash part. Thanks to Jorge_C.
23495 · #1467: Exception on Python3 if nonexistent method is specified by
23497 automethod
23498 · #1441: autosummary can’t handle nested classes correctly.
23500 · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
23502 user-friendly error message.
23503 · #1502: In autodoc, fix display of parameter defaults containing back‐
23505 slashes.
23506 · #1226: autodoc, autosummary: importing setup.py by automodule will
23508 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
23509 mExit exception and emits warnings without unexpected termination.
23510 · #1503: py:function directive generate incorrectly signature when
23512 specifying a default parameter with an empty list []. Thanks to Geert
23513 Jansen.
23514 · #1508: Non-ASCII filename raise exception on make singlehtml, latex,
23516 man, texinfo and changes.
23517 · #1531: On Python3 environment, docutils.conf with ‘source_link=true’
23519 in the general section cause type error.
23520 · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
23522 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
23523 · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
23525 Thanks to Takeshi Komiya.
23526 · #1477: gettext does not extract nodes.line in a table or list.
23528 · #1544: make text generates wrong table when it has empty table cells.
23530 · #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
23532 lem has been appeared from Sphinx-1.2.1 by #949.
23533 · #508: Sphinx every time exit with zero when is invoked from setup.py
23535 command. ex. python setup.py build_sphinx -b doctest return zero
23536 even if doctest failed.
23537 Release 1.2.2 (released Mar 2, 2014)
23539 Bugs fixed
23540 · PR#211: When checking for existence of the html_logo file, check the
23541 full relative path and not the basename.
23542 · PR#212: Fix traceback with autodoc and __init__ methods without doc‐
23544 string.
23545 · PR#213: Fix a missing import in the setup command.
23547 · #1357: Option names documented by option are now again allowed to not
23549 start with a dash or slash, and referencing them will work correctly.
23550 · #1358: Fix handling of image paths outside of the source directory
23552 when using the “wildcard” style reference.
23553 · #1374: Fix for autosummary generating overly-long summaries if first
23555 line doesn’t end with a period.
23556 · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
23558 · #1391: Actually prevent using “pngmath” and “mathjax” extensions at
23560 the same time in sphinx-quickstart.
23561 · #1386: Fix bug preventing more than one theme being added by the
23563 entry point mechanism.
23564 · #1370: Ignore “toctree” nodes in text writer, instead of raising.
23566 · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
23568 present.
23569 · #1367: Fix a change of PR#96 that break sphinx.util.doc‐
23571 fields.Field.make_field interface/behavior for item argument usage.
23572 Documentation
23574 · Extended the documentation about building extensions.
23575 Release 1.2.1 (released Jan 19, 2014)
23577 Bugs fixed
23578 · #1335: Fix autosummary template overloading with exclamation prefix
23579 like {% extends "!autosummary/class.rst" %} cause infinite recursive
23580 function call. This was caused by PR#181.
23581 · #1337: Fix autodoc with autoclass_content="both" uses useless
23583 object.__init__ docstring when class does not have __init__. This
23584 was caused by a change for #1138.
23585 · #1340: Can’t search alphabetical words on the HTML quick search gen‐
23587 erated with language=’ja’.
23588 · #1319: Do not crash if the html_logo file does not exist.
23590 · #603: Do not use the HTML-ized title for building the search index
23592 (that resulted in “literal” being found on every page with a literal
23593 in the title).
23594 · #751: Allow production lists longer than a page in LaTeX by using
23596 longtable.
23597 · #764: Always look for stopwords lowercased in JS search.
23599 · #814: autodoc: Guard against strange type objects that don’t have
23601 __bases__.
23602 · #932: autodoc: Do not crash if __doc__ is not a string.
23604 · #933: Do not crash if an option value is malformed (contains spaces
23606 but no option name).
23607 · #908: On Python 3, handle error messages from LaTeX correctly in the
23609 pngmath extension.
23610 · #943: In autosummary, recognize “first sentences” to pull from the
23612 docstring if they contain uppercase letters.
23613 · #923: Take the entire LaTeX document into account when caching png‐
23615 math-generated images. This rebuilds them correctly when png‐
23616 math_latex_preamble changes.
23617 · #901: Emit a warning when using docutils’ new “math” markup without a
23619 Sphinx math extension active.
23620 · #845: In code blocks, when the selected lexer fails, display line
23622 numbers nevertheless if configured.
23623 · #929: Support parsed-literal blocks in LaTeX output correctly.
23625 · #949: Update the tabulary.sty packed with Sphinx.
23627 · #1050: Add anonymous labels into objects.inv to be referenced via
23629 intersphinx.
23630 · #1095: Fix print-media stylesheet being included always in the
23632 “scrolls” theme.
23633 · #1085: Fix current classname not getting set if class description has
23635 :noindex: set.
23636 · #1181: Report option errors in autodoc directives more gracefully.
23638 · #1155: Fix autodocumenting C-defined methods as attributes in Python
23640 3.
23641 · #1233: Allow finding both Python classes and exceptions with the
23643 “class” and “exc” roles in intersphinx.
23644 · #1198: Allow “image” for the “figwidth” option of the figure direc‐
23646 tive as documented by docutils.
23647 · #1152: Fix pycode parsing errors of Python 3 code by including two
23649 grammar versions for Python 2 and 3, and loading the appropriate ver‐
23650 sion for the running Python version.
23651 · #1017: Be helpful and tell the user when the argument to option does
23653 not match the required format.
23654 · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
23656 the store environment for changes to have effect.
23657 · #1072: In the JS search, fix issues searching for upper-cased words
23659 by lowercasing words before stemming.
23660 · #1299: Make behavior of the math directive more consistent and avoid
23662 producing empty environments in LaTeX output.
23663 · #1308: Strip HTML tags from the content of “raw” nodes before feeding
23665 it to the search indexer.
23666 · #1249: Fix duplicate LaTeX page numbering for manual documents.
23668 · #1292: In the linkchecker, retry HEAD requests when denied by HTTP
23670 405. Also make the redirect code apparent and tweak the output a bit
23671 to be more obvious.
23672 · #1285: Avoid name clashes between C domain objects and section
23674 titles.
23675 · #848: Always take the newest code in incremental rebuilds with the
23677 sphinx.ext.viewcode extension.
23678 · #979, #1266: Fix exclude handling in sphinx-apidoc.
23680 · #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
23682 menting classes that can’t be pickled.
23683 · #1316: Remove hard-coded font-face resources from epub theme.
23685 · #1329: Fix traceback with empty translation msgstr in .po files.
23687 · #1300: Fix references not working in translated documents in some
23689 instances.
23690 · #1283: Fix a bug in the detection of changed files that would try to
23692 access doctrees of deleted documents.
23693 · #1330: Fix exclude_patterns behavior with subdirectories in the
23695 html_static_path.
23696 · #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
23698 valid HTML.
23699 · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
23701 Documentation
23703 · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
23704 Release 1.2 (released Dec 10, 2013)
23706 Features added
23707 · Added sphinx.version_info tuple for programmatic checking of the
23708 Sphinx version.
23709 Incompatible changes
23711 · Removed the sphinx.ext.refcounting extension – it is very specific to
23712 CPython and has no place in the main distribution.
23713 Bugs fixed
23715 · Restore versionmodified CSS class for versionadded/changed and depre‐
23716 cated directives.
23717 · PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
23719 ments always (This change keeps the current “theme changes cause a
23720 rebuild” feature).
23721 · #1296: Fix invalid charset in HTML help generated HTML files for
23723 default locale.
23724 · PR#190: Fix gettext does not extract figure caption and rubric title
23726 inside other blocks. Thanks to Michael Schlenker.
23727 · PR#176: Make sure setup_command test can always import Sphinx. Thanks
23729 to Dmitry Shachnev.
23730 · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
23732 · #1269: Fix ResourceWarnings with Python 3.2 or later.
23734 · #1138: Fix: When autodoc_docstring_signature = True and auto‐
23736 class_content = 'init' or 'both', __init__ line should be removed
23737 from class documentation.
23738 Release 1.2 beta3 (released Oct 3, 2013)
23740 Features added
23741 · The Sphinx error log files will now include a list of the loaded
23742 extensions for help in debugging.
23743 Incompatible changes
23745 · PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
23746 manual’ and ‘sphinxhowto’. Now you can use your custom document class
23747 without ‘sphinx’ prefix. Thanks to Erik B.
23748 Bugs fixed
23750 · #1265: Fix i18n: crash when translating a section name that is
23751 pointed to from a named target.
23752 · A wrong condition broke the search feature on first page that is usu‐
23754 ally index.rst. This issue was introduced in 1.2b1.
23755 · #703: When Sphinx can’t decode filenames with non-ASCII characters,
23757 Sphinx now catches UnicodeError and will continue if possible instead
23758 of raising the exception.
23759 Release 1.2 beta2 (released Sep 17, 2013)
23761 Features added
23762 · apidoc now ignores “_private” modules by default, and has an option
23763 -P to include them.
23764 · apidoc now has an option to not generate headings for packages and
23766 modules, for the case that the module docstring already includes a
23767 reST heading.
23768 · PR#161: apidoc can now write each module to a standalone page instead
23770 of combining all modules in a package on one page.
23771 · Builders: rebuild i18n target document when catalog updated.
23773 · Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
23775 HTML writer. The latex, manpage and texinfo writers also support
23776 their respective ‘writers’ sections.
23777 · The new html_extra_path config value allows to specify directories
23779 with files that should be copied directly to the HTML output direc‐
23780 tory.
23781 · Autodoc directives for module data and attributes now support an
23783 annotation option, so that the default display of the data/attribute
23784 value can be overridden.
23785 · PR#136: Autodoc directives now support an imported-members option to
23787 include members imported from different modules.
23788 · New locales: Macedonian, Sinhala, Indonesian.
23790 · Theme package collection by using setuptools plugin mechanism.
23792 Incompatible changes
23794 · PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
23795 ation-Date that was generated by gettext builder. Thanks to masklinn
23796 and Jakub Wilk.
23797 Bugs fixed
23799 · PR#132: Updated jQuery version to 1.8.3.
23800 · PR#141, #982: Avoid crash when writing PNG file using Python 3.
23802 Thanks to Marcin Wojdyr.
23803 · PR#145: In parallel builds, sphinx drops second document file to
23805 write. Thanks to tychoish.
23806 · PR#151: Some styling updates to tables in LaTeX.
23808 · PR#153: The “extensions” config value can now be overridden.
23810 · PR#155: Added support for some C++11 function qualifiers.
23812 · Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
23814 utf-8 encoded strings.
23815 · #828: use inspect.getfullargspec() to be able to document functions
23817 with keyword-only arguments on Python 3.
23818 · #1090: Fix i18n: multiple cross references (term, ref, doc) in the
23820 same line return the same link.
23821 · #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
23823 exception.
23824 · #1159: fix wrong generation of objects inventory for Python modules,
23826 and add a workaround in intersphinx to fix handling of affected
23827 inventories.
23828 · #1160: Citation target missing caused an AssertionError.
23830 · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
23832 · #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
23834 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
23835 der Dupuy.
23836 · #1185: Don’t crash when a Python module has a wrong or no encoding
23838 declared, and non-ASCII characters are included.
23839 · #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
23841 sion” includes non-ASCII characters.
23842 · #1189: “Title underline is too short” WARNING is given when using
23844 fullwidth characters to “Project name” on quickstart.
23845 · #1190: Output TeX/texinfo/man filename has no basename (only exten‐
23847 sion) when using non-ASCII characters in the “Project name” on quick‐
23848 start.
23849 · #1192: Fix escaping problem for hyperlinks in the manpage writer.
23851 · #1193: Fix i18n: multiple link references in the same line return the
23853 same link.
23854 · #1176: Fix i18n: footnote reference number missing for auto numbered
23856 named footnote and auto symbol footnote.
23857 · PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to
23859 tychoish.
23860 · #1204: Fix wrong generation of links to local intersphinx targets.
23862 · #1206: Fix i18n: gettext did not translate admonition directive’s
23864 title.
23865 · #1232: Sphinx generated broken ePub files on Windows.
23867 · #1259: Guard the debug output call when emitting events; to prevent
23869 the repr() implementation of arbitrary objects causing build fail‐
23870 ures.
23871 · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
23873 · #1234: Ignoring the string consists only of white-space characters.
23875 Release 1.2 beta1 (released Mar 31, 2013)
23877 Incompatible changes
23878 · Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
23879 eref_role() which were deprecated since version 1.0.
23880 · PR#122: the files given in latex_additional_files now override TeX
23882 files included by Sphinx, such as sphinx.sty.
23883 · PR#124: the node generated by versionadded, versionchanged and depre‐
23885 cated directives now includes all added markup (such as “New in ver‐
23886 sion X”) as child nodes, and no additional text must be generated by
23887 writers.
23888 · PR#99: the seealso directive now generates admonition nodes instead
23890 of the custom seealso node.
23891 Features added
23893 · Markup
23894 · The toctree directive and the toctree() template function now have
23896 an includehidden option that includes hidden toctree entries (bugs
23897 #790 and #1047). A bug in the maxdepth option for the toctree()
23898 template function has been fixed (bug #1046).
23899 · PR#99: Strip down seealso directives to normal admonitions. This
23901 removes their unusual CSS classes (admonition-see-also), inconsis‐
23902 tent LaTeX admonition title (“See Also” instead of “See also”), and
23903 spurious indentation in the text builder.
23904 · HTML builder
23906 · #783: Create a link to full size image if it is scaled with width
23908 or height.
23909 · #1067: Improve the ordering of the JavaScript search results:
23911 matches in titles come before matches in full text, and object
23912 results are better categorized. Also implement a pluggable search
23913 scorer.
23914 · #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
23916 options now work together.
23917 · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
23919 · Texinfo builder
23921 · An “Index” node is no longer added when there are no entries.
23923 · “deffn” categories are no longer capitalized if they contain capi‐
23925 tal letters.
23926 · desc_annotation nodes are now rendered.
23928 · strong and emphasis nodes are now formatted like literals. The rea‐
23930 son for this is because the standard Texinfo markup (*strong* and
23931 _emphasis_) resulted in confusing output due to the common usage of
23932 using these constructs for documenting parameter names.
23933 · Field lists formatting has been tweaked to better display “Info
23935 field lists”.
23936 · system_message and problematic nodes are now formatted in a similar
23938 fashion as done by the text builder.
23939 · “en-dash” and “em-dash” conversion of hyphens is no longer per‐
23941 formed in option directive signatures.
23942 · @ref is now used instead of @pxref for cross-references which pre‐
23944 vents the word “see” from being added before the link (does not
23945 affect the Info output).
23946 · The @finalout command has been added for better TeX output.
23948 · transition nodes are now formatted using underscores (“_”) instead
23950 of asterisks (“*”).
23951 · The default value for the paragraphindent has been changed from 2
23953 to 0 meaning that paragraphs are no longer indented by default.
23954 · #1110: A new configuration value texinfo_no_detailmenu has been
23956 added for controlling whether a @detailmenu is added in the “Top”
23957 node’s menu.
23958 · Detailed menus are no longer created except for the “Top” node.
23960 · Fixed an issue where duplicate domain indices would result in
23962 invalid output.
23963 · LaTeX builder:
23965 · PR#115: Add 'transition' item in latex_elements for customizing how
23967 transitions are displayed. Thanks to Jeff Klukas.
23968 · PR#114: The LaTeX writer now includes the “cmap” package by
23970 default. The 'cmappkg' item in latex_elements can be used to con‐
23971 trol this. Thanks to Dmitry Shachnev.
23972 · The 'fontpkg' item in latex_elements now defaults to '' when the
23974 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
23975 · The latex_documents, texinfo_documents, and man_pages configuration
23977 values will be set to default values based on the master_doc if not
23978 explicitly set in conf.py. Previously, if these values were not
23979 set, no output would be generated by their respective builders.
23980 · Internationalization:
23982 · Add i18n capabilities for custom templates. For example: The
23984 Sphinx reference documentation in doc directory provides a
23985 sphinx.pot file with message strings from doc/_templates/*.html
23986 when using make gettext.
23987 · PR#61,#703: Add support for non-ASCII filename handling.
23989 · Other builders:
23991 · Added the Docutils-native XML and pseudo-XML builders. See XML‐
23993 Builder and PseudoXMLBuilder.
23994 · PR#45: The linkcheck builder now checks #anchors for existence.
23996 · PR#123, #1106: Add epub_use_index configuration value. If pro‐
23998 vided, it will be used instead of html_use_index for epub builder.
23999 · PR#126: Add epub_tocscope configuration value. The setting controls
24001 the generation of the epub toc. The user can now also include hid‐
24002 den toc entries.
24003 · PR#112: Add epub_show_urls configuration value.
24005 · Extensions:
24007 · PR#52: special_members flag to autodoc now behaves like members.
24009 · PR#47: Added sphinx.ext.linkcode extension.
24011 · PR#25: In inheritance diagrams, the first line of the class doc‐
24013 string is now the tooltip for the class.
24014 · Command-line interfaces:
24016 · PR#75: Added --follow-links option to sphinx-apidoc.
24018 · #869: sphinx-build now has the option -T for printing the full
24020 traceback after an unhandled exception.
24021 · sphinx-build now supports the standard --help and --version
24023 options.
24024 · sphinx-build now provides more specific error messages when called
24026 with invalid options or arguments.
24027 · sphinx-build now has a verbose option -v which can be repeated for
24029 greater effect. A single occurrence provides a slightly more ver‐
24030 bose output than normal. Two or more occurrences of this option
24031 provides more detailed output which may be useful for debugging.
24032 · Locales:
24034 · PR#74: Fix some Russian translation.
24036 · PR#54: Added Norwegian bokmaal translation.
24038 · PR#35: Added Slovak translation.
24040 · PR#28: Added Hungarian translation.
24042 · #1113: Add Hebrew locale.
24044 · #1097: Add Basque locale.
24046 · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
24048 · #1012: Update Estonian translation.
24050 · Optimizations:
24052 · Speed up building the search index by caching the results of the
24054 word stemming routines. Saves about 20 seconds when building the
24055 Python documentation.
24056 · PR#108: Add experimental support for parallel building with a new
24058 sphinx-build -j option.
24059 Documentation
24061 · PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
24062 outlines the basic development process of the Sphinx project.
24063 · Added a detailed “Installing Sphinx” document (doc/install.rst).
24065 Bugs fixed
24067 · PR#124: Fix paragraphs in versionmodified are ignored when it has no
24068 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
24069 versionmodified is not translatable. Thanks to Nozomu Kaneko.
24070 · PR#111: Respect add_autodoc_attrgetter() even when inherited-members
24072 is set. Thanks to A. Jesse Jiryu Davis.
24073 · PR#97: Fix footnote handling in translated documents.
24075 · Fix text writer not handling visit_legend for figure directive con‐
24077 tents.
24078 · Fix text builder not respecting wide/fullwidth characters: title
24080 underline width, table layout width and text wrap width.
24081 · Fix leading space in LaTeX table header cells.
24083 · #1132: Fix LaTeX table output for multi-row cells in the first col‐
24085 umn.
24086 · #1128: Fix Unicode errors when trying to format time strings with a
24088 non-standard locale.
24089 · #1127: Fix traceback when autodoc tries to tokenize a non-Python
24091 file.
24092 · #1126: Fix double-hyphen to en-dash conversion in wrong places such
24094 as command-line option names in LaTeX.
24095 · #1123: Allow whitespaces in filenames given to literalinclude.
24097 · #1120: Added improvements about i18n for themes “basic”, “haiku” and
24099 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
24100 · #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
24102 G.
24103 · #1117: Handle .pyx files in sphinx-apidoc.
24105 · #1112: Avoid duplicate download files when referenced from documents
24107 in different ways (absolute/relative).
24108 · #1111: Fix failure to find uppercase words in search when
24110 html_search_language is ‘ja’. Thanks to Tomo Saito.
24111 · #1108: The text writer now correctly numbers enumerated lists with
24113 non-default start values (based on patch by Ewan Edwards).
24114 · #1102: Support multi-context “with” statements in autodoc.
24116 · #1090: Fix gettext not extracting glossary terms.
24118 · #1074: Add environment version info to the generated search index to
24120 avoid compatibility issues with old builds.
24121 · #1070: Avoid un-pickling issues when running Python 3 and the saved
24123 environment was created under Python 2.
24124 · #1069: Fixed error caused when autodoc would try to format signatures
24126 of “partial” functions without keyword arguments (patch by Artur Gas‐
24127 par).
24128 · #1062: sphinx.ext.autodoc use __init__ method signature for class
24130 signature.
24131 · #1055: Fix web support with relative path to source directory.
24133 · #1043: Fix sphinx-quickstart asking again for yes/no questions
24135 because input() returns values with an extra ‘r’ on Python 3.2.0 +
24136 Windows. Thanks to Régis Décamps.
24137 · #1041: Fix failure of the cpp domain parser to parse a const type
24139 with a modifier.
24140 · #1038: Fix failure of the cpp domain parser to parse C+11 “static
24142 constexpr” declarations. Thanks to Jakub Wilk.
24143 · #1029: Fix intersphinx_mapping values not being stable if the mapping
24145 has plural key/value set with Python 3.3.
24146 · #1028: Fix line block output in the text builder.
24148 · #1024: Improve Makefile/make.bat error message if Sphinx is not
24150 found. Thanks to Anatoly Techtonik.
24151 · #1018: Fix “container” directive handling in the text builder.
24153 · #1015: Stop overriding jQuery contains() in the JavaScript.
24155 · #1010: Make pngmath images transparent by default; IE7+ should handle
24157 it.
24158 · #1008: Fix test failures with Python 3.3.
24160 · #995: Fix table-of-contents and page numbering for the LaTeX “howto”
24162 class.
24163 · #976: Fix gettext does not extract index entries.
24165 · PR#72: #975: Fix gettext not extracting definition terms before docu‐
24167 tils 0.10.
24168 · #961: Fix LaTeX output for triple quotes in code snippets.
24170 · #958: Do not preserve environment.pickle after a failed build.
24172 · #955: Fix i18n transformation.
24174 · #940: Fix gettext does not extract figure caption.
24176 · #920: Fix PIL packaging issue that allowed to import Image without
24178 PIL namespace. Thanks to Marc Schlaich.
24179 · #723: Fix the search function on local files in WebKit based
24181 browsers.
24182 · #440: Fix coarse timestamp resolution in some filesystem generating a
24184 wrong list of outdated files.
24185 Release 1.1.3 (Mar 10, 2012)
24187 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
24188 characters correctly.
24189 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
24191 · PR#34: Restore Python 2.4 compatibility.
24193 · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
24195 the document class.
24196 · #695: When the highlight language “python” is specified explicitly,
24198 do not try to parse the code to recognize non-Python snippets.
24199 · #859: Fix exception under certain circumstances when not finding
24201 appropriate objects to link to.
24202 · #860: Do not crash when encountering invalid doctest examples, just
24204 emit a warning.
24205 · #864: Fix crash with some settings of modindex_common_prefix.
24207 · #862: Fix handling of -D and -A options on Python 3.
24209 · #851: Recognize and warn about circular toctrees, instead of running
24211 into recursion errors.
24212 · #853: Restore compatibility with docutils trunk.
24214 · #852: Fix HtmlHelp index entry links again.
24216 · #854: Fix inheritance_diagram raising attribute errors on builtins.
24218 · #832: Fix crashes when putting comments or lone terms in a glossary.
24220 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
24222 supported languages.
24223 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
24225 sion.
24226 · #831: Provide --project flag in setup_command as advertised.
24228 · #875: Fix reading config files under Python 3.
24230 · #876: Fix quickstart test under Python 3.
24232 · #870: Fix spurious KeyErrors when removing documents.
24234 · #892: Fix single-HTML builder misbehaving with the master document in
24236 a subdirectory.
24237 · #873: Fix assertion errors with empty only directives.
24239 · #816: Fix encoding issues in the Qt help builder.
24241 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
24243 · #809: Include custom fixers in the source distribution.
24244 Release 1.1.1 (Nov 1, 2011)
24246 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
24247 · #792: Include “sphinx-apidoc” in the source distribution.
24249 · #797: Don’t crash on a misformatted glossary.
24251 · #801: Make intersphinx work properly without SSL support.
24253 · #805: Make the Sphinx.add_index_to_domain method work correctly.
24255 · #780: Fix Python 2.5 compatibility.
24257 Release 1.1 (Oct 9, 2011)
24259 Incompatible changes
24260 · The py:module directive doesn’t output its platform option value any‐
24261 more. (It was the only thing that the directive did output, and
24262 therefore quite inconsistent.)
24263 · Removed support for old dependency versions; requirements are now:
24265 · Pygments >= 1.2
24267 · Docutils >= 0.7
24269 · Jinja2 >= 2.3
24271 Features added
24273 · Added Python 3.x support.
24274 · New builders and subsystems:
24276 · Added a Texinfo builder.
24278 · Added i18n support for content, a gettext builder and related util‐
24280 ities.
24281 · Added the websupport library and builder.
24283 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
24285 source files containing autodoc directives to document modules and
24286 packages.
24287 · #273: Add an API for adding full-text search support for languages
24289 other than English. Add support for Japanese.
24290 · Markup:
24292 · #138: Added an index role, to make inline index entries.
24294 · #454: Added more index markup capabilities: marking see/seealso
24296 entries, and main entries for a given key.
24297 · #460: Allowed limiting the depth of section numbers for HTML using
24299 the toctree’s numbered option.
24300 · #586: Implemented improved glossary markup which allows multiple
24302 terms per definition.
24303 · #478: Added py:decorator directive to describe decorators.
24305 · C++ domain now supports array definitions.
24307 · C++ domain now supports doc fields (:param x: inside directives).
24309 · Section headings in only directives are now correctly handled.
24311 · Added emphasize-lines option to source code directives.
24313 · #678: C++ domain now supports superclasses.
24315 · HTML builder:
24317 · Added pyramid theme.
24319 · #559: html_add_permalinks is now a string giving the text to dis‐
24321 play in permalinks.
24322 · #259: HTML table rows now have even/odd CSS classes to enable
24324 “Zebra styling”.
24325 · #554: Add theme option sidebarwidth to the basic theme.
24327 · Other builders:
24329 · #516: Added new value of the latex_show_urls option to show the
24331 URLs in footnotes.
24332 · #209: Added text_newlines and text_sectionchars config values.
24334 · Added man_show_urls config value.
24336 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
24338 requests and allow configuring the timeout. New config values:
24339 linkcheck_timeout and linkcheck_workers.
24340 · #521: Added linkcheck_ignore config value.
24342 · #28: Support row/colspans in tables in the LaTeX builder.
24344 · Configuration and extensibility:
24346 · #537: Added nitpick_ignore.
24348 · #306: Added env-get-outdated event.
24350 · Application.add_stylesheet() now accepts full URIs.
24352 · Autodoc:
24354 · #564: Add autodoc_docstring_signature. When enabled (the default),
24356 autodoc retrieves the signature from the first line of the doc‐
24357 string, if it is found there.
24358 · #176: Provide private-members option for autodoc directives.
24360 · #520: Provide special-members option for autodoc directives.
24362 · #431: Doc comments for attributes can now be given on the same line
24364 as the assignment.
24365 · #437: autodoc now shows values of class data attributes.
24367 · autodoc now supports documenting the signatures of functools.par‐
24369 tial objects.
24370 · Other extensions:
24372 · Added the sphinx.ext.mathjax extension.
24374 · #443: Allow referencing external graphviz files.
24376 · Added inline option to graphviz directives, and fixed the default
24378 (block-style) in LaTeX output.
24379 · #590: Added caption option to graphviz directives.
24381 · #553: Added testcleanup blocks in the doctest extension.
24383 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
24385 · #367: Added automatic exclusion of hidden members in inheritance
24387 diagrams, and an option to selectively enable it.
24388 · Added pngmath_add_tooltips.
24390 · The math extension displaymath directives now support name in addi‐
24392 tion to label for giving the equation label, for compatibility with
24393 Docutils.
24394 · New locales:
24396 · #221: Added Swedish locale.
24398 · #526: Added Iranian locale.
24400 · #694: Added Latvian locale.
24402 · Added Nepali locale.
24404 · #714: Added Korean locale.
24406 · #766: Added Estonian locale.
24408 · Bugs fixed:
24410 · #778: Fix “hide search matches” link on pages linked by search.
24412 · Fix the source positions referenced by the “viewcode” extension.
24414 Release 1.0.8 (Sep 23, 2011)
24416 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
24417 · Fix the abbr role when the abbreviation has newlines in it.
24419 · #727: Fix the links to search results with custom object types.
24421 · #648: Fix line numbers reported in warnings about undefined refer‐
24423 ences.
24424 · #696, #666: Fix C++ array definitions and template arguments that are
24426 not type names.
24427 · #633: Allow footnotes in section headers in LaTeX output.
24429 · #616: Allow keywords to be linked via intersphinx.
24431 · #613: Allow Unicode characters in production list token names.
24433 · #720: Add dummy visitors for graphviz nodes for text and man.
24435 · #704: Fix image file duplication bug.
24437 · #677: Fix parsing of multiple signatures in C++ domain.
24439 · #637: Ignore Emacs lock files when looking for source files.
24441 · #544: Allow .pyw extension for importable modules in autodoc.
24443 · #700: Use $(MAKE) in quickstart-generated Makefiles.
24445 · #734: Make sidebar search box width consistent in browsers.
24447 · #644: Fix spacing of centered figures in HTML output.
24449 · #767: Safely encode SphinxError messages when printing them to
24451 sys.stderr.
24452 · #611: Fix LaTeX output error with a document with no sections but a
24454 link target.
24455 · Correctly treat built-in method descriptors as methods in autodoc.
24457 · #706: Stop monkeypatching the Python textwrap module.
24459 · #657: viewcode now works correctly with source files that have
24461 non-ASCII encoding.
24462 · #669: Respect the noindex flag option in py:module directives.
24464 · #675: Fix IndexErrors when including nonexisting lines with literal‐
24466 include.
24467 · #676: Respect custom function/method parameter separator strings.
24469 · #682: Fix JS incompatibility with jQuery >= 1.5.
24471 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
24473 · #647: Do not apply SmartyPants in parsed-literal blocks.
24475 · C++ domain now supports array definitions.
24477 Release 1.0.7 (Jan 15, 2011)
24479 · #347: Fix wrong generation of directives of static methods in auto‐
24480 summary.
24481 · #599: Import PIL as from PIL import Image.
24483 · #558: Fix longtables with captions in LaTeX output.
24485 · Make token references work as hyperlinks again in LaTeX output.
24487 · #572: Show warnings by default when reference labels cannot be found.
24489 · #536: Include line number when complaining about missing reference
24491 targets in nitpicky mode.
24492 · #590: Fix inline display of graphviz diagrams in LaTeX output.
24494 · #589: Build using app.build() in setup command.
24496 · Fix a bug in the inheritance diagram exception that caused base
24498 classes to be skipped if one of them is a builtin.
24499 · Fix general index links for C++ domain objects.
24501 · #332: Make admonition boundaries in LaTeX output visible.
24503 · #573: Fix KeyErrors occurring on rebuild after removing a file.
24505 · Fix a traceback when removing files with globbed toctrees.
24507 · If an autodoc object cannot be imported, always re-read the document
24509 containing the directive on next build.
24510 · If an autodoc object cannot be imported, show the full traceback of
24512 the import error.
24513 · Fix a bug where the removal of download files and images wasn’t
24515 noticed.
24516 · #571: Implement ~ cross-reference prefix for the C domain.
24518 · Fix regression of LaTeX output with the fix of #556.
24520 · #568: Fix lookup of class attribute documentation on descriptors so
24522 that comment documentation now works.
24523 · Fix traceback with only directives preceded by targets.
24525 · Fix tracebacks occurring for duplicate C++ domain objects.
24527 · Fix JavaScript domain links to objects with $ in their name.
24529 Release 1.0.6 (Jan 04, 2011)
24531 · #581: Fix traceback in Python domain for empty cross-reference tar‐
24532 gets.
24533 · #283: Fix literal block display issues on Chrome browsers.
24535 · #383, #148: Support sorting a limited range of accented characters in
24537 the general index and the glossary.
24538 · #570: Try decoding -D and -A command-line arguments with the locale’s
24540 preferred encoding.
24541 · #528: Observe locale_dirs when looking for the JS translations file.
24543 · #574: Add special code for better support of Japanese documents in
24545 the LaTeX builder.
24546 · Regression of #77: If there is only one parameter given with :param:
24548 markup, the bullet list is now suppressed again.
24549 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
24551 tions.
24552 · #567: Emit the autodoc-process-docstring event even for objects with‐
24554 out a docstring so that it can add content.
24555 · #565: In the LaTeX builder, not only literal blocks require different
24557 table handling, but also quite a few other list-like block elements.
24558 · #515: Fix tracebacks in the viewcode extension for Python objects
24560 that do not have a valid signature.
24561 · Fix strange reports of line numbers for warnings generated from
24563 autodoc-included docstrings, due to different behavior depending on
24564 docutils version.
24565 · Several fixes to the C++ domain.
24567 Release 1.0.5 (Nov 12, 2010)
24569 · #557: Add CSS styles required by docutils 0.7 for aligned images and
24570 figures.
24571 · In the Makefile generated by LaTeX output, do not delete pdf files on
24573 clean; they might be required images.
24574 · #535: Fix LaTeX output generated for line blocks.
24576 · #544: Allow .pyw as a source file extension.
24578 Release 1.0.4 (Sep 17, 2010)
24580 · #524: Open intersphinx inventories in binary mode on Windows, since
24581 version 2 contains zlib-compressed data.
24582 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
24584 JSMath extension.
24585 · #512: Fix traceback when intersphinx_mapping is empty.
24587 Release 1.0.3 (Aug 23, 2010)
24589 · #495: Fix internal vs. external link distinction for links coming
24590 from a docutils table-of-contents.
24591 · #494: Fix the maxdepth option for the toctree() template callable
24593 when used with collapse=True.
24594 · #507: Fix crash parsing Python argument lists containing brackets in
24596 string literals.
24597 · #501: Fix regression when building LaTeX docs with figures that don’t
24599 have captions.
24600 · #510: Fix inheritance diagrams for classes that are not picklable.
24602 · #497: Introduce separate background color for the sidebar collapse
24604 button, making it easier to see.
24605 · #502, #503, #496: Fix small layout bugs in several builtin themes.
24607 Release 1.0.2 (Aug 14, 2010)
24609 · #490: Fix cross-references to objects of types added by the
24610 add_object_type() API function.
24611 · Fix handling of doc field types for different directive types.
24613 · Allow breaking long signatures, continuing with backlash-escaped new‐
24615 lines.
24616 · Fix unwanted styling of C domain references (because of a namespace
24618 clash with Pygments styles).
24619 · Allow references to PEPs and RFCs with explicit anchors.
24621 · #471: Fix LaTeX references to figures.
24623 · #482: When doing a non-exact search, match only the given type of
24625 object.
24626 · #481: Apply non-exact search for Python reference targets with .name
24628 for modules too.
24629 · #484: Fix crash when duplicating a parameter in an info field list.
24631 · #487: Fix setting the default role to one provided by the oldcmarkup
24633 extension.
24634 · #488: Fix crash when json-py is installed, which provides a json mod‐
24636 ule but is incompatible to simplejson.
24637 · #480: Fix handling of target naming in intersphinx.
24639 · #486: Fix removal of ! for all cross-reference roles.
24641 Release 1.0.1 (Jul 27, 2010)
24643 · #470: Fix generated target names for reST domain objects; they are
24644 not in the same namespace.
24645 · #266: Add Bengali language.
24647 · #473: Fix a bug in parsing JavaScript object names.
24649 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
24651 · Fix display names for objects linked to by intersphinx with explicit
24653 targets.
24654 · Fix building with the JSON builder.
24656 · Fix hyperrefs in object descriptions for LaTeX.
24658 Release 1.0 (Jul 23, 2010)
24660 Incompatible changes
24661 · Support for domains has been added. A domain is a collection of
24662 directives and roles that all describe objects belonging together,
24663 e.g. elements of a programming language. A few builtin domains are
24664 provided:
24665 · Python
24667 · C
24669 · C++
24671 · JavaScript
24673 · reStructuredText
24675 · The old markup for defining and linking to C directives is now depre‐
24677 cated. It will not work anymore in future versions without activat‐
24678 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
24679 default.
24680 · Removed support for old dependency versions; requirements are now:
24682 · docutils >= 0.5
24684 · Jinja2 >= 2.2
24686 · Removed deprecated elements:
24688 · exclude_dirs config value
24690 · sphinx.builder module
24692 Features added
24694 · General:
24695 · Added a “nitpicky” mode that emits warnings for all missing refer‐
24697 ences. It is activated by the sphinx-build -n command-line switch
24698 or the nitpicky config value.
24699 · Added latexpdf target in quickstart Makefile.
24701 · Markup:
24703 · The menuselection and guilabel roles now support ampersand acceler‐
24705 ators.
24706 · New more compact doc field syntax is now recognized: :param type
24708 name: description.
24709 · Added tab-width option to literalinclude directive.
24711 · Added titlesonly option to toctree directive.
24713 · Added the prepend and append options to the literalinclude direc‐
24715 tive.
24716 · #284: All docinfo metadata is now put into the document metadata,
24718 not just the author.
24719 · The ref role can now also reference tables by caption.
24721 · The include directive now supports absolute paths, which are inter‐
24723 preted as relative to the source directory.
24724 · In the Python domain, references like :func:`.name` now look for
24726 matching names with any prefix if no direct match is found.
24727 · Configuration:
24729 · Added rst_prolog config value.
24731 · Added html_secnumber_suffix config value to control section number‐
24733 ing format.
24734 · Added html_compact_lists config value to control docutils’ compact
24736 lists feature.
24737 · The html_sidebars config value can now contain patterns as keys,
24739 and the values can be lists that explicitly select which sidebar
24740 templates should be rendered. That means that the builtin sidebar
24741 contents can be included only selectively.
24742 · html_static_path can now contain single file entries.
24744 · The new universal config value exclude_patterns makes the old
24746 unused_docs, exclude_trees and exclude_dirnames obsolete.
24747 · Added html_output_encoding config value.
24749 · Added the latex_docclass config value and made the “twoside” docu‐
24751 mentclass option overridable by “oneside”.
24752 · Added the trim_doctest_flags config value, which is true by
24754 default.
24755 · Added html_show_copyright config value.
24757 · Added latex_show_pagerefs and latex_show_urls config values.
24759 · The behavior of html_file_suffix changed slightly: the empty string
24761 now means “no suffix” instead of “default suffix”, use None for
24762 “default suffix”.
24763 · New builders:
24765 · Added a builder for the Epub format.
24767 · Added a builder for manual pages.
24769 · Added a single-file HTML builder.
24771 · HTML output:
24773 · Inline roles now get a CSS class with their name, allowing styles
24775 to customize their appearance. Domain-specific roles get two
24776 classes, domain and domain-rolename.
24777 · References now get the class internal if they are internal to the
24779 whole project, as opposed to internal to the current page.
24780 · External references can be styled differently with the new exter‐
24782 nalrefs theme option for the default theme.
24783 · In the default theme, the sidebar can experimentally now be made
24785 collapsible using the new collapsiblesidebar theme option.
24786 · #129: Toctrees are now wrapped in a div tag with class toc‐
24788 tree-wrapper in HTML output.
24789 · The toctree callable in templates now has a maxdepth keyword argu‐
24791 ment to control the depth of the generated tree.
24792 · The toctree callable in templates now accepts a titles_only keyword
24794 argument.
24795 · Added htmltitle block in layout template.
24797 · In the JavaScript search, allow searching for object names includ‐
24799 ing the module name, like sys.argv.
24800 · Added new theme haiku, inspired by the Haiku OS user guide.
24802 · Added new theme nature.
24804 · Added new theme agogo, created by Andi Albrecht.
24806 · Added new theme scrolls, created by Armin Ronacher.
24808 · #193: Added a visitedlinkcolor theme option to the default theme.
24810 · #322: Improved responsiveness of the search page by loading the
24812 search index asynchronously.
24813 · Extension API:
24815 · Added html-collect-pages.
24817 · Added needs_sphinx config value and require_sphinx() application
24819 API method.
24820 · #200: Added add_stylesheet() application API method.
24822 · Extensions:
24824 · Added the viewcode extension.
24826 · Added the extlinks extension.
24828 · Added support for source ordering of members in autodoc, with
24830 autodoc_member_order = 'bysource'.
24831 · Added autodoc_default_flags config value, which can be used to
24833 select default flags for all autodoc directives.
24834 · Added a way for intersphinx to refer to named labels in other
24836 projects, and to specify the project you want to link to.
24837 · #280: Autodoc can now document instance attributes assigned in
24839 __init__ methods.
24840 · Many improvements and fixes to the autosummary extension, thanks to
24842 Pauli Virtanen.
24843 · #309: The graphviz extension can now output SVG instead of PNG
24845 images, controlled by the graphviz_output_format config value.
24846 · Added alt option to graphviz extension directives.
24848 · Added exclude argument to autodoc.between().
24850 · Translations:
24852 · Added Croatian translation, thanks to Bojan Mihelač.
24854 · Added Turkish translation, thanks to Firat Ozgul.
24856 · Added Catalan translation, thanks to Pau Fernández.
24858 · Added simplified Chinese translation.
24860 · Added Danish translation, thanks to Hjorth Larsen.
24862 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
24864 · Bugs fixed:
24866 · #445: Fix links to result pages when using the search function of
24868 HTML built with the dirhtml builder.
24869 · #444: In templates, properly re-escape values treated with the
24871 “striptags” Jinja filter.
24872 Previous versions
24874 The changelog for versions before 1.0 can be found in the file
24875 CHANGES.old in the source distribution or at GitHub.
24876
24878 This is an (incomplete) alphabetic list of projects that use Sphinx or
24879 are experimenting with using it for their documentation. If you like
24880 to be included, please mail to the Google group.
24881 I’ve grouped the list into sections to make it easier to find interest‐
24883 ing examples.
24884 Documentation using the alabaster theme
24886 · Alabaster
24887 · Blinker
24889 · Calibre
24891 · Click (customized)
24893 · coala (customized)
24895 · CodePy
24897 · Eve (Python REST API framework)
24899 · Fabric
24901 · Fityk
24903 · Flask
24905 · Flask-OpenID
24907 · Invoke
24909 · Jinja
24911 · Lino (customized)
24913 · marbl
24915 · MDAnalysis (customized)
24917 · MeshPy
24919 · Molecule
24921 · PyCUDA
24923 · PyOpenCL
24925 · PyLangAcq
24927 · pytest (customized)
24929 · python-apt
24931 · PyVisfile
24933 · Requests
24935 · searx
24937 · Spyder (customized)
24939 · Tablib
24941 · urllib3 (customized)
24943 · Werkzeug (customized)
24945 Documentation using the classic theme
24947 · Advanced Generic Widgets (customized)
24948 · Apache CouchDB (customized)
24950 · APSW
24952 · Arb
24954 · Bazaar (customized)
24956 · Beautiful Soup
24958 · Blender
24960 · Bugzilla
24962 · Buildbot
24964 · CMake (customized)
24966 · Chaco (customized)
24968 · CORE
24970 · CORE Python modules
24972 · Cormoran
24974 · DEAP (customized)
24976 · Director
24978 · EZ-Draw (customized)
24980 · F2py
24982 · Generic Mapping Tools (GMT) (customized)
24984 · Genomedata
24986 · GetFEM++ (customized)
24988 · Glasgow Haskell Compiler (customized)
24990 · Grok (customized)
24992 · GROMACS
24994 · GSL Shell
24996 · Hands-on Python Tutorial
24998 · Kaa (customized)
25000 · Leo
25002 · LEPL (customized)
25004 · Mayavi (customized)
25006 · MediaGoblin (customized)
25008 · mpmath
25010 · OpenCV (customized)
25012 · OpenEXR
25014 · OpenGDA
25016 · Peach^3 (customized)
25018 · Plone (customized)
25020 · PyEMD
25022 · Pyevolve
25024 · Pygame (customized)
25026 · PyMQI
25028 · PyQt4 (customized)
25030 · PyQt5 (customized)
25032 · Python 2
25034 · Python 3 (customized)
25036 · Python Packaging Authority (customized)
25038 · Ring programming language (customized)
25040 · SageMath (customized)
25042 · Segway
25044 · simuPOP (customized)
25046 · Sprox (customized)
25048 · SymPy
25050 · TurboGears (customized)
25052 · tvtk
25054 · Varnish (customized, alabaster for index)
25056 · Waf
25058 · wxPython Phoenix (customized)
25060 · Yum
25062 · z3c
25064 · zc.async (customized)
25066 · Zope (customized)
25068 Documentation using the sphinxdoc theme
25070 · ABRT
25071 · cartopy
25073 · Jython
25075 · Matplotlib
25077 · MDAnalysis Tutorial
25079 · NetworkX
25081 · PyCantonese
25083 · Pyre
25085 · pySPACE
25087 · Pysparse
25089 · PyTango
25091 · Python Wild Magic (customized)
25093 · Reteisi (customized)
25095 · Sqlkit (customized)
25097 · Turbulenz
25099 Documentation using the nature theme
25101 · Alembic
25102 · Cython
25104 · easybuild
25106 · jsFiddle
25108 · libLAS (customized)
25110 · Lmod
25112 · MapServer (customized)
25114 · Pandas
25116 · pyglet (customized)
25118 · Setuptools
25120 · Spring Python
25122 · StatsModels (customized)
25124 · Sylli
25126 Documentation using another builtin theme
25128 · Breathe (haiku)
25129 · MPipe (sphinx13)
25131 · NLTK (agogo)
25133 · Programmieren mit PyGTK und Glade (German) (agogo, customized)
25135 · PyPubSub (bizstyle)
25137 · Pylons (pyramid)
25139 · Pyramid web framework (pyramid)
25141 · Sphinx (sphinx13) :-)
25143 · Valence (haiku, customized)
25145 Documentation using sphinx_rtd_theme
25147 · Annotator
25148 · Ansible (customized)
25150 · Arcade
25152 · aria2
25154 · ASE
25156 · Autofac
25158 · BigchainDB
25160 · Blocks
25162 · bootstrap-datepicker
25164 · Certbot
25166 · Chainer (customized)
25168 · CherryPy
25170 · cloud-init
25172 · CodeIgniter
25174 · Conda
25176 · Corda
25178 · Dask
25180 · Databricks (customized)
25182 · Dataiku DSS
25184 · DNF
25186 · edX
25188 · Electrum
25190 · Elemental
25192 · ESWP3
25194 · Ethereum Homestead
25196 · Faker
25198 · Fidimag
25200 · Flake8
25202 · Flatpak
25204 · FluidDyn
25206 · Fluidsim
25208 · GeoNode
25210 · Glances
25212 · Godot
25214 · Graylog
25216 · GPAW (customized)
25218 · HDF5 for Python (h5py)
25220 · Hyperledger Fabric
25222 · Hyperledger Sawtooth
25224 · IdentityServer
25226 · Idris
25228 · javasphinx
25230 · Julia
25232 · Jupyter Notebook
25234 · Lasagne
25236 · latexindent.pl
25238 · Linguistica
25240 · Linux kernel
25242 · MathJax
25244 · MDTraj (customized)
25246 · MICrobial Community Analysis (micca)
25248 · MicroPython
25250 · Minds (customized)
25252 · Mink
25254 · Mockery
25256 · mod_wsgi
25258 · MoinMoin
25260 · Mopidy
25262 · MyHDL
25264 · Nextflow
25266 · NICOS (customized)
25268 · Pelican
25270 · picamera
25272 · Pillow
25274 · pip
25276 · Paver
25278 · peewee
25280 · Phinx
25282 · phpMyAdmin
25284 · PROS (customized)
25286 · Pushkin
25288 · Pweave
25290 · PyPy
25292 · python-sqlparse
25294 · PyVISA
25296 · Read The Docs
25298 · Free your information from their silos (French) (customized)
25300 · Releases Sphinx extension
25302 · Qtile
25304 · Quex
25306 · QuTiP
25308 · Satchmo
25310 · Scapy
25312 · SimGrid
25314 · SimPy
25316 · six
25318 · SlamData
25320 · Solidity
25322 · Sonos Controller (SoCo)
25324 · Sphinx AutoAPI
25326 · sphinx-argparse
25328 · Sphinx-Gallery (customized)
25330 · SpotBugs
25332 · StarUML
25334 · Sublime Text Unofficial Documentation
25336 · SunPy
25338 · Sylius
25340 · Syncthing
25342 · Tango Controls (customized)
25344 · Topshelf
25346 · Theano
25348 · ThreatConnect
25350 · Tuleap
25352 · TYPO3 (customized)
25354 · Veyon
25356 · uWSGI
25358 · virtualenv
25360 · Wagtail
25362 · Web Application Attack and Audit Framework (w3af)
25364 · Weblate
25366 · x265
25368 · ZeroNet
25370 · Zulip
25372 Documentation using sphinx_bootstrap_theme
25374 · Bootstrap Theme
25375 · C/C++ Software Development with Eclipse
25377 · Dataverse
25379 · e-cidadania
25381 · Hangfire
25383 · Hedge
25385 · ObsPy
25387 · Open Dylan
25389 · Pootle
25391 · PyUblas
25393 · seaborn
25395 Documentation using a custom theme or integrated in a website
25397 · Apache Cassandra
25398 · Astropy
25400 · Bokeh
25402 · Boto 3
25404 · CakePHP
25406 · CasperJS
25408 · Ceph
25410 · Chef
25412 · CKAN
25414 · Confluent Platform
25416 · Django
25418 · Doctrine
25420 · Enterprise Toolkit for Acrobat products
25422 · Gameduino
25424 · gensim
25426 · GeoServer
25428 · gevent
25430 · GHC - Glasgow Haskell Compiler
25432 · Guzzle
25434 · H2O.ai
25436 · Heka
25438 · Istihza (Turkish Python documentation project)
25440 · Kombu
25442 · Lasso
25444 · Mako
25446 · MirrorBrain
25448 · MongoDB
25450 · Music21
25452 · MyHDL
25454 · nose
25456 · ns-3
25458 · NumPy
25460 · ObjectListView
25462 · OpenERP
25464 · OpenCV
25466 · OpenLayers
25468 · OpenTURNS
25470 · Open vSwitch
25472 · PlatformIO
25474 · PyEphem
25476 · Pygments
25478 · Plone User Manual (German)
25480 · PSI4
25482 · PyMOTW
25484 · python-aspectlib (sphinx_py3doc_enhanced_theme)
25486 · QGIS
25488 · qooxdoo
25490 · Roundup
25492 · SaltStack
25494 · scikit-learn
25496 · SciPy
25498 · Scrapy
25500 · Seaborn
25502 · Selenium
25504 · Self
25506 · Substance D
25508 · Sulu
25510 · SQLAlchemy
25512 · tinyTiM
25514 · Twisted
25516 · Ubuntu Packaging Guide
25518 · WebFaction
25520 · WTForms
25522 Homepages and other non-documentation sites
25524 · Arizona State University PHY494/PHY598/CHM598 Simulation approaches
25525 to Bio-and Nanophysics (classic)
25526 · Benoit Boissinot (classic, customized)
25528 · Computer Networks, Parallelization, and Simulation Laboratory
25530 (CNPSLab) (sphinx_rtd_theme)
25531 · Deep Learning Tutorials (sphinxdoc)
25533 · Eric Holscher (alabaster)
25535 · Lei Ma’s Statistical Mechanics lecture notes (sphinx_bootstrap_theme)
25537 · Loyola University Chicago COMP 339-439 Distributed Systems course
25539 (sphinx_bootstrap_theme)
25540 · Pylearn2 (sphinxdoc, customized)
25542 · PyXLL (sphinx_bootstrap_theme, customized)
25544 · SciPy Cookbook (sphinx_rtd_theme)
25546 · The Wine Cellar Book (sphinxdoc)
25548 · Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials
25550 (standard)
25551 · UC Berkeley ME233 Advanced Control Systems II course (sphinxdoc)
25553 · Željko Svedružić’s Biomolecular Structure and Function Laboratory
25555 (BioSFLab) (sphinx_bootstrap_theme)
25556 Books produced using Sphinx
25558 · “The Art of Community” (Japanese translation)
25559 · “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”
25561 · “Expert Python Programming”
25563 · “Expert Python Programming” (Japanese translation)
25565 · “Expert Python Programming 2nd Edition” (Japanese translation)
25567 · “The Hitchhiker’s Guide to Python”
25569 · “LassoGuide”
25571 · “Learning Sphinx” (in Japanese)
25573 · “Learning System Programming with Go (Japanese)”
25575 · “Mercurial: the definitive guide (Second edition)”
25577 · “Mithril – The fastest clientside MVC (Japanese)”
25579 · “Pioneers and Prominent Men of Utah”
25581 · “Pomodoro Technique Illustrated” (Japanese translation)
25583 · “Professional Software Development”
25585 · “Python Professional Programming” (in Japanese)
25587 · “Python Professional Programming 2nd Edition” (in Japanese)
25589 · “Python Professional Programming 3rd Edition” (in Japanese)
25591 · “Real World HTTP – Learning The Internet and Web Technology via its
25593 history and code (Japanese)”
25594 · “Redmine Primer 5th Edition (in Japanese)”
25596 · “The repoze.bfg Web Application Framework”
25598 · “The Self-Taught Programmer” (Japanese translation)
25600 · “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
25602 panese)
25603 · “Software-Dokumentation mit Sphinx”
25605 · “Theoretical Physics Reference”
25607 · “The Varnish Book”
25609 Theses produced using Sphinx
25611 · “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
25612 the Use of CouchDB”
25613 · “Content Conditioning and Distribution for Dynamic Virtual Worlds”
25615 · “The Sphinx Thesis Resource”
25617 Projects integrating Sphinx functionality
25619 · Read the Docs, a software-as-a-service documentation hosting plat‐
25620 form, uses Sphinx to automatically build documentation updates that
25621 are pushed to GitHub.
25622 · Spyder, the Scientific Python Development Environment, uses Sphinx in
25624 its help pane to render rich documentation for functions, classes and
25625 methods automatically or on-demand.
25626
25628 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
25629 Substantial parts of the templates were written by Armin Ronacher <‐
25631 armin.ronacher@active-4.com>.
25632 Other co-maintainers:
25634 · Takayuki Shimizukawa <shimizukawa@gmail.com>
25636 · Daniel Neuhäuser <@DasIch>
25638 · Jon Waltman <@jonwaltman>
25640 · Rob Ruana <@RobRuana>
25642 · Robert Lehmann <@lehmannro>
25644 · Roland Meister <@rolmei>
25646 · Takeshi Komiya <@tk0miya>
25648 · Jean-François Burnol <@jfbu>
25650 · Yoshiki Shibukawa <@shibu_jp>
25652 · Timotheus Kampik - <@TimKam>
25654 Other contributors, listed alphabetically, are:
25656 · Alastair Houghton – Apple Help builder
25658 · Alexander Todorov – inheritance_diagram tests and improvements
25660 · Andi Albrecht – agogo theme
25662 · Jakob Lykke Andersen – Rewritten C++ domain
25664 · Henrique Bastos – SVG support for graphviz extension
25666 · Daniel Bültmann – todo extension
25668 · Marco Buttu – doctest extension (pyversion option)
25670 · Etienne Desautels – apidoc module
25672 · Michael Droettboom – inheritance_diagram extension
25674 · Charles Duffy – original graphviz extension
25676 · Kevin Dunn – MathJax extension
25678 · Josip Dzolonga – coverage builder
25680 · Buck Evan – dummy builder
25682 · Matthew Fernandez – todo extension fix
25684 · Hernan Grecco – search improvements
25686 · Horst Gutmann – internationalization support
25688 · Martin Hans – autodoc improvements
25690 · Zac Hatfield-Dodds – doctest reporting improvements
25692 · Doug Hellmann – graphviz improvements
25694 · Tim Hoffmann – theme improvements
25696 · Antti Kaihola – doctest extension (skipif option)
25698 · Dave Kuhlman – original LaTeX writer
25700 · Blaise Laflamme – pyramid theme
25702 · Chris Lamb – reproducibility fixes
25704 · Thomas Lamb – linkcheck builder
25706 · Łukasz Langa – partial support for autodoc
25708 · Martin Larralde – additional napoleon admonitions
25710 · Ian Lee – quickstart improvements
25712 · Robert Lehmann – gettext builder (GSOC project)
25714 · Dan MacKinlay – metadata fixes
25716 · Martin Mahner – nature theme
25718 · Will Maier – directory HTML builder
25720 · Jacob Mason – websupport library (GSOC project)
25722 · Glenn Matthews – python domain signature improvements
25724 · Kurt McKee – documentation updates
25726 · Roland Meister – epub builder
25728 · Ezio Melotti – collapsible sidebar JavaScript
25730 · Bruce Mitchener – Minor epub improvement
25732 · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
25734 · Julien Palard – Colspan and rowspan in text builder
25736 · Christopher Perkins – autosummary integration
25738 · Benjamin Peterson – unittests
25740 · T. Powers – HTML output improvements
25742 · Jeppe Pihl – literalinclude improvements
25744 · Rob Ruana – napoleon extension
25746 · Stefan Seefeld – toctree improvements
25748 · Gregory Szorc – performance improvements
25750 · Taku Shimizu – epub3 builder
25752 · Antonio Valentino – qthelp builder, docstring inheritance
25754 · Filip Vavera – napoleon todo directive
25756 · Pauli Virtanen – autodoc improvements, autosummary extension
25758 · Eric N. Vander Weele – autodoc improvements
25760 · Stefan van der Walt – autosummary extension
25762 · Thomas Waldmann – apidoc module fixes
25764 · John Waltman – Texinfo builder
25766 · Barry Warsaw – setup command improvements
25768 · Sebastian Wiesner – image handling, distutils support
25770 · Michael Wilson – Intersphinx HTTP basic auth support
25772 · Matthew Woodcraft – text output improvements
25774 · Joel Wurtz – cellspanning support in LaTeX
25776 · Hong Xu – svg support in imgmath extension and various bug fixes
25778 · Stephen Finucane – setup command improvements and documentation
25780 · Daniel Pizetta – inheritance diagram improvements
25782 · KINEBUCHI Tomohiko – typing Sphinx as well as docutils
25784 · Adrián Chaves (Gallaecio) – coverage builder improvements
25786 Many thanks for all contributions!
25788 There are also a few modules or functions incorporated from other
25790 authors and projects:
25791 · sphinx.util.jsdump uses the basestring encoding from simplejson,
25793 written by Bob Ippolito, released under the MIT license
25794 · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
25796 Domain
25797 · modindex
25799 · glossary
25801
25803 Georg Brandl
25804
25806 2007-2019, Georg Brandl and the Sphinx team
258072.1.2 Jul 26, 2019 SPHINX-ALL(1)