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 LaTeX file that you can
17 compile into a PDF version of the documents, or a PDF file directly
18 using rst2pdf.
19 The focus is on hand-written documentation, rather than auto-generated
21 API docs. Though there is support for that kind of docs as well (which
22 is intended to be freely mixed with hand-written content), if you need
23 pure API docs have a look at Epydoc, which also understands reST.
24 Conversion from other systems
26 This section is intended to collect helpful hints for those wanting to
27 migrate to reStructuredText/Sphinx from other documentation systems.
28 · Gerard Flanagan has written a script to convert pure HTML to reST; it
30 can be found at BitBucket.
31 · For converting the old Python docs to Sphinx, a converter was written
33 which can be found at the Python SVN repository. It contains generic
34 code to convert Python-doc-style LaTeX markup to Sphinx reST.
35 · Marcin Wojdyr has written a script to convert Docbook to reST with
37 Sphinx markup; it is at Google Code.
38 Use with other systems
40 See the pertinent section in the FAQ list.
41 Prerequisites
43 Sphinx needs at least Python 2.4 to run, as well as the docutils and
44 Jinja2 libraries. Sphinx should work with docutils version 0.5 or some
45 (not broken) SVN trunk snapshot. If you like to have source code high‐
46 lighting support, you must also install the Pygments library.
47 Usage
49 See tutorial for an introduction. It also contains links to more
50 advanced sections in this manual for the topics it discusses.
51
53 This document is meant to give a tutorial-like overview of all common
54 tasks while using Sphinx.
55 The green arrows designate "more info" links leading to advanced sec‐
57 tions about the described task.
58 Setting up the documentation sources
60 The root directory of a documentation collection is called the source
61 directory. This directory also contains the Sphinx configuration file
62 conf.py, where you can configure all aspects of how Sphinx reads your
63 sources and builds your documentation. [1]
64 Sphinx comes with a script called sphinx-quickstart that sets up a
66 source directory and creates a default conf.py with the most useful
67 configuration values from a few questions it asks you. Just run
68 $ sphinx-quickstart
70 and answer its questions. (Be sure to say yes to the "autodoc" exten‐
72 sion.)
73 Defining document structure
75 Let's assume you've run sphinx-quickstart. It created a source direc‐
76 tory with conf.py and a master document, index.rst (if you accepted the
77 defaults). The main function of the master document is to serve as a
78 welcome page, and to contain the root of the "table of contents tree"
79 (or toctree). This is one of the main things that Sphinx adds to
80 reStructuredText, a way to connect multiple files to a single hierarchy
81 of documents.
82 reStructuredText directives
84 toctree is a reStructuredText directive, a very versatile piece of
85 markup. Directives can have arguments, options and content.
86 Arguments are given directly after the double colon following the
88 directive's name. Each directive decides whether it can have argu‐
89 ments, and how many.
90 Options are given after the arguments, in form of a "field list". The
92 maxdepth is such an option for the toctree directive.
93 Content follows the options or arguments after a blank line. Each
95 directive decides whether to allow content, and what to do with it.
96 A common gotcha with directives is that the first line of the content
98 must be indented to the same level as the options are.
99 The toctree directive initially is empty, and looks like this:
101 .. toctree::
103 :maxdepth: 2
104 You add documents listing them in the content of the directive:
106 .. toctree::
108 :maxdepth: 2
109 intro
111 tutorial
112 ...
113 This is exactly how the toctree for this documentation looks. The doc‐
115 uments to include are given as document names, which in short means
116 that you leave off the file name extension and use slashes as directory
117 separators.
118 [image: more info] [image]
120 Read more about the toctree directive.
121 You can now create the files you listed in the toctree and add content,
123 and their section titles will be inserted (up to the "maxdepth" level)
124 at the place where the toctree directive is placed. Also, Sphinx now
125 knows about the order and hierarchy of your documents. (They may con‐
126 tain toctree directives themselves, which means you can create deeply
127 nested hierarchies if necessary.)
128 Adding content
130 In Sphinx source files, you can use most features of standard reStruc‐
131 turedText. There are also several features added by Sphinx. For exam‐
132 ple, you can add cross-file references in a portable way (which works
133 for all output types) using the ref role.
134 For an example, if you are viewing the HTML version you can look at the
136 source for this document -- use the "Show Source" link in the sidebar.
137 [image: more info] [image]
139 See rst-primer for a more in-depth introduction to reStructuredText
140 and sphinxmarkup for a full list of markup added by Sphinx.
141 Running the build
143 Now that you have added some files and content, let's make a first
144 build of the docs. A build is started with the sphinx-build program,
145 called like this:
146 $ sphinx-build -b html sourcedir builddir
148 where sourcedir is the source directory, and builddir is the directory
150 in which you want to place the built documentation. The -b option
151 selects a builder; in this example Sphinx will build HTML files.
152 [image: more info] [image]
154 See invocation for all options that sphinx-build supports.
155 However, sphinx-quickstart script creates a Makefile and a make.bat
157 which make life even easier for you: with them you only need to run
158 $ make html
160 to build HTML docs in the build directory you chose. Execute make
162 without an argument to see which targets are available.
163 Documenting objects
165 One of Sphinx' main objectives is easy documentation of objects (in a
166 very general sense) in any domain. A domain is a collection of object
167 types that belong together, complete with markup to create and refer‐
168 ence descriptions of these objects.
169 The most prominent domain is the Python domain. To e.g. document the
171 Python built-in function enumerate(), you would add this to one of your
172 source files:
173 .. py:function:: enumerate(sequence[, start=0])
175 Return an iterator that yields tuples of an index and an item of the
177 *sequence*. (And so on.)
178 This is rendered like this:
180 enumerate(sequence[, start=0])
182 Return an iterator that yields tuples of an index and an item of
184 the sequence. (And so on.)
185 The argument of the directive is the signature of the object you
187 describe, the content is the documentation for it. Multiple signatures
188 can be given, each in its own line.
189 The Python domain also happens to be the default domain, so you don't
191 need to prefix the markup with the domain name:
192 .. function:: enumerate(sequence[, start=0])
194 ...
196 does the same job if you keep the default setting for the default
198 domain.
199 There are several more directives for documenting other types of Python
201 objects, for example py:class or py:method. There is also a cross-ref‐
202 erencing role for each of these object types. This markup will create
203 a link to the documentation of enumerate():
204 The :py:func:`enumerate` function can be used for ...
206 And here is the proof: A link to enumerate().
208 Again, the py: can be left out if the Python domain is the default one.
210 It doesn't matter which file contains the actual documentation for enu‐
211 merate(); Sphinx will find it and create a link to it.
212 Each domain will have special rules for how the signatures can look
214 like, and make the formatted output look pretty, or add specific fea‐
215 tures like links to parameter types, e.g. in the C/C++ domains.
216 [image: more info] [image]
218 See domains for all the available domains and their directives/roles.
219 Basic configuration
221 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
222 cesses your documents. In that file, which is executed as a Python
223 source file, you assign configuration values. For advanced users:
224 since it is executed by Sphinx, you can do non-trivial tasks in it,
225 like extending sys.path or importing a module to find out the version
226 your are documenting.
227 The config values that you probably want to change are already put into
229 the conf.py by sphinx-quickstart and initially commented out (with
230 standard Python syntax: a # comments the rest of the line). To change
231 the default value, remove the hash sign and modify the value. To cus‐
232 tomize a config value that is not automatically added by sphinx-quick‐
233 start, just add an additional assignment.
234 Keep in mind that the file uses Python syntax for strings, numbers,
236 lists and so on. The file is saved in UTF-8 by default, as indicated
237 by the encoding declaration in the first line. If you use non-ASCII
238 characters in any string value, you need to use Python Unicode strings
239 (like project = u'Exposé').
240 [image: more info] [image]
242 See build-config for documentation of all available config values.
243 Autodoc
245 When documenting Python code, it is common to put a lot of documenta‐
246 tion in the source files, in documentation strings. Sphinx supports
247 the inclusion of docstrings from your modules with an extension (an
248 extension is a Python module that provides additional features for
249 Sphinx projects) called "autodoc".
250 In order to use autodoc, you need to activate it in conf.py by putting
252 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
253 sions config value. Then, you have a few additional directives at your
254 disposal.
255 For example, to document the function io.open(), reading its signature
257 and docstring from the source file, you'd write this:
258 .. autofunction:: io.open
260 You can also document whole classes or even modules automatically,
262 using member options for the auto directives, like
263 .. automodule:: io
265 :members:
266 autodoc needs to import your modules in order to extract the doc‐
268 strings. Therefore, you must add the appropriate path to sys.path in
269 your conf.py.
270 [image: more info] [image]
272 See sphinx.ext.autodoc for the complete description of the features of
273 autodoc.
274 More topics to be covered
276 · Other extensions (math, intersphinx, viewcode, doctest)
277 · Static files
279 · Selecting a theme
281 · Templating
283 · Using extensions
285 · Writing extensions
287
289 [1] This is the usual lay-out. However, conf.py can also live in
290 another directory, the configuration directory. See invocation.
291
293 The sphinx-build script builds a Sphinx documentation set. It is
294 called like this:
295 $ sphinx-build [options] sourcedir builddir [filenames]
297 where sourcedir is the source directory, and builddir is the directory
299 in which you want to place the built documentation. Most of the time,
300 you don't need to specify any filenames.
301 The sphinx-build script has several options:
303 -b buildername
305 The most important option: it selects a builder. The most com‐
307 mon builders are:
308 html
310 Build HTML pages. This is the default builder.
312 dirhtml
314 Build HTML pages, but with a single directory per docu‐
316 ment. Makes for prettier URLs (no .html) if served from
317 a webserver.
318 singlehtml
320 Build a single HTML with the whole content.
322 htmlhelp, qthelp, devhelp, epub
324 Build HTML files with additional information for building
326 a documentation collection in one of these formats.
327 latex
329 Build LaTeX sources that can be compiled to a PDF docu‐
331 ment using pdflatex.
332 man
334 Build manual pages in groff format for UNIX systems.
336 text
338 Build plain text files.
340 doctest
342 Run all doctests in the documentation, if the doctest
344 extension is enabled.
345 linkcheck
347 Check the integrity of all external links.
349 See builders for a list of all builders shipped with Sphinx.
351 Extensions can add their own builders.
352 -a If given, always write all output files. The default is to only
354 write output files for new and changed source files. (This may
355 not apply to all builders.)
356 -E Don't use a saved environment (the structure caching all
358 cross-references), but rebuild it completely. The default is to
359 only read and parse source files that are new or have changed
360 since the last run.
361 -t tag
363 Define the tag tag. This is relevant for only directives that
365 only include their content if this tag is set.
366 New in version 0.6.
368 -d path
370 Since Sphinx has to read and parse all source files before it
372 can write an output file, the parsed source files are cached as
373 "doctree pickles". Normally, these files are put in a directory
374 called .doctrees under the build directory; with this option you
375 can select a different cache directory (the doctrees can be
376 shared between all builders).
377 -c path
379 Don't look for the conf.py in the source directory, but use the
381 given configuration directory instead. Note that various other
382 files and paths given by configuration values are expected to be
383 relative to the configuration directory, so they will have to be
384 present at this location too.
385 New in version 0.3.
387 -C Don't look for a configuration file; only take options via the
389 -D option.
390 New in version 0.5.
392 -D setting=value
394 Override a configuration value set in the conf.py file. The
396 value must be a string or dictionary value. For the latter,
397 supply the setting name and key like this: -D latex_ele‐
398 ments.docclass=scrartcl. For boolean values, use 0 or 1 as the
399 value.
400 Changed in version 0.6: The value can now be a dictionary value.
402 -A name=value
404 Make the name assigned to value in the HTML templates.
406 New in version 0.5.
408 -n Run in nit-picky mode. Currently, this generates warnings for
410 all missing references.
411 -N Do not emit colored output. (On Windows, colored output is dis‐
413 abled in any case.)
414 -q Do not output anything on standard output, only write warnings
416 and errors to standard error.
417 -Q Do not output anything on standard output, also suppress warn‐
419 ings. Only errors are written to standard error.
420 -w file
422 Write warnings (and errors) to the given file, in addition to
424 standard error.
425 -W Turn warnings into errors. This means that the build stops at
427 the first warning and sphinx-build exits with exit status 1.
428 -P (Useful for debugging only.) Run the Python debugger, pdb, if
430 an unhandled exception occurs while building.
431 You can also give one or more filenames on the command line after the
433 source and build directories. Sphinx will then try to build only these
434 output files (and their dependencies).
435 Makefile options
437 The Makefile and make.bat files created by sphinx-quickstart usually
438 run sphinx-build only with the -b and -d options. However, they sup‐
439 port the following variables to customize behavior:
440 PAPER The value for latex_paper_size.
442 SPHINXBUILD
444 The command to use instead of sphinx-build.
445 BUILDDIR
447 The build directory to use instead of the one chosen in
448 sphinx-quickstart.
449 SPHINXOPTS
451 Additional options for sphinx-build.
452
454 This section is a brief introduction to reStructuredText (reST) con‐
455 cepts and syntax, intended to provide authors with enough information
456 to author documents productively. Since reST was designed to be a sim‐
457 ple, unobtrusive markup language, this will not take too long.
458 See also
460 The authoritative reStructuredText User Documentation. The
462 "ref" links in this document link to the description of the
463 individual constructs in the reST reference.
464 Paragraphs
466 The paragraph (ref) is the most basic block in a reST document. Para‐
467 graphs are simply chunks of text separated by one or more blank lines.
468 As in Python, indentation is significant in reST, so all lines of the
469 same paragraph must be left-aligned to the same level of indentation.
470 Inline markup
472 The standard reST inline markup is quite simple: use
473 · one asterisk: *text* for emphasis (italics),
475 · two asterisks: **text** for strong emphasis (boldface), and
477 · backquotes: ``text`` for code samples.
479 If asterisks or backquotes appear in running text and could be confused
481 with inline markup delimiters, they have to be escaped with a back‐
482 slash.
483 Be aware of some restrictions of this markup:
485 · it may not be nested,
487 · content may not start or end with whitespace: * text* is wrong,
489 · it must be separated from surrounding text by non-word characters.
491 Use a backslash escaped space to work around that: thisis\ *one*\
492 word.
493 These restrictions may be lifted in future versions of the docutils.
495 reST also allows for custom "interpreted text roles"', which signify
497 that the enclosed text should be interpreted in a specific way. Sphinx
498 uses this to provide semantic markup and cross-referencing of identi‐
499 fiers, as described in the appropriate section. The general syntax is
500 :rolename:`content`.
501 Standard reST provides the following roles:
503 · emphasis -- alternate spelling for *emphasis*
505 · strong -- alternate spelling for **strong**
507 · literal -- alternate spelling for ``literal``
509 · subscript -- subscript text
511 · superscript -- superscript text
513 · title-reference -- for titles of books, periodicals, and other mate‐
515 rials
516 See inline-markup for roles added by Sphinx.
518 Lists and Quote-like blocks
520 List markup (ref) is natural: just place an asterisk at the start of a
521 paragraph and indent properly. The same goes for numbered lists; they
522 can also be autonumbered using a # sign:
523 * This is a bulleted list.
525 * It has two items, the second
526 item uses two lines.
527 1. This is a numbered list.
529 2. It has two items too.
530 #. This is a numbered list.
532 #. It has two items too.
533 Nested lists are possible, but be aware that they must be separated
535 from the parent list items by blank lines:
536 * this is
538 * a list
539 * with a nested list
541 * and some subitems
542 * and here the parent list continues
544 Definition lists (ref) are created as follows:
546 term (up to a line of text)
548 Definition of the term, which must be indented
549 and can even consist of multiple paragraphs
551 next term
553 Description.
554 Note that the term cannot have more than one line of text.
556 Quoted paragraphs (ref) are created by just indenting them more than
558 the surrounding paragraphs.
559 Line blocks (ref) are a way of preserving line breaks:
561 | These lines are
563 | broken exactly like in
564 | the source file.
565 There are also several more special blocks available:
567 · field lists (ref)
569 · option lists (ref)
571 · quoted literal blocks (ref)
573 · doctest blocks (ref)
575 Source Code
577 Literal code blocks (ref) are introduced by ending a paragraph with the
578 special marker ::. The literal block must be indented (and, like all
579 paragraphs, separated from the surrounding ones by blank lines):
580 This is a normal text paragraph. The next paragraph is a code sample::
582 It is not processed in any way, except
584 that the indentation is removed.
585 It can span multiple lines.
587 This is a normal text paragraph again.
589 The handling of the :: marker is smart:
591 · If it occurs as a paragraph of its own, that paragraph is completely
593 left out of the document.
594 · If it is preceded by whitespace, the marker is removed.
596 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
598 gle colon.
599 That way, the second sentence in the above example's first paragraph
601 would be rendered as "The next paragraph is a code sample:".
602 Tables
604 Two forms of tables are supported. For grid tables (ref), you have to
605 "paint" the cell grid yourself. They look like this:
606 +------------------------+------------+----------+----------+
608 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
609 | (header rows optional) | | | |
610 +========================+============+==========+==========+
611 | body row 1, column 1 | column 2 | column 3 | column 4 |
612 +------------------------+------------+----------+----------+
613 | body row 2 | ... | ... | |
614 +------------------------+------------+----------+----------+
615 Simple tables (ref) are easier to write, but limited: they must contain
617 more than one row, and the first column cannot contain multiple lines.
618 They look like this:
619 ===== ===== =======
621 A B A and B
622 ===== ===== =======
623 False False False
624 True False False
625 False True False
626 True True True
627 ===== ===== =======
628 Hyperlinks
630 External links
631 Use `Link text <http://example.com/>`_ for inline web links. If the
632 link text should be the web address, you don't need special markup at
633 all, the parser finds links and mail addresses in ordinary text.
634 You can also separate the link and the target definition (ref), like
636 this:
637 This is a paragraph that contains `a link`_.
639 .. _a link: http://example.com/
641 Internal links
643 Internal linking is done via a special reST role provided by Sphinx,
644 see the section on specific markup, ref-role.
645 Sections
647 Section headers (ref) are created by underlining (and optionally over‐
648 lining) the section title with a punctuation character, at least as
649 long as the text:
650 =================
652 This is a heading
653 =================
654 Normally, there are no heading levels assigned to certain characters as
656 the structure is determined from the succession of headings. However,
657 for the Python documentation, this convention is used which you may
658 follow:
659 · # with overline, for parts
661 · * with overline, for chapters
663 · =, for sections
665 · -, for subsections
667 · ^, for subsubsections
669 · ", for paragraphs
671 Of course, you are free to use your own marker characters (see the reST
673 documentation), and use a deeper nesting level, but keep in mind that
674 most target formats (HTML, LaTeX) have a limited supported nesting
675 depth.
676 Explicit Markup
678 "Explicit markup" (ref) is used in reST for most constructs that need
679 special handling, such as footnotes, specially-highlighted paragraphs,
680 comments, and generic directives.
681 An explicit markup block begins with a line starting with .. followed
683 by whitespace and is terminated by the next paragraph at the same level
684 of indentation. (There needs to be a blank line between explicit
685 markup and normal paragraphs. This may all sound a bit complicated,
686 but it is intuitive enough when you write it.)
687 Directives
689 A directive (ref) is a generic block of explicit markup. Besides
690 roles, it is one of the extension mechanisms of reST, and Sphinx makes
691 heavy use of it.
692 Docutils supports the following directives:
694 · Admonitions: attention, caution, danger, error, hint, important,
696 note, tip, warning and the generic admonition. (Most themes style
697 only "note" and "warning" specially.)
698 · Images:
700 · image (see also Images below)
702 · figure (an image with caption and optional legend)
704 · Additional body elements:
706 · contents (a local, i.e. for the current file only, table of con‐
708 tents)
709 · container (a container with a custom class, useful to generate an
711 outer <div> in HTML)
712 · rubric (a heading without relation to the document sectioning)
714 · topic, sidebar (special highlighted body elements)
716 · parsed-literal (literal block that supports inline markup)
718 · epigraph (a block quote with optional attribution line)
720 · highlights, pull-quote (block quotes with their own class
722 attribute)
723 · compound (a compound paragraph)
725 · Special tables:
727 · table (a table with title)
729 · csv-table (a table generated from comma-separated values)
731 · list-table (a table generated from a list of lists)
733 · Special directives:
735 · raw (include raw target-format markup)
737 · include (include reStructuredText from another file) -- in Sphinx,
739 when given an absolute include file path, this directive takes it
740 as relative to the source directory
741 · class (assign a class attribute to the next element) [1]
743 · HTML specifics:
745 · meta (generation of HTML <meta> tags)
747 · title (override document title)
749 · Influencing markup:
751 · default-role (set a new default role)
753 · role (create a new role)
755 Since these are only per-file, better use Sphinx' facilities for set‐
757 ting the default_role.
758 Do not use the directives sectnum, header and footer.
760 Directives added by Sphinx are described in sphinxmarkup.
762 Basically, a directive consists of a name, arguments, options and con‐
764 tent. (Keep this terminology in mind, it is used in the next chapter
765 describing custom directives.) Looking at this example,
766 .. function:: foo(x)
768 foo(y, z)
769 :module: some.module.name
770 Return a line of text input from the user.
772 function is the directive name. It is given two arguments here, the
774 remainder of the first line and the second line, as well as one option
775 module (as you can see, options are given in the lines immediately fol‐
776 lowing the arguments and indicated by the colons). Options must be
777 indented to the same level as the directive content.
778 The directive content follows after a blank line and is indented rela‐
780 tive to the directive start.
781 Images
783 reST supports an image directive (ref), used like so:
784 .. image:: gnu.png
786 (options)
787 When used within Sphinx, the file name given (here gnu.png) must either
789 be relative to the source file, or absolute which means that they are
790 relative to the top source directory. For example, the file
791 sketch/spam.rst could refer to the image images/spam.png as
792 ../images/spam.png or /images/spam.png.
793 Sphinx will automatically copy image files over to a subdirectory of
795 the output directory on building (e.g. the _static directory for HTML
796 output.)
797 Interpretation of image size options (width and height) is as follows:
799 if the size has no unit or the unit is pixels, the given size will only
800 be respected for output channels that support pixels (i.e. not in LaTeX
801 output). Other units (like pt for points) will be used for HTML and
802 LaTeX output.
803 Sphinx extends the standard docutils behavior by allowing an asterisk
805 for the extension:
806 .. image:: gnu.*
808 Sphinx then searches for all images matching the provided pattern and
810 determines their type. Each builder then chooses the best image out of
811 these candidates. For instance, if the file name gnu.* was given and
812 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
813 builder would choose the former, while the HTML builder would prefer
814 the latter.
815 Changed in version 0.4: Added the support for file names ending in an
817 asterisk.
818 Changed in version 0.6: Image paths can now be absolute.
820 Footnotes
822 For footnotes (ref), use [#name]_ to mark the footnote location, and
823 add the footnote body at the bottom of the document after a "Footnotes"
824 rubric heading, like so:
825 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
827 .. rubric:: Footnotes
829 .. [#f1] Text of the first footnote.
831 .. [#f2] Text of the second footnote.
832 You can also explicitly number the footnotes ([1]_) or use auto-num‐
834 bered footnotes without names ([#]_).
835 Citations
837 Standard reST citations (ref) are supported, with the additional fea‐
838 ture that they are "global", i.e. all citations can be referenced from
839 all files. Use them like so:
840 Lorem ipsum [Ref]_ dolor sit amet.
842 .. [Ref] Book or article reference, URL or whatever.
844 Citation usage is similar to footnote usage, but with a label that is
846 not numeric or begins with #.
847 Substitutions
849 reST supports "substitutions" (ref), which are pieces of text and/or
850 markup referred to in the text by |name|. They are defined like foot‐
851 notes with explicit markup blocks, like this:
852 .. |name| replace:: replacement *text*
854 or this:
856 .. |caution| image:: warning.png
858 :alt: Warning!
859 See the reST reference for substitutions for details.
861 If you want to use some substitutions for all documents, put them into
863 rst_prolog or put them into a separate file and include it into all
864 documents you want to use them in, using the include directive. (Be
865 sure to give the include file a file name extension differing from that
866 of other source files, to avoid Sphinx finding it as a standalone docu‐
867 ment.)
868 Sphinx defines some default substitutions, see default-substitutions.
870 Comments
872 Every explicit markup block which isn't a valid markup construct (like
873 the footnotes above) is regarded as a comment (ref). For example:
874 .. This is a comment.
876 You can indent text after a comment start to form multiline comments:
878 ..
880 This whole indented block
881 is a comment.
882 Still in the comment.
884 Source encoding
886 Since the easiest way to include special characters like em dashes or
887 copyright signs in reST is to directly write them as Unicode charac‐
888 ters, one has to specify an encoding. Sphinx assumes source files to
889 be encoded in UTF-8 by default; you can change this with the
890 source_encoding config value.
891 Gotchas
893 There are some problems one commonly runs into while authoring reST
894 documents:
895 · Separation of inline markup: As said above, inline markup spans must
897 be separated from the surrounding text by non-word characters, you
898 have to use a backslash-escaped space to get around that. See the
899 reference for the details.
900 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
902 sible.
903
905 [1] When the default domain contains a class directive, this directive
906 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
907
909 Sphinx adds a lot of new directives and interpreted text roles to
910 standard reST markup. This section contains the reference material for
911 these facilities.
912 The TOC tree
914 Since reST does not have facilities to interconnect several documents,
915 or split documents into multiple output files, Sphinx uses a custom
916 directive to add relations between the single files the documentation
917 is made of, as well as tables of contents. The toctree directive is
918 the central element.
919 .. toctree::
921 This directive inserts a "TOC tree" at the current location,
923 using the individual TOCs (including "sub-TOC trees") of the
924 documents given in the directive body. Relative document names
925 (not beginning with a slash) are relative to the document the
926 directive occurs in, absolute names are relative to the source
927 directory. A numeric maxdepth option may be given to indicate
928 the depth of the tree; by default, all levels are included. [1]
929 Consider this example (taken from the Python docs' library ref‐
931 erence index):
932 .. toctree::
934 :maxdepth: 2
935 intro
937 strings
938 datatypes
939 numeric
940 (many more documents listed here)
941 This accomplishes two things:
943 · Tables of contents from all those documents are inserted, with
945 a maximum depth of two, that means one nested heading. toc‐
946 tree directives in those documents are also taken into
947 account.
948 · Sphinx knows that the relative order of the documents intro,
950 strings and so forth, and it knows that they are children of
951 the shown document, the library index. From this information
952 it generates "next chapter", "previous chapter" and "parent
953 chapter" links.
954 Document titles in the toctree will be automatically read from
956 the title of the referenced document. If that isn't what you
957 want, you can specify an explicit title and target using a simi‐
958 lar syntax to reST hyperlinks (and Sphinx's cross-referencing
959 syntax). This looks like:
960 .. toctree::
962 intro
964 All about strings <strings>
965 datatypes
966 The second line above will link to the strings document, but
968 will use the title "All about strings" instead of the title of
969 the strings document.
970 You can also add external links, by giving an HTTP URL instead
972 of a document name.
973 If you want to have section numbers even in HTML output, give
975 the toctree a numbered flag option. For example:
976 .. toctree::
978 :numbered:
979 foo
981 bar
982 Numbering then starts at the heading of foo. Sub-toctrees are
984 automatically numbered (don't give the numbered flag to those).
985 If you want only the titles of documents in the tree to show up,
987 not other headings of the same level, you can use the titlesonly
988 option:
989 .. toctree::
991 :titlesonly:
992 foo
994 bar
995 You can use "globbing" in toctree directives, by giving the glob
997 flag option. All entries are then matched against the list of
998 available documents, and matches are inserted into the list
999 alphabetically. Example:
1000 .. toctree::
1002 :glob:
1003 intro*
1005 recipe/*
1006 *
1007 This includes first all documents whose names start with intro,
1009 then all documents in the recipe folder, then all remaining doc‐
1010 uments (except the one containing the directive, of course.) [2]
1011 The special entry name self stands for the document containing
1013 the toctree directive. This is useful if you want to generate a
1014 "sitemap" from the toctree.
1015 You can also give a "hidden" option to the directive, like this:
1017 .. toctree::
1019 :hidden:
1020 doc_1
1022 doc_2
1023 This will still notify Sphinx of the document hierarchy, but not
1025 insert links into the document at the location of the directive
1026 -- this makes sense if you intend to insert these links your‐
1027 self, in a different style, or in the HTML sidebar.
1028 In the end, all documents in the source directory (or subdirec‐
1030 tories) must occur in some toctree directive; Sphinx will emit a
1031 warning if it finds a file that is not included, because that
1032 means that this file will not be reachable through standard nav‐
1033 igation. Use unused_docs to explicitly exclude documents from
1034 building, and exclude_trees to exclude whole directories.
1035 The "master document" (selected by master_doc) is the "root" of
1037 the TOC tree hierarchy. It can be used as the documentation's
1038 main page, or as a "full table of contents" if you don't give a
1039 maxdepth option.
1040 Changed in version 0.3: Added "globbing" option.
1042 Changed in version 0.6: Added "numbered" and "hidden" options as
1044 well as external links and support for "self" references.
1045 Changed in version 1.0: Added "titlesonly" option.
1047 Special names
1049 Sphinx reserves some document names for its own use; you should not try
1050 to create documents with these names -- it will cause problems.
1051 The special document names (and pages generated for them) are:
1053 · genindex, modindex, search
1055 These are used for the general index, the Python module index, and
1057 the search page, respectively.
1058 The general index is populated with entries from modules, all
1060 index-generating object descriptions, and from index directives.
1061 The Python module index contains one entry per py:module directive.
1063 The search page contains a form that uses the generated JSON search
1065 index and JavaScript to full-text search the generated documents for
1066 search words; it should work on every major browser that supports
1067 modern JavaScript.
1068 · every name beginning with _
1070 Though only few such names are currently used by Sphinx, you should
1072 not create documents or document-containing directories with such
1073 names. (Using _ as a prefix for a custom template directory is
1074 fine.)
1075
1077 [1] The maxdepth option does not apply to the LaTeX writer, where the
1078 whole table of contents will always be presented at the begin of
1079 the document, and its depth is controlled by the tocdepth counter,
1080 which you can reset in your latex_preamble config value using e.g.
1081 \setcounter{tocdepth}{2}.
1082 [2] A note on available globbing syntax: you can use the standard
1084 shell constructs *, ?, [...] and [!...] with the feature that
1085 these all don't match slashes. A double star ** can be used to
1086 match any sequence of characters including slashes.
1087 Paragraph-level markup
1089 These directives create short paragraphs and can be used inside infor‐
1090 mation units as well as normal text:
1091 .. note::
1093 An especially important bit of information about an API that a
1095 user should be aware of when using whatever bit of API the note
1096 pertains to. The content of the directive should be written in
1097 complete sentences and include all appropriate punctuation.
1098 Example:
1100 .. note::
1102 This function is not suitable for sending spam e-mails.
1104 .. warning::
1106 An important bit of information about an API that a user should
1108 be very aware of when using whatever bit of API the warning per‐
1109 tains to. The content of the directive should be written in
1110 complete sentences and include all appropriate punctuation. This
1111 differs from note in that it is recommended over note for infor‐
1112 mation regarding security.
1113 .. versionadded:: version
1115 This directive documents the version of the project which added
1117 the described feature to the library or C API. When this applies
1118 to an entire module, it should be placed at the top of the mod‐
1119 ule section before any prose.
1120 The first argument must be given and is the version in question;
1122 you can add a second argument consisting of a brief explanation
1123 of the change.
1124 Example:
1126 .. versionadded:: 2.5
1128 The *spam* parameter.
1129 Note that there must be no blank line between the directive head
1131 and the explanation; this is to make these blocks visually con‐
1132 tinuous in the markup.
1133 .. versionchanged:: version
1135 Similar to versionadded, but describes when and what changed in
1137 the named feature in some way (new parameters, changed side
1138 effects, etc.).
1139 .. deprecated:: vesion
1141 Similar to versionchanged, but describes when the feature was
1143 deprecated. An explanation can also be given, for example to
1144 inform the reader what should be used instead. Example:
1145 .. deprecated:: 3.1
1147 Use :func:`spam` instead.
1148 ----
1151 .. seealso::
1155 Many sections include a list of references to module documenta‐
1157 tion or external documents. These lists are created using the
1158 seealso directive.
1159 The seealso directive is typically placed in a section just
1161 before any sub-sections. For the HTML output, it is shown boxed
1162 off from the main flow of the text.
1163 The content of the seealso directive should be a reST definition
1165 list. Example:
1166 .. seealso::
1168 Module :py:mod:`zipfile`
1170 Documentation of the :py:mod:`zipfile` standard module.
1171 `GNU tar manual, Basic Tar Format <http://link>`_
1173 Documentation for tar archive files, including GNU tar extensions.
1174 There's also a "short form" allowed that looks like this:
1176 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1178 New in version 0.5: The short form.
1180 .. rubric:: title
1182 This directive creates a paragraph heading that is not used to
1184 create a table of contents node.
1185 Note If the title of the rubric is "Footnotes" (or the selected lan‐
1187 guage's equivalent), this rubric is ignored by the LaTeX writer,
1188 since it is assumed to only contain footnote definitions and
1189 therefore would create an empty heading.
1190 .. centered::
1192 This directive creates a centered boldfaced line of text. Use
1194 it as follows:
1195 .. centered:: LICENSE AGREEMENT
1197 .. hlist::
1199 This directive must contain a bullet list. It will transform it
1201 into a more compact list by either distributing more than one
1202 item horizontally, or reducing spacing between items, depending
1203 on the builder.
1204 For builders that support the horizontal distribution, there is
1206 a columns option that specifies the number of columns; it
1207 defaults to 2. Example:
1208 .. hlist::
1210 :columns: 3
1211 * A list of
1213 * short items
1214 * that should be
1215 * displayed
1216 * horizontally
1217 New in version 0.6.
1219 Table-of-contents markup
1221 The toctree directive, which generates tables of contents of subdocu‐
1222 ments, is described in toctree-directive.
1223 For local tables of contents, use the standard reST contents directive.
1225 Index-generating markup
1227 Sphinx automatically creates index entries from all object descriptions
1228 (like functions, classes or attributes) like discussed in domains.
1229 However, there is also an explicit directive available, to make the
1231 index more comprehensive and enable index entries in documents where
1232 information is not mainly contained in information units, such as the
1233 language reference.
1234 .. index:: <entries>
1236 This directive contains one or more index entries. Each entry
1238 consists of a type and a value, separated by a colon.
1239 For example:
1241 .. index::
1243 single: execution; context
1244 module: __main__
1245 module: sys
1246 triple: module; search; path
1247 The execution context
1249 ---------------------
1250 ...
1252 This directive contains five entries, which will be converted to
1254 entries in the generated index which link to the exact location
1255 of the index statement (or, in case of offline media, the corre‐
1256 sponding page number).
1257 Since index directives generate cross-reference targets at their
1259 location in the source, it makes sense to put them before the
1260 thing they refer to -- e.g. a heading, as in the example above.
1261 The possible entry types are:
1263 single Creates a single index entry. Can be made a subentry by
1265 separating the subentry text with a semicolon (this nota‐
1266 tion is also used below to describe what entries are cre‐
1267 ated).
1268 pair pair: loop; statement is a shortcut that creates two
1270 index entries, namely loop; statement and statement;
1271 loop.
1272 triple Likewise, triple: module; search; path is a shortcut that
1274 creates three index entries, which are module; search
1275 path, search; path, module and path; module search.
1276 module, keyword, operator, object, exception, statement, builtin
1278 These all create two index entries. For example, module:
1279 hashlib creates the entries module; hashlib and hashlib;
1280 module. (These are Python-specific and therefore depre‐
1281 cated.)
1282 For index directives containing only "single" entries, there is
1284 a shorthand notation:
1285 .. index:: BNF, grammar, syntax, notation
1287 This creates four index entries.
1289 Glossary
1291 .. glossary::
1292 This directive must contain a reST definition list with terms
1294 and definitions. The definitions will then be referencable with
1295 the term role. Example:
1296 .. glossary::
1298 environment
1300 A structure where information about all documents under the root is
1301 saved, and used for cross-referencing. The environment is pickled
1302 after the parsing stage, so that successive runs only need to read
1303 and parse new and changed documents.
1304 source directory
1306 The directory which, including its subdirectories, contains all
1307 source files for one Sphinx project.
1308 New in version 0.6: You can now give the glossary directive a
1310 :sorted: flag that will automatically sort the entries alphabet‐
1311 ically.
1312 Grammar production displays
1314 Special markup is available for displaying the productions of a formal
1315 grammar. The markup is simple and does not attempt to model all
1316 aspects of BNF (or any derived forms), but provides enough to allow
1317 context-free grammars to be displayed in a way that causes uses of a
1318 symbol to be rendered as hyperlinks to the definition of the symbol.
1319 There is this directive:
1320 .. productionlist:: [name]
1322 This directive is used to enclose a group of productions. Each
1324 production is given on a single line and consists of a name,
1325 separated by a colon from the following definition. If the def‐
1326 inition spans multiple lines, each continuation line must begin
1327 with a colon placed at the same column as in the first line.
1328 The argument to productionlist serves to distinguish different
1330 sets of production lists that belong to different grammars.
1331 Blank lines are not allowed within productionlist directive
1333 arguments.
1334 The definition can contain token names which are marked as
1336 interpreted text (e.g. sum ::= `integer` "+" `integer`) -- this
1337 generates cross-references to the productions of these tokens.
1338 Outside of the production list, you can reference to token pro‐
1339 ductions using token.
1340 Note that no further reST parsing is done in the production, so
1342 that you don't have to escape * or | characters.
1343 The following is an example taken from the Python Reference Manual:
1345 .. productionlist::
1347 try_stmt: try1_stmt | try2_stmt
1348 try1_stmt: "try" ":" `suite`
1349 : ("except" [`expression` ["," `target`]] ":" `suite`)+
1350 : ["else" ":" `suite`]
1351 : ["finally" ":" `suite`]
1352 try2_stmt: "try" ":" `suite`
1353 : "finally" ":" `suite`
1354 Showing code examples
1356 Examples of Python source code or interactive sessions are represented
1357 using standard reST literal blocks. They are started by a :: at the
1358 end of the preceding paragraph and delimited by indentation.
1359 Representing an interactive session requires including the prompts and
1361 output along with the Python code. No special markup is required for
1362 interactive sessions. After the last line of input or output pre‐
1363 sented, there should not be an "unused" primary prompt; this is an
1364 example of what not to do:
1365 >>> 1 + 1
1367 2
1368 >>>
1369 Syntax highlighting is done with Pygments (if it's installed) and han‐
1371 dled in a smart way:
1372 · There is a "highlighting language" for each source file. Per
1374 default, this is 'python' as the majority of files will have to high‐
1375 light Python snippets, but the doc-wide default can be set with the
1376 highlight_language config value.
1377 · Within Python highlighting mode, interactive sessions are recognized
1379 automatically and highlighted appropriately. Normal Python code is
1380 only highlighted if it is parseable (so you can use Python as the
1381 default, but interspersed snippets of shell commands or other code
1382 blocks will not be highlighted as Python).
1383 · The highlighting language can be changed using the highlight direc‐
1385 tive, used as follows:
1386 .. highlight:: c
1388 This language is used until the next highlight directive is encoun‐
1390 tered.
1391 · For documents that have to show snippets in different languages,
1393 there's also a code-block directive that is given the highlighting
1394 language directly:
1395 .. code-block:: ruby
1397 Some Ruby code.
1399 The directive's alias name sourcecode works as well.
1401 · The valid values for the highlighting language are:
1403 · none (no highlighting)
1405 · python (the default when highlight_language isn't set)
1407 · guess (let Pygments guess the lexer based on contents, only works
1409 with certain well-recognizable languages)
1410 · rest
1412 · c
1414 ·
1416 · If highlighting with the selected language fails, the block is not
1418 highlighted in any way.
1419 Line numbers
1421 If installed, Pygments can generate line numbers for code blocks. For
1422 automatically-highlighted blocks (those started by ::), line numbers
1423 must be switched on in a highlight directive, with the linenothreshold
1424 option:
1425 .. highlight:: python
1427 :linenothreshold: 5
1428 This will produce line numbers for all code blocks longer than five
1430 lines.
1431 For code-block blocks, a linenos flag option can be given to switch on
1433 line numbers for the individual block:
1434 .. code-block:: ruby
1436 :linenos:
1437 Some more Ruby code.
1439 Includes
1441 .. literalinclude:: filename
1442 Longer displays of verbatim text may be included by storing the
1444 example text in an external file containing only plain text.
1445 The file may be included using the literalinclude directive. [1]
1446 For example, to include the Python source file example.py, use:
1447 .. literalinclude:: example.py
1449 The file name is usually relative to the current file's path.
1451 However, if it is absolute (starting with /), it is relative to
1452 the top source directory.
1453 Tabs in the input are expanded if you give a tab-width option
1455 with the desired tab width.
1456 The directive also supports the linenos flag option to switch on
1458 line numbers, and a language option to select a language differ‐
1459 ent from the current file's standard language. Example with
1460 options:
1461 .. literalinclude:: example.rb
1463 :language: ruby
1464 :linenos:
1465 Include files are assumed to be encoded in the source_encoding.
1467 If the file has a different encoding, you can specify it with
1468 the encoding option:
1469 .. literalinclude:: example.py
1471 :encoding: latin-1
1472 The directive also supports including only parts of the file.
1474 If it is a Python module, you can select a class, function or
1475 method to include using the pyobject option:
1476 .. literalinclude:: example.py
1478 :pyobject: Timer.start
1479 This would only include the code lines belonging to the start()
1481 method in the Timer class within the file.
1482 Alternately, you can specify exactly which lines to include by
1484 giving a lines option:
1485 .. literalinclude:: example.py
1487 :lines: 1,3,5-10,20-
1488 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
1490 line.
1491 Another way to control which part of the file is included is to
1493 use the start-after and end-before options (or only one of
1494 them). If start-after is given as a string option, only lines
1495 that follow the first line containing that string are included.
1496 If end-before is given as a string option, only lines that pre‐
1497 cede the first lines containing that string are included.
1498 You can prepend and/or append a line to the included code, using
1500 the prepend and append option, respectively. This is useful
1501 e.g. for highlighting PHP code that doesn't include the <?php/?>
1502 markers.
1503 New in version 0.4.3: The encoding option.
1505 New in version 0.6: The pyobject, lines, start-after and
1507 end-before options, as well as support for absolute filenames.
1508 New in version 1.0: The prepend and append options, as well as
1510 tab-width.
1511
1513 [1] There is a standard .. include directive, but it raises errors if
1514 the file is not found. This one only emits a warning.
1515 Inline markup
1517 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1518 ments. They are written as :rolename:`content`.
1519 Note The default role (`content`) has no special meaning by default.
1521 You are free to use it for anything you like, e.g. variable
1522 names; use the default_role config value to set it to a known
1523 role.
1524 See domains for roles added by domains.
1526 Cross-referencing syntax
1528 Cross-references are generated by many semantic interpreted text roles.
1529 Basically, you only need to write :role:`target`, and a link will be
1530 created to the item named target of the type indicated by role. The
1531 links's text will be the same as target.
1532 There are some additional facilities, however, that make cross-refer‐
1534 encing roles more versatile:
1535 · You may supply an explicit title and reference target, like in reST
1537 direct hyperlinks: :role:`title <target>` will refer to target, but
1538 the link text will be title.
1539 · If you prefix the content with !, no reference/hyperlink will be cre‐
1541 ated.
1542 · If you prefix the content with ~, the link text will only be the last
1544 component of the target. For example, :py:meth:`~Queue.Queue.get`
1545 will refer to Queue.Queue.get but only display get as the link text.
1546 In HTML output, the link's title attribute (that is e.g. shown as a
1548 tool-tip on mouse-hover) will always be the full target name.
1549 Cross-referencing objects
1551 These roles are described with their respective domains:
1552 · Python
1554 · C
1556 · C++
1558 · JavaScript
1560 · ReST
1562 Cross-referencing arbitrary locations
1564 :ref: To support cross-referencing to arbitrary locations in any docu‐
1565 ment, the standard reST labels are used. For this to work label
1566 names must be unique throughout the entire documentation. There
1567 are two ways in which you can refer to labels:
1568 · If you place a label directly before a section title, you can
1570 reference to it with :ref:`label-name`. Example:
1571 .. _my-reference-label:
1573 Section to cross-reference
1575 --------------------------
1576 This is the text of the section.
1578 It refers to the section itself, see :ref:`my-reference-label`.
1580 The :ref: role would then generate a link to the section, with
1582 the link title being "Section to cross-reference". This works
1583 just as well when section and reference are in different
1584 source files.
1585 Automatic labels also work with figures: given
1587 .. _my-figure:
1589 .. figure:: whatever
1591 Figure caption
1593 a reference :ref:`my-figure` would insert a reference to the
1595 figure with link text "Figure caption".
1596 The same works for tables that are given an explicit caption
1598 using the table directive.
1599 · Labels that aren't placed before a section title can still be
1601 referenced to, but you must give the link an explicit title,
1602 using this syntax: :ref:`Link title <label-name>`.
1603 Using ref is advised over standard reStructuredText links to
1605 sections (like `Section title`_) because it works across files,
1606 when section headings are changed, and for all builders that
1607 support cross-references.
1608 Cross-referencing documents
1610 New in version 0.6.
1611 There is also a way to directly link to documents:
1613 :doc: Link to the specified document; the document name can be speci‐
1615 fied in absolute or relative fashion. For example, if the ref‐
1616 erence :doc:`parrot` occurs in the document sketches/index, then
1617 the link refers to sketches/parrot. If the reference is
1618 :doc:`/people` or :doc:`../people`, the link refers to people.
1619 If no explicit link text is given (like usual: :doc:`Monty
1621 Python members </people>`), the link caption will be the title
1622 of the given document.
1623 Referencing downloadable files
1625 New in version 0.6.
1626 :download:
1628 This role lets you link to files within your source tree that
1629 are not reST documents that can be viewed, but files that can be
1630 downloaded.
1631 When you use this role, the referenced file is automatically
1633 marked for inclusion in the output when building (obviously, for
1634 HTML output only). All downloadable files are put into the
1635 _downloads subdirectory of the output directory; duplicate file‐
1636 names are handled.
1637 An example:
1639 See :download:`this example script <../example.py>`.
1641 The given filename is usually relative to the directory the cur‐
1643 rent source file is contained in, but if it absolute (starting
1644 with /), it is taken as relative to the top source directory.
1645 The example.py file will be copied to the output directory, and
1647 a suitable link generated to it.
1648 Cross-referencing other items of interest
1650 The following roles do possibly create a cross-reference, but do not
1651 refer to objects:
1652 :envvar:
1654 An environment variable. Index entries are generated. Also
1655 generates a link to the matching envvar directive, if it exists.
1656 :token:
1658 The name of a grammar token (used to create links between pro‐
1659 ductionlist directives).
1660 :keyword:
1662 The name of a keyword in Python. This creates a link to a ref‐
1663 erence label with that name, if it exists.
1664 :option:
1666 A command-line option to an executable program. The leading
1667 hyphen(s) must be included. This generates a link to a option
1668 directive, if it exists.
1669 The following role creates a cross-reference to the term in the glos‐
1671 sary:
1672 :term: Reference to a term in the glossary. The glossary is created
1674 using the glossary directive containing a definition list with
1675 terms and definitions. It does not have to be in the same file
1676 as the term markup, for example the Python docs have one global
1677 glossary in the glossary.rst file.
1678 If you use a term that's not explained in a glossary, you'll get
1680 a warning during build.
1681 Other semantic markup
1683 The following roles don't do anything special except formatting the
1684 text in a different style:
1685 :abbr: An abbreviation. If the role content contains a parenthesized
1687 explanation, it will be treated specially: it will be shown in a
1688 tool-tip in HTML, and output only once in LaTeX.
1689 Example: :abbr:`LIFO (last-in, first-out)`.
1691 New in version 0.6.
1693 :command:
1695 The name of an OS-level command, such as rm.
1696 :dfn: Mark the defining instance of a term in the text. (No index
1698 entries are generated.)
1699 :file: The name of a file or directory. Within the contents, you can
1701 use curly braces to indicate a "variable" part, for example:
1702 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1704 In the built documentation, the x will be displayed differently
1706 to indicate that it is to be replaced by the Python minor ver‐
1707 sion.
1708 :guilabel:
1710 Labels presented as part of an interactive user interface should
1711 be marked using guilabel. This includes labels from text-based
1712 interfaces such as those created using curses or other
1713 text-based libraries. Any label used in the interface should be
1714 marked with this role, including button labels, window titles,
1715 field names, menu and menu selection names, and even values in
1716 selection lists.
1717 Changed in version 1.0: An accelerator key for the GUI label can
1719 be included using an ampersand; this will be stripped and dis‐
1720 played underlined in the output (example: :guilabel:`&Cancel`).
1721 To include a literal ampersand, double it.
1722 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1724 may depend on platform- or application-specific conventions.
1725 When there are no relevant conventions, the names of modifier
1726 keys should be spelled out, to improve accessibility for new
1727 users and non-native speakers. For example, an xemacs key
1728 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1729 ence to a specific application or platform, the same sequence
1730 should be marked as :kbd:`Control-x Control-f`.
1731 :mailheader:
1733 The name of an RFC 822-style mail header. This markup does not
1734 imply that the header is being used in an email message, but can
1735 be used to refer to any header of the same "style." This is
1736 also used for headers defined by the various MIME specifica‐
1737 tions. The header name should be entered in the same way it
1738 would normally be found in practice, with the camel-casing con‐
1739 ventions being preferred where there is more than one common
1740 usage. For example: :mailheader:`Content-Type`.
1741 :makevar:
1743 The name of a make variable.
1744 :manpage:
1746 A reference to a Unix manual page including the section, e.g.
1747 :manpage:`ls(1)`.
1748 :menuselection:
1750 Menu selections should be marked using the menuselection role.
1751 This is used to mark a complete sequence of menu selections,
1752 including selecting submenus and choosing a specific operation,
1753 or any subsequence of such a sequence. The names of individual
1754 selections should be separated by -->.
1755 For example, to mark the selection "Start > Programs", use this
1757 markup:
1758 :menuselection:`Start --> Programs`
1760 When including a selection that includes some trailing indica‐
1762 tor, such as the ellipsis some operating systems use to indicate
1763 that the command opens a dialog, the indicator should be omitted
1764 from the selection name.
1765 menuselection also supports ampersand accelerators just like
1767 guilabel.
1768 :mimetype:
1770 The name of a MIME type, or a component of a MIME type (the
1771 major or minor portion, taken alone).
1772 :newsgroup:
1774 The name of a Usenet newsgroup.
1775 :program:
1777 The name of an executable program. This may differ from the
1778 file name for the executable for some platforms. In particular,
1779 the .exe (or other) extension should be omitted for Windows pro‐
1780 grams.
1781 :regexp:
1783 A regular expression. Quotes should not be included.
1784 :samp: A piece of literal text, such as code. Within the contents, you
1786 can use curly braces to indicate a "variable" part, as in file.
1787 For example, in :samp:`print 1+{variable}`, the part variable
1788 would be emphasized.
1789 If you don't need the "variable part" indication, use the stan‐
1791 dard ``code`` instead.
1792 The following roles generate external links:
1794 :pep: A reference to a Python Enhancement Proposal. This generates
1796 appropriate index entries. The text "PEP number" is generated;
1797 in the HTML output, this text is a hyperlink to an online copy
1798 of the specified PEP. You can link to a specific section by
1799 saying :pep:`number#anchor`.
1800 :rfc: A reference to an Internet Request for Comments. This generates
1802 appropriate index entries. The text "RFC number" is generated;
1803 in the HTML output, this text is a hyperlink to an online copy
1804 of the specified RFC. You can link to a specific section by
1805 saying :rfc:`number#anchor`.
1806 Note that there are no special roles for including hyperlinks as you
1808 can use the standard reST markup for that purpose.
1809 Substitutions
1811 The documentation system provides three substitutions that are defined
1812 by default. They are set in the build configuration file.
1813 |release|
1815 Replaced by the project release the documentation refers to.
1816 This is meant to be the full version string including
1817 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1818 release.
1819 |version|
1821 Replaced by the project version the documentation refers to.
1822 This is meant to consist only of the major and minor version
1823 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1824 |today|
1826 Replaced by either today's date (the date on which the document
1827 is read), or the date set in the build configuration file. Nor‐
1828 mally has the format April 14, 2007. Set by today_fmt and
1829 today.
1830 Miscellaneous markup
1832 File-wide metadata
1833 reST has the concept of "field lists"; these are a sequence of fields
1834 marked up like this:
1835 :fieldname: Field content
1837 A field list near the top of a file is parsed by docutils as the
1839 "docinfo" which is normally used to record the author, date of publica‐
1840 tion and other metadata. In Sphinx, a field list preceding any other
1841 markup is moved from the docinfo to the Sphinx environment as document
1842 metadata and is not displayed in the output; a field list appearing
1843 after the document title will be part of the docinfo as normal and will
1844 be displayed in the output.
1845 At the moment, these metadata fields are recognized:
1847 tocdepth
1849 The maximum depth for a table of contents of this file.
1851 New in version 0.4.
1853 nocomments
1855 If set, the web application won't display a comment form for a
1857 page generated from this source file.
1858 orphan
1860 If set, warnings about this file not being included in any toc‐
1862 tree will be suppressed.
1863 New in version 1.0.
1865 Meta-information markup
1867 .. sectionauthor:: name <email>
1868 Identifies the author of the current section. The argument
1870 should include the author's name such that it can be used for
1871 presentation and email address. The domain name portion of the
1872 address should be lower case. Example:
1873 .. sectionauthor:: Guido van Rossum <guido@python.org>
1875 By default, this markup isn't reflected in the output in any way
1877 (it helps keep track of contributions), but you can set the con‐
1878 figuration value show_authors to True to make them produce a
1879 paragraph in the output.
1880 .. codeauthor:: name <email>
1882 The codeauthor directive, which can appear multiple times, names
1884 the authors of the described code, just like sectionauthor names
1885 the author(s) of a piece of documentation. It too only produces
1886 output if the show_authors configuration value is True.
1887 Including content based on tags
1889 .. only:: <expression>
1890 Include the content of the directive only if the expression is
1892 true. The expression should consist of tags, like this:
1893 .. only:: html and draft
1895 Undefined tags are false, defined tags (via the -t command-line
1897 option or within conf.py) are true. Boolean expressions, also
1898 using parentheses (like html and (latex or draft)) are sup‐
1899 ported.
1900 The format of the current builder (html, latex or text) is
1902 always set as a tag.
1903 New in version 0.6.
1905 Tables
1907 Use standard reStructuredText tables. They work fine in HTML output,
1908 however there are some gotchas when using tables in LaTeX: the column
1909 width is hard to determine correctly automatically. For this reason,
1910 the following directive exists:
1911 .. tabularcolumns:: column spec
1913 This directive gives a "column spec" for the next table occur‐
1915 ring in the source file. The spec is the second argument to the
1916 LaTeX tabulary package's environment (which Sphinx uses to
1917 translate tables). It can have values like
1918 |l|l|l|
1920 which means three left-adjusted, nonbreaking columns. For col‐
1922 umns with longer text that should automatically be broken, use
1923 either the standard p{width} construct, or tabulary's automatic
1924 specifiers:
1925 ┌──┬────────────────────────────┐
1927 │L │ ragged-left column with │
1928 │ │ automatic width │
1929 └──┴────────────────────────────┘
1930 │R │ ragged-right column with │
1932 │ │ automatic width │
1933 ├──┼────────────────────────────┤
1934 │C │ centered column with auto‐ │
1935 │ │ matic width │
1936 ├──┼────────────────────────────┤
1937 │J │ justified column with │
1938 │ │ automatic width │
1939 └──┴────────────────────────────┘
1940 The automatic width is determined by rendering the content in
1942 the table, and scaling them according to their share of the
1943 total width.
1944 By default, Sphinx uses a table layout with L for every column.
1946 New in version 0.3.
1948 Warning
1950 Tables that contain list-like elements such as object descrip‐
1951 tions, blockquotes or any kind of lists cannot be set out of the
1952 box with tabulary. They are therefore set with the standard
1953 LaTeX tabular environment if you don't give a tabularcolumns
1954 directive. If you do, the table will be set with tabulary, but
1955 you must use the p{width} construct for the columns that contain
1956 these elements.
1957 Literal blocks do not work with tabulary at all, so tables con‐
1959 taining a literal block are always set with tabular. Also, the
1960 verbatim environment used for literal blocks only works in
1961 p{width} columns, which means that by default, Sphinx generates
1962 such column specs for such tables. Use the tabularcolumns
1963 directive to get finer control over such tables.
1964 More markup is added by domains.
1966
1968 New in version 1.0.
1969 What is a Domain?
1971 Originally, Sphinx was conceived for a single project, the documenta‐
1972 tion of the Python language. Shortly afterwards, it was made available
1973 for everyone as a documentation tool, but the documentation of Python
1974 modules remained deeply built in -- the most fundamental directives,
1975 like function, were designed for Python objects. Since Sphinx has
1976 become somewhat popular, interest developed in using it for many dif‐
1977 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
1978 markup (like in this documentation).
1979 While this was always possible, it is now much easier to easily support
1981 documentation of projects using different programming languages or even
1982 ones not supported by the main Sphinx distribution, by providing a
1983 domain for every such purpose.
1984 A domain is a collection of markup (reStructuredText directives and
1986 roles) to describe and link to objects belonging together, e.g. ele‐
1987 ments of a programming language. Directive and role names in a domain
1988 have names like domain:name, e.g. py:function. Domains can also pro‐
1989 vide custom indices (like the Python Module Index).
1990 Having domains means that there are no naming problems when one set of
1992 documentation wants to refer to e.g. C++ and Python classes. It also
1993 means that extensions that support the documentation of whole new lan‐
1994 guages are much easier to write.
1995 This section describes what the domains that come with Sphinx provide.
1997 The domain API is documented as well, in the section domain-api.
1998 Basic Markup
2000 Most domains provide a number of object description directives, used to
2001 describe specific objects provided by modules. Each directive requires
2002 one or more signatures to provide basic information about what is being
2003 described, and the content should be the description. The basic ver‐
2004 sion makes entries in the general index; if no index entry is desired,
2005 you can give the directive option flag :noindex:. An example using a
2006 Python domain directive:
2007 .. py:function:: spam(eggs)
2009 ham(eggs)
2010 Spam or ham the foo.
2012 This describes the two Python functions spam and ham. (Note that when
2014 signatures become too long, you can break them if you add a backslash
2015 to lines that are continued in the next line. Example:
2016 .. py:function:: filterwarnings(action, message='', category=Warning, \
2018 module='', lineno=0, append=False)
2019 :noindex:
2020 (This example also shows how to use the :noindex: flag.)
2022 The domains also provide roles that link back to these object descrip‐
2024 tions. For example, to link to one of the functions described in the
2025 example above, you could say
2026 The function :py:func:`spam` does a similar thing.
2028 As you can see, both directive and role names contain the domain name
2030 and the directive name. Default Domain
2031 To avoid having to writing the domain name all the time when you e.g.
2033 only describe Python objects, a default domain can be selected with
2034 either the config value primary_domain or this directive:
2035 .. default-domain:: name
2037 Select a new default domain. While the primary_domain selects a
2039 global default, this only has an effect within the same file.
2040 If no other default is selected, the Python domain (named py) is the
2042 default one, mostly for compatibility with documentation written for
2043 older versions of Sphinx.
2044 Directives and roles that belong to the default domain can be mentioned
2046 without giving the domain name, i.e.
2047 .. function:: pyfunc()
2049 Describes a Python function.
2051 Reference to :func:`pyfunc`.
2053 Cross-referencing syntax
2055 For cross-reference roles provided by domains, the same facilities
2056 exist as for general cross-references. See xref-syntax.
2057 In short:
2059 · You may supply an explicit title and reference target: :role:`title
2061 <target>` will refer to target, but the link text will be title.
2062 · If you prefix the content with !, no reference/hyperlink will be cre‐
2064 ated.
2065 · If you prefix the content with ~, the link text will only be the last
2067 component of the target. For example, :py:meth:`~Queue.Queue.get`
2068 will refer to Queue.Queue.get but only display get as the link text.
2069 The Python Domain
2071 The Python domain (name py) provides the following directives for mod‐
2072 ule declarations:
2073 .. py:module:: name
2075 This directive marks the beginning of the description of a mod‐
2077 ule (or package submodule, in which case the name should be
2078 fully qualified, including the package name). It does not cre‐
2079 ate content (like e.g. py:class does).
2080 This directive will also cause an entry in the global module
2082 index.
2083 The platform option, if present, is a comma-separated list of
2085 the platforms on which the module is available (if it is avail‐
2086 able on all platforms, the option should be omitted). The keys
2087 are short identifiers; examples that are in use include "IRIX",
2088 "Mac", "Windows", and "Unix". It is important to use a key
2089 which has already been used when applicable.
2090 The synopsis option should consist of one sentence describing
2092 the module's purpose -- it is currently only used in the Global
2093 Module Index.
2094 The deprecated option can be given (with no value) to mark a
2096 module as deprecated; it will be designated as such in various
2097 locations then.
2098 .. py:currentmodule:: name
2100 This directive tells Sphinx that the classes, functions etc.
2102 documented from here are in the given module (like py:module),
2103 but it will not create index entries, an entry in the Global
2104 Module Index, or a link target for py:mod. This is helpful in
2105 situations where documentation for things in a module is spread
2106 over multiple files or sections -- one location has the py:mod‐
2107 ule directive, the others only py:currentmodule.
2108 The following directives are provided for module and class contents:
2110 .. py:data:: name
2112 Describes global data in a module, including both variables and
2114 values used as "defined constants." Class and object attributes
2115 are not documented using this environment.
2116 .. py:exception:: name
2118 Describes an exception class. The signature can, but need not
2120 include parentheses with constructor arguments.
2121 .. py:function:: name(signature)
2123 Describes a module-level function. The signature should include
2125 the parameters, enclosing optional parameters in brackets.
2126 Default values can be given if it enhances clarity; see signa‐
2127 tures. For example:
2128 .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
2130 Object methods are not documented using this directive. Bound
2132 object methods placed in the module namespace as part of the
2133 public interface of the module are documented using this, as
2134 they are equivalent to normal functions for most purposes.
2135 The description should include information about the parameters
2137 required and how they are used (especially whether mutable
2138 objects passed as parameters are modified), side effects, and
2139 possible exceptions. A small example may be provided.
2140 .. py:class:: name[(signature)]
2142 Describes a class. The signature can include parentheses with
2144 parameters which will be shown as the constructor arguments.
2145 See also signatures.
2146 Methods and attributes belonging to the class should be placed
2148 in this directive's body. If they are placed outside, the sup‐
2149 plied name should contain the class name so that cross-refer‐
2150 ences still work. Example:
2151 .. py:class:: Foo
2153 .. py:method:: quux()
2154 -- or --
2156 .. py:class:: Bar
2158 .. py:method:: Bar.quux()
2160 The first way is the preferred one.
2162 .. py:attribute:: name
2164 Describes an object data attribute. The description should
2166 include information about the type of the data to be expected
2167 and whether it may be changed directly.
2168 .. py:method:: name(signature)
2170 Describes an object method. The parameters should not include
2172 the self parameter. The description should include similar
2173 information to that described for function. See also signa‐
2174 tures.
2175 .. py:staticmethod:: name(signature)
2177 Like py:method, but indicates that the method is a static
2179 method.
2180 New in version 0.4.
2182 .. py:classmethod:: name(signature)
2184 Like py:method, but indicates that the method is a class method.
2186 New in version 0.6.
2188 Python Signatures
2190 Signatures of functions, methods and class constructors can be given
2191 like they would be written in Python, with the exception that optional
2192 parameters can be indicated by brackets:
2193 .. py:function:: compile(source[, filename[, symbol]])
2195 It is customary to put the opening bracket before the comma. In addi‐
2197 tion to this "nested" bracket style, a "flat" style can also be used,
2198 due to the fact that most optional parameters can be given indepen‐
2199 dently:
2200 .. py:function:: compile(source[, filename, symbol])
2202 Default values for optional arguments can be given (but if they contain
2204 commas, they will confuse the signature parser). Python 3-style argu‐
2205 ment annotations can also be given as well as return type annotations:
2206 .. py:function:: compile(source : string[, filename, symbol]) -> ast object
2208 Info field lists
2210 New in version 0.4.
2211 Inside Python object description directives, reST field lists with
2213 these fields are recognized and formatted nicely:
2214 · param, parameter, arg, argument, key, keyword: Description of a
2216 parameter.
2217 · type: Type of a parameter.
2219 · raises, raise, except, exception: That (and when) a specific excep‐
2221 tion is raised.
2222 · var, ivar, cvar: Description of a variable.
2224 · returns, return: Description of the return value.
2226 · rtype: Return type.
2228 The field names must consist of one of these keywords and an argument
2230 (except for returns and rtype, which do not need an argument). This is
2231 best explained by an example:
2232 .. py:function:: format_exception(etype, value, tb[, limit=None])
2234 Format the exception with a traceback.
2236 :param etype: exception type
2238 :param value: exception value
2239 :param tb: traceback object
2240 :param limit: maximum number of stack frames to show
2241 :type limit: integer or None
2242 :rtype: list of strings
2243 This will render like this:
2245 format_exception(etype, value, tb[, limit=None])
2247 Format the exception with a traceback.
2249 Parameters
2251 · etype -- exception type
2253 · value -- exception value
2255 · tb -- traceback object
2257 · limit (integer or None) -- maximum number of stack
2259 frames to show
2260 Return type
2262 list of strings
2263 It is also possible to combine parameter type and description, if the
2265 type is a single word, like this:
2266 :param integer limit: maximum number of stack frames to show
2268 Cross-referencing Python objects
2270 The following roles refer to objects in modules and are possibly hyper‐
2271 linked if a matching identifier is found:
2272 :py:mod:
2274 Reference a module; a dotted name may be used. This should also
2275 be used for package names.
2276 :py:func:
2278 Reference a Python function; dotted names may be used. The role
2279 text needs not include trailing parentheses to enhance readabil‐
2280 ity; they will be added automatically by Sphinx if the add_func‐
2281 tion_parentheses config value is true (the default).
2282 :py:data:
2284 Reference a module-level variable.
2285 :py:const:
2287 Reference a "defined" constant. This may be a C-language
2288 #define or a Python variable that is not intended to be changed.
2289 :py:class:
2291 Reference a class; a dotted name may be used.
2292 :py:meth:
2294 Reference a method of an object. The role text can include the
2295 type name and the method name; if it occurs within the descrip‐
2296 tion of a type, the type name can be omitted. A dotted name may
2297 be used.
2298 :py:attr:
2300 Reference a data attribute of an object.
2301 :py:exc:
2303 Reference an exception. A dotted name may be used.
2304 :py:obj:
2306 Reference an object of unspecified type. Useful e.g. as the
2307 default_role.
2308 New in version 0.4.
2310 The name enclosed in this markup can include a module name and/or a
2312 class name. For example, :py:func:`filter` could refer to a function
2313 named filter in the current module, or the built-in function of that
2314 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
2315 function in the foo module.
2316 Normally, names in these roles are searched first without any further
2318 qualification, then with the current module name prepended, then with
2319 the current module and class name (if any) prepended. If you prefix
2320 the name with a dot, this order is reversed. For example, in the docu‐
2321 mentation of Python's codecs module, :py:func:`open` always refers to
2322 the built-in function, while :py:func:`.open` refers to codecs.open().
2323 A similar heuristic is used to determine whether the name is an
2325 attribute of the currently documented class.
2326 Also, if the name is prefixed with a dot, and no exact match is found,
2328 the target is taken as a suffix and all object names with that suffix
2329 are searched. For example, :py:meth:`.TarFile.close` references the
2330 tarfile.TarFile.close() function, even if the current module is not
2331 tarfile. Since this can get ambiguous, if there is more than one pos‐
2332 sible match, you will get a warning from Sphinx.
2333 Note that you can combine the ~ and . prefixes:
2335 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
2336 method, but the visible link caption will only be close().
2337 The C Domain
2339 The C domain (name c) is suited for documentation of C API.
2340 .. c:function:: type name(signature)
2342 Describes a C function. The signature should be given as in C,
2344 e.g.:
2345 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
2347 This is also used to describe function-like preprocessor macros.
2349 The names of the arguments should be given so they may be used
2350 in the description.
2351 Note that you don't have to backslash-escape asterisks in the
2353 signature, as it is not parsed by the reST inliner.
2354 .. c:member:: type name
2356 Describes a C struct member. Example signature:
2358 .. c:member:: PyObject* PyTypeObject.tp_bases
2360 The text of the description should include the range of values
2362 allowed, how the value should be interpreted, and whether the
2363 value can be changed. References to structure members in text
2364 should use the member role.
2365 .. c:macro:: name
2367 Describes a "simple" C macro. Simple macros are macros which
2369 are used for code expansion, but which do not take arguments so
2370 cannot be described as functions. This is not to be used for
2371 simple constant definitions. Examples of its use in the Python
2372 documentation include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
2373 .. c:type:: name
2375 Describes a C type (whether defined by a typedef or struct). The
2377 signature should just be the type name.
2378 .. c:var:: type name
2380 Describes a global C variable. The signature should include the
2382 type, such as:
2383 .. c:var:: PyObject* PyClass_Type
2385 Cross-referencing C constructs
2387 The following roles create cross-references to C-language constructs if
2388 they are defined in the documentation:
2389 :c:data:
2391 Reference a C-language variable.
2392 :c:func:
2394 Reference a C-language function. Should include trailing paren‐
2395 theses.
2396 :c:macro:
2398 Reference a "simple" C macro, as defined above.
2399 :c:type:
2401 Reference a C-language type.
2402 The C++ Domain
2404 The C++ domain (name cpp) supports documenting C++ projects.
2405 The following directives are available:
2407 .. cpp:class:: signatures
2409 .. cpp:function:: signatures
2411 .. cpp:member:: signatures
2413 .. cpp:type:: signatures
2415 Describe a C++ object. Full signature specification is sup‐
2417 ported -- give the signature as you would in the declaration.
2418 Here some examples:
2419 .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
2421 Describes a method with parameters and types.
2423 .. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
2425 Describes a method without types.
2427 .. cpp:function:: const T &array<T>::operator[]() const
2429 Describes the constant indexing operator of a templated array.
2431 .. cpp:function:: operator bool() const
2433 Describe a casting operator here.
2435 .. cpp:member:: std::string theclass::name
2437 .. cpp:type:: theclass::const_iterator
2439 Will be rendered like this:
2441 bool namespaced::theclass::method(int arg1, std::string arg2)
2443 Describes a method with parameters and types.
2445 bool namespaced::theclass::method(arg1 None, arg2 None)
2447 Describes a method without types.
2449 const T& array<T>::operator[]() const
2451 Describes the constant indexing operator of a tem‐
2453 plated array.
2454 operator bool() const
2456 Describe a casting operator here.
2458 std::string theclass::name
2460 type theclass::const_iterator
2462 .. cpp:namespace:: namespace
2464 Select the current C++ namespace for the following objects.
2466 These roles link to the given object types:
2468 :cpp:class:
2470 :cpp:func:
2472 :cpp:member:
2474 :cpp:type:
2476 Reference a C++ object. You can give the full signature (and
2477 need to, for overloaded functions.)
2478 Note Sphinx' syntax to give references a custom title can interfere
2480 with linking to template classes, if nothing follows the closing
2481 angle bracket, i.e. if the link looks like this:
2482 :cpp:class:`MyClass<T>`. This is interpreted as a link to T
2483 with a title of MyClass. In this case, please escape the open‐
2484 ing angle bracket with a backslash, like this:
2485 :cpp:class:`MyClass\<T>`.
2486 Note on References
2488 It is currently impossible to link to a specific version of an
2490 overloaded method. Currently the C++ domain is the first domain
2491 that has basic support for overloaded methods and until there is
2492 more data for comparison we don't want to select a bad syntax to
2493 reference a specific overload. Currently Sphinx will link to
2494 the first overloaded version of the method / function.
2495 The Standard Domain
2497 The so-called "standard" domain collects all markup that doesn't war‐
2498 rant a domain of its own. Its directives and roles are not prefixed
2499 with a domain name.
2500 The standard domain is also where custom object descriptions, added
2502 using the add_object_type() API, are placed.
2503 There is a set of directives allowing documenting command-line pro‐
2505 grams:
2506 .. option:: name args, name args, ...
2508 Describes a command line option or switch. Option argument
2510 names should be enclosed in angle brackets. Example:
2511 .. option:: -m <module>, --module <module>
2513 Run a module as a script.
2515 The directive will create a cross-reference target named after
2517 the first option, referencable by option (in the example case,
2518 you'd use something like :option:`-m`).
2519 .. envvar:: name
2521 Describes an environment variable that the documented code or
2523 program uses or defines. Referencable by envvar.
2524 .. program:: name
2526 Like py:currentmodule, this directive produces no output.
2528 Instead, it serves to notify Sphinx that all following option
2529 directives document options for the program called name.
2530 If you use program, you have to qualify the references in your
2532 option roles by the program name, so if you have the following
2533 situation
2534 .. program:: rm
2536 .. option:: -r
2538 Work recursively.
2540 .. program:: svn
2542 .. option:: -r revision
2544 Specify the revision to work upon.
2546 then :option:`rm -r` would refer to the first option, while
2548 :option:`svn -r` would refer to the second one.
2549 The program name may contain spaces (in case you want to docu‐
2551 ment subcommands like svn add and svn commit separately).
2552 New in version 0.5.
2554 There is also a very generic object description directive, which is not
2556 tied to any domain:
2557 .. describe:: text
2559 .. object:: text
2561 This directive produces the same formatting as the specific ones
2563 provided by domains, but does not create index entries or
2564 cross-referencing targets. Example:
2565 .. describe:: PAPER
2567 You can set this variable to select a paper size.
2569 The JavaScript Domain
2571 The JavaScript domain (name js) provides the following directives:
2572 .. js:function:: name(signature)
2574 Describes a JavaScript function or method. If you want to
2576 describe arguments as optional use square brackets as documented
2577 for Python signatures.
2578 You can use fields to give more details about arguments and
2580 their expected types, errors which may be thrown by the func‐
2581 tion, and the value being returned:
2582 .. js:function:: $.getJSON(href, callback[, errback])
2584 :param string href: An URI to the location of the resource.
2586 :param callback: Get's called with the object.
2587 :param errback:
2588 Get's called in case the request fails. And a lot of other
2589 text so we need multiple lines
2590 :throws SomeError: For whatever reason in that case.
2591 :returns: Something
2592 This is rendered as:
2594 $.getJSON(href, callback[, errback])
2596 Arguments
2598 · href (string) -- An URI to the location of
2600 the resource.
2601 · callback -- Get's called with the object.
2603 · errback -- Get's called in case the request
2605 fails. And a lot of other text so we need
2606 multiple lines.
2607 Throws SomeError
2609 For whatever reason in that case.
2611 Returns
2613 Something
2614 .. js:class:: name
2616 Describes a constructor that creates an object. This is basi‐
2618 cally like a function but will show up with a class prefix:
2619 .. js:class:: MyAnimal(name[, age])
2621 :param string name: The name of the animal
2623 :param number age: an optional age for the animal
2624 This is rendered as:
2626 class MyAnimal(name[, age])
2628 Arguments
2630 · name (string) -- The name of the animal
2632 · age (number) -- an optional age for the ani‐
2634 mal
2635 .. js:data:: name
2637 Describes a global variable or constant.
2639 .. js:attribute:: object.name
2641 Describes the attribute name of object.
2643 These roles are provided to refer to the described objects:
2645 :js:func:
2647 :js:class:
2649 :js:data:
2651 :js:attr:
2653 The reStructuredText domain
2655 The reStructuredText domain (name rst) provides the following direc‐
2656 tives:
2657 .. rst:directive:: name
2659 Describes a reST directive. The name can be a single directive
2661 name or actual directive syntax (.. prefix and :: suffix) with
2662 arguments that will be rendered differently. For example:
2663 .. rst:directive:: foo
2665 Foo description.
2667 .. rst:directive:: .. bar:: baz
2669 Bar description.
2671 will be rendered as:
2673 .. foo::
2675 Foo description.
2677 .. bar:: baz
2679 Bar description.
2681 .. rst:role:: name
2683 Describes a reST role. For example:
2685 .. rst:role:: foo
2687 Foo description.
2689 will be rendered as:
2691 :foo: Foo description.
2693 These roles are provided to refer to the described objects:
2695 :rst:dir:
2697 :rst:role:
2699 More domains
2701 The sphinx-contrib repository contains more domains available as exten‐
2702 sions; currently a Ruby and an Erlang domain.
2703
2705 These are the built-in Sphinx builders. More builders can be added by
2706 extensions.
2707 The builder's "name" must be given to the -b command-line option of
2709 sphinx-build to select a builder.
2710 class sphinx.builders.html.StandaloneHTMLBuilder
2712 This is the standard HTML builder. Its output is a directory
2714 with HTML files, complete with style sheets and optionally the
2715 reST sources. There are quite a few configuration values that
2716 customize the output of this builder, see the chapter
2717 html-options for details.
2718 Its name is html.
2720 class sphinx.builders.html.DirectoryHTMLBuilder
2722 This is a subclass of the standard HTML builder. Its output is
2724 a directory with HTML files, where each file is called
2725 index.html and placed in a subdirectory named like its page
2726 name. For example, the document markup/rest.rst will not result
2727 in an output file markup/rest.html, but markup/rest/index.html.
2728 When generating links between pages, the index.html is omitted,
2729 so that the URL would look like markup/rest/.
2730 Its name is dirhtml.
2732 New in version 0.6.
2734 class sphinx.builders.html.SingleFileHTMLBuilder
2736 This is an HTML builder that combines the whole project in one
2738 output file. (Obviously this only works with smaller projects.)
2739 The file is named like the master document. No indices will be
2740 generated.
2741 Its name is singlehtml.
2743 New in version 1.0.
2745 class sphinx.builders.htmlhelp.HTMLHelpBuilder
2747 This builder produces the same output as the standalone HTML
2749 builder, but also generates HTML Help support files that allow
2750 the Microsoft HTML Help Workshop to compile them into a CHM
2751 file.
2752 Its name is htmlhelp.
2754 class sphinx.builders.qthelp.QtHelpBuilder
2756 This builder produces the same output as the standalone HTML
2758 builder, but also generates Qt help collection support files
2759 that allow the Qt collection generator to compile them.
2760 Its name is qthelp.
2762 class sphinx.builders.devhelp.DevhelpBuilder
2764 This builder produces the same output as the standalone HTML
2766 builder, but also generates GNOME Devhelp support file that
2767 allows the GNOME Devhelp reader to view them.
2768 Its name is devhelp.
2770 class sphinx.builders.epub.EpubBuilder
2772 This builder produces the same output as the standalone HTML
2774 builder, but also generates an epub file for ebook readers. See
2775 epub-faq for details about it. For definition of the epub for‐
2776 mat, have a look at http://www.idpf.org/specs.htm or
2777 http://en.wikipedia.org/wiki/EPUB.
2778 Some ebook readers do not show the link targets of references.
2780 Therefore this builder adds the targets after the link when nec‐
2781 essary. The display of the URLs can be customized by adding CSS
2782 rules for the class link-target.
2783 Its name is epub.
2785 class sphinx.builders.latex.LaTeXBuilder
2787 This builder produces a bunch of LaTeX files in the output
2789 directory. You have to specify which documents are to be
2790 included in which LaTeX files via the latex_documents configura‐
2791 tion value. There are a few configuration values that customize
2792 the output of this builder, see the chapter latex-options for
2793 details.
2794 Note The produced LaTeX file uses several LaTeX packages that may not
2796 be present in a "minimal" TeX distribution installation. For
2797 TeXLive, the following packages need to be installed:
2798 · latex-recommended
2800 · latex-extra
2802 · fonts-recommended
2804 Its name is latex.
2806 Note that a direct PDF builder using ReportLab is available in rst2pdf
2808 version 0.12 or greater. You need to add 'rst2pdf.pdfbuilder' to your
2809 extensions to enable it, its name is pdf. Refer to the rst2pdf manual
2810 for details.
2811 class sphinx.builders.text.TextBuilder
2813 This builder produces a text file for each reST file -- this is
2815 almost the same as the reST source, but with much of the markup
2816 stripped for better readability.
2817 Its name is text.
2819 New in version 0.4.
2821 class sphinx.builders.manpage.ManualPageBuilder
2823 This builder produces manual pages in the groff format. You
2825 have to specify which documents are to be included in which man‐
2826 ual pages via the man_pages configuration value.
2827 Its name is man.
2829 Note This builder requires the docutils manual page writer, which is
2831 only available as of docutils 0.6.
2832 New in version 1.0.
2834 class sphinx.builders.html.SerializingHTMLBuilder
2836 This builder uses a module that implements the Python serializa‐
2838 tion API (pickle, simplejson, phpserialize, and others) to dump
2839 the generated HTML documentation. The pickle builder is a sub‐
2840 class of it.
2841 A concrete subclass of this builder serializing to the PHP seri‐
2843 alization format could look like this:
2844 import phpserialize
2846 class PHPSerializedBuilder(SerializingHTMLBuilder):
2848 name = 'phpserialized'
2849 implementation = phpserialize
2850 out_suffix = '.file.phpdump'
2851 globalcontext_filename = 'globalcontext.phpdump'
2852 searchindex_filename = 'searchindex.phpdump'
2853 implementation
2855 A module that implements dump(), load(), dumps() and
2856 loads() functions that conform to the functions with the
2857 same names from the pickle module. Known modules imple‐
2858 menting this interface are simplejson (or json in Python
2859 2.6), phpserialize, plistlib, and others.
2860 out_suffix
2862 The suffix for all regular files.
2863 globalcontext_filename
2865 The filename for the file that contains the "global con‐
2866 text". This is a dict with some general configuration
2867 values such as the name of the project.
2868 searchindex_filename
2870 The filename for the search index Sphinx generates.
2871 See serialization-details for details about the output format.
2873 New in version 0.5.
2875 class sphinx.builders.html.PickleHTMLBuilder
2877 This builder produces a directory with pickle files containing
2879 mostly HTML fragments and TOC information, for use of a web
2880 application (or custom postprocessing tool) that doesn't use the
2881 standard HTML templates.
2882 See serialization-details for details about the output format.
2884 Its name is pickle. (The old name web still works as well.)
2886 The file suffix is .fpickle. The global context is called glob‐
2888 alcontext.pickle, the search index searchindex.pickle.
2889 class sphinx.builders.html.JSONHTMLBuilder
2891 This builder produces a directory with JSON files containing
2893 mostly HTML fragments and TOC information, for use of a web
2894 application (or custom postprocessing tool) that doesn't use the
2895 standard HTML templates.
2896 See serialization-details for details about the output format.
2898 Its name is json.
2900 The file suffix is .fjson. The global context is called global‐
2902 context.json, the search index searchindex.json.
2903 New in version 0.5.
2905 class sphinx.builders.changes.ChangesBuilder
2907 This builder produces an HTML overview of all versionadded, ver‐
2909 sionchanged and deprecated directives for the current version.
2910 This is useful to generate a ChangeLog file, for example.
2911 Its name is changes.
2913 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
2915 This builder scans all documents for external links, tries to
2917 open them with urllib2, and writes an overview which ones are
2918 broken and redirected to standard output and to output.txt in
2919 the output directory.
2920 Its name is linkcheck.
2922 Built-in Sphinx extensions that offer more builders are:
2924 · doctest
2926 · coverage
2928 Serialization builder details
2930 All serialization builders outputs one file per source file and a few
2931 special files. They also copy the reST source files in the directory
2932 _sources under the output directory.
2933 The PickleHTMLBuilder is a builtin subclass that implements the pickle
2935 serialization interface.
2936 The files per source file have the extensions of out_suffix, and are
2938 arranged in directories just as the source files are. They unserialize
2939 to a dictionary (or dictionary like structure) with these keys:
2940 body
2942 The HTML "body" (that is, the HTML rendering of the source
2944 file), as rendered by the HTML translator.
2945 title
2947 The title of the document, as HTML (may contain markup).
2949 toc
2951 The table of contents for the file, rendered as an HTML <ul>.
2953 display_toc
2955 A boolean that is True if the toc contains more than one entry.
2957 current_page_name
2959 The document name of the current file.
2961 parents, prev and next
2963 Information about related chapters in the TOC tree. Each rela‐
2965 tion is a dictionary with the keys link (HREF for the relation)
2966 and title (title of the related document, as HTML). parents is
2967 a list of relations, while prev and next are a single relation.
2968 sourcename
2970 The name of the source file under _sources.
2972 The special files are located in the root output directory. They are:
2974 SerializingHTMLBuilder.globalcontext_filename
2976 A pickled dict with these keys:
2978 project, copyright, release, version
2980 The same values as given in the configuration file.
2982 style
2984 html_style.
2986 last_updated
2988 Date of last build.
2990 builder
2992 Name of the used builder, in the case of pickles this is
2994 always 'pickle'.
2995 titles
2997 A dictionary of all documents' titles, as HTML strings.
2999 SerializingHTMLBuilder.searchindex_filename
3001 An index that can be used for searching the documentation. It
3003 is a pickled list with these entries:
3004 · A list of indexed docnames.
3006 · A list of document titles, as HTML strings, in the same order
3008 as the first list.
3009 · A dict mapping word roots (processed by an English-language
3011 stemmer) to a list of integers, which are indices into the
3012 first list.
3013 environment.pickle
3015 The build environment. This is always a pickle file, indepen‐
3017 dent of the builder and a copy of the environment that was used
3018 when the builder was started.
3019 Todo
3021 Document common members.
3022 Unlike the other pickle files this pickle file requires that the sphinx
3024 package is available on unpickling.
3025
3027 The configuration directory must contain a file named conf.py. This
3028 file (containing Python code) is called the "build configuration file"
3029 and contains all configuration needed to customize Sphinx input and
3030 output behavior.
3031 The configuration file is executed as Python code at build time (using
3033 execfile(), and with the current directory set to its containing direc‐
3034 tory), and therefore can execute arbitrarily complex code. Sphinx then
3035 reads simple names from the file's namespace as its configuration.
3036 Important points to note:
3038 · If not otherwise documented, values must be strings, and their
3040 default is the empty string.
3041 · The term "fully-qualified name" refers to a string that names an
3043 importable Python object inside a module; for example, the FQN
3044 "sphinx.builders.Builder" means the Builder class in the
3045 sphinx.builders module.
3046 · Remember that document names use / as the path separator and don't
3048 contain the file name extension.
3049 · Since conf.py is read as a Python file, the usual rules apply for
3051 encodings and Unicode support: declare the encoding using an encoding
3052 cookie (a comment like # -*- coding: utf-8 -*-) and use Unicode
3053 string literals when you include non-ASCII characters in configura‐
3054 tion values.
3055 · The contents of the config namespace are pickled (so that Sphinx can
3057 find out when configuration changes), so it may not contain unpick‐
3058 leable values -- delete them from the namespace with del if appropri‐
3059 ate. Modules are removed automatically, so you don't need to del
3060 your imports after use.
3061 · There is a special object named tags available in the config file.
3063 It can be used to query and change the tags (see tags). Use
3064 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
3065 change.
3066 General configuration
3068 extensions
3069 A list of strings that are module names of Sphinx extensions.
3070 These can be extensions coming with Sphinx (named sphinx.ext.*)
3071 or custom ones.
3072 Note that you can extend sys.path within the conf file if your
3074 extensions live in another directory -- but make sure you use
3075 absolute paths. If your extension path is relative to the con‐
3076 figuration directory, use os.path.abspath() like so:
3077 import sys, os
3079 sys.path.append(os.path.abspath('sphinxext'))
3081 extensions = ['extname']
3083 That way, you can load an extension called extname from the sub‐
3085 directory sphinxext.
3086 The configuration file itself can be an extension; for that, you
3088 only need to provide a setup() function in it.
3089 source_suffix
3091 The file name extension of source files. Only files with this
3092 suffix will be read as sources. Default is '.rst'.
3093 source_encoding
3095 The encoding of all reST source files. The recommended encod‐
3096 ing, and the default value, is 'utf-8-sig'.
3097 New in version 0.5: Previously, Sphinx accepted only UTF-8
3099 encoded sources.
3100 master_doc
3102 The document name of the "master" document, that is, the docu‐
3103 ment that contains the root toctree directive. Default is 'con‐
3104 tents'.
3105 exclude_patterns
3107 A list of glob-style patterns that should be excluded when look‐
3108 ing for source files. [1] They are matched against the source
3109 file names relative to the source directory, using slashes as
3110 directory separators on all platforms.
3111 Example patterns:
3113 · 'library/xml.rst' -- ignores the library/xml.rst file
3115 (replaces entry in unused_docs)
3116 · 'library/xml' -- ignores the library/xml directory (replaces
3118 entry in exclude_trees)
3119 · 'library/xml*' -- ignores all files and directories starting
3121 with library/xml
3122 · '**/.svn' -- ignores all .svn directories (replaces entry in
3124 exclude_dirnames)
3125 exclude_patterns is also consulted when looking for static files
3127 in html_static_path.
3128 New in version 1.0.
3130 unused_docs
3132 A list of document names that are present, but not currently
3133 included in the toctree. Use this setting to suppress the warn‐
3134 ing that is normally emitted in that case.
3135 Deprecated since version 1.0: Use exclude_patterns instead.
3137 exclude_trees
3139 A list of directory paths, relative to the source directory,
3140 that are to be recursively excluded from the search for source
3141 files, that is, their subdirectories won't be searched too. The
3142 default is [].
3143 New in version 0.4.
3145 Deprecated since version 1.0: Use exclude_patterns instead.
3147 exclude_dirnames
3149 A list of directory names that are to be excluded from any
3150 recursive operation Sphinx performs (e.g. searching for source
3151 files or copying static files). This is useful, for example, to
3152 exclude version-control-specific directories like 'CVS'. The
3153 default is [].
3154 New in version 0.5.
3156 Deprecated since version 1.0: Use exclude_patterns instead.
3158 locale_dirs
3160 New in version 0.5.
3161 Directories in which to search for additional Sphinx message
3163 catalogs (see language), relative to the source directory. The
3164 directories on this path are searched by the standard gettext
3165 module for a text domain of sphinx; so if you add the directory
3166 ./locale to this settting, the message catalogs (compiled from
3167 .po format using msgfmt) must be in ./locale/language/LC_MES‐
3168 SAGES/sphinx.mo.
3169 The default is [].
3171 templates_path
3173 A list of paths that contain extra templates (or templates that
3174 overwrite builtin/theme-specific templates). Relative paths are
3175 taken as relative to the configuration directory.
3176 template_bridge
3178 A string with the fully-qualified name of a callable (or simply
3179 a class) that returns an instance of TemplateBridge. This
3180 instance is then used to render HTML documents, and possibly the
3181 output of other builders (currently the changes builder). (Note
3182 that the template bridge must be made theme-aware if HTML themes
3183 are to be used.)
3184 rst_epilog
3186 A string of reStructuredText that will be included at the end of
3187 every source file that is read. This is the right place to add
3188 substitutions that should be available in every file. An exam‐
3189 ple:
3190 rst_epilog = """
3192 .. |psf| replace:: Python Software Foundation
3193 """
3194 New in version 0.6.
3196 rst_prolog
3198 A string of reStructuredText that will be included at the begin‐
3199 ning of every source file that is read.
3200 New in version 1.0.
3202 primary_domain
3204 The name of the default domain. Can also be None to disable a
3205 default domain. The default is 'py'. Those objects in other
3206 domains (whether the domain name is given explicitly, or
3207 selected by a default-domain directive) will have the domain
3208 name explicitly prepended when named (e.g., when the default
3209 domain is C, Python functions will be named "Python function",
3210 not just "function").
3211 New in version 1.0.
3213 default_role
3215 The name of a reST role (builtin or Sphinx extension) to use as
3216 the default role, that is, for text marked up `like this`. This
3217 can be set to 'py:obj' to make `filter` a cross-reference to the
3218 Python function "filter". The default is None, which doesn't
3219 reassign the default role.
3220 The default role can always be set within individual documents
3222 using the standard reST default-role directive.
3223 New in version 0.4.
3225 keep_warnings
3227 If true, keep warnings as "system message" paragraphs in the
3228 built documents. Regardless of this setting, warnings are
3229 always written to the standard error stream when sphinx-build is
3230 run.
3231 The default is False, the pre-0.5 behavior was to always keep
3233 them.
3234 New in version 0.5.
3236 needs_sphinx
3238 If set to a major.minor version string like '1.1', Sphinx will
3239 compare it with its version and refuse to build if it is too
3240 old. Default is no requirement.
3241 New in version 1.0.
3243 nitpicky
3245 If true, Sphinx will warn about all references where the target
3246 cannot be found. Default is False. You can activate this mode
3247 temporarily using the -n command-line switch.
3248 New in version 1.0.
3250 Project information
3252 project
3253 The documented project's name.
3254 copyright
3256 A copyright statement in the style '2008, Author Name'.
3257 version
3259 The major project version, used as the replacement for |ver‐
3260 sion|. For example, for the Python documentation, this may be
3261 something like 2.6.
3262 release
3264 The full project version, used as the replacement for |release|
3265 and e.g. in the HTML templates. For example, for the Python
3266 documentation, this may be something like 2.6.0rc1.
3267 If you don't need the separation provided between version and
3269 release, just set them both to the same value.
3270 language
3272 The code for the language the docs are written in. Any text
3273 automatically generated by Sphinx will be in that language.
3274 Also, in the LaTeX builder, a suitable language will be selected
3275 as an option for the Babel package. Default is None, which
3276 means that no translation will be done.
3277 New in version 0.5.
3279 Currently supported languages are:
3281 · bn -- Bengali
3283 · ca -- Catalan
3285 · cs -- Czech
3287 · da -- Danish
3289 · de -- German
3291 · en -- English
3293 · es -- Spanish
3295 · fi -- Finnish
3297 · fr -- French
3299 · hr -- Croatian
3301 · it -- Italian
3303 · ja -- Japanese
3305 · lt -- Lithuanian
3307 · nl -- Dutch
3309 · pl -- Polish
3311 · pt_BR -- Brazilian Portuguese
3313 · ru -- Russian
3315 · sl -- Slovenian
3317 · tr -- Turkish
3319 · uk_UA -- Ukrainian
3321 · zh_CN -- Simplified Chinese
3323 · zh_TW -- Traditional Chinese
3325 today
3327 today_fmt
3329 These values determine how to format the current date, used as
3330 the replacement for |today|.
3331 · If you set today to a non-empty value, it is used.
3333 · Otherwise, the current time is formatted using time.strftime()
3335 and the format given in today_fmt.
3336 The default is no today and a today_fmt of '%B %d, %Y' (or, if
3338 translation is enabled with language, am equivalent %format for
3339 the selected locale).
3340 highlight_language
3342 The default language to highlight source code in. The default
3343 is 'python'. The value should be a valid Pygments lexer name,
3344 see code-examples for more details.
3345 New in version 0.5.
3347 pygments_style
3349 The style name to use for Pygments highlighting of source code.
3350 The default style is selected by the theme for HTML output, and
3351 'sphinx' otherwise.
3352 Changed in version 0.3: If the value is a fully-qualified name
3354 of a custom Pygments style class, this is then used as custom
3355 style.
3356 add_function_parentheses
3358 A boolean that decides whether parentheses are appended to func‐
3359 tion and method role text (e.g. the content of :func:`input`) to
3360 signify that the name is callable. Default is True.
3361 add_module_names
3363 A boolean that decides whether module names are prepended to all
3364 object names (for object types where a "module" of some kind is
3365 defined), e.g. for py:function directives. Default is True.
3366 show_authors
3368 A boolean that decides whether codeauthor and sectionauthor
3369 directives produce any output in the built files.
3370 modindex_common_prefix
3372 A list of prefixes that are ignored for sorting the Python mod‐
3373 ule index (e.g., if this is set to ['foo.'], then foo.bar is
3374 shown under B, not F). This can be handy if you document a
3375 project that consists of a single package. Works only for the
3376 HTML builder currently. Default is [].
3377 New in version 0.6.
3379 trim_footnote_reference_space
3381 Trim spaces before footnote references that are necessary for
3382 the reST parser to recognize the footnote, but do not look too
3383 nice in the output.
3384 New in version 0.6.
3386 trim_doctest_flags
3388 If true, doctest flags (comments looking like # doctest: FLAG,
3389 ...) at the ends of lines are removed for all code blocks show‐
3390 ing interactive Python sessions (i.e. doctests). Default is
3391 true. See the extension doctest for more possibilities of
3392 including doctests.
3393 New in version 1.0.
3395 Options for HTML output
3397 These options influence HTML as well as HTML Help output, and other
3398 builders that use Sphinx' HTMLWriter class.
3399 html_theme
3401 The "theme" that the HTML output should use. See the section
3402 about theming. The default is 'default'.
3403 New in version 0.6.
3405 html_theme_options
3407 A dictionary of options that influence the look and feel of the
3408 selected theme. These are theme-specific. For the options
3409 understood by the builtin themes, see this section.
3410 New in version 0.6.
3412 html_theme_path
3414 A list of paths that contain custom themes, either as subdirec‐
3415 tories or as zip files. Relative paths are taken as relative to
3416 the configuration directory.
3417 New in version 0.6.
3419 html_style
3421 The style sheet to use for HTML pages. A file of that name must
3422 exist either in Sphinx' static/ path, or in one of the custom
3423 paths given in html_static_path. Default is the stylesheet
3424 given by the selected theme. If you only want to add or over‐
3425 ride a few things compared to the theme's stylesheet, use CSS
3426 @import to import the theme's stylesheet.
3427 html_title
3429 The "title" for HTML documentation generated with Sphinx' own
3430 templates. This is appended to the <title> tag of individual
3431 pages, and used in the navigation bar as the "topmost" element.
3432 It defaults to '<project> v<revision> documentation', where the
3433 placeholders are replaced by the config values of the same name.
3434 html_short_title
3436 A shorter "title" for the HTML docs. This is used in for links
3437 in the header and in the HTML Help docs. If not given, it
3438 defaults to the value of html_title.
3439 New in version 0.4.
3441 html_context
3443 A dictionary of values to pass into the template engine's con‐
3444 text for all pages. Single values can also be put in this dic‐
3445 tionary using the -A command-line option of sphinx-build.
3446 New in version 0.5.
3448 html_logo
3450 If given, this must be the name of an image file that is the
3451 logo of the docs. It is placed at the top of the sidebar; its
3452 width should therefore not exceed 200 pixels. Default: None.
3453 New in version 0.4.1: The image file will be copied to the
3455 _static directory of the output HTML, so an already existing
3456 file with that name will be overwritten.
3457 html_favicon
3459 If given, this must be the name of an image file (within the
3460 static path, see below) that is the favicon of the docs. Modern
3461 browsers use this as icon for tabs, windows and bookmarks. It
3462 should be a Windows-style icon file (.ico), which is 16x16 or
3463 32x32 pixels large. Default: None.
3464 New in version 0.4.
3466 html_static_path
3468 A list of paths that contain custom static files (such as style
3469 sheets or script files). Relative paths are taken as relative
3470 to the configuration directory. They are copied to the output
3471 directory after the theme's static files, so a file named
3472 default.css will overwrite the theme's default.css.
3473 Changed in version 0.4: The paths in html_static_path can now
3475 contain subdirectories.
3476 Changed in version 1.0: The entries in html_static_path can now
3478 be single files.
3479 html_last_updated_fmt
3481 If this is not the empty string, a 'Last updated on:' timestamp
3482 is inserted at every page bottom, using the given strftime()
3483 format. Default is '%b %d, %Y' (or a locale-dependent equiva‐
3484 lent).
3485 html_use_smartypants
3487 If true, SmartyPants will be used to convert quotes and dashes
3488 to typographically correct entities. Default: True.
3489 html_add_permalinks
3491 If true, Sphinx will add "permalinks" for each heading and
3492 description environment as paragraph signs that become visible
3493 when the mouse hovers over them. Default: True.
3494 New in version 0.6: Previously, this was always activated.
3496 html_sidebars
3498 Custom sidebar templates, must be a dictionary that maps docu‐
3499 ment names to template names.
3500 The keys can contain glob-style patterns [1], in which case all
3502 matching documents will get the specified sidebars. (A warning
3503 is emitted when a more than one glob-style pattern matches for
3504 any document.)
3505 The values can be either lists or single strings.
3507 · If a value is a list, it specifies the complete list of side‐
3509 bar templates to include. If all or some of the default side‐
3510 bars are to be included, they must be put into this list as
3511 well.
3512 The default sidebars (for documents that don't match any pat‐
3514 tern) are: ['localtoc.html', 'relations.html',
3515 'sourcelink.html', 'searchbox.html'].
3516 · If a value is a single string, it specifies a custom sidebar
3518 to be added between the 'sourcelink.html' and 'searchbox.html'
3519 entries. This is for compatibility with Sphinx versions
3520 before 1.0.
3521 Builtin sidebar templates that can be rendered are:
3523 · localtoc.html -- a fine-grained table of contents of the cur‐
3525 rent document
3526 · globaltoc.html -- a coarse-grained table of contents for the
3528 whole documentation set, collapsed
3529 · relations.html -- two links to the previous and next documents
3531 · sourcelink.html -- a link to the source of the current docu‐
3533 ment, if enabled in html_show_sourcelink
3534 · searchbox.html -- the "quick search" box
3536 Example:
3538 html_sidebars = {
3540 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
3541 'using/windows': ['windowssidebar.html', 'searchbox.html'],
3542 }
3543 This will render the custom template windowssidebar.html and the
3545 quick search box within the sidebar of the given document, and
3546 render the default sidebars for all other pages (except that the
3547 local TOC is replaced by the global TOC).
3548 New in version 1.0: The ability to use globbing keys and to
3550 specify multiple sidebars.
3551 Note that this value only has no effect if the chosen theme does
3553 not possess a sidebar, like the builtin scrolls and haiku
3554 themes.
3555 html_additional_pages
3557 Additional templates that should be rendered to HTML pages, must
3558 be a dictionary that maps document names to template names.
3559 Example:
3561 html_additional_pages = {
3563 'download': 'customdownload.html',
3564 }
3565 This will render the template customdownload.html as the page
3567 download.html.
3568 html_domain_indices
3570 If true, generate domain-specific indices in addition to the
3571 general index. For e.g. the Python domain, this is the global
3572 module index. Default is True.
3573 This value can be a bool or a list of index names that should be
3575 generated. To find out the index name for a specific index,
3576 look at the HTML file name. For example, the Python module
3577 index has the name 'py-modindex'.
3578 New in version 1.0.
3580 html_use_modindex
3582 If true, add a module index to the HTML documents. Default is
3583 True.
3584 Deprecated since version 1.0: Use html_domain_indices.
3586 html_use_index
3588 If true, add an index to the HTML documents. Default is True.
3589 New in version 0.4.
3591 html_split_index
3593 If true, the index is generated twice: once as a single page
3594 with all the entries, and once as one page per starting letter.
3595 Default is False.
3596 New in version 0.4.
3598 html_copy_source
3600 If true, the reST sources are included in the HTML build as
3601 _sources/name. The default is True.
3602 Warning
3604 If this config value is set to False, the JavaScript search
3605 function will only display the titles of matching documents, and
3606 no excerpt from the matching contents.
3607 html_show_sourcelink
3609 If true (and html_copy_source is true as well), links to the
3610 reST sources will be added to the sidebar. The default is True.
3611 New in version 0.6.
3613 html_use_opensearch
3615 If nonempty, an OpenSearch <http://opensearch.org> description
3616 file will be output, and all pages will contain a <link> tag
3617 referring to it. Since OpenSearch doesn't support relative URLs
3618 for its search page location, the value of this option must be
3619 the base URL from which these documents are served (without
3620 trailing slash), e.g. "http://docs.python.org". The default is
3621 ''.
3622 html_file_suffix
3624 This is the file name suffix for generated HTML files. The
3625 default is ".html".
3626 New in version 0.4.
3628 html_link_suffix
3630 Suffix for generated links to HTML files. The default is what‐
3631 ever html_file_suffix is set to; it can be set differently (e.g.
3632 to support different web server setups).
3633 New in version 0.6.
3635 html_translator_class
3637 A string with the fully-qualified name of a HTML Translator
3638 class, that is, a subclass of Sphinx' HTMLTranslator, that is
3639 used to translate document trees to HTML. Default is None (use
3640 the builtin translator).
3641 html_show_copyright
3643 If true, "(C) Copyright ..." is shown in the HTML footer.
3644 Default is True.
3645 New in version 1.0.
3647 html_show_sphinx
3649 If true, "Created using Sphinx" is shown in the HTML footer.
3650 Default is True.
3651 New in version 0.4.
3653 html_output_encoding
3655 Encoding of HTML output files. Default is 'utf-8'. Note that
3656 this encoding name must both be a valid Python encoding name and
3657 a valid HTML charset value.
3658 New in version 1.0.
3660 html_compact_lists
3662 If true, list items containing only a single paragraph will not
3663 be rendered with a <p> element. This is standard docutils
3664 behavior. Default: True.
3665 New in version 1.0.
3667 html_secnumber_suffix
3669 Suffix for section numbers. Default: ". ". Set to " " to sup‐
3670 press the final dot on section numbers.
3671 New in version 1.0.
3673 htmlhelp_basename
3675 Output file base name for HTML help builder. Default is
3676 'pydoc'.
3677 Options for epub output
3679 These options influence the epub output. As this builder derives from
3680 the HTML builder, the HTML options also apply where appropriate. The
3681 actual values for some of the options is not really important, they
3682 just have to be entered into the Dublin Core metadata.
3683 epub_basename
3685 The basename for the epub file. It defaults to the project
3686 name.
3687 epub_theme
3689 The HTML theme for the epub output. Since the default themes
3690 are not optimized for small screen space, using the same theme
3691 for HTML and epub output is usually not wise. This defaults to
3692 'epub', a theme designed to save visual space.
3693 epub_title
3695 The title of the document. It defaults to the html_title option
3696 but can be set independently for epub creation.
3697 epub_author
3699 The author of the document. This is put in the Dublin Core
3700 metadata. The default value is 'unknown'.
3701 epub_language
3703 The language of the document. This is put in the Dublin Core
3704 metadata. The default is the language option or 'en' if unset.
3705 epub_publisher
3707 The publisher of the document. This is put in the Dublin Core
3708 metadata. You may use any sensible string, e.g. the project
3709 homepage. The default value is 'unknown'.
3710 epub_copyright
3712 The copyright of the document. It defaults to the copyright
3713 option but can be set independently for epub creation.
3714 epub_identifier
3716 An identifier for the document. This is put in the Dublin Core
3717 metadata. For published documents this is the ISBN number, but
3718 you can also use an alternative scheme, e.g. the project home‐
3719 page. The default value is 'unknown'.
3720 epub_scheme
3722 The publication scheme for the epub_identifier. This is put in
3723 the Dublin Core metadata. For published books the scheme is
3724 'ISBN'. If you use the project homepage, 'URL' seems reason‐
3725 able. The default value is 'unknown'.
3726 epub_uid
3728 A unique identifier for the document. This is put in the Dublin
3729 Core metadata. You may use a random string. The default value
3730 is 'unknown'.
3731 epub_pre_files
3733 Additional files that should be inserted before the text gener‐
3734 ated by Sphinx. It is a list of tuples containing the file name
3735 and the title. If the title is empty, no entry is added to
3736 toc.ncx. Example:
3737 epub_pre_files = [
3739 ('index.html', 'Welcome'),
3740 ]
3741 The default value is [].
3743 epub_post_files
3745 Additional files that should be inserted after the text gener‐
3746 ated by Sphinx. It is a list of tuples containing the file name
3747 and the title. This option can be used to add an appendix. If
3748 the title is empty, no entry is added to toc.ncx. The default
3749 value is [].
3750 epub_exclude_files
3752 A list of files that are generated/copied in the build directory
3753 but should not be included in the epub file. The default value
3754 is [].
3755 epub_tocdepth
3757 The depth of the table of contents in the file toc.ncx. It
3758 should be an integer greater than zero. The default value is 3.
3759 Note: A deeply nested table of contents may be difficult to nav‐
3760 igate.
3761 epub_tocdup
3763 This flag determines if a toc entry is inserted again at the
3764 beginning of it's nested toc listing. This allows easier navi‐
3765 tation to the top of a chapter, but can be confusing because it
3766 mixes entries of differnet depth in one list. The default value
3767 is True.
3768 Options for LaTeX output
3770 These options influence LaTeX output.
3771 latex_documents
3773 This value determines how to group the document tree into LaTeX
3774 source files. It must be a list of tuples (startdocname, tar‐
3775 getname, title, author, documentclass, toctree_only), where the
3776 items are:
3777 · startdocname: document name that is the "root" of the LaTeX
3779 file. All documents referenced by it in TOC trees will be
3780 included in the LaTeX file too. (If you want only one LaTeX
3781 file, use your master_doc here.)
3782 · targetname: file name of the LaTeX file in the output direc‐
3784 tory.
3785 · title: LaTeX document title. Can be empty to use the title of
3787 the startdoc. This is inserted as LaTeX markup, so special
3788 characters like a backslash or ampersand must be represented
3789 by the proper LaTeX commands if they are to be inserted liter‐
3790 ally.
3791 · author: Author for the LaTeX document. The same LaTeX markup
3793 caveat as for title applies. Use \and to separate multiple
3794 authors, as in: 'John \and Sarah'.
3795 · documentclass: Normally, one of 'manual' or 'howto' (provided
3797 by Sphinx). Other document classes can be given, but they
3798 must include the "sphinx" package in order to define Sphinx'
3799 custom LaTeX commands. "howto" documents will not get appen‐
3800 dices. Also, howtos will have a simpler title page.
3801 · toctree_only: Must be True or False. If True, the startdoc
3803 document itself is not included in the output, only the docu‐
3804 ments referenced by it via TOC trees. With this option, you
3805 can put extra stuff in the master document that shows up in
3806 the HTML, but not the LaTeX output.
3807 New in version 0.3: The 6th item toctree_only. Tuples with 5
3809 items are still accepted.
3810 latex_logo
3812 If given, this must be the name of an image file (relative to
3813 the configuration directory) that is the logo of the docs. It
3814 is placed at the top of the title page. Default: None.
3815 latex_use_parts
3817 If true, the topmost sectioning unit is parts, else it is chap‐
3818 ters. Default: False.
3819 New in version 0.3.
3821 latex_appendices
3823 A list of document names to append as an appendix to all manu‐
3824 als.
3825 latex_domain_indices
3827 If true, generate domain-specific indices in addition to the
3828 general index. For e.g. the Python domain, this is the global
3829 module index. Default is True.
3830 This value can be a bool or a list of index names that should be
3832 generated, like for html_domain_indices.
3833 New in version 1.0.
3835 latex_use_modindex
3837 If true, add a module index to LaTeX documents. Default is
3838 True.
3839 Deprecated since version 1.0: Use latex_domain_indices.
3841 latex_show_pagerefs
3843 If true, add page references after internal references. This is
3844 very useful for printed copies of the manual. Default is False.
3845 New in version 1.0.
3847 latex_show_urls
3849 If true, add URL addresses after links. This is very useful for
3850 printed copies of the manual. Default is False.
3851 New in version 1.0.
3853 latex_elements
3855 New in version 0.5.
3856 A dictionary that contains LaTeX snippets that override those
3858 Sphinx usually puts into the generated .tex files.
3859 Keep in mind that backslashes must be doubled in Python string
3861 literals to avoid interpretation as escape sequences.
3862 · Keys that you may want to override include:
3864 'papersize'
3866 Paper size option of the document class ('a4paper' or
3868 'letterpaper'), default 'letterpaper'.
3869 'pointsize'
3871 Point size option of the document class ('10pt', '11pt'
3873 or '12pt'), default '10pt'.
3874 'babel'
3876 "babel" package inclusion, default '\\usepack‐
3878 age{babel}'.
3879 'fontpkg'
3881 Font package inclusion, default '\\usepackage{times}'
3883 (which uses Times and Helvetica). You can set this to
3884 '' to use the Computer Modern fonts.
3885 'fncychap'
3887 Inclusion of the "fncychap" package (which makes fancy
3889 chapter titles), default '\\usepackage[Bjarne]{fncy‐
3890 chap}' for English documentation, '\\usepack‐
3891 age[Sonny]{fncychap}' for internationalized docs
3892 (because the "Bjarne" style uses numbers spelled out in
3893 English). Other "fncychap" styles you can try include
3894 "Lenny", "Glenn", "Conny" and "Rejne". You can also
3895 set this to '' to disable fncychap.
3896 'preamble'
3898 Additional preamble content, default empty.
3900 'footer'`
3902 Additional footer content (before the indices), default
3904 empty.
3905 · Keys that don't need be overridden unless in special cases
3907 are:
3908 'inputenc'
3910 "inputenc" package inclusion, default '\\usepack‐
3912 age[utf8]{inputenc}'.
3913 'fontenc'
3915 "fontenc" package inclusion, default '\\usepack‐
3917 age[T1]{fontenc}'.
3918 'maketitle'
3920 "maketitle" call, default '\\maketitle'. Override if
3922 you want to generate a differently-styled title page.
3923 'tableofcontents'
3925 "tableofcontents" call, default '\\tableofcontents'.
3927 Override if you want to generate a different table of
3928 contents or put content between the title page and the
3929 TOC.
3930 'printindex'
3932 "printindex" call, the last thing in the file, default
3934 '\\printindex'. Override if you want to generate the
3935 index differently or append some content after the
3936 index.
3937 · Keys that are set by other options and therefore should not be
3939 overridden are:
3940 'docclass' 'classoptions' 'title' 'date' 'release' 'author'
3942 'logo' 'releasename' 'makeindex' 'shorthandoff'
3943 latex_docclass
3945 A dictionary mapping 'howto' and 'manual' to names of real docu‐
3946 ment classes that will be used as the base for the two Sphinx
3947 classes. Default is to use 'article' for 'howto' and 'report'
3948 for 'manual'.
3949 New in version 1.0.
3951 latex_additional_files
3953 A list of file names, relative to the configuration directory,
3954 to copy to the build directory when building LaTeX output. This
3955 is useful to copy files that Sphinx doesn't copy automatically,
3956 e.g. if they are referenced in custom LaTeX added in latex_ele‐
3957 ments. Image files that are referenced in source files (e.g.
3958 via .. image::) are copied automatically.
3959 You have to make sure yourself that the filenames don't collide
3961 with those of any automatically copied files.
3962 New in version 0.6.
3964 latex_preamble
3966 Additional LaTeX markup for the preamble.
3967 Deprecated since version 0.5: Use the 'preamble' key in the
3969 latex_elements value.
3970 latex_paper_size
3972 The output paper size ('letter' or 'a4'). Default is 'letter'.
3973 Deprecated since version 0.5: Use the 'papersize' key in the
3975 latex_elements value.
3976 latex_font_size
3978 The font size ('10pt', '11pt' or '12pt'). Default is '10pt'.
3979 Deprecated since version 0.5: Use the 'pointsize' key in the
3981 latex_elements value.
3982 Options for manual page output
3984 These options influence manual page output.
3985 man_pages
3987 This value determines how to group the document tree into manual
3988 pages. It must be a list of tuples (startdocname, name,
3989 description, authors, section), where the items are:
3990 · startdocname: document name that is the "root" of the manual
3992 page. All documents referenced by it in TOC trees will be
3993 included in the manual file too. (If you want one master man‐
3994 ual page, use your master_doc here.)
3995 · name: name of the manual page. This should be a short string
3997 without spaces or special characters. It is used to determine
3998 the file name as well as the name of the manual page (in the
3999 NAME section).
4000 · description: description of the manual page. This is used in
4002 the NAME section.
4003 · authors: A list of strings with authors, or a single string.
4005 Can be an empty string or list if you do not want to automati‐
4006 cally generate an AUTHORS section in the manual page.
4007 · section: The manual page section. Used for the output file
4009 name as well as in the manual page header.
4010 New in version 1.0.
4012
4014 [1] A note on available globbing syntax: you can use the standard
4015 shell constructs *, ?, [...] and [!...] with the feature that
4016 these all don't match slashes. A double star ** can be used to
4017 match any sequence of characters including slashes.
4018
4020 New in version 0.6.
4021 Sphinx supports changing the appearance of its HTML output via themes.
4023 A theme is a collection of HTML templates, stylesheet(s) and other
4024 static files. Additionally, it has a configuration file which speci‐
4025 fies from which theme to inherit, which highlighting style to use, and
4026 what options exist for customizing the theme's look and feel.
4027 Themes are meant to be project-unaware, so they can be used for differ‐
4029 ent projects without change.
4030 Using a theme
4032 Using an existing theme is easy. If the theme is builtin to Sphinx,
4033 you only need to set the html_theme config value. With the
4034 html_theme_options config value you can set theme-specific options that
4035 change the look and feel. For example, you could have the following in
4036 your conf.py:
4037 html_theme = "default"
4039 html_theme_options = {
4040 "rightsidebar": "true",
4041 "relbarbgcolor": "black"
4042 }
4043 That would give you the default theme, but with a sidebar on the right
4045 side and a black background for the relation bar (the bar with the nav‐
4046 igation links at the page's top and bottom).
4047 If the theme does not come with Sphinx, it can be in two forms: either
4049 a directory (containing theme.conf and other needed files), or a zip
4050 file with the same contents. Either of them must be put where Sphinx
4051 can find it; for this there is the config value html_theme_path. It
4052 gives a list of directories, relative to the directory containing
4053 conf.py, that can contain theme directories or zip files. For example,
4054 if you have a theme in the file blue.zip, you can put it right in the
4055 directory containing conf.py and use this configuration:
4056 html_theme = "blue"
4058 html_theme_path = ["."]
4059 Builtin themes
4061 ┌───────────────────────────┬────────────────────────────┐
4062 │Theme overview │ │
4063 ├───────────────────────────┼────────────────────────────┤
4064 │[image: default] [image] │ [image: sphinxdoc] [image] │
4065 │ │ │
4066 │ │ │
4067 │default │ sphinxdoc │
4068 ├───────────────────────────┼────────────────────────────┤
4069 │[image: scrolls] [image] │ [image: agogo] [image] │
4070 │ │ │
4071 │ │ │
4072 │scrolls │ agogo │
4073 ├───────────────────────────┼────────────────────────────┤
4074 │[image: traditional] │ [image: nature] [image] │
4075 │[image] │ │
4076 │ │ │
4077 │ │ nature │
4078 │traditional │ │
4079 ├───────────────────────────┼────────────────────────────┤
4080 │[image: haiku] [image] │ │
4081 │ │ │
4082 │ │ │
4083 │haiku │ │
4084 └───────────────────────────┴────────────────────────────┘
4085 Sphinx comes with a selection of themes to choose from.
4087 These themes are:
4089 · basic -- This is a basically unstyled layout used as the base for the
4091 other themes, and usable as the base for custom themes as well. The
4092 HTML contains all important elements like sidebar and relation bar.
4093 There is one option (which is inherited by the other themes):
4094 · nosidebar (true or false): Don't include the sidebar. Defaults to
4096 false.
4097 · default -- This is the default theme, which looks like the Python
4099 documentation. It can be customized via these options:
4100 · rightsidebar (true or false): Put the sidebar on the right side.
4102 Defaults to false.
4103 · stickysidebar (true or false): Make the sidebar "fixed" so that it
4105 doesn't scroll out of view for long body content. This may not
4106 work well with all browsers. Defaults to false.
4107 · collapsiblesidebar (true or false): Add an experimental JavaScript
4109 snippet that makes the sidebar collapsible via a button on its
4110 side. Doesn't work together with "rightsidebar" or "stickyside‐
4111 bar". Defaults to false.
4112 · externalrefs (true or false): Display external links differently
4114 from internal links. Defaults to false.
4115 There are also various color and font options that can change the
4117 color scheme without having to write a custom stylesheet:
4118 · footerbgcolor (CSS color): Background color for the footer line.
4120 · footertextcolor (CSS color): Text color for the footer line.
4122 · sidebarbgcolor (CSS color): Background color for the sidebar.
4124 · sidebarbtncolor (CSS color): Background color for the sidebar col‐
4126 lapse button (used when collapsiblesidebar is true).
4127 · sidebartextcolor (CSS color): Text color for the sidebar.
4129 · sidebarlinkcolor (CSS color): Link color for the sidebar.
4131 · relbarbgcolor (CSS color): Background color for the relation bar.
4133 · relbartextcolor (CSS color): Text color for the relation bar.
4135 · relbarlinkcolor (CSS color): Link color for the relation bar.
4137 · bgcolor (CSS color): Body background color.
4139 · textcolor (CSS color): Body text color.
4141 · linkcolor (CSS color): Body link color.
4143 · visitedlinkcolor (CSS color): Body color for visited links.
4145 · headbgcolor (CSS color): Background color for headings.
4147 · headtextcolor (CSS color): Text color for headings.
4149 · headlinkcolor (CSS color): Link color for headings.
4151 · codebgcolor (CSS color): Background color for code blocks.
4153 · codetextcolor (CSS color): Default text color for code blocks, if
4155 not set differently by the highlighting style.
4156 · bodyfont (CSS font-family): Font for normal text.
4158 · headfont (CSS font-family): Font for headings.
4160 · sphinxdoc -- The theme used for this documentation. It features a
4162 sidebar on the right side. There are currently no options beyond
4163 nosidebar.
4164 · scrolls -- A more lightweight theme, based on the Jinja documenta‐
4166 tion. The following color options are available:
4167 · headerbordercolor
4169 · subheadlinecolor
4171 · linkcolor
4173 · visitedlinkcolor
4175 · admonitioncolor
4177 · agogo -- A theme created by Andi Albrecht. The following options are
4179 supported:
4180 · bodyfont (CSS font family): Font for normal text.
4182 · headerfont (CSS font family): Font for headings.
4184 · pagewidth (CSS length): Width of the page content, default 70em.
4186 · documentwidth (CSS length): Width of the document (without side‐
4188 bar), default 50em.
4189 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
4191 · bgcolor (CSS color): Background color.
4193 · headerbg (CSS value for "background"): background for the header
4195 area, default a grayish gradient.
4196 · footerbg (CSS value for "background"): background for the footer
4198 area, default a light gray gradient.
4199 · linkcolor (CSS color): Body link color.
4201 · headercolor1, headercolor2 (CSS color): colors for <h1> and <h2>
4203 headings.
4204 · headerlinkcolor (CSS color): Color for the backreference link in
4206 headings.
4207 · textalign (CSS text-align value): Text alignment for the body,
4209 default is justify.
4210 · nature -- A greenish theme. There are currently no options beyond
4212 nosidebar.
4213 · haiku -- A theme without sidebar inspired by the Haiku OS user guide.
4215 The following options are supported:
4216 · full_logo (true or false, default false): If this is true, the
4218 header will only show the html_logo. Use this for large logos. If
4219 this is false, the logo (if present) will be shown floating right,
4220 and the documentation title will be put in the header.
4221 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlink‐
4223 color (CSS colors): Colors for various body elements.
4224 · traditional -- A theme resembling the old Python documentation.
4226 There are currently no options beyond nosidebar.
4227 · epub -- A theme for the epub builder. There are currently no
4229 options. This theme tries to save visual space which is a sparse
4230 resource on ebook readers.
4231 Creating themes
4233 As said, themes are either a directory or a zipfile (whose name is the
4234 theme name), containing the following:
4235 · A theme.conf file, see below.
4237 · HTML templates, if needed.
4239 · A static/ directory containing any static files that will be copied
4241 to the output statid directory on build. These can be images,
4242 styles, script files.
4243 The theme.conf file is in INI format [1] (readable by the standard
4245 Python ConfigParser module) and has the following structure:
4246 [theme]
4248 inherit = base theme
4249 stylesheet = main CSS name
4250 pygments_style = stylename
4251 [options]
4253 variable = default value
4254 · The inherit setting gives the name of a "base theme", or none. The
4256 base theme will be used to locate missing templates (most themes will
4257 not have to supply most templates if they use basic as the base
4258 theme), its options will be inherited, and all of its static files
4259 will be used as well.
4260 · The stylesheet setting gives the name of a CSS file which will be
4262 referenced in the HTML header. If you need more than one CSS file,
4263 either include one from the other via CSS' @import, or use a custom
4264 HTML template that adds <link rel="stylesheet"> tags as necessary.
4265 Setting the html_style config value will override this setting.
4266 · The pygments_style setting gives the name of a Pygments style to use
4268 for highlighting. This can be overridden by the user in the pyg‐
4269 ments_style config value.
4270 · The options section contains pairs of variable names and default val‐
4272 ues. These options can be overridden by the user in
4273 html_theme_options and are accessible from all templates as
4274 theme_<name>.
4275 Templating
4277 The guide to templating is helpful if you want to write your own tem‐
4278 plates. What is important to keep in mind is the order in which Sphinx
4279 searches for templates:
4280 · First, in the user's templates_path directories.
4282 · Then, in the selected theme.
4284 · Then, in its base theme, its base's base theme, etc.
4286 When extending a template in the base theme with the same name, use the
4288 theme name as an explicit directory: {% extends "basic/layout.html" %}.
4289 From a user templates_path template, you can still use the "exclamation
4290 mark" syntax as described in the templating document.
4291 Static templates
4293 Since theme options are meant for the user to configure a theme more
4294 easily, without having to write a custom stylesheet, it is necessary to
4295 be able to template static files as well as HTML files. Therefore,
4296 Sphinx supports so-called "static templates", like this:
4297 If the name of a file in the static/ directory of a theme (or in the
4299 user's static path, for that matter) ends with _t, it will be processed
4300 by the template engine. The _t will be left from the final file name.
4301 For example, the default theme has a file static/default.css_t which
4302 uses templating to put the color options into the stylesheet. When a
4303 documentation is built with the default theme, the output directory
4304 will contain a _static/default.css file where all template tags have
4305 been processed.
4306 [1] It is not an executable Python file, as opposed to conf.py,
4308 because that would pose an unnecessary security risk if themes are
4309 shared.
4310
4312 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
4313 is a text-based engine, and inspired by Django templates, so anyone
4314 having used Django will already be familiar with it. It also has
4315 excellent documentation for those who need to make themselves familiar
4316 with it.
4317 Do I need to use Sphinx' templates to produce HTML?
4319 No. You have several other options:
4320 · You can write a TemplateBridge subclass that calls your template
4322 engine of choice, and set the template_bridge configuration value
4323 accordingly.
4324 · You can write a custom builder that derives from StandaloneHTML‐
4326 Builder and calls your template engine of choice.
4327 · You can use the PickleHTMLBuilder that produces pickle files with the
4329 page contents, and postprocess them using a custom tool, or use them
4330 in your Web application.
4331 Jinja/Sphinx Templating Primer
4333 The default templating language in Sphinx is Jinja. It's Django/Smarty
4334 inspired and easy to understand. The most important concept in Jinja
4335 is template inheritance, which means that you can overwrite only spe‐
4336 cific blocks within a template, customizing it while also keeping the
4337 changes at a minimum.
4338 To customize the output of your documentation you can override all the
4340 templates (both the layout templates and the child templates) by adding
4341 files with the same name as the original filename into the template
4342 directory of the structure the Sphinx quickstart generated for you.
4343 Sphinx will look for templates in the folders of templates_path first,
4345 and if it can't find the template it's looking for there, it falls back
4346 to the selected theme's templates.
4347 A template contains variables, which are replaced with values when the
4349 template is evaluated, tags, which control the logic of the template
4350 and blocks which are used for template inheritance.
4351 Sphinx' basic theme provides base templates with a couple of blocks it
4353 will fill with data. These are located in the themes/basic subdirec‐
4354 tory of the Sphinx installation directory, and used by all builtin
4355 Sphinx themes. Templates with the same name in the templates_path
4356 override templates supplied by the selected theme.
4357 For example, to add a new link to the template area containing related
4359 links all you have to do is to add a new template called layout.html
4360 with the following contents:
4361 {% extends "!layout.html" %}
4363 {% block rootrellink %}
4364 <li><a href="http://project.invalid/">Project Homepage</a> »</li>
4365 {{ super() }}
4366 {% endblock %}
4367 By prefixing the name of the overridden template with an exclamation
4369 mark, Sphinx will load the layout template from the underlying HTML
4370 theme.
4371 Important: If you override a block, call {{ super() }} somewhere to
4373 render the block's content in the extended template -- unless you don't
4374 want that content to show up.
4375 Working with the builtin templates
4377 The builtin basic theme supplies the templates that all builtin Sphinx
4378 themes are based on. It has the following elements you can override or
4379 use:
4380 Blocks
4382 The following blocks exist in the layout.html template:
4383 doctype
4385 The doctype of the output format. By default this is XHTML 1.0
4387 Transitional as this is the closest to what Sphinx and Docutils
4388 generate and it's a good idea not to change it unless you want
4389 to switch to HTML 5 or a different but compatible XHTML doctype.
4390 linktags
4392 This block adds a couple of <link> tags to the head section of
4394 the template.
4395 extrahead
4397 This block is empty by default and can be used to add extra con‐
4399 tents into the <head> tag of the generated HTML file. This is
4400 the right place to add references to JavaScript or extra CSS
4401 files.
4402 relbar1 / relbar2
4404 This block contains the relation bar, the list of related links
4406 (the parent documents on the left, and the links to index, mod‐
4407 ules etc. on the right). relbar1 appears before the document,
4408 relbar2 after the document. By default, both blocks are filled;
4409 to show the relbar only before the document, you would override
4410 relbar2 like this:
4411 {% block relbar2 %}{% endblock %}
4413 rootrellink / relbaritems
4415 Inside the relbar there are three sections: The rootrellink, the
4417 links from the documentation and the custom relbaritems. The
4418 rootrellink is a block that by default contains a list item
4419 pointing to the master document by default, the relbaritems is
4420 an empty block. If you override them to add extra links into
4421 the bar make sure that they are list items and end with the
4422 reldelim1.
4423 document
4425 The contents of the document itself. It contains the block
4427 "body" where the individual content is put by subtemplates like
4428 page.html.
4429 sidebar1 / sidebar2
4431 A possible location for a sidebar. sidebar1 appears before the
4433 document and is empty by default, sidebar2 after the document
4434 and contains the default sidebar. If you want to swap the side‐
4435 bar location override this and call the sidebar helper:
4436 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
4438 {% block sidebar2 %}{% endblock %}
4439 (The sidebar2 location for the sidebar is needed by the sphinx‐
4441 doc.css stylesheet, for example.)
4442 sidebarlogo
4444 The logo location within the sidebar. Override this if you want
4446 to place some content at the top of the sidebar.
4447 footer
4449 The block for the footer div. If you want a custom footer or
4451 markup before or after it, override this one.
4452 The following four blocks are only used for pages that do not have
4454 assigned a list of custom sidebars in the html_sidebars config value.
4455 Their use is deprecated in favor of separate sidebar templates, which
4456 can be included via html_sidebars.
4457 sidebartoc
4459 The table of contents within the sidebar.
4461 Deprecated since version 1.0.
4463 sidebarrel
4465 The relation links (previous, next document) within the sidebar.
4467 Deprecated since version 1.0.
4469 sidebarsourcelink
4471 The "Show source" link within the sidebar (normally only shown
4473 if this is enabled by html_show_sourcelink).
4474 Deprecated since version 1.0.
4476 sidebarsearch
4478 The search box within the sidebar. Override this if you want to
4480 place some content at the bottom of the sidebar.
4481 Deprecated since version 1.0.
4483 Configuration Variables
4485 Inside templates you can set a couple of variables used by the layout
4486 template using the {% set %} tag:
4487 reldelim1
4489 The delimiter for the items on the left side of the related bar.
4490 This defaults to ' »' Each item in the related bar ends
4491 with the value of this variable.
4492 reldelim2
4494 The delimiter for the items on the right side of the related
4495 bar. This defaults to ' |'. Each item except of the last one
4496 in the related bar ends with the value of this variable.
4497 Overriding works like this:
4499 {% extends "!layout.html" %}
4501 {% set reldelim1 = ' >' %}
4502 script_files
4504 Add additional script files here, like this:
4505 {% set script_files = script_files + [pathto("_static/myscript.js", 1)] %}
4507 Helper Functions
4509 Sphinx provides various Jinja functions as helpers in the template.
4510 You can use them to generate links or output multiply used elements.
4511 pathto(document)
4513 Return the path to a Sphinx document as a URL. Use this to
4515 refer to built documents.
4516 pathto(file, 1)
4518 Return the path to a file which is a filename relative to the
4520 root of the generated output. Use this to refer to static
4521 files.
4522 hasdoc(document)
4524 Check if a document with the name document exists.
4526 sidebar()
4528 Return the rendered sidebar.
4530 relbar()
4532 Return the rendered relation bar.
4534 Global Variables
4536 These global variables are available in every template and are safe to
4537 use. There are more, but most of them are an implementation detail and
4538 might change in the future.
4539 builder
4541 The name of the builder (e.g. html or htmlhelp).
4542 copyright
4544 The value of copyright.
4545 docstitle
4547 The title of the documentation (the value of html_title).
4548 embedded
4550 True if the built HTML is meant to be embedded in some viewing
4551 application that handles navigation, not the web browser, such
4552 as for HTML help or Qt help formats. In this case, the sidebar
4553 is not included.
4554 favicon
4556 The path to the HTML favicon in the static path, or ''.
4557 file_suffix
4559 The value of the builder's out_suffix attribute, i.e. the file
4560 name extension that the output files will get. For a standard
4561 HTML builder, this is usually .html.
4562 has_source
4564 True if the reST document sources are copied (if
4565 html_copy_source is true).
4566 last_updated
4568 The build date.
4569 logo The path to the HTML logo image in the static path, or ''.
4571 master_doc
4573 The value of master_doc, for usage with pathto().
4574 next The next document for the navigation. This variable is either
4576 false or has two attributes link and title. The title contains
4577 HTML markup. For example, to generate a link to the next page,
4578 you can use this snippet:
4579 {% if next %}
4581 <a href="{{ next.link|e }}">{{ next.title }}</a>
4582 {% endif %}
4583 pagename
4585 The "page name" of the current file, i.e. either the document
4586 name if the file is generated from a reST source, or the equiva‐
4587 lent hierarchical name relative to the output directory ([direc‐
4588 tory/]filename_without_extension).
4589 parents
4591 A list of parent documents for navigation, structured like the
4592 next item.
4593 prev Like next, but for the previous page.
4595 project
4597 The value of project.
4598 release
4600 The value of release.
4601 rellinks
4603 A list of links to put at the left side of the relbar, next to
4604 "next" and "prev". This usually contains links to the general
4605 index and other indices, such as the Python module index. If
4606 you add something yourself, it must be a tuple (pagename, link
4607 title, accesskey, link text).
4608 shorttitle
4610 The value of html_short_title.
4611 show_source
4613 True if html_show_sourcelink is true.
4614 sphinx_version
4616 The version of Sphinx used to build.
4617 style The name of the main stylesheet, as given by the theme or
4619 html_style.
4620 title The title of the current document, as used in the <title> tag.
4622 use_opensearch
4624 The value of html_use_opensearch.
4625 version
4627 The value of version.
4628 In addition to these values, there are also all theme options available
4630 (prefixed by theme_), as well as the values given by the user in
4631 html_context.
4632 In documents that are created from source files (as opposed to automat‐
4634 ically-generated files like the module index, or documents that already
4635 are in HTML form), these variables are also available:
4636 meta Document metadata (a dictionary), see metadata.
4638 sourcename
4640 The name of the copied source file for the current document.
4641 This is only nonempty if the html_copy_source value is true.
4642 toc The local table of contents for the current page, rendered as
4644 HTML bullet lists.
4645 toctree
4647 A callable yielding the global TOC tree containing the current
4648 page, rendered as HTML bullet lists. Optional keyword argu‐
4649 ments:
4650 · collapse (true by default): if true, all TOC entries that are
4652 not ancestors of the current page are collapsed
4653 · maxdepth (defaults to the max depth selected in the toctree
4655 directive): the maximum depth of the tree; set it to -1 to
4656 allow unlimited depth
4657 · titles_only (false by default): if true, put only toplevel
4659 document titles in the tree
4660
4662 Since many projects will need special features in their documentation,
4663 Sphinx is designed to be extensible on several levels.
4664 This is what you can do in an extension: First, you can add new
4666 builders to support new output formats or actions on the parsed docu‐
4667 ments. Then, it is possible to register custom reStructuredText roles
4668 and directives, extending the markup. And finally, there are so-called
4669 "hook points" at strategic places throughout the build process, where
4670 an extension can register a hook and run specialized code.
4671 An extension is simply a Python module. When an extension is loaded,
4673 Sphinx imports this module and executes its setup() function, which in
4674 turn notifies Sphinx of everything the extension offers -- see the
4675 extension tutorial for examples.
4676 The configuration file itself can be treated as an extension if it con‐
4678 tains a setup() function. All other extensions to load must be listed
4679 in the extensions configuration value.
4680 Tutorial: Writing a simple extension
4682 This section is intended as a walkthrough for the creation of custom
4683 extensions. It covers the basics of writing and activating an exten‐
4684 sions, as well as commonly used features of extensions.
4685 As an example, we will cover a "todo" extension that adds capabilities
4687 to include todo entries in the documentation, and collecting these in a
4688 central place. (A similar "todo" extension is distributed with
4689 Sphinx.)
4690 Build Phases
4692 One thing that is vital in order to understand extension mechanisms is
4693 the way in which a Sphinx project is built: this works in several
4694 phases.
4695 Phase 0: Initialization
4697 In this phase, almost nothing interesting for us happens. The
4699 source directory is searched for source files, and extensions are
4700 initialized. Should a stored build environment exist, it is loaded,
4701 otherwise a new one is created.
4702 Phase 1: Reading
4704 In Phase 1, all source files (and on subsequent builds, those that
4706 are new or changed) are read and parsed. This is the phase where
4707 directives and roles are encountered by the docutils, and the corre‐
4708 sponding functions are called. The output of this phase is a doc‐
4709 tree for each source files, that is a tree of docutils nodes. For
4710 document elements that aren't fully known until all existing files
4711 are read, temporary nodes are created.
4712 During reading, the build environment is updated with all meta- and
4714 cross reference data of the read documents, such as labels, the
4715 names of headings, described Python objects and index entries. This
4716 will later be used to replace the temporary nodes.
4717 The parsed doctrees are stored on the disk, because it is not possi‐
4719 ble to hold all of them in memory.
4720 Phase 2: Consistency checks
4722 Some checking is done to ensure no surprises in the built documents.
4724 Phase 3: Resolving
4726 Now that the metadata and cross-reference data of all existing docu‐
4728 ments is known, all temporary nodes are replaced by nodes that can
4729 be converted into output. For example, links are created for object
4730 references that exist, and simple literal nodes are created for
4731 those that don't.
4732 Phase 4: Writing
4734 This phase converts the resolved doctrees to the desired output for‐
4736 mat, such as HTML or LaTeX. This happens via a so-called docutils
4737 writer that visits the individual nodes of each doctree and produces
4738 some output in the process.
4739 Note Some builders deviate from this general build plan, for example,
4741 the builder that checks external links does not need anything
4742 more than the parsed doctrees and therefore does not have phases
4743 2--4.
4744 Extension Design
4746 We want the extension to add the following to Sphinx:
4747 · A "todo" directive, containing some content that is marked with
4749 "TODO", and only shown in the output if a new config value is set.
4750 (Todo entries should not be in the output by default.)
4751 · A "todolist" directive that creates a list of all todo entries
4753 throughout the documentation.
4754 For that, we will need to add the following elements to Sphinx:
4756 · New directives, called todo and todolist.
4758 · New document tree nodes to represent these directives, conventionally
4760 also called todo and todolist. We wouldn't need new nodes if the new
4761 directives only produced some content representable by existing
4762 nodes.
4763 · A new config value todo_include_todos (config value names should
4765 start with the extension name, in order to stay unique) that controls
4766 whether todo entries make it into the output.
4767 · New event handlers: one for the doctree-resolved event, to replace
4769 the todo and todolist nodes, and one for env-purge-doc (the reason
4770 for that will be covered later).
4771 The Setup Function
4773 The new elements are added in the extension's setup function. Let us
4774 create a new Python module called todo.py and add the setup function:
4775 def setup(app):
4777 app.add_config_value('todo_include_todos', False, False)
4778 app.add_node(todolist)
4780 app.add_node(todo,
4781 html=(visit_todo_node, depart_todo_node),
4782 latex=(visit_todo_node, depart_todo_node),
4783 text=(visit_todo_node, depart_todo_node))
4784 app.add_directive('todo', TodoDirective)
4786 app.add_directive('todolist', TodolistDirective)
4787 app.connect('doctree-resolved', process_todo_nodes)
4788 app.connect('env-purge-doc', purge_todos)
4789 The calls in this function refer to classes and functions not yet writ‐
4791 ten. What the individual calls do is the following:
4792 · add_config_value() lets Sphinx know that it should recognize the new
4794 config value todo_include_todos, whose default value should be False
4795 (this also tells Sphinx that it is a boolean value).
4796 If the third argument was True, all documents would be re-read if the
4798 config value changed its value. This is needed for config values
4799 that influence reading (build phase 1).
4800 · add_node() adds a new node class to the build system. It also can
4802 specify visitor functions for each supported output format. These
4803 visitor functions are needed when the new nodes stay until phase 4 --
4804 since the todolist node is always replaced in phase 3, it doesn't
4805 need any.
4806 We need to create the two node classes todo and todolist later.
4808 · add_directive() adds a new directive, given by name and class.
4810 The handler functions are created later.
4812 · Finally, connect() adds an event handler to the event whose name is
4814 given by the first argument. The event handler function is called
4815 with several arguments which are documented with the event.
4816 The Node Classes
4818 Let's start with the node classes:
4819 from docutils import nodes
4821 class todo(nodes.Admonition, nodes.Element):
4823 pass
4824 class todolist(nodes.General, nodes.Element):
4826 pass
4827 def visit_todo_node(self, node):
4829 self.visit_admonition(node)
4830 def depart_todo_node(self, node):
4832 self.depart_admonition(node)
4833 Node classes usually don't have to do anything except inherit from the
4835 standard docutils classes defined in docutils.nodes. todo inherits
4836 from Admonition because it should be handled like a note or warning,
4837 todolist is just a "general" node.
4838 The Directive Classes
4840 A directive class is a class deriving usually from docu‐
4841 tils.parsers.rst.Directive. Since the class-based directive interface
4842 doesn't exist yet in Docutils 0.4, Sphinx has another base class called
4843 sphinx.util.compat.Directive that you can derive your directive from,
4844 and it will work with both Docutils 0.4 and 0.5 upwards. The directive
4845 interface is covered in detail in the docutils documentation; the
4846 important thing is that the class has a method run that returns a list
4847 of nodes.
4848 The todolist directive is quite simple:
4850 from sphinx.util.compat import Directive
4852 class TodolistDirective(Directive):
4854 def run(self):
4856 return [todolist('')]
4857 An instance of our todolist node class is created and returned. The
4859 todolist directive has neither content nor arguments that need to be
4860 handled.
4861 The todo directive function looks like this:
4863 from sphinx.util.compat import make_admonition
4865 class TodoDirective(Directive):
4867 # this enables content in the directive
4869 has_content = True
4870 def run(self):
4872 env = self.state.document.settings.env
4873 targetid = "todo-%d" % env.new_serialno('todo')
4875 targetnode = nodes.target('', '', ids=[targetid])
4876 ad = make_admonition(todo, self.name, [_('Todo')], self.options,
4878 self.content, self.lineno, self.content_offset,
4879 self.block_text, self.state, self.state_machine)
4880 if not hasattr(env, 'todo_all_todos'):
4882 env.todo_all_todos = []
4883 env.todo_all_todos.append({
4884 'docname': env.docname,
4885 'lineno': self.lineno,
4886 'todo': ad[0].deepcopy(),
4887 'target': targetnode,
4888 })
4889 return [targetnode] + ad
4891 Several important things are covered here. First, as you can see, you
4893 can refer to the build environment instance using self.state.docu‐
4894 ment.settings.env.
4895 Then, to act as a link target (from the todolist), the todo directive
4897 needs to return a target node in addition to the todo node. The target
4898 ID (in HTML, this will be the anchor name) is generated by using
4899 env.new_serialno which is returns a new integer directive on each call
4900 and therefore leads to unique target names. The target node is instan‐
4901 tiated without any text (the first two arguments).
4902 An admonition is created using a standard docutils function (wrapped in
4904 Sphinx for docutils cross-version compatibility). The first argument
4905 gives the node class, in our case todo. The third argument gives the
4906 admonition title (use arguments here to let the user specify the
4907 title). A list of nodes is returned from make_admonition.
4908 Then, the todo node is added to the environment. This is needed to be
4910 able to create a list of all todo entries throughout the documentation,
4911 in the place where the author puts a todolist directive. For this
4912 case, the environment attribute todo_all_todos is used (again, the name
4913 should be unique, so it is prefixed by the extension name). It does
4914 not exist when a new environment is created, so the directive must
4915 check and create it if necessary. Various information about the todo
4916 entry's location are stored along with a copy of the node.
4917 In the last line, the nodes that should be put into the doctree are
4919 returned: the target node and the admonition node.
4920 The node structure that the directive returns looks like this:
4922 +--------------------+
4924 | target node |
4925 +--------------------+
4926 +--------------------+
4927 | todo node |
4928 +--------------------+
4929 \__+--------------------+
4930 | admonition title |
4931 +--------------------+
4932 | paragraph |
4933 +--------------------+
4934 | ... |
4935 +--------------------+
4936 The Event Handlers
4938 Finally, let's look at the event handlers. First, the one for the
4939 env-purge-doc event:
4940 def purge_todos(app, env, docname):
4942 if not hasattr(env, 'todo_all_todos'):
4943 return
4944 env.todo_all_todos = [todo for todo in env.todo_all_todos
4945 if todo['docname'] != docname]
4946 Since we store information from source files in the environment, which
4948 is persistent, it may become out of date when the source file changes.
4949 Therefore, before each source file is read, the environment's records
4950 of it are cleared, and the env-purge-doc event gives extensions a
4951 chance to do the same. Here we clear out all todos whose docname
4952 matches the given one from the todo_all_todos list. If there are todos
4953 left in the document, they will be added again during parsing.
4954 The other handler belongs to the doctree-resolved event. This event is
4956 emitted at the end of phase 3 and allows custom resolving to be done:
4957 def process_todo_nodes(app, doctree, fromdocname):
4959 if not app.config.todo_include_todos:
4960 for node in doctree.traverse(todo):
4961 node.parent.remove(node)
4962 # Replace all todolist nodes with a list of the collected todos.
4964 # Augment each todo with a backlink to the original location.
4965 env = app.builder.env
4966 for node in doctree.traverse(todolist):
4968 if not app.config.todo_include_todos:
4969 node.replace_self([])
4970 continue
4971 content = []
4973 for todo_info in env.todo_all_todos:
4975 para = nodes.paragraph()
4976 filename = env.doc2path(todo_info['docname'], base=None)
4977 description = (
4978 _('(The original entry is located in %s, line %d and can be found ') %
4979 (filename, todo_info['lineno']))
4980 para += nodes.Text(description, description)
4981 # Create a reference
4983 newnode = nodes.reference('', '')
4984 innernode = nodes.emphasis(_('here'), _('here'))
4985 newnode['refdocname'] = todo_info['docname']
4986 newnode['refuri'] = app.builder.get_relative_uri(
4987 fromdocname, todo_info['docname'])
4988 newnode['refuri'] += '#' + todo_info['target']['refid']
4989 newnode.append(innernode)
4990 para += newnode
4991 para += nodes.Text('.)', '.)')
4992 # Insert into the todolist
4994 content.append(todo_info['todo'])
4995 content.append(para)
4996 node.replace_self(content)
4998 It is a bit more involved. If our new "todo_include_todos" config
5000 value is false, all todo and todolist nodes are removed from the docu‐
5001 ments.
5002 If not, todo nodes just stay where and how they are. Todolist nodes
5004 are replaced by a list of todo entries, complete with backlinks to the
5005 location where they come from. The list items are composed of the
5006 nodes from the todo entry and docutils nodes created on the fly: a
5007 paragraph for each entry, containing text that gives the location, and
5008 a link (reference node containing an italic node) with the backrefer‐
5009 ence. The reference URI is built by app.builder.get_relative_uri which
5010 creates a suitable URI depending on the used builder, and appending the
5011 todo node's (the target's) ID as the anchor name.
5012 Extension API
5014 Each Sphinx extension is a Python module with at least a setup() func‐
5015 tion. This function is called at initialization time with one argu‐
5016 ment, the application object representing the Sphinx process. This
5017 application object has the following public API:
5018 Sphinx.setup_extension(name)
5020 Load the extension given by the module name. Use this if your
5022 extension needs the features provided by another extension.
5023 Sphinx.add_builder(builder)
5025 Register a new builder. builder must be a class that inherits
5027 from Builder.
5028 Sphinx.add_config_value(name, default, rebuild)
5030 Register a configuration value. This is necessary for Sphinx to
5032 recognize new values and set default values accordingly. The
5033 name should be prefixed with the extension name, to avoid
5034 clashes. The default value can be any Python object. The
5035 string value rebuild must be one of those values:
5036 · 'env' if a change in the setting only takes effect when a doc‐
5038 ument is parsed -- this means that the whole environment must
5039 be rebuilt.
5040 · 'html' if a change in the setting needs a full rebuild of HTML
5042 documents.
5043 · '' if a change in the setting will not need any special
5045 rebuild.
5046 Changed in version 0.4: If the default value is a callable, it
5048 will be called with the config object as its argument in order
5049 to get the default value. This can be used to implement config
5050 values whose default depends on other values.
5051 Changed in version 0.6: Changed rebuild from a simple boolean
5053 (equivalent to '' or 'env') to a string. However, booleans are
5054 still accepted and converted internally.
5055 Sphinx.add_domain(domain)
5057 Make the given domain (which must be a class; more precisely, a
5059 subclass of Domain) known to Sphinx.
5060 New in version 1.0.
5062 Sphinx.override_domain(domain)
5064 Make the given domain class known to Sphinx, assuming that there
5066 is already a domain with its .name. The new domain must be a
5067 subclass of the existing one.
5068 New in version 1.0.
5070 Sphinx.add_index_to_domain(domain, index)
5072 Add a custom index class to the domain named domain. index must
5074 be a subclass of Index.
5075 New in version 1.0.
5077 Sphinx.add_event(name)
5079 Register an event called name. This is needed to be able to
5081 emit it.
5082 Sphinx.add_node(node, **kwds)
5084 Register a Docutils node class. This is necessary for Docutils
5086 internals. It may also be used in the future to validate nodes
5087 in the parsed documents.
5088 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
5090 page writers can be given as keyword arguments: the keyword must
5091 be one or more of 'html', 'latex', 'text', 'man', the value a
5092 2-tuple of (visit, depart) methods. depart can be None if the
5093 visit function raises docutils.nodes.SkipNode. Example:
5094 class math(docutils.nodes.Element): pass
5096 def visit_math_html(self, node):
5098 self.body.append(self.starttag(node, 'math'))
5099 def depart_math_html(self, node):
5100 self.body.append('</math>')
5101 app.add_node(math, html=(visit_math_html, depart_math_html))
5103 Obviously, translators for which you don't specify visitor meth‐
5105 ods will choke on the node when encountered in a document to
5106 translate.
5107 Changed in version 0.5: Added the support for keyword arguments
5109 giving visit functions.
5110 Sphinx.add_directive(name, func, content, arguments, **options)
5112 Sphinx.add_directive(name, directiveclass)
5114 Register a Docutils directive. name must be the prospective
5116 directive name. There are two possible ways to write a direc‐
5117 tive:
5118 · In the docutils 0.4 style, obj is the directive function.
5120 content, arguments and options are set as attributes on the
5121 function and determine whether the directive has content,
5122 arguments and options, respectively. This style is depre‐
5123 cated.
5124 · In the docutils 0.5 style, directiveclass is the directive
5126 class. It must already have attributes named has_content,
5127 required_arguments, optional_arguments, final_argument_white‐
5128 space and option_spec that correspond to the options for the
5129 function way. See the Docutils docs for details.
5130 The directive class normally must inherit from the class docu‐
5132 tils.parsers.rst.Directive. When writing a directive for
5133 usage in a Sphinx extension, you inherit from sphinx.util.com‐
5134 pat.Directive instead which does the right thing even on docu‐
5135 tils 0.4 (which doesn't support directive classes otherwise).
5136 For example, the (already existing) literalinclude directive
5138 would be added like this:
5139 from docutils.parsers.rst import directives
5141 add_directive('literalinclude', literalinclude_directive,
5142 content = 0, arguments = (1, 0, 0),
5143 linenos = directives.flag,
5144 language = direcitves.unchanged,
5145 encoding = directives.encoding)
5146 Changed in version 0.6: Docutils 0.5-style directive classes are
5148 now supported.
5149 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
5151 **options)
5152 Sphinx.add_directive_to_domain(domain, name, directiveclass)
5154 Like add_directive(), but the directive is added to the domain
5156 named domain.
5157 New in version 1.0.
5159 Sphinx.add_role(name, role)
5161 Register a Docutils role. name must be the role name that
5163 occurs in the source, role the role function (see the Docutils
5164 documentation on details).
5165 Sphinx.add_role_to_domain(domain, name, role)
5167 Like add_role(), but the role is added to the domain named
5169 domain.
5170 New in version 1.0.
5172 Sphinx.add_generic_role(name, nodeclass)
5174 Register a Docutils role that does nothing but wrap its contents
5176 in the node given by nodeclass.
5177 New in version 0.6.
5179 Sphinx.add_object_type(directivename, rolename, indextemplate='',
5181 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
5182 This method is a very convenient way to add a new object type
5184 that can be cross-referenced. It will do this:
5185 · Create a new directive (called directivename) for documenting
5187 an object. It will automatically add index entries if index‐
5188 template is nonempty; if given, it must contain exactly one
5189 instance of %s. See the example below for how the template
5190 will be interpreted.
5191 · Create a new role (called rolename) to cross-reference to
5193 these object descriptions.
5194 · If you provide parse_node, it must be a function that takes a
5196 string and a docutils node, and it must populate the node with
5197 children parsed from the string. It must then return the name
5198 of the item to be used in cross-referencing and index entries.
5199 See the conf.py file in the source for this documentation for
5200 an example.
5201 · The objname (if not given, will default to directivename)
5203 names the type of object. It is used when listing objects,
5204 e.g. in search results.
5205 For example, if you have this call in a custom Sphinx extension:
5207 app.add_object_type('directive', 'dir', 'pair: %s; directive')
5209 you can use this markup in your documents:
5211 .. rst:directive:: function
5213 Document a function.
5215 <...>
5217 See also the :rst:dir:`function` directive.
5219 For the directive, an index entry will be generated as if you
5221 had prepended
5222 .. index:: pair: function; directive
5224 The reference node will be of class literal (so it will be ren‐
5226 dered in a proportional font, as appropriate for code) unless
5227 you give the ref_nodeclass argument, which must be a docutils
5228 node class (most useful are docutils.nodes.emphasis or docu‐
5229 tils.nodes.strong -- you can also use docutils.nodes.generated
5230 if you want no further text decoration).
5231 For the role content, you have the same syntactical possibili‐
5233 ties as for standard Sphinx roles (see xref-syntax).
5234 This method is also available under the deprecated alias
5236 add_description_unit.
5237 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
5239 ref_nodeclass=None, objname='')
5240 This method is very similar to add_object_type() except that the
5242 directive it generates must be empty, and will produce no out‐
5243 put.
5244 That means that you can add semantic targets to your sources,
5246 and refer to them using custom roles instead of generic ones
5247 (like ref). Example call:
5248 app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
5250 Example usage:
5252 .. topic:: application API
5254 The application API
5256 -------------------
5257 <...>
5259 See also :topic:`this section <application API>`.
5261 (Of course, the element following the topic directive needn't be
5263 a section.)
5264 Sphinx.add_transform(transform)
5266 Add the standard docutils Transform subclass transform to the
5268 list of transforms that are applied after Sphinx parses a reST
5269 document.
5270 Sphinx.add_javascript(filename)
5272 Add filename to the list of JavaScript files that the default
5274 HTML template will include. The filename must be relative to
5275 the HTML static path, see the docs for the config value. A full
5276 URI with scheme, like http://example.org/foo.js, is also sup‐
5277 ported.
5278 New in version 0.5.
5280 Sphinx.add_stylesheet(filename)
5282 Add filename to the list of CSS files that the default HTML tem‐
5284 plate will include. Like for add_javascript(), the filename
5285 must be relative to the HTML static path.
5286 New in version 1.0.
5288 Sphinx.add_lexer(alias, lexer)
5290 Use lexer, which must be an instance of a Pygments lexer class,
5292 to highlight code blocks with the given language alias.
5293 New in version 0.6.
5295 Sphinx.add_autodocumenter(cls)
5297 Add cls as a new documenter class for the sphinx.ext.autodoc
5299 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
5300 menter. This allows to auto-document new types of objects. See
5301 the source of the autodoc module for examples on how to subclass
5302 Documenter.
5303 New in version 0.6.
5305 Sphinx.add_autodoc_attrgetter(type, getter)
5307 Add getter, which must be a function with an interface compati‐
5309 ble to the getattr() builtin, as the autodoc attribute getter
5310 for objects that are instances of type. All cases where autodoc
5311 needs to get an attribute of a type are then handled by this
5312 function instead of getattr().
5313 New in version 0.6.
5315 Sphinx.connect(event, callback)
5317 Register callback to be called when event is emitted. For
5319 details on available core events and the arguments of callback
5320 functions, please see events.
5321 The method returns a "listener ID" that can be used as an argu‐
5323 ment to disconnect().
5324 Sphinx.disconnect(listener_id)
5326 Unregister callback listener_id.
5328 Sphinx.emit(event, *arguments)
5330 Emit event and pass arguments to the callback functions. Return
5332 the return values of all callbacks as a list. Do not emit core
5333 Sphinx events in extensions!
5334 Sphinx.emit_firstresult(event, *arguments)
5336 Emit event and pass arguments to the callback functions. Return
5338 the result of the first callback that doesn't return None.
5339 New in version 0.5.
5341 Sphinx.require_sphinx(version)
5343 Compare version (which must be a major.minor version string,
5345 e.g. '1.1') with the version of the running Sphinx, and abort
5346 the build when it is too old.
5347 New in version 1.0.
5349 exception sphinx.application.ExtensionError
5351 All these functions raise this exception if something went wrong
5353 with the extension API.
5354 Examples of using the Sphinx extension API can be seen in the
5356 sphinx.ext package.
5357 Sphinx core events
5359 These events are known to the core. The arguments shown are given to
5360 the registered event handlers.
5361 builder-inited(app)
5363 Emitted when the builder object has been created. It is avail‐
5365 able as app.builder.
5366 env-purge-doc(app, env, docname)
5368 Emitted when all traces of a source file should be cleaned from
5370 the environment, that is, if the source file is removed or
5371 before it is freshly read. This is for extensions that keep
5372 their own caches in attributes of the environment.
5373 For example, there is a cache of all modules on the environment.
5375 When a source file has been changed, the cache's entries for the
5376 file are cleared, since the module declarations could have been
5377 removed from the file.
5378 New in version 0.5.
5380 source-read(app, docname, source)
5382 Emitted when a source file has been read. The source argument
5384 is a list whose single element is the contents of the source
5385 file. You can process the contents and replace this item to
5386 implement source-level transformations.
5387 For example, if you want to use $ signs to delimit inline math,
5389 like in LaTeX, you can use a regular expression to replace $...$
5390 by :math:`...`.
5391 New in version 0.5.
5393 doctree-read(app, doctree)
5395 Emitted when a doctree has been parsed and read by the environ‐
5397 ment, and is about to be pickled. The doctree can be modified
5398 in-place.
5399 missing-reference(app, env, node, contnode)
5401 Emitted when a cross-reference to a Python module or object can‐
5403 not be resolved. If the event handler can resolve the refer‐
5404 ence, it should return a new docutils node to be inserted in the
5405 document tree in place of the node node. Usually this node is a
5406 reference node containing contnode as a child.
5407 Parameters
5409 · env -- The build environment (app.builder.env).
5411 · node -- The pending_xref node to be resolved. Its
5413 attributes reftype, reftarget, modname and classname
5414 attributes determine the type and target of the refer‐
5415 ence.
5416 · contnode -- The node that carries the text and format‐
5418 ting inside the future reference and should be a child
5419 of the returned reference node.
5420 New in version 0.5.
5422 doctree-resolved(app, doctree, docname)
5424 Emitted when a doctree has been "resolved" by the environment,
5426 that is, all references have been resolved and TOCs have been
5427 inserted. The doctree can be modified in place.
5428 Here is the place to replace custom nodes that don't have visi‐
5430 tor methods in the writers, so that they don't cause errors when
5431 the writers encounter them.
5432 env-updated(app, env)
5434 Emitted when the update() method of the build environment has
5436 completed, that is, the environment and all doctrees are now
5437 up-to-date.
5438 New in version 0.5.
5440 html-collect-pages(app)
5442 Emitted when the HTML builder is starting to write non-document
5444 pages. You can add pages to write by returning an iterable from
5445 this event consisting of (pagename, context, templatename).
5446 New in version 1.0.
5448 html-page-context(app, pagename, templatename, context, doctree)
5450 Emitted when the HTML builder has created a context dictionary
5452 to render a template with -- this can be used to add custom ele‐
5453 ments to the context.
5454 The pagename argument is the canonical name of the page being
5456 rendered, that is, without .html suffix and using slashes as
5457 path separators. The templatename is the name of the template
5458 to render, this will be 'page.html' for all pages from reST doc‐
5459 uments.
5460 The context argument is a dictionary of values that are given to
5462 the template engine to render the page and can be modified to
5463 include custom values. Keys must be strings.
5464 The doctree argument will be a doctree when the page is created
5466 from a reST documents; it will be None when the page is created
5467 from an HTML template alone.
5468 New in version 0.4.
5470 build-finished(app, exception)
5472 Emitted when a build has finished, before Sphinx exits, usually
5474 used for cleanup. This event is emitted even when the build
5475 process raised an exception, given as the exception argument.
5476 The exception is reraised in the application after the event
5477 handlers have run. If the build process raised no exception,
5478 exception will be None. This allows to customize cleanup
5479 actions depending on the exception status.
5480 New in version 0.5.
5482 The template bridge
5484 class sphinx.application.TemplateBridge
5485 This class defines the interface for a "template bridge", that
5487 is, a class that renders templates given a template name and a
5488 context.
5489 init(builder, theme=None, dirs=None)
5491 Called by the builder to initialize the template system.
5493 builder is the builder object; you'll probably want to
5495 look at the value of builder.config.templates_path.
5496 theme is a sphinx.theming.Theme object or None; in the
5498 latter case, dirs can be list of fixed directories to
5499 look for templates.
5500 newest_template_mtime()
5502 Called by the builder to determine if output files are
5504 outdated because of template changes. Return the mtime
5505 of the newest template file that was changed. The
5506 default implementation returns 0.
5507 render(template, context)
5509 Called by the builder to render a template given as a
5511 filename with a specified context (a Python dictionary).
5512 render_string(template, context)
5514 Called by the builder to render a template given as a
5516 string with a specified context (a Python dictionary).
5517 Domain API
5519 class sphinx.domains.Domain(env)
5520 A Domain is meant to be a group of "object" description direc‐
5522 tives for objects of a similar nature, and corresponding roles
5523 to create references to them. Examples would be Python modules,
5524 classes, functions etc., elements of a templating language,
5525 Sphinx roles and directives, etc.
5526 Each domain has a separate storage for information about exist‐
5528 ing objects and how to reference them in self.data, which must
5529 be a dictionary. It also must implement several functions that
5530 expose the object information in a uniform way to parts of
5531 Sphinx that allow the user to reference or search for objects in
5532 a domain-agnostic way.
5533 About self.data: since all object and cross-referencing informa‐
5535 tion is stored on a BuildEnvironment instance, the domain.data
5536 object is also stored in the env.domaindata dict under the key
5537 domain.name. Before the build process starts, every active
5538 domain is instantiated and given the environment object; the
5539 domaindata dict must then either be nonexistent or a dictionary
5540 whose 'version' key is equal to the domain class' data_version
5541 attribute. Otherwise, IOError is raised and the pickled envi‐
5542 ronment is discarded.
5543 clear_doc(docname)
5545 Remove traces of a document in the domain-specific inven‐
5547 tories.
5548 directive(name)
5550 Return a directive adapter class that always gives the
5552 registered directive its full name ('domain:name') as
5553 self.name.
5554 get_objects()
5556 Return an iterable of "object descriptions", which are
5558 tuples with five items:
5559 · name -- fully qualified name
5561 · dispname -- name to display when searching/linking
5563 · type -- object type, a key in self.object_types
5565 · docname -- the document where it is to be found
5567 · anchor -- the anchor name for the object
5569 · priority -- how "important" the object is (determines
5571 placement in search results)
5572 · 1: default priority (placed before full-text matches)
5574 · 0: object is important (placed before default-prior‐
5576 ity objects)
5577 · 2: object is unimportant (placed after full-text
5579 matches)
5580 · -1: object should not show up in search at all
5582 get_type_name(type, primary=False)
5584 Return full name for given ObjType.
5586 process_doc(env, docname, document)
5588 Process a document after it is read by the environment.
5590 resolve_xref(env, fromdocname, builder, typ, target, node, con‐
5592 tnode)
5593 Resolve the pending_xref node with the given typ and tar‐
5595 get.
5596 This method should return a new node, to replace the xref
5598 node, containing the contnode which is the markup content
5599 of the cross-reference.
5600 If no resolution can be found, None can be returned; the
5602 xref node will then given to the 'missing-reference'
5603 event, and if that yields no resolution, replaced by con‐
5604 tnode.
5605 The method can also raise sphinx.environment.NoUri to
5607 suppress the 'missing-reference' event being emitted.
5608 role(name)
5610 Return a role adapter function that always gives the reg‐
5612 istered role its full name ('domain:name') as the first
5613 argument.
5614 dangling_warnings
5616 role name -> a warning message if reference is missing
5617 data_version
5619 data version, bump this when the format of self.data
5620 changes
5621 directives
5623 directive name -> directive class
5624 indices
5626 a list of Index subclasses
5627 initial_data
5629 data value for a fresh environment
5630 label domain label: longer, more descriptive (used in messages)
5632 name domain name: should be short, but unique
5634 object_types
5636 type (usually directive) name -> ObjType instance
5637 roles role name -> role callable
5639 class sphinx.domains.ObjType(lname, *roles, **attrs)
5641 An ObjType is the description for a type of object that a domain
5643 can document. In the object_types attribute of Domain sub‐
5644 classes, object type names are mapped to instances of this
5645 class.
5646 Constructor arguments:
5648 · lname: localized name of the type (do not include domain name)
5650 · roles: all the roles that can refer to an object of this type
5652 · attrs: object attributes -- currently only "searchprio" is
5654 known, which defines the object's priority in the full-text
5655 search index, see Domain.get_objects().
5656 class sphinx.domains.Index(domain)
5658 An Index is the description for a domain-specific index. To add
5660 an index to a domain, subclass Index, overriding the three name
5661 attributes:
5662 · name is an identifier used for generating file names.
5664 · localname is the section title for the index.
5666 · shortname is a short name for the index, for use in the rela‐
5668 tion bar in HTML output. Can be empty to disable entries in
5669 the relation bar.
5670 and providing a generate() method. Then, add the index class to
5672 your domain's indices list. Extensions can add indices to
5673 existing domains using add_index_to_domain().
5674 generate(docnames=None)
5676 Return entries for the index given by name. If docnames
5678 is given, restrict to entries referring to these doc‐
5679 names.
5680 The return value is a tuple of (content, collapse), where
5682 collapse is a boolean that determines if sub-entries
5683 should start collapsed (for output formats that support
5684 collapsing sub-entries).
5685 content is a sequence of (letter, entries) tuples, where
5687 letter is the "heading" for the given entries, usually
5688 the starting letter.
5689 entries is a sequence of single entries, where a single
5691 entry is a sequence [name, subtype, docname, anchor,
5692 extra, qualifier, descr]. The items in this sequence
5693 have the following meaning:
5694 · name -- the name of the index entry to be displayed
5696 · subtype -- sub-entry related type: 0 -- normal entry 1
5698 -- entry with sub-entries 2 -- sub-entry
5699 · docname -- docname where the entry is located
5701 · anchor -- anchor for the entry within docname
5703 · extra -- extra info for the entry
5705 · qualifier -- qualifier for the description
5707 · descr -- description for the entry
5709 Qualifier and description are not rendered e.g. in LaTeX
5711 output.
5712 Writing new builders
5714 Todo
5715 Expand this.
5716 class sphinx.builders.Builder
5718 This is the base class for all builders.
5720 These methods are predefined and will be called from the appli‐
5722 cation:
5723 get_relative_uri(from_, to, typ=None)
5725 Return a relative URI between two source filenames. May
5727 raise environment.NoUri if there's no way to return a
5728 sensible URI.
5729 build_all()
5731 Build all source files.
5733 build_specific(filenames)
5735 Only rebuild as much as needed for changes in the file‐
5737 names.
5738 build_update()
5740 Only rebuild what was changed or added since last build.
5742 build(docnames, summary=None, method='update')
5744 Main build method. First updates the environment, and
5746 then calls write().
5747 These methods can be overridden in concrete builder classes:
5749 init()
5751 Load necessary templates and perform initialization. The
5753 default implementation does nothing.
5754 get_outdated_docs()
5756 Return an iterable of output files that are outdated, or
5758 a string describing what an update build will build.
5759 If the builder does not output individual files corre‐
5761 sponding to source files, return a string here. If it
5762 does, return an iterable of those files that need to be
5763 written.
5764 get_target_uri(docname, typ=None)
5766 Return the target URI for a document name (typ can be
5768 used to qualify the link characteristic for individual
5769 builders).
5770 prepare_writing(docnames)
5772 write_doc(docname, doctree)
5774 finish()
5776 Finish the building process. The default implementation
5778 does nothing.
5779 Builtin Sphinx extensions
5781 These extensions are built in and can be activated by respective
5782 entries in the extensions configuration value:
5783 sphinx.ext.autodoc -- Include documentation from docstrings
5785 This extension can import the modules you are documenting, and pull in
5786 documentation from docstrings in a semi-automatic way.
5787 Note For Sphinx (actually, the Python interpreter that executes
5789 Sphinx) to find your module, it must be importable. That means
5790 that the module or the package must be in one of the directories
5791 on sys.path -- adapt your sys.path in the configuration file
5792 accordingly.
5793 For this to work, the docstrings must of course be written in correct
5795 reStructuredText. You can then use all of the usual Sphinx markup in
5796 the docstrings, and it will end up correctly in the documentation.
5797 Together with hand-written documentation, this technique eases the pain
5798 of having to maintain two locations for documentation, while at the
5799 same time avoiding auto-generated-looking pure API documentation.
5800 autodoc provides several directives that are versions of the usual
5802 py:module, py:class and so forth. On parsing time, they import the
5803 corresponding module and extract the docstring of the given objects,
5804 inserting them into the page source under a suitable py:module,
5805 py:class etc. directive.
5806 Note Just as py:class respects the current py:module, autoclass will
5808 also do so. Likewise, automethod will respect the current
5809 py:class.
5810 .. automodule::
5812 .. autoclass::
5814 .. autoexception::
5816 Document a module, class or exception. All three directives
5818 will by default only insert the docstring of the object itself:
5819 .. autoclass:: Noodle
5821 will produce source like this:
5823 .. class:: Noodle
5825 Noodle's docstring.
5827 The "auto" directives can also contain content of their own, it
5829 will be inserted into the resulting non-auto directive source
5830 after the docstring (but before any automatic member documenta‐
5831 tion).
5832 Therefore, you can also mix automatic and non-automatic member
5834 documentation, like so:
5835 .. autoclass:: Noodle
5837 :members: eat, slurp
5838 .. method:: boil(time=10)
5840 Boil the noodle *time* minutes.
5842 Options and advanced usage
5844 · If you want to automatically document members, there's a mem‐
5846 bers option:
5847 .. automodule:: noodle
5849 :members:
5850 will document all module members (recursively), and
5852 .. autoclass:: Noodle
5854 :members:
5855 will document all non-private member functions and properties
5857 (that is, those whose name doesn't start with _).
5858 For modules, __all__ will be respected when looking for mem‐
5860 bers; the order of the members will also be the order in
5861 __all__.
5862 You can also give an explicit list of members; only these will
5864 then be documented:
5865 .. autoclass:: Noodle
5867 :members: eat, slurp
5868 · If you want to make the members option the default, see
5870 autodoc_default_flags.
5871 · Members without docstrings will be left out, unless you give
5873 the undoc-members flag option:
5874 .. automodule:: noodle
5876 :members:
5877 :undoc-members:
5878 · For classes and exceptions, members inherited from base
5880 classes will be left out when documenting all members, unless
5881 you give the inherited-members flag option, in addition to
5882 members:
5883 .. autoclass:: Noodle
5885 :members:
5886 :inherited-members:
5887 This can be combined with undoc-members to document all avail‐
5889 able members of the class or module.
5890 Note: this will lead to markup errors if the inherited members
5892 come from a module whose docstrings are not reST formatted.
5893 New in version 0.3.
5895 · It's possible to override the signature for explicitly docu‐
5897 mented callable objects (functions, methods, classes) with the
5898 regular syntax that will override the signature gained from
5899 introspection:
5900 .. autoclass:: Noodle(type)
5902 .. automethod:: eat(persona)
5904 This is useful if the signature from the method is hidden by a
5906 decorator.
5907 New in version 0.4.
5909 · The automodule, autoclass and autoexception directives also
5911 support a flag option called show-inheritance. When given, a
5912 list of base classes will be inserted just below the class
5913 signature (when used with automodule, this will be inserted
5914 for every class that is documented in the module).
5915 New in version 0.4.
5917 · All autodoc directives support the noindex flag option that
5919 has the same effect as for standard py:function etc. direc‐
5920 tives: no index entries are generated for the documented
5921 object (and all autodocumented members).
5922 New in version 0.4.
5924 · automodule also recognizes the synopsis, platform and depre‐
5926 cated options that the standard py:module directive supports.
5927 New in version 0.5.
5929 · automodule and autoclass also has an member-order option that
5931 can be used to override the global value of autodoc_mem‐
5932 ber_order for one directive.
5933 New in version 0.6.
5935 · The directives supporting member documentation also have a
5937 exclude-members option that can be used to exclude single mem‐
5938 ber names from documentation, if all members are to be docu‐
5939 mented.
5940 New in version 0.6.
5942 Note In an automodule directive with the members option set, only
5944 module members whose __module__ attribute is equal to the module
5945 name as given to automodule will be documented. This is to pre‐
5946 vent documentation of imported classes or functions.
5947 .. autofunction::
5949 .. autodata::
5951 .. automethod::
5953 .. autoattribute::
5955 These work exactly like autoclass etc., but do not offer the
5957 options used for automatic member documentation.
5958 For module data members and class attributes, documentation can
5960 either be put into a special-formatted comment before the
5961 attribute definition, or in a docstring after the definition.
5962 This means that in the following class definition, both
5963 attributes can be autodocumented:
5964 class Foo:
5966 """Docstring for class Foo."""
5967 #: Doc comment for attribute Foo.bar.
5969 bar = 1
5970 baz = 2
5972 """Docstring for attribute Foo.baz."""
5973 Changed in version 0.6: autodata and autoattribute can now
5975 extract docstrings.
5976 Note If you document decorated functions or methods, keep in mind
5978 that autodoc retrieves its docstrings by importing the module
5979 and inspecting the __doc__ attribute of the given function or
5980 method. That means that if a decorator replaces the decorated
5981 function with another, it must copy the original __doc__ to the
5982 new function.
5983 From Python 2.5, functools.wraps() can be used to create
5985 well-behaved decorating functions.
5986 There are also new config values that you can set:
5988 autoclass_content
5990 This value selects what content will be inserted into the main
5991 body of an autoclass directive. The possible values are:
5992 "class"
5994 Only the class' docstring is inserted. This is the
5996 default. You can still document __init__ as a separate
5997 method using automethod or the members option to auto‐
5998 class.
5999 "both"
6001 Both the class' and the __init__ method's docstring are
6003 concatenated and inserted.
6004 "init"
6006 Only the __init__ method's docstring is inserted.
6008 New in version 0.3.
6010 autodoc_member_order
6012 This value selects if automatically documented members are
6013 sorted alphabetical (value 'alphabetical'), by member type
6014 (value 'groupwise') or by source order (value 'bysource'). The
6015 default is alphabetical.
6016 Note that for source order, the module must be a Python module
6018 with the source code available.
6019 New in version 0.6.
6021 Changed in version 1.0: Support for 'bysource'.
6023 autodoc_default_flags
6025 This value is a list of autodoc directive flags that should be
6026 automatically applied to all autodoc directives. The supported
6027 flags are 'members', 'undoc-members', 'inherited-members' and
6028 'show-inheritance'.
6029 If you set one of these flags in this config value, you can use
6031 a negated form, 'no-flag', in an autodoc directive, to disable
6032 it once. For example, if autodoc_default_flags is set to ['mem‐
6033 bers', 'undoc-members'], and you write a directive like this:
6034 .. automodule:: foo
6036 :no-undoc-members:
6037 the directive will be interpreted as if only :members: was
6039 given.
6040 New in version 1.0.
6042 Docstring preprocessing
6044 autodoc provides the following additional events:
6045 autodoc-process-docstring(app, what, name, obj, options, lines)
6047 New in version 0.4.
6049 Emitted when autodoc has read and processed a docstring. lines
6051 is a list of strings -- the lines of the processed docstring --
6052 that the event handler can modify in place to change what Sphinx
6053 puts into the output.
6054 Parameters
6056 · app -- the Sphinx application object
6058 · what -- the type of the object which the docstring
6060 belongs to (one of "module", "class", "exception",
6061 "function", "method", "attribute")
6062 · name -- the fully qualified name of the object
6064 · obj -- the object itself
6066 · options -- the options given to the directive: an
6068 object with attributes inherited_members, undoc_mem‐
6069 bers, show_inheritance and noindex that are true if the
6070 flag option of same name was given to the auto direc‐
6071 tive
6072 · lines -- the lines of the docstring, see above
6074 autodoc-process-signature(app, what, name, obj, options, signature,
6076 return_annotation)
6077 New in version 0.5.
6079 Emitted when autodoc has formatted a signature for an object.
6081 The event handler can return a new tuple (signature,
6082 return_annotation) to change what Sphinx puts into the output.
6083 Parameters
6085 · app -- the Sphinx application object
6087 · what -- the type of the object which the docstring
6089 belongs to (one of "module", "class", "exception",
6090 "function", "method", "attribute")
6091 · name -- the fully qualified name of the object
6093 · obj -- the object itself
6095 · options -- the options given to the directive: an
6097 object with attributes inherited_members, undoc_mem‐
6098 bers, show_inheritance and noindex that are true if the
6099 flag option of same name was given to the auto direc‐
6100 tive
6101 · signature -- function signature, as a string of the
6103 form "(parameter_1, parameter_2)", or None if intro‐
6104 spection didn't succeed and signature wasn't specified
6105 in the directive.
6106 · return_annotation -- function return annotation as a
6108 string of the form " -> annotation", or None if there
6109 is no return annotation
6110 The sphinx.ext.autodoc module provides factory functions for commonly
6112 needed docstring processing in event autodoc-process-docstring:
6113 sphinx.ext.autodoc.cut_lines(pre, post=0, what=None)
6115 Return a listener that removes the first pre and last post lines
6117 of every docstring. If what is a sequence of strings, only doc‐
6118 strings of a type in what will be processed.
6119 Use like this (e.g. in the setup() function of conf.py):
6121 from sphinx.ext.autodoc import cut_lines
6123 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
6124 This can (and should) be used in place of automodule_skip_lines.
6126 sphinx.ext.autodoc.between(marker, what=None, keepempty=False,
6128 exclude=False)
6129 Return a listener that either keeps, or if exclude is True
6131 excludes, lines between lines that match the marker regular
6132 expression. If no line matches, the resulting docstring would
6133 be empty, so no change will be made unless keepempty is true.
6134 If what is a sequence of strings, only docstrings of a type in
6136 what will be processed.
6137 Skipping members
6139 autodoc allows the user to define a custom method for determining
6140 whether a member should be included in the documentation by using the
6141 following event:
6142 autodoc-skip-member(app, what, name, obj, skip, options)
6144 New in version 0.5.
6146 Emitted when autodoc has to decide whether a member should be
6148 included in the documentation. The member is excluded if a han‐
6149 dler returns True. It is included if the handler returns False.
6150 Parameters
6152 · app -- the Sphinx application object
6154 · what -- the type of the object which the docstring
6156 belongs to (one of "module", "class", "exception",
6157 "function", "method", "attribute")
6158 · name -- the fully qualified name of the object
6160 · obj -- the object itself
6162 · skip -- a boolean indicating if autodoc will skip this
6164 member if the user handler does not override the deci‐
6165 sion
6166 · options -- the options given to the directive: an
6168 object with attributes inherited_members, undoc_mem‐
6169 bers, show_inheritance and noindex that are true if the
6170 flag option of same name was given to the auto direc‐
6171 tive
6172 sphinx.ext.autosummary -- Generate autodoc summaries
6174 New in version 0.6.
6175 This extension generates function/method/attribute summary lists, simi‐
6177 lar to those output e.g. by Epydoc and other API doc generation tools.
6178 This is especially useful when your docstrings are long and detailed,
6179 and putting each one of them on a separate page makes them easier to
6180 read.
6181 The sphinx.ext.autosummary extension does this in two parts:
6183 1. There is an autosummary directive for generating summary listings
6185 that contain links to the documented items, and short summary blurbs
6186 extracted from their docstrings.
6187 2. The convenience script sphinx-autogen or the new autosummary_gener‐
6189 ate config value can be used to generate short "stub" files for the
6190 entries listed in the autosummary directives. These by default con‐
6191 tain only the corresponding sphinx.ext.autodoc directive.
6192 .. autosummary::
6194 Insert a table that contains links to documented items, and a
6196 short summary blurb (the first sentence of the docstring) for
6197 each of them. The autosummary directive can also optionally
6198 serve as a toctree entry for the included items.
6199 For example,
6201 .. currentmodule:: sphinx
6203 .. autosummary::
6205 environment.BuildEnvironment
6207 util.relative_uri
6208 produces a table like this:
6210 ┌──────────────────────────┬────────────────────────────┐
6212 │environment.BuildEnviron‐ │ The environment in which │
6213 │ment(srcdir, ...) │ the ReST files are trans‐ │
6214 │ │ lated. │
6215 ├──────────────────────────┼────────────────────────────┤
6216 │util.relative_uri(base, │ Return a relative URL from │
6217 │to) │ base to to. │
6218 └──────────────────────────┴────────────────────────────┘
6219 Autosummary preprocesses the docstrings and signatures with the
6221 same autodoc-process-docstring and autodoc-process-signature
6222 hooks as autodoc.
6223 Options
6225 · If you want the autosummary table to also serve as a toctree
6227 entry, use the toctree option, for example:
6228 .. autosummary::
6230 :toctree: DIRNAME
6231 sphinx.environment.BuildEnvironment
6233 sphinx.util.relative_uri
6234 The toctree option also signals to the sphinx-autogen script
6236 that stub pages should be generated for the entries listed in
6237 this directive. The option accepts a directory name as an
6238 argument; sphinx-autogen will by default place its output in
6239 this directory. If no argument is given, output is placed in
6240 the same directory as the file that contains the directive.
6241 · If you don't want the autosummary to show function signatures
6243 in the listing, include the nosignatures option:
6244 .. autosummary::
6246 :nosignatures:
6247 sphinx.environment.BuildEnvironment
6249 sphinx.util.relative_uri
6250 · You can specify a custom template with the template option.
6252 For example,
6253 .. autosummary::
6255 :template: mytemplate.rst
6256 sphinx.environment.BuildEnvironment
6258 would use the template mytemplate.rst in your templates_path
6260 to generate the pages for all entries listed. See Customizing
6261 templates below.
6262 New in version 1.0.
6264 sphinx-autogen -- generate autodoc stub pages
6266 The sphinx-autogen script can be used to conveniently generate stub
6267 documentation pages for items included in autosummary listings.
6268 For example, the command
6270 $ sphinx-autogen -o generated *.rst
6272 will read all autosummary tables in the *.rst files that have the :toc‐
6274 tree: option set, and output corresponding stub pages in directory gen‐
6275 erated for all documented items. The generated pages by default con‐
6276 tain text of the form:
6277 sphinx.util.relative_uri
6279 ========================
6280 .. autofunction:: sphinx.util.relative_uri
6282 If the -o option is not given, the script will place the output files
6284 in the directories specified in the :toctree: options.
6285 Generating stub pages automatically
6287 If you do not want to create stub pages with sphinx-autogen, you can
6288 also use this new config value:
6289 autosummary_generate
6291 Boolean indicating whether to scan all found documents for auto‐
6292 summary directives, and to generate stub pages for each.
6293 Can also be a list of documents for which stub pages should be
6295 generated.
6296 The new files will be placed in the directories specified in the
6298 :toctree: options of the directives.
6299 Customizing templates
6301 New in version 1.0.
6302 You can customize the stub page templates, in a similar way as the HTML
6304 Jinja templates, see templating. (TemplateBridge is not supported.)
6305 Note If you find yourself spending much time tailoring the stub tem‐
6307 plates, this may indicate that it's a better idea to write cus‐
6308 tom narrative documentation instead.
6309 Autosummary uses the following template files:
6311 · autosummary/base.rst -- fallback template
6313 · autosummary/module.rst -- template for modules
6315 · autosummary/class.rst -- template for classes
6317 · autosummary/function.rst -- template for functions
6319 · autosummary/attribute.rst -- template for class attributes
6321 · autosummary/method.rst -- template for class methods
6323 The following variables available in the templates:
6325 name Name of the documented object, excluding the module and class
6327 parts.
6328 objname
6330 Name of the documented object, excluding the module parts.
6331 fullname
6333 Full name of the documented object, including module and class
6334 parts.
6335 module Name of the module the documented object belongs to.
6337 class Name of the class the documented object belongs to. Only avail‐
6339 able for methods and attributes.
6340 underline
6342 A string containing len(full_name) * '='.
6343 members
6345 List containing names of all members of the module or class.
6346 Only available for modules and classes.
6347 functions
6349 List containing names of "public" functions in the module.
6350 Here, "public" here means that the name does not start with an
6351 underscore. Only available for modules.
6352 classes
6354 List containing names of "public" classes in the module. Only
6355 available for modules.
6356 exceptions
6358 List containing names of "public" exceptions in the module.
6359 Only available for modules.
6360 methods
6362 List containing names of "public" methods in the class. Only
6363 available for classes.
6364 attributes
6366 List containing names of "public" attributes in the class. Only
6367 available for classes.
6368 Note You can use the autosummary directive in the stub pages. Stub
6370 pages are generated also based on these directives.
6371 sphinx.ext.doctest -- Test snippets in the documentation
6373 This extension allows you to test snippets in the documentation in a
6374 natural way. It works by collecting specially-marked up code blocks
6375 and running them as doctest tests.
6376 Within one document, test code is partitioned in groups, where each
6378 group consists of:
6379 · zero or more setup code blocks (e.g. importing the module to test)
6381 · one or more test blocks
6383 When building the docs with the doctest builder, groups are collected
6385 for each document and run one after the other, first executing setup
6386 code blocks, then the test blocks in the order they appear in the file.
6387 There are two kinds of test blocks:
6389 · doctest-style blocks mimic interactive sessions by interleaving
6391 Python code (including the interpreter prompt) and output.
6392 · code-output-style blocks consist of an ordinary piece of Python code,
6394 and optionally, a piece of output for that code.
6395 The doctest extension provides four directives. The group argument is
6397 interpreted as follows: if it is empty, the block is assigned to the
6398 group named default. If it is *, the block is assigned to all groups
6399 (including the default group). Otherwise, it must be a comma-separated
6400 list of group names.
6401 .. testsetup:: [group]
6403 A setup code block. This code is not shown in the output for
6405 other builders, but executed before the doctests of the group(s)
6406 it belongs to.
6407 .. doctest:: [group]
6409 A doctest-style code block. You can use standard doctest flags
6411 for controlling how actual output is compared with what you give
6412 as output. By default, these options are enabled: ELLIPSIS
6413 (allowing you to put ellipses in the expected output that match
6414 anything in the actual output), IGNORE_EXCEPTION_DETAIL (not
6415 comparing tracebacks), DONT_ACCEPT_TRUE_FOR_1 (by default,
6416 doctest accepts "True" in the output where "1" is given -- this
6417 is a relic of pre-Python 2.2 times).
6418 This directive supports two options:
6420 · hide, a flag option, hides the doctest block in other
6422 builders. By default it is shown as a highlighted doctest
6423 block.
6424 · options, a string option, can be used to give a comma-sepa‐
6426 rated list of doctest flags that apply to each example in the
6427 tests. (You still can give explicit flags per example, with
6428 doctest comments, but they will show up in other builders
6429 too.)
6430 Note that like with standard doctests, you have to use
6432 <BLANKLINE> to signal a blank line in the expected output. The
6433 <BLANKLINE> is removed when building presentation output (HTML,
6434 LaTeX etc.).
6435 Also, you can give inline doctest options, like in doctest:
6437 >>> datetime.date.now() # doctest: +SKIP
6439 datetime.date(2008, 1, 1)
6440 They will be respected when the test is run, but stripped from
6442 presentation output.
6443 .. testcode:: [group]
6445 A code block for a code-output-style test.
6447 This directive supports one option:
6449 · hide, a flag option, hides the code block in other builders.
6451 By default it is shown as a highlighted code block.
6452 Note Code in a testcode block is always executed all at once, no mat‐
6454 ter how many statements it contains. Therefore, output will not
6455 be generated for bare expressions -- use print. Example:
6456 .. testcode::
6458 1+1 # this will give no output!
6460 print 2+2 # this will give output
6461 .. testoutput::
6463 4
6465 Also, please be aware that since the doctest module does not
6467 support mixing regular output and an exception message in the
6468 same snippet, this applies to testcode/testoutput as well.
6469 .. testoutput:: [group]
6471 The corresponding output, or the exception message, for the last
6473 testcode block.
6474 This directive supports two options:
6476 · hide, a flag option, hides the output block in other builders.
6478 By default it is shown as a literal block without highlight‐
6479 ing.
6480 · options, a string option, can be used to give doctest flags
6482 (comma-separated) just like in normal doctest blocks.
6483 Example:
6485 .. testcode::
6487 print 'Output text.'
6489 .. testoutput::
6491 :hide:
6492 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
6493 Output text.
6495 The following is an example for the usage of the directives. The test
6497 via doctest and the test via testcode and testoutput are equivalent.
6498 The parrot module
6500 =================
6501 .. testsetup:: *
6503 import parrot
6505 The parrot module is a module about parrots.
6507 Doctest example:
6509 .. doctest::
6511 >>> parrot.voom(3000)
6513 This parrot wouldn't voom if you put 3000 volts through it!
6514 Test-Output example:
6516 .. testcode::
6518 parrot.voom(3000)
6520 This would output:
6522 .. testoutput::
6524 This parrot wouldn't voom if you put 3000 volts through it!
6526 There are also these config values for customizing the doctest exten‐
6528 sion:
6529 doctest_path
6531 A list of directories that will be added to sys.path when the
6532 doctest builder is used. (Make sure it contains absolute
6533 paths.)
6534 doctest_global_setup
6536 Python code that is treated like it were put in a testsetup
6537 directive for every file that is tested, and for every group.
6538 You can use this to e.g. import modules you will always need in
6539 your doctests.
6540 New in version 0.6.
6542 doctest_test_doctest_blocks
6544 If this is a nonempty string (the default is 'default'), stan‐
6545 dard reST doctest blocks will be tested too. They will be
6546 assigned to the group name given.
6547 reST doctest blocks are simply doctests put into a paragraph of
6549 their own, like so:
6550 Some documentation text.
6552 >>> print 1
6554 1
6555 Some more documentation text.
6557 (Note that no special :: is used to introduce a doctest block;
6559 docutils recognizes them from the leading >>>. Also, no addi‐
6560 tional indentation is used, though it doesn't hurt.)
6561 If this value is left at its default value, the above snippet is
6563 interpreted by the doctest builder exactly like the following:
6564 Some documentation text.
6566 .. doctest::
6568 >>> print 1
6570 1
6571 Some more documentation text.
6573 This feature makes it easy for you to test doctests in doc‐
6575 strings included with the autodoc extension without marking them
6576 up with a special directive.
6577 Note though that you can't have blank lines in reST doctest
6579 blocks. They will be interpreted as one block ending and
6580 another one starting. Also, removal of <BLANKLINE> and #
6581 doctest: options only works in doctest blocks, though you may
6582 set trim_doctest_flags to achieve the latter in all code blocks
6583 with Python console content.
6584 sphinx.ext.intersphinx -- Link to other projects' documentation
6586 New in version 0.5.
6587 This extension can generate automatic links to the documentation of
6589 objects in other projects.
6590 Usage is simple: whenever Sphinx encounters a cross-reference that has
6592 no matching target in the current documentation set, it looks for tar‐
6593 gets in the documentation sets configured in intersphinx_mapping. A
6594 reference like :py:class:`zipfile.ZipFile` can then link to the Python
6595 documentation for the ZipFile class, without you having to specify
6596 where it is located exactly.
6597 When using the "new" format (see below), you can even force lookup in a
6599 foreign set by prefixing the link target appropriately. A link like
6600 :ref:`comparison manual <python:comparisons>` will then link to the
6601 label "comparisons" in the doc set "python", if it exists.
6602 Behind the scenes, this works as follows:
6604 · Each Sphinx HTML build creates a file named objects.inv that contains
6606 a mapping from object names to URIs relative to the HTML set's root.
6607 · Projects using the Intersphinx extension can specify the location of
6609 such mapping files in the intersphinx_mapping config value. The map‐
6610 ping will then be used to resolve otherwise missing references to
6611 objects into links to the other documentation.
6612 · By default, the mapping file is assumed to be at the same location as
6614 the rest of the documentation; however, the location of the mapping
6615 file can also be specified individually, e.g. if the docs should be
6616 buildable without Internet access.
6617 To use intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
6619 sions config value, and use these new config values to activate link‐
6620 ing:
6621 intersphinx_mapping
6623 This config value contains the locations and names of other
6624 projects that should be linked to in this documentation.
6625 Relative local paths for target locations are taken as relative
6627 to the base of the built documentation, while relative local
6628 paths for inventory locations are taken as relative to the
6629 source directory.
6630 When fetching remote inventory files, proxy settings will be
6632 read from the $HTTP_PROXY environment variable.
6633 Old format for this config value
6635 This is the format used before Sphinx 1.0. It is still recog‐
6637 nized.
6638 A dictionary mapping URIs to either None or an URI. The keys
6640 are the base URI of the foreign Sphinx documentation sets and
6641 can be local paths or HTTP URIs. The values indicate where the
6642 inventory file can be found: they can be None (at the same loca‐
6643 tion as the base URI) or another local or HTTP URI.
6644 New format for this config value
6646 New in version 1.0.
6648 A dictionary mapping unique identifiers to a tuple (target,
6650 inventory). Each target is the base URI of a foreign Sphinx
6651 documentation set and can be a local path or an HTTP URI. The
6652 inventory indicates where the inventory file can be found: it
6653 can be None (at the same location as the base URI) or another
6654 local or HTTP URI.
6655 The unique identifier can be used to prefix cross-reference tar‐
6657 gets, so that it is clear which intersphinx set the target
6658 belongs to. A link like :ref:`comparison manual <python:compar‐
6659 isons>` will link to the label "comparisons" in the doc set
6660 "python", if it exists.
6661 Example
6663 To add links to modules and objects in the Python standard
6665 library documentation, use:
6666 intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}
6668 This will download the corresponding objects.inv file from the
6670 Internet and generate links to the pages under the given URI.
6671 The downloaded inventory is cached in the Sphinx environment, so
6672 it must be redownloaded whenever you do a full rebuild.
6673 A second example, showing the meaning of a non-None value of the
6675 second tuple item:
6676 intersphinx_mapping = {'python': ('http://docs.python.org/3.2',
6678 'python-inv.txt')}
6679 This will read the inventory from python-inv.txt in the source
6681 directory, but still generate links to the pages under
6682 http://docs.python.org/3.2. It is up to you to update the
6683 inventory file as new objects are added to the Python documenta‐
6684 tion.
6685 intersphinx_cache_limit
6687 The maximum number of days to cache remote inventories. The
6688 default is 5, meaning five days. Set this to a negative value
6689 to cache inventories for unlimited time.
6690 Math support in Sphinx
6692 New in version 0.5.
6693 Since mathematical notation isn't natively supported by HTML in any
6695 way, Sphinx supports math in documentation with two extensions.
6696 The basic math support that is common to both extensions is contained
6698 in sphinx.ext.mathbase. Other math support extensions should, if pos‐
6699 sible, reuse that support too.
6700 Note mathbase is not meant to be added to the extensions config
6702 value, instead, use either sphinx.ext.pngmath or
6703 sphinx.ext.jsmath as described below.
6704 The input language for mathematics is LaTeX markup. This is the
6706 de-facto standard for plain-text math notation and has the added advan‐
6707 tage that no further translation is necessary when building LaTeX out‐
6708 put.
6709 mathbase defines these new markup elements:
6711 :math: Role for inline math. Use like this:
6713 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
6715 .. math::
6717 Directive for displayed math (math that takes the whole line for
6719 itself).
6720 The directive supports multiple equations, which should be sepa‐
6722 rated by a blank line:
6723 .. math::
6725 (a + b)^2 = a^2 + 2ab + b^2
6727 (a - b)^2 = a^2 - 2ab + b^2
6729 In addition, each single equation is set within a split environ‐
6731 ment, which means that you can have multiple aligned lines in an
6732 equation, aligned at & and separated by \\:
6733 .. math::
6735 (a + b)^2 &= (a + b)(a + b) \\
6737 &= a^2 + 2ab + b^2
6738 For more details, look into the documentation of the AmSMath
6740 LaTeX package.
6741 When the math is only one line of text, it can also be given as
6743 a directive argument:
6744 .. math:: (a + b)^2 = a^2 + 2ab + b^2
6746 Normally, equations are not numbered. If you want your equation
6748 to get a number, use the label option. When given, it selects a
6749 label for the equation, by which it can be cross-referenced, and
6750 causes an equation number to be issued. See eqref for an exam‐
6751 ple. The numbering style depends on the output format.
6752 There is also an option nowrap that prevents any wrapping of the
6754 given math in a math environment. When you give this option,
6755 you must make sure yourself that the math is properly set up.
6756 For example:
6757 .. math::
6759 :nowrap:
6760 \begin{eqnarray}
6762 y & = & ax^2 + bx + c \\
6763 f(x) & = & x^2 + 2xy + y^2
6764 \end{eqnarray}
6765 :eq: Role for cross-referencing equations via their label. This cur‐
6767 rently works only within the same document. Example:
6768 .. math:: e^{i\pi} + 1 = 0
6770 :label: euler
6771 Euler's identity, equation :eq:`euler`, was elected one of the most
6773 beautiful mathematical formulas.
6774 sphinx.ext.pngmath -- Render math as PNG images
6776 This extension renders math via LaTeX and dvipng into PNG images. This
6777 of course means that the computer where the docs are built must have
6778 both programs available.
6779 There are various config values you can set to influence how the images
6781 are built:
6782 pngmath_latex
6784 The command name with which to invoke LaTeX. The default is
6785 'latex'; you may need to set this to a full path if latex is not
6786 in the executable search path.
6787 Since this setting is not portable from system to system, it is
6789 normally not useful to set it in conf.py; rather, giving it on
6790 the sphinx-build command line via the -D option should be
6791 preferable, like this:
6792 sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
6794 Changed in version 0.5.1: This value should only contain the
6796 path to the latex executable, not further arguments; use png‐
6797 math_latex_args for that purpose.
6798 pngmath_dvipng
6800 The command name with which to invoke dvipng. The default is
6801 'dvipng'; you may need to set this to a full path if dvipng is
6802 not in the executable search path.
6803 pngmath_latex_args
6805 Additional arguments to give to latex, as a list. The default
6806 is an empty list.
6807 New in version 0.5.1.
6809 pngmath_latex_preamble
6811 Additional LaTeX code to put into the preamble of the short
6812 LaTeX files that are used to translate the math snippets. This
6813 is empty by default. Use it e.g. to add more packages whose
6814 commands you want to use in the math.
6815 pngmath_dvipng_args
6817 Additional arguments to give to dvipng, as a list. The default
6818 value is ['-gamma 1.5', '-D 110'] which makes the image a bit
6819 darker and larger then it is by default.
6820 An arguments you might want to add here is e.g. '-bg Transpar‐
6822 ent', which produces PNGs with a transparent background. This
6823 is not enabled by default because some Internet Explorer ver‐
6824 sions don't like transparent PNGs.
6825 Note When you "add" an argument, you need to reproduce the default
6827 arguments if you want to keep them; that is, like this:
6828 pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']
6830 pngmath_use_preview
6832 dvipng has the ability to determine the "depth" of the rendered
6833 text: for example, when typesetting a fraction inline, the base‐
6834 line of surrounding text should not be flush with the bottom of
6835 the image, rather the image should extend a bit below the base‐
6836 line. This is what TeX calls "depth". When this is enabled,
6837 the images put into the HTML document will get a vertical-align
6838 style that correctly aligns the baselines.
6839 Unfortunately, this only works when the preview-latex package is
6841 installed. Therefore, the default for this option is False.
6842 sphinx.ext.jsmath -- Render math via JavaScript
6844 This extension puts math as-is into the HTML files. The JavaScript
6845 package jsMath is then loaded and transforms the LaTeX markup to read‐
6846 able math live in the browser.
6847 Because jsMath (and the necessary fonts) is very large, it is not
6849 included in Sphinx. You must install it yourself, and give Sphinx its
6850 path in this config value:
6851 jsmath_path
6853 The path to the JavaScript file to include in the HTML files in
6854 order to load JSMath. There is no default.
6855 The path can be absolute or relative; if it is relative, it is
6857 relative to the _static directory of the built docs.
6858 For example, if you put JSMath into the static path of the
6860 Sphinx docs, this value would be jsMath/easy/load.js. If you
6861 host more than one Sphinx documentation set on one server, it is
6862 advisable to install jsMath in a shared location.
6863 sphinx.ext.graphviz -- Add Graphviz graphs
6865 New in version 0.6.
6866 This extension allows you to embed Graphviz graphs in your documents.
6868 It adds these directives:
6870 .. graphviz::
6872 Directive to embed graphviz code. The input code for dot is
6874 given as the content. For example:
6875 .. graphviz::
6877 digraph foo {
6879 "bar" -> "baz";
6880 }
6881 In HTML output, the code will be rendered to a PNG or SVG image
6883 (see graphviz_output_format). In LaTeX output, the code will be
6884 rendered to an embeddable PDF file.
6885 .. graph::
6887 Directive for embedding a single undirected graph. The name is
6889 given as a directive argument, the contents of the graph are the
6890 directive content. This is a convenience directive to generate
6891 graph <name> { <content> }.
6892 For example:
6894 .. graph:: foo
6896 "bar" -- "baz";
6898 .. digraph::
6900 Directive for embedding a single directed graph. The name is
6902 given as a directive argument, the contents of the graph are the
6903 directive content. This is a convenience directive to generate
6904 digraph <name> { <content> }.
6905 For example:
6907 .. digraph:: foo
6909 "bar" -> "baz" -> "quux";
6911 New in version 1.0: All three directives support an alt option that
6913 determines the image's alternate text for HTML output. If not given,
6914 the alternate text defaults to the graphviz code.
6915 There are also these new config values:
6917 graphviz_dot
6919 The command name with which to invoke dot. The default is
6920 'dot'; you may need to set this to a full path if dot is not in
6921 the executable search path.
6922 Since this setting is not portable from system to system, it is
6924 normally not useful to set it in conf.py; rather, giving it on
6925 the sphinx-build command line via the -D option should be
6926 preferable, like this:
6927 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
6929 graphviz_dot_args
6931 Additional command-line arguments to give to dot, as a list.
6932 The default is an empty list. This is the right place to set
6933 global graph, node or edge attributes via dot's -G, -N and -E
6934 options.
6935 graphviz_output_format
6937 The output format for Graphviz when building HTML files. This
6938 must be either 'png' or 'svg'; the default is 'png'.
6939 New in version 1.0: Previously, output always was PNG.
6941 sphinx.ext.inheritance_diagram -- Include inheritance diagrams
6943 New in version 0.6.
6944 This extension allows you to include inheritance diagrams, rendered via
6946 the Graphviz extension.
6947 It adds this directive:
6949 .. inheritance-diagram::
6951 This directive has one or more arguments, each giving a module
6953 or class name. Class names can be unqualified; in that case
6954 they are taken to exist in the currently described module (see
6955 py:module).
6956 For each given class, and each class in each given module, the
6958 base classes are determined. Then, from all classes and their
6959 base classes, a graph is generated which is then rendered via
6960 the graphviz extension to a directed graph.
6961 This directive supports an option called parts that, if given,
6963 must be an integer, advising the directive to remove that many
6964 parts of module names from the displayed names. (For example,
6965 if all your class names start with lib., you can give :parts: 1
6966 to remove that prefix from the displayed node names.)
6967 New config values are:
6969 inheritance_graph_attrs
6971 A dictionary of graphviz graph attributes for inheritance dia‐
6972 grams.
6973 For example:
6975 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
6977 fontsize=14, ratio='compress')
6978 inheritance_node_attrs
6980 A dictionary of graphviz node attributes for inheritance dia‐
6981 grams.
6982 For example:
6984 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
6986 color='dodgerblue1', style='filled')
6987 inheritance_edge_attrs
6989 A dictionary of graphviz edge attributes for inheritance dia‐
6990 grams.
6991 sphinx.ext.refcounting -- Keep track of reference counting behavior
6993 Todo
6994 Write this section.
6995 sphinx.ext.ifconfig -- Include content based on configuration
6997 This extension is quite simple, and features only one directive:
6998 .. ifconfig::
7000 Include content of the directive only if the Python expression
7002 given as an argument is True, evaluated in the namespace of the
7003 project's configuration (that is, all registered variables from
7004 conf.py are available).
7005 For example, one could write
7007 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
7009 This stuff is only included in the built docs for unstable versions.
7011 To make a custom config value known to Sphinx, use add_con‐
7013 fig_value() in the setup function in conf.py, e.g.:
7014 def setup(app):
7016 app.add_config_value('releaselevel', '', True)
7017 The second argument is the default value, the third should
7019 always be True for such values (it selects if Sphinx re-reads
7020 the documents if the value changes).
7021 sphinx.ext.coverage -- Collect doc coverage stats
7023 This extension features one additional builder, the CoverageBuilder.
7024 class sphinx.ext.coverage.CoverageBuilder
7026 To use this builder, activate the coverage extension in your
7028 configuration file and give -b coverage on the command line.
7029 Todo
7031 Write this section.
7032 Several new configuration values can be used to specify what the
7034 builder should check:
7035 coverage_ignore_modules
7037 coverage_ignore_functions
7039 coverage_ignore_classes
7041 coverage_c_path
7043 coverage_c_regexes
7045 coverage_ignore_c_items
7047 sphinx.ext.todo -- Support for todo items
7049 Module author: Daniel Bültmann
7050 New in version 0.5.
7052 There are two additional directives when using this extension:
7054 .. todo::
7056 Use this directive like, for example, note.
7058 It will only show up in the output if todo_include_todos is
7060 true.
7061 .. todolist::
7063 This directive is replaced by a list of all todo directives in
7065 the whole documentation, if todo_include_todos is true.
7066 There is also an additional config value:
7068 todo_include_todos
7070 If this is True, todo and todolist produce output, else they
7071 produce nothing. The default is False.
7072 sphinx.ext.extlinks -- Markup to shorten external links
7074 Module author: Georg Brandl
7075 New in version 1.0.
7077 This extension is meant to help with the common pattern of having many
7079 external links that point to URLs on one and the same site, e.g. links
7080 to bug trackers, version control web interfaces, or simply subpages in
7081 other websites. It does so by providing aliases to base URLs, so that
7082 you only need to give the subpage name when creating a link.
7083 Let's assume that you want to include many links to issues at the
7085 Sphinx tracker, at http://bitbucket.org/birkenfeld/sphinx/issue/num.
7086 Typing this URL again and again is tedious, so you can use extlinks to
7087 avoid repeating yourself.
7088 The extension adds one new config value:
7090 extlinks
7092 This config value must be a dictionary of external sites, map‐
7093 ping unique short alias names to a base URL and a prefix. For
7094 example, to create an alias for the above mentioned issues, you
7095 would add
7096 extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
7098 'issue ')}
7099 Now, you can use the alias name as a new role, e.g.
7101 :issue:`123`. This then inserts a link to
7102 http://bitbucket.org/birkenfeld/sphinx/issue/123. As you can
7103 see, the target given in the role is substituted in the base URL
7104 in the place of %s.
7105 The link caption depends on the second item in the tuple, the
7107 prefix:
7108 · If the prefix is None, the link caption is the full URL.
7110 · If the prefix is the empty string, the link caption is the
7112 partial URL given in the role content (123 in this case.)
7113 · If the prefix is a non-empty string, the link caption is the
7115 partial URL, prepended by the prefix -- in the above example,
7116 the link caption would be issue 123.
7117 You can also use the usual "explicit title" syntax supported by
7119 other roles that generate links, i.e. :issue:`this issue <123>`.
7120 In this case, the prefix is not relevant.
7121 Note Since links are generated from the role in the reading stage,
7123 they appear as ordinary links to e.g. the linkcheck builder.
7124 sphinx.ext.viewcode -- Add links to highlighted source code
7126 Module author: Georg Brandl
7127 New in version 1.0.
7129 This extension looks at your Python object descriptions (.. class::, ..
7131 function:: etc.) and tries to find the source files where the objects
7132 are contained. When found, a separate HTML page will be output for
7133 each module with a highlighted version of the source code, and a link
7134 will be added to all object descriptions that leads to the source code
7135 of the described object. A link back from the source to the descrip‐
7136 tion will also be inserted.
7137 There are currently no configuration values for this extension; you
7139 just need to add 'sphinx.ext.viewcode' to your extensions value for it
7140 to work.
7141 sphinx.ext.oldcmarkup -- Compatibility extension for old C markup
7143 Module author: Georg Brandl
7144 New in version 1.0.
7146 This extension is a transition helper for projects that used the old
7148 (pre-domain) C markup, i.e. the directives like cfunction and roles
7149 like cfunc. Since the introduction of domains, they must be called by
7150 their fully-qualified name (c:function and c:func, respectively) or,
7151 with the default domain set to c, by their new name (function and
7152 func). (See c-domain for the details.)
7153 If you activate this extension, it will register the old names, and you
7155 can use them like before Sphinx 1.0. The directives are:
7156 · cfunction
7158 · cmember
7160 · cmacro
7162 · ctype
7164 · cvar
7166 The roles are:
7168 · cdata
7170 · cfunc
7172 · cmacro
7174 · ctype
7176 However, it is advised to migrate to the new markup -- this extension
7178 is a compatibility convenience and will disappear in a future version
7179 of Sphinx.
7180 Third-party extensions
7182 You can find several extensions contributed by users in the Sphinx Con‐
7183 trib repository. It is open for anyone who wants to maintain an exten‐
7184 sion publicly; just send a short message asking for write permissions.
7185 There are also several extensions hosted elsewhere. The Wiki at Bit‐
7187 Bucket maintains a list of those.
7188 If you write an extension that you think others will find useful or you
7190 think should be included as a part of Sphinx, please write to the
7191 project mailing list (join here).
7192 Where to put your own extensions?
7194 Extensions local to a project should be put within the project's direc‐
7195 tory structure. Set Python's module search path, sys.path, accordingly
7196 so that Sphinx can find them. E.g., if your extension foo.py lies in
7197 the exts subdirectory of the project root, put into conf.py:
7198 import sys, os
7200 sys.path.append(os.path.abspath('exts'))
7202 extensions = ['foo']
7204 You can also install extensions anywhere else on sys.path, e.g. in the
7206 site-packages directory.
7207
7209 This is a list of Frequently Asked Questions about Sphinx. Feel free
7210 to suggest new entries!
7211 How do I...
7213 ... create PDF files without LaTeX?
7214 You can use rst2pdf version 0.12 or greater which comes with
7216 built-in Sphinx integration. See the builders section for
7217 details.
7218 ... get section numbers?
7220 They are automatic in LaTeX output; for HTML, give a :numbered:
7222 option to the toctree directive where you want to start number‐
7223 ing.
7224 ... customize the look of the built HTML files?
7226 Use themes, see theming.
7228 ... add global substitutions or includes?
7230 Add them in the rst_epilog config value.
7232 ... display the whole TOC tree in the sidebar?
7234 Use the toctree callable in a custom layout template, probably
7236 in the sidebartoc block.
7237 ... write my own extension?
7239 See the extension tutorial.
7241 ... convert from my existing docs using MoinMoin markup?
7243 The easiest way is to convert to xhtml, then convert xhtml to
7245 reST. You'll still need to mark up classes and such, but the
7246 headings and code examples come through cleanly.
7247 Using Sphinx with...
7249 Epydoc There's a third-party extension providing an api role which
7250 refers to Epydoc's API docs for a given identifier.
7251 Doxygen
7253 Michael Jones is developing a reST/Sphinx bridge to doxygen
7254 called breathe.
7255 SCons Glenn Hutchings has written a SCons build script to build Sphinx
7257 documentation; it is hosted here:
7258 http://bitbucket.org/zondo/sphinx-scons
7259 PyPI Jannis Leidel wrote a setuptools command that automatically
7261 uploads Sphinx documentation to the PyPI package documentation
7262 area at http://packages.python.org/.
7263 MediaWiki
7265 See http://bitbucket.org/kevindunn/sphinx-wiki, a project by
7266 Kevin Dunn.
7267 github pages
7269 You'll have to opt out of processing your pages with the
7270 "Jekyll" preprocessor as described in
7271 http://pages.github.com/#using_jekyll_for_complex_layouts.
7272 Google Analytics
7274 You can use a custom layout.html template, like this:
7275 {% extends "!layout.html" %}
7277 {%- block extrahead %}
7279 {{ super() }}
7280 <script type="text/javascript">
7281 var _gaq = _gaq || [];
7282 _gaq.push(['_setAccount', 'XXX account number XXX']);
7283 _gaq.push(['_trackPageview']);
7284 </script>
7285 {% endblock %}
7286 {% block footer %}
7288 {{ super() }}
7289 <div class="footer">This page uses <a href="http://analytics.google.com/">
7290 Google Analytics</a> to collect statistics. You can disable it by blocking
7291 the JavaScript coming from www.google-analytics.com.
7292 <script type="text/javascript">
7293 (function() {
7294 var ga = document.createElement('script');
7295 ga.src = ('https:' == document.location.protocol ?
7296 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
7297 ga.setAttribute('async', 'true');
7298 document.documentElement.firstChild.appendChild(ga);
7299 })();
7300 </script>
7301 </div>
7302 {% endblock %}
7303 Epub info
7305 The epub builder is currently in an experimental stage. It has only
7306 been tested with the Sphinx documentation itself. If you want to cre‐
7307 ate epubs, here are some notes:
7308 · Split the text into several files. The longer the individual HTML
7310 files are, the longer it takes the ebook reader to render them. In
7311 extreme cases, the rendering can take up to one minute.
7312 · Try to minimize the markup. This also pays in rendering time.
7314 · For some readers you can use embedded or external fonts using the CSS
7316 @font-face directive. This is extremely useful for code listings
7317 which are often cut at the right margin. The default Courier font
7318 (or variant) is quite wide and you can only display up to 60 charac‐
7319 ters on a line. If you replace it with a narrower font, you can get
7320 more characters on a line. You may even use FontForge and create
7321 narrow variants of some free font. In my case I get up to 70 charac‐
7322 ters on a line.
7323 You may have to experiment a little until you get reasonable results.
7325 · Test the created epubs. You can use several alternatives. The ones I
7327 am aware of are Epubcheck, Calibre, FBreader (although it does not
7328 render the CSS), and Bookworm. For bookworm you can download the
7329 source from http://code.google.com/p/threepress/ and run your own
7330 local server.
7331 · Large floating divs are not displayed properly. If they cover more
7333 than one page, the div is only shown on the first page. In that case
7334 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
7335 tory to your local _static/ directory and remove the float settings.
7336 · Files that are inserted outside of the toctree directive must be man‐
7338 ually included. This sometimes applies to appendixes, e.g. the glos‐
7339 sary or the indices. You can add them with the epub_post_files
7340 option.
7341
7343 builder
7344 A class (inheriting from Builder) that takes parsed documents
7345 and performs an action on them. Normally, builders translate
7346 the documents to an output format, but it is also possible to
7347 use the builder builders that e.g. check for broken links in the
7348 documentation, or build coverage information.
7349 See builders for an overview over Sphinx' built-in builders.
7351 configuration directory
7353 The directory containing conf.py. By default, this is the same
7354 as the source directory, but can be set differently with the -c
7355 command-line option.
7356 directive
7358 A reStructuredText markup element that allows marking a block of
7359 content with special meaning. Directives are supplied not only
7360 by docutils, but Sphinx and custom extensions can add their own.
7361 The basic directive syntax looks like this:
7362 .. directivename:: argument ...
7364 :option: value
7365 Content of the directive.
7367 See directives for more information.
7369 document name
7371 Since reST source files can have different extensions (some peo‐
7372 ple like .txt, some like .rst -- the extension can be configured
7373 with source_suffix) and different OSes have different path sepa‐
7374 rators, Sphinx abstracts them: document names are always rela‐
7375 tive to the source directory, the extension is stripped, and
7376 path separators are converted to slashes. All values, parame‐
7377 ters and such referring to "documents" expect such document
7378 names.
7379 Examples for document names are index, library/zipfile, or ref‐
7381 erence/datamodel/types. Note that there is no leading or trail‐
7382 ing slash.
7383 domain A domain is a collection of markup (reStructuredText directives
7385 and roles) to describe and link to objects belonging together,
7386 e.g. elements of a programming language. Directive and role
7387 names in a domain have names like domain:name, e.g. py:function.
7388 Having domains means that there are no naming problems when one
7390 set of documentation wants to refer to e.g. C++ and Python
7391 classes. It also means that extensions that support the docu‐
7392 mentation of whole new languages are much easier to write. For
7393 more information about domains, see the chapter domains.
7394 environment
7396 A structure where information about all documents under the root
7397 is saved, and used for cross-referencing. The environment is
7398 pickled after the parsing stage, so that successive runs only
7399 need to read and parse new and changed documents.
7400 master document
7402 The document that contains the root toctree directive.
7403 object The basic building block of Sphinx documentation. Every "object
7405 directive" (e.g. function or object) creates such a block; and
7406 most objects can be cross-referenced to.
7407 role A reStructuredText markup element that allows marking a piece of
7409 text. Like directives, roles are extensible. The basic syntax
7410 looks like this: :rolename:`content`. See inlinemarkup for
7411 details.
7412 source directory
7414 The directory which, including its subdirectories, contains all
7415 source files for one Sphinx project.
7416
7418 Release 1.0.7 (Jan 15, 2011)
7419 · #347: Fix wrong generation of directives of static methods in auto‐
7420 summary.
7421 · #599: Import PIL as from PIL import Image.
7423 · #558: Fix longtables with captions in LaTeX output.
7425 · Make token references work as hyperlinks again in LaTeX output.
7427 · #572: Show warnings by default when reference labels cannot be found.
7429 · #536: Include line number when complaining about missing reference
7431 targets in nitpicky mode.
7432 · #590: Fix inline display of graphviz diagrams in LaTeX output.
7434 · #589: Build using app.build() in setup command.
7436 · Fix a bug in the inheritance diagram exception that caused base
7438 classes to be skipped if one of them is a builtin.
7439 · Fix general index links for C++ domain objects.
7441 · #332: Make admonition boundaries in LaTeX output visible.
7443 · #573: Fix KeyErrors occurring on rebuild after removing a file.
7445 · Fix a traceback when removing files with globbed toctrees.
7447 · If an autodoc object cannot be imported, always re-read the document
7449 containing the directive on next build.
7450 · If an autodoc object cannot be imported, show the full traceback of
7452 the import error.
7453 · Fix a bug where the removal of download files and images wasn't
7455 noticed.
7456 · #571: Implement ~ cross-reference prefix for the C domain.
7458 · Fix regression of LaTeX output with the fix of #556.
7460 · #568: Fix lookup of class attribute documentation on descriptors so
7462 that comment documentation now works.
7463 · Fix traceback with only directives preceded by targets.
7465 · Fix tracebacks occurring for duplicate C++ domain objects.
7467 · Fix JavaScript domain links to objects with $ in their name.
7469 Release 1.0.6 (Jan 04, 2011)
7471 · #581: Fix traceback in Python domain for empty cross-reference tar‐
7472 gets.
7473 · #283: Fix literal block display issues on Chrome browsers.
7475 · #383, #148: Support sorting a limited range of accented characters in
7477 the general index and the glossary.
7478 · #570: Try decoding -D and -A command-line arguments with the locale's
7480 preferred encoding.
7481 · #528: Observe locale_dirs when looking for the JS translations file.
7483 · #574: Add special code for better support of Japanese documents in
7485 the LaTeX builder.
7486 · Regression of #77: If there is only one parameter given with :param:
7488 markup, the bullet list is now suppressed again.
7489 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
7491 tions.
7492 · #567: Emit the autodoc-process-docstring event even for objects with‐
7494 out a docstring so that it can add content.
7495 · #565: In the LaTeX builder, not only literal blocks require different
7497 table handling, but also quite a few other list-like block elements.
7498 · #515: Fix tracebacks in the viewcode extension for Python objects
7500 that do not have a valid signature.
7501 · Fix strange reportings of line numbers for warnings generated from
7503 autodoc-included docstrings, due to different behavior depending on
7504 docutils version.
7505 · Several fixes to the C++ domain.
7507 Release 1.0.5 (Nov 12, 2010)
7509 · #557: Add CSS styles required by docutils 0.7 for aligned images and
7510 figures.
7511 · In the Makefile generated by LaTeX output, do not delete pdf files on
7513 clean; they might be required images.
7514 · #535: Fix LaTeX output generated for line blocks.
7516 · #544: Allow .pyw as a source file extension.
7518 Release 1.0.4 (Sep 17, 2010)
7520 · #524: Open intersphinx inventories in binary mode on Windows, since
7521 version 2 contains zlib-compressed data.
7522 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
7524 JSMath extension.
7525 · #512: Fix traceback when intersphinx_mapping is empty.
7527 Release 1.0.3 (Aug 23, 2010)
7529 · #495: Fix internal vs. external link distinction for links coming
7530 from a docutils table-of-contents.
7531 · #494: Fix the maxdepth option for the toctree() template callable
7533 when used with collapse=True.
7534 · #507: Fix crash parsing Python argument lists containing brackets in
7536 string literals.
7537 · #501: Fix regression when building LaTeX docs with figures that don't
7539 have captions.
7540 · #510: Fix inheritance diagrams for classes that are not picklable.
7542 · #497: Introduce separate background color for the sidebar collapse
7544 button, making it easier to see.
7545 · #502, #503, #496: Fix small layout bugs in several builtin themes.
7547 Release 1.0.2 (Aug 14, 2010)
7549 · #490: Fix cross-references to objects of types added by the
7550 add_object_type() API function.
7551 · Fix handling of doc field types for different directive types.
7553 · Allow breaking long signatures, continuing with backlash-escaped new‐
7555 lines.
7556 · Fix unwanted styling of C domain references (because of a namespace
7558 clash with Pygments styles).
7559 · Allow references to PEPs and RFCs with explicit anchors.
7561 · #471: Fix LaTeX references to figures.
7563 · #482: When doing a non-exact search, match only the given type of
7565 object.
7566 · #481: Apply non-exact search for Python reference targets with .name
7568 for modules too.
7569 · #484: Fix crash when duplicating a parameter in an info field list.
7571 · #487: Fix setting the default role to one provided by the oldcmarkup
7573 extension.
7574 · #488: Fix crash when json-py is installed, which provides a json mod‐
7576 ule but is incompatible to simplejson.
7577 · #480: Fix handling of target naming in intersphinx.
7579 · #486: Fix removal of ! for all cross-reference roles.
7581 Release 1.0.1 (Jul 27, 2010)
7583 · #470: Fix generated target names for reST domain objects; they are
7584 not in the same namespace.
7585 · #266: Add Bengali language.
7587 · #473: Fix a bug in parsing JavaScript object names.
7589 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
7591 · Fix display names for objects linked to by intersphinx with explicit
7593 targets.
7594 · Fix building with the JSON builder.
7596 · Fix hyperrefs in object descriptions for LaTeX.
7598 Release 1.0 (Jul 23, 2010)
7600 Incompatible changes
7601 · Support for domains has been added. A domain is a collection of
7602 directives and roles that all describe objects belonging together,
7603 e.g. elements of a programming language. A few builtin domains are
7604 provided:
7605 · Python
7607 · C
7609 · C++
7611 · JavaScript
7613 · reStructuredText
7615 · The old markup for defining and linking to C directives is now depre‐
7617 cated. It will not work anymore in future versions without activat‐
7618 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
7619 default.
7620 · Removed support for old dependency versions; requirements are now:
7622 · docutils >= 0.5
7624 · Jinja2 >= 2.2
7626 · Removed deprecated elements:
7628 · exclude_dirs config value
7630 · sphinx.builder module
7632 Features added
7634 · General:
7635 · Added a "nitpicky" mode that emits warnings for all missing refer‐
7637 ences. It is activated by the -n command-line switch or the nit‐
7638 picky config value.
7639 · Added latexpdf target in quickstart Makefile.
7641 · Markup:
7643 · The menuselection and guilabel roles now support ampersand acceler‐
7645 ators.
7646 · New more compact doc field syntax is now recognized: :param type
7648 name: description.
7649 · Added tab-width option to literalinclude directive.
7651 · Added titlesonly option to toctree directive.
7653 · Added the prepend and append options to the literalinclude direc‐
7655 tive.
7656 · #284: All docinfo metadata is now put into the document metadata,
7658 not just the author.
7659 · The ref role can now also reference tables by caption.
7661 · The include directive now supports absolute paths, which are inter‐
7663 preted as relative to the source directory.
7664 · In the Python domain, references like :func:`.name` now look for
7666 matching names with any prefix if no direct match is found.
7667 · Configuration:
7669 · Added rst_prolog config value.
7671 · Added html_secnumber_suffix config value to control section number‐
7673 ing format.
7674 · Added html_compact_lists config value to control docutils' compact
7676 lists feature.
7677 · The html_sidebars config value can now contain patterns as keys,
7679 and the values can be lists that explicitly select which sidebar
7680 templates should be rendered. That means that the builtin sidebar
7681 contents can be included only selectively.
7682 · html_static_path can now contain single file entries.
7684 · The new universal config value exclude_patterns makes the old
7686 unused_docs, exclude_trees and exclude_dirnames obsolete.
7687 · Added html_output_encoding config value.
7689 · Added the latex_docclass config value and made the "twoside" docu‐
7691 mentclass option overridable by "oneside".
7692 · Added the trim_doctest_flags config value, which is true by
7694 default.
7695 · Added html_show_copyright config value.
7697 · Added latex_show_pagerefs and latex_show_urls config values.
7699 · The behavior of html_file_suffix changed slightly: the empty string
7701 now means "no suffix" instead of "default suffix", use None for
7702 "default suffix".
7703 · New builders:
7705 · Added a builder for the Epub format.
7707 · Added a builder for manual pages.
7709 · Added a single-file HTML builder.
7711 · HTML output:
7713 · Inline roles now get a CSS class with their name, allowing styles
7715 to customize their appearance. Domain-specific roles get two
7716 classes, domain and domain-rolename.
7717 · References now get the class internal if they are internal to the
7719 whole project, as opposed to internal to the current page.
7720 · External references can be styled differently with the new exter‐
7722 nalrefs theme option for the default theme.
7723 · In the default theme, the sidebar can experimentally now be made
7725 collapsible using the new collapsiblesidebar theme option.
7726 · #129: Toctrees are now wrapped in a div tag with class toc‐
7728 tree-wrapper in HTML output.
7729 · The toctree callable in templates now has a maxdepth keyword argu‐
7731 ment to control the depth of the generated tree.
7732 · The toctree callable in templates now accepts a titles_only keyword
7734 argument.
7735 · Added htmltitle block in layout template.
7737 · In the JavaScript search, allow searching for object names includ‐
7739 ing the module name, like sys.argv.
7740 · Added new theme haiku, inspired by the Haiku OS user guide.
7742 · Added new theme nature.
7744 · Added new theme agogo, created by Andi Albrecht.
7746 · Added new theme scrolls, created by Armin Ronacher.
7748 · #193: Added a visitedlinkcolor theme option to the default theme.
7750 · #322: Improved responsiveness of the search page by loading the
7752 search index asynchronously.
7753 · Extension API:
7755 · Added html-collect-pages.
7757 · Added needs_sphinx config value and require_sphinx() application
7759 API method.
7760 · #200: Added add_stylesheet() application API method.
7762 · Extensions:
7764 · Added the viewcode extension.
7766 · Added the extlinks extension.
7768 · Added support for source ordering of members in autodoc, with
7770 autodoc_member_order = 'bysource'.
7771 · Added autodoc_default_flags config value, which can be used to
7773 select default flags for all autodoc directives.
7774 · Added a way for intersphinx to refer to named labels in other
7776 projects, and to specify the project you want to link to.
7777 · #280: Autodoc can now document instance attributes assigned in
7779 __init__ methods.
7780 · Many improvements and fixes to the autosummary extension, thanks to
7782 Pauli Virtanen.
7783 · #309: The graphviz extension can now output SVG instead of PNG
7785 images, controlled by the graphviz_output_format config value.
7786 · Added alt option to graphviz extension directives.
7788 · Added exclude argument to autodoc.between().
7790 · Translations:
7792 · Added Croatian translation, thanks to Bojan Mihelač.
7794 · Added Turkish translation, thanks to Firat Ozgul.
7796 · Added Catalan translation, thanks to Pau Fernández.
7798 · Added simplified Chinese translation.
7800 · Added Danish translation, thanks to Hjorth Larsen.
7802 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
7804 · Bugs fixed:
7806 · #445: Fix links to result pages when using the search function of
7808 HTML built with the dirhtml builder.
7809 · #444: In templates, properly re-escape values treated with the
7811 "striptags" Jinja filter.
7812 Release 0.6.7 (Jun 05, 2010)
7814 · #440: Remove usage of a Python >= 2.5 API in the literalinclude
7815 directive.
7816 · Fix a bug that prevented some references being generated in the LaTeX
7818 builder.
7819 · #428: Add some missing CSS styles for standard docutils classes.
7821 · #432: Fix UnicodeErrors while building LaTeX in translated locale.
7823 Release 0.6.6 (May 25, 2010)
7825 · Handle raw nodes in the text writer.
7826 · Fix a problem the Qt help project generated by the qthelp builder
7828 that would lead to no content being displayed in the Qt Assistant.
7829 · #393: Fix the usage of Unicode characters in mathematic formulas when
7831 using the pngmath extension.
7832 · #404: Make \and work properly in the author field of the latex_docu‐
7834 ments setting.
7835 · #409: Make the highlight_language config value work properly in the
7837 LaTeX builder.
7838 · #418: Allow relocation of the translation JavaScript files to the
7840 system directory on Unix systems.
7841 · #414: Fix handling of Windows newlines in files included with the
7843 literalinclude directive.
7844 · #377: Fix crash in linkcheck builder.
7846 · #387: Fix the display of search results in dirhtml output.
7848 · #376: In autodoc, fix display of parameter defaults containing back‐
7850 slashes.
7851 · #370: Fix handling of complex list item labels in LaTeX output.
7853 · #374: Make the doctest_path config value of the doctest extension
7855 actually work.
7856 · Fix the handling of multiple toctrees when creating the global TOC
7858 for the toctree() template function.
7859 · Fix the handling of hidden toctrees when creating the global TOC for
7861 the toctree() template function.
7862 · Fix the handling of nested lists in the text writer.
7864 · #362: In autodoc, check for the existence of __self__ on function
7866 objects before accessing it.
7867 · #353: Strip leading and trailing whitespace when extracting search
7869 words in the search function.
7870 Release 0.6.5 (Mar 01, 2010)
7872 · In autodoc, fix the omission of some module members explicitly docu‐
7873 mented using documentation comments.
7874 · #345: Fix cropping of sidebar scroll bar with stickysidebar option of
7876 the default theme.
7877 · #341: Always generate UNIX newlines in the quickstart Makefile.
7879 · #338: Fix running with -C under Windows.
7881 · In autodoc, allow customizing the signature of an object where the
7883 built-in mechanism fails.
7884 · #331: Fix output for enumerated lists with start values in LaTeX.
7886 · Make the start-after and end-before options to the literalinclude
7888 directive work correctly if not used together.
7889 · #321: Fix link generation in the LaTeX builder.
7891 Release 0.6.4 (Jan 12, 2010)
7893 · Improve the handling of non-Unicode strings in the configuration.
7894 · #316: Catch OSErrors occurring when calling graphviz with arguments
7896 it doesn't understand.
7897 · Restore compatibility with Pygments >= 1.2.
7899 · #295: Fix escaping of hyperref targets in LaTeX output.
7901 · #302: Fix links generated by the :doc: role for LaTeX output.
7903 · #286: collect todo nodes after the whole document has been read; this
7905 allows placing substitution references in todo items.
7906 · #294: do not ignore an explicit today config value in a LaTeX build.
7908 · The alt text of inheritance diagrams is now much cleaner.
7910 · Ignore images in section titles when generating link captions.
7912 · #310: support exception messages in the testoutput blocks of the
7914 doctest extension.
7915 · #293: line blocks are styled properly in HTML output.
7917 · #285: make the locale_dirs config value work again.
7919 · #303: html_context values given on the command line via -A should not
7921 override other values given in conf.py.
7922 · Fix a bug preventing incremental rebuilds for the dirhtml builder.
7924 · #299: Fix the mangling of quotes in some literal blocks.
7926 · #292: Fix path to the search index for the dirhtml builder.
7928 · Fix a Jython compatibility issue: make the dependence on the parser
7930 module optional.
7931 · #238: In autodoc, catch all errors that occur on module import, not
7933 just ImportError.
7934 · Fix the handling of non-data, but non-method descriptors in autodoc.
7936 · When copying file times, ignore OSErrors raised by os.utime().
7938 Release 0.6.3 (Sep 03, 2009)
7940 · Properly add C module filenames as dependencies in autodoc.
7941 · #253: Ignore graphviz directives without content instead of raising
7943 an unhandled exception.
7944 · #241: Fix a crash building LaTeX output for documents that contain a
7946 todolist directive.
7947 · #252: Make it easier to change the build dir in the Makefiles gener‐
7949 ated by quickstart.
7950 · #220: Fix CSS so that displaymath really is centered.
7952 · #222: Allow the "Footnotes" header to be translated.
7954 · #225: Don't add whitespace in generated HTML after inline tags.
7956 · #227: Make literalinclude work when the document's path name contains
7958 non-ASCII characters.
7959 · #229: Fix autodoc failures with members that raise errors on
7961 getattr().
7962 · #205: When copying files, don't copy full stat info, only modifica‐
7964 tion times.
7965 · #232: Support non-ASCII metadata in Qt help builder.
7967 · Properly format bullet lists nested in definition lists for LaTeX.
7969 · Section titles are now allowed inside only directives.
7971 · #201: Make centered directive work in LaTeX output.
7973 · #206: Refuse to overwrite an existing master document in
7975 sphinx-quickstart.
7976 · #208: Use MS-sanctioned locale settings, determined by the language
7978 config option, in the HTML help builder.
7979 · #210: Fix nesting of HTML tags for displayed math from pngmath exten‐
7981 sion.
7982 · #213: Fix centering of images in LaTeX output.
7984 · #211: Fix compatibility with docutils 0.5.
7986 Release 0.6.2 (Jun 16, 2009)
7988 · #130: Fix obscure IndexError in doctest extension.
7989 · #167: Make glossary sorting case-independent.
7991 · #196: Add a warning if an extension module doesn't have a setup()
7993 function.
7994 · #158: Allow '..' in template names, and absolute template paths;
7996 Jinja 2 by default disables both.
7997 · When highlighting Python code, ignore extra indentation before trying
7999 to parse it as Python.
8000 · #191: Don't escape the tilde in URIs in LaTeX.
8002 · Don't consider contents of source comments for the search index.
8004 · Set the default encoding to utf-8-sig to handle files with a UTF-8
8006 BOM correctly.
8007 · #178: apply add_function_parentheses config value to C functions as
8009 promised.
8010 · #173: Respect the docutils title directive.
8012 · #172: The obj role now links to modules as promised.
8014 · #19: Tables now can have a "longtable" class, in order to get cor‐
8016 rectly broken into pages in LaTeX output.
8017 · Look for Sphinx message catalogs in the system default path before
8019 trying sphinx/locale.
8020 · Fix the search for methods via "classname.methodname".
8022 · #155: Fix Python 2.4 compatibility: exceptions are old-style classes
8024 there.
8025 · #150: Fix display of the "sphinxdoc" theme on Internet Explorer ver‐
8027 sions 6 and 7.
8028 · #146: Don't fail to generate LaTeX when the user has an active .docu‐
8030 tils configuration.
8031 · #29: Don't generate visible "-{-}" in option lists in LaTeX.
8033 · Fix cross-reference roles when put into substitutions.
8035 · Don't put image "alt" text into table-of-contents entries.
8037 · In the LaTeX writer, do not raise an exception on too many section
8039 levels, just use the "subparagraph" level for all of them.
8040 · #145: Fix autodoc problem with automatic members that refuse to be
8042 getattr()'d from their parent.
8043 · If specific filenames to build are given on the command line, check
8045 that they are within the source directory.
8046 · Fix autodoc crash for objects without a __name__.
8048 · Fix intersphinx for installations without urllib2.HTTPSHandler.
8050 · #134: Fix pending_xref leftover nodes when using the todolist direc‐
8052 tive from the todo extension.
8053 Release 0.6.1 (Mar 26, 2009)
8055 · #135: Fix problems with LaTeX output and the graphviz extension.
8056 · #132: Include the autosummary "module" template in the distribution.
8058 Release 0.6 (Mar 24, 2009)
8060 New features added
8061 · Incompatible changes:
8062 · Templating now requires the Jinja2 library, which is an enhanced
8064 version of the old Jinja1 engine. Since the syntax and semantic is
8065 largely the same, very few fixes should be necessary in custom tem‐
8066 plates.
8067 · The "document" div tag has been moved out of the layout.html tem‐
8069 plate's "document" block, because the closing tag was already out‐
8070 side. If you overwrite this block, you need to remove your "docu‐
8071 ment" div tag as well.
8072 · The autodoc_skip_member event now also gets to decide whether to
8074 skip members whose name starts with underscores. Previously, these
8075 members were always automatically skipped. Therefore, if you han‐
8076 dle this event, add something like this to your event handler to
8077 restore the old behavior:
8078 if name.startswith('_'):
8080 return True
8081 · Theming support, see the new section in the documentation.
8083 · Markup:
8085 · Due to popular demand, added a :doc: role which directly links to
8087 another document without the need of creating a label to which a
8088 :ref: could link to.
8089 · #4: Added a :download: role that marks a non-document file for
8091 inclusion into the HTML output and links to it.
8092 · Added an only directive that can selectively include text based on
8094 enabled "tags". Tags can be given on the command line. Also, the
8095 current builder output format (e.g. "html" or "latex") is always a
8096 defined tag.
8097 · #10: Added HTML section numbers, enabled by giving a :numbered:
8099 flag to the toctree directive.
8100 · #114: Added an abbr role to markup abbreviations and acronyms.
8102 · The literalinclude directive now supports several more options, to
8104 include only parts of a file.
8105 · The toctree directive now supports a :hidden: flag, which will pre‐
8107 vent links from being generated in place of the directive -- this
8108 allows you to define your document structure, but place the links
8109 yourself.
8110 · #123: The glossary directive now supports a :sorted: flag that
8112 sorts glossary entries alphabetically.
8113 · Paths to images, literal include files and download files can now
8115 be absolute (like /images/foo.png). They are treated as relative
8116 to the top source directory.
8117 · #52: There is now a hlist directive, creating a compact list by
8119 placing distributing items into multiple columns.
8120 · #77: If a description environment with info field list only con‐
8122 tains one :param: entry, no bullet list is generated.
8123 · #6: Don't generate redundant <ul> for top-level TOC tree items,
8125 which leads to a visual separation of TOC entries.
8126 · #23: Added a classmethod directive along with method and stat‐
8128 icmethod.
8129 · Scaled images now get a link to the unscaled version.
8131 · SVG images are now supported in HTML (via <object> and <embed>
8133 tags).
8134 · Added a toctree callable to the templates, and the ability to
8136 include external links in toctrees. The 'collapse' keyword argument
8137 indicates whether or not to only display subitems of the current
8138 page. (Defaults to True.)
8139 · Configuration:
8141 · The new config value rst_epilog can contain reST that is appended
8143 to each source file that is read. This is the right place for
8144 global substitutions.
8145 · The new html_add_permalinks config value can be used to switch off
8147 the generated "paragraph sign" permalinks for each heading and def‐
8148 inition environment.
8149 · The new html_show_sourcelink config value can be used to switch off
8151 the links to the reST sources in the sidebar.
8152 · The default value for htmlhelp_basename is now the project title,
8154 cleaned up as a filename.
8155 · The new modindex_common_prefix config value can be used to ignore
8157 certain package names for module index sorting.
8158 · The new trim_footnote_reference_space config value mirrors the
8160 docutils config value of the same name and removes the space before
8161 a footnote reference that is necessary for reST to recognize the
8162 reference.
8163 · The new latex_additional_files config value can be used to copy
8165 files (that Sphinx doesn't copy automatically, e.g. if they are
8166 referenced in custom LaTeX added in latex_elements) to the build
8167 directory.
8168 · Builders:
8170 · The HTML builder now stores a small file named .buildinfo in its
8172 output directory. It stores a hash of config values that can be
8173 used to determine if a full rebuild needs to be done (e.g. after
8174 changing html_theme).
8175 · New builder for Qt help collections, by Antonio Valentino.
8177 · The new DirectoryHTMLBuilder (short name dirhtml) creates a sepa‐
8179 rate directory for every page, and places the page there in a file
8180 called index.html. Therefore, page URLs and links don't need to
8181 contain .html.
8182 · The new html_link_suffix config value can be used to select the
8184 suffix of generated links between HTML files.
8185 · #96: The LaTeX builder now supports figures wrapped by text, when
8187 using the figwidth option and right/left alignment.
8188 · New translations:
8190 · Italian by Sandro Dentella.
8192 · Ukrainian by Petro Sasnyk.
8194 · Finnish by Jukka Inkeri.
8196 · Russian by Alexander Smishlajev.
8198 · Extensions and API:
8200 · New graphviz extension to embed graphviz graphs.
8202 · New inheritance_diagram extension to embed... inheritance diagrams!
8204 · New autosummary extension that generates summaries of modules and
8206 automatic documentation of modules.
8207 · Autodoc now has a reusable Python API, which can be used to create
8209 custom types of objects to auto-document (e.g. Zope interfaces).
8210 See also Sphinx.add_autodocumenter().
8211 · Autodoc now handles documented attributes.
8213 · Autodoc now handles inner classes and their methods.
8215 · Autodoc can document classes as functions now if explicitly marked
8217 with autofunction.
8218 · Autodoc can now exclude single members from documentation via the
8220 exclude-members option.
8221 · Autodoc can now order members either alphabetically (like previ‐
8223 ously) or by member type; configurable either with the config value
8224 autodoc_member_order or a member-order option per directive.
8225 · The function Sphinx.add_directive() now also supports docutils
8227 0.5-style directive classes. If they inherit from sphinx.util.com‐
8228 pat.Directive, they also work with docutils 0.4.
8229 · There is now a Sphinx.add_lexer() method to be able to use custom
8231 Pygments lexers easily.
8232 · There is now Sphinx.add_generic_role() to mirror the docutils' own
8234 function.
8235 · Other changes:
8237 · Config overrides for single dict keys can now be given on the com‐
8239 mand line.
8240 · There is now a doctest_global_setup config value that can be used
8242 to give setup code for all doctests in the documentation.
8243 · Source links in HTML are now generated with rel="nofollow".
8245 · Quickstart can now generate a Windows make.bat file.
8247 · #62: There is now a -w option for sphinx-build that writes warnings
8249 to a file, in addition to stderr.
8250 · There is now a -W option for sphinx-build that turns warnings into
8252 errors.
8253 Release 0.5.2 (Mar 24, 2009)
8255 · Properly escape | in LaTeX output.
8256 · #71: If a decoding error occurs in source files, print a warning and
8258 replace the characters by "?".
8259 · Fix a problem in the HTML search if the index takes too long to load.
8261 · Don't output system messages while resolving, because they would stay
8263 in the doctrees even if keep_warnings is false.
8264 · #82: Determine the correct path for dependencies noted by docutils.
8266 This fixes behavior where a source with dependent files was always
8267 reported as changed.
8268 · Recognize toctree directives that are not on section toplevel, but
8270 within block items, such as tables.
8271 · Use a new RFC base URL, since rfc.org seems down.
8273 · Fix a crash in the todolist directive when no todo items are defined.
8275 · Don't call LaTeX or dvipng over and over again if it was not found
8277 once, and use text-only latex as a substitute in that case.
8278 · Fix problems with footnotes in the LaTeX output.
8280 · Prevent double hyphens becoming en-dashes in literal code in the
8282 LaTeX output.
8283 · Open literalinclude files in universal newline mode to allow arbi‐
8285 trary newline conventions.
8286 · Actually make the -Q option work.
8288 · #86: Fix explicit document titles in toctrees.
8290 · #81: Write environment and search index in a manner that is safe from
8292 exceptions that occur during dumping.
8293 · #80: Fix UnicodeErrors when a locale is set with setlocale().
8295 Release 0.5.1 (Dec 15, 2008)
8297 · #67: Output warnings about failed doctests in the doctest extension
8298 even when running in quiet mode.
8299 · #72: In pngmath, make it possible to give a full path to LaTeX and
8301 dvipng on Windows. For that to work, the pngmath_latex and png‐
8302 math_dvipng options are no longer split into command and additional
8303 arguments; use pngmath_latex_args and pngmath_dvipng_args to give
8304 additional arguments.
8305 · Don't crash on failing doctests with non-ASCII characters.
8307 · Don't crash on writing status messages and warnings containing unen‐
8309 codable characters.
8310 · Warn if a doctest extension block doesn't contain any code.
8312 · Fix the handling of :param: and :type: doc fields when they contain
8314 markup (especially cross-referencing roles).
8315 · #65: Fix storage of depth information for PNGs generated by the png‐
8317 math extension.
8318 · Fix autodoc crash when automethod is used outside a class context.
8320 · #68: Fix LaTeX writer output for images with specified height.
8322 · #60: Fix wrong generated image path when including images in sources
8324 in subdirectories.
8325 · Fix the JavaScript search when html_copy_source is off.
8327 · Fix an indentation problem in autodoc when documenting classes with
8329 the option autoclass_content = "both" set.
8330 · Don't crash on empty index entries, only emit a warning.
8332 · Fix a typo in the search JavaScript code, leading to unusable search
8334 function in some setups.
8335 Release 0.5 (Nov 23, 2008) -- Birthday release!
8337 New features added
8338 · Markup features:
8339 · Citations are now global: all citation defined in any file can be
8341 referenced from any file. Citations are collected in a bibliogra‐
8342 phy for LaTeX output.
8343 · Footnotes are now properly handled in the LaTeX builder: they
8345 appear at the location of the footnote reference in text, not at
8346 the end of a section. Thanks to Andrew McNamara for the initial
8347 patch.
8348 · "System Message" warnings are now automatically removed from the
8350 built documentation, and only written to stderr. If you want the
8351 old behavior, set the new config value keep_warnings to True.
8352 · Glossary entries are now automatically added to the index.
8354 · Figures with captions can now be referred to like section titles,
8356 using the :ref: role without an explicit link text.
8357 · Added cmember role for consistency.
8359 · Lists enumerated by letters or roman numerals are now handled like
8361 in standard reST.
8362 · The seealso directive can now also be given arguments, as a short
8364 form.
8365 · You can now document several programs and their options with the
8367 new program directive.
8368 · HTML output and templates:
8370 · Incompatible change: The "root" relation link (top left in the rel‐
8372 bar) now points to the master_doc by default, no longer to a docu‐
8373 ment called "index". The old behavior, while useful in some situa‐
8374 tions, was somewhat unexpected. Override the "rootrellink" block
8375 in the template to customize where it refers to.
8376 · The JavaScript search now searches for objects before searching in
8378 the full text.
8379 · TOC tree entries now have CSS classes that make it possible to
8381 style them depending on their depth.
8382 · Highlighted code blocks now have CSS classes that make it possible
8384 to style them depending on their language.
8385 · HTML <meta> tags via the docutils meta directive are now supported.
8387 · SerializingHTMLBuilder was added as new abstract builder that can
8389 be subclassed to serialize build HTML in a specific format. The
8390 PickleHTMLBuilder is a concrete subclass of it that uses pickle as
8391 serialization implementation.
8392 · JSONHTMLBuilder was added as another SerializingHTMLBuilder sub‐
8394 class that dumps the generated HTML into JSON files for further
8395 processing.
8396 · The rellinks block in the layout template is now called linktags to
8398 avoid confusion with the relbar links.
8399 · The HTML builders have two additional attributes now that can be
8401 used to disable the anchor-link creation after headlines and defi‐
8402 nition links.
8403 · Only generate a module index if there are some modules in the docu‐
8405 mentation.
8406 · New and changed config values:
8408 · Added support for internationalization in generated text with the
8410 language and locale_dirs config values. Many thanks to language
8411 contributors:
8412 · Horst Gutmann -- German
8414 · Pavel Kosina -- Czech
8416 · David Larlet -- French
8418 · Michał Kandulski -- Polish
8420 · Yasushi Masuda -- Japanese
8422 · Guillem Borrell -- Spanish
8424 · Luc Saffre and Peter Bertels -- Dutch
8426 · Fred Lin -- Traditional Chinese
8428 · Roger Demetrescu -- Brazilian Portuguese
8430 · Rok Garbas -- Slovenian
8432 · The new config value highlight_language set a global default for
8434 highlighting. When 'python3' is selected, console output blocks
8435 are recognized like for 'python'.
8436 · Exposed Pygments' lexer guessing as a highlight "language" guess.
8438 · The new config value latex_elements allows to override all LaTeX
8440 snippets that Sphinx puts into the generated .tex file by default.
8441 · Added exclude_dirnames config value that can be used to exclude
8443 e.g. CVS directories from source file search.
8444 · Added source_encoding config value to select input encoding.
8446 · Extensions:
8448 · The new extensions sphinx.ext.jsmath and sphinx.ext.pngmath provide
8450 math support for both HTML and LaTeX builders.
8451 · The new extension sphinx.ext.intersphinx half-automatically creates
8453 links to Sphinx documentation of Python objects in other projects.
8454 · The new extension sphinx.ext.todo allows the insertion of "To do"
8456 directives whose visibility in the output can be toggled. It also
8457 adds a directive to compile a list of all todo items.
8458 · sphinx.ext.autodoc has a new event autodoc-process-signature that
8460 allows tuning function signature introspection.
8461 · sphinx.ext.autodoc has a new event autodoc-skip-member that allows
8463 tuning which members are included in the generated content.
8464 · Respect __all__ when autodocumenting module members.
8466 · The automodule directive now supports the synopsis, deprecated and
8468 platform options.
8469 · Extension API:
8471 · Sphinx.add_node() now takes optional visitor methods for the HTML,
8473 LaTeX and text translators; this prevents having to manually patch
8474 the classes.
8475 · Added Sphinx.add_javascript() that adds scripts to load in the
8477 default HTML template.
8478 · Added new events: source-read, env-updated, env-purge-doc, miss‐
8480 ing-reference, build-finished.
8481 · Other changes:
8483 · Added a command-line switch -Q: it will suppress warnings.
8485 · Added a command-line switch -A: it can be used to supply additional
8487 values into the HTML templates.
8488 · Added a command-line switch -C: if it is given, no configuration
8490 file conf.py is required.
8491 · Added a distutils command build_sphinx: When Sphinx is installed,
8493 you can call python setup.py build_sphinx for projects that have
8494 Sphinx documentation, which will build the docs and place them in
8495 the standard distutils build directory.
8496 · In quickstart, if the selected root path already contains a Sphinx
8498 project, complain and abort.
8499 Bugs fixed
8501 · #51: Escape configuration values placed in HTML templates.
8502 · #44: Fix small problems in HTML help index generation.
8504 · Fix LaTeX output for line blocks in tables.
8506 · #38: Fix "illegal unit" error when using pixel image widths/heights.
8508 · Support table captions in LaTeX output.
8510 · #39: Work around a bug in Jinja that caused "<generator ...>" to be
8512 emitted in HTML output.
8513 · Fix a problem with module links not being generated in LaTeX output.
8515 · Fix the handling of images in different directories.
8517 · #29: Support option lists in the text writer. Make sure that dashes
8519 introducing long option names are not contracted to en-dashes.
8520 · Support the "scale" option for images in HTML output.
8522 · #25: Properly escape quotes in HTML help attribute values.
8524 · Fix LaTeX build for some description environments with :noindex:.
8526 · #24: Don't crash on uncommon casing of role names (like :Class:).
8528 · Only output ANSI colors on color terminals.
8530 · Update to newest fncychap.sty, to fix problems with non-ASCII charac‐
8532 ters at the start of chapter titles.
8533 · Fix a problem with index generation in LaTeX output, caused by hyper‐
8535 ref not being included last.
8536 · Don't disregard return annotations for functions without any parame‐
8538 ters.
8539 · Don't throw away labels for code blocks.
8541 Release 0.4.3 (Oct 8, 2008)
8543 · Fix a bug in autodoc with directly given autodoc members.
8544 · Fix a bug in autodoc that would import a module twice, once as "mod‐
8546 ule", once as "module.".
8547 · Fix a bug in the HTML writer that created duplicate id attributes for
8549 section titles with docutils 0.5.
8550 · Properly call super() in overridden blocks in templates.
8552 · Add a fix when using XeTeX.
8554 · Unify handling of LaTeX escaping.
8556 · Rebuild everything when the extensions config value changes.
8558 · Don't try to remove a nonexisting static directory.
8560 · Fix an indentation problem in production lists.
8562 · Fix encoding handling for literal include files: literalinclude now
8564 has an encoding option that defaults to UTF-8.
8565 · Fix the handling of non-ASCII characters entered in quickstart.
8567 · Fix a crash with nonexisting image URIs.
8569 Release 0.4.2 (Jul 29, 2008)
8571 · Fix rendering of the samp role in HTML.
8572 · Fix a bug with LaTeX links to headings leading to a wrong page.
8574 · Reread documents with globbed toctrees when source files are added or
8576 removed.
8577 · Add a missing parameter to PickleHTMLBuilder.handle_page().
8579 · Put inheritance info always on its own line.
8581 · Don't automatically enclose code with whitespace in it in quotes;
8583 only do this for the samp role.
8584 · autodoc now emits a more precise error message when a module can't be
8586 imported or an attribute can't be found.
8587 · The JavaScript search now uses the correct file name suffix when
8589 referring to found items.
8590 · The automodule directive now accepts the inherited-members and
8592 show-inheritance options again.
8593 · You can now rebuild the docs normally after relocating the source
8595 and/or doctree directory.
8596 Release 0.4.1 (Jul 5, 2008)
8598 · Added sub-/superscript node handling to TextBuilder.
8599 · Label names in references are now case-insensitive, since reST label
8601 names are always lowercased.
8602 · Fix linkcheck builder crash for malformed URLs.
8604 · Add compatibility for admonitions and docutils 0.5.
8606 · Remove the silly restriction on "rubric" in the LaTeX writer: you can
8608 now write arbitrary "rubric" directives, and only those with a title
8609 of "Footnotes" will be ignored.
8610 · Copy the HTML logo to the output _static directory.
8612 · Fix LaTeX code for modules with underscores in names and platforms.
8614 · Fix a crash with nonlocal image URIs.
8616 · Allow the usage of :noindex: in automodule directives, as documented.
8618 · Fix the delete() docstring processor function in autodoc.
8620 · Fix warning message for nonexisting images.
8622 · Fix JavaScript search in Internet Explorer.
8624 Release 0.4 (Jun 23, 2008)
8626 New features added
8627 · tocdepth can be given as a file-wide metadata entry, and specifies
8628 the maximum depth of a TOC of this file.
8629 · The new config value default_role can be used to select the default
8631 role for all documents.
8632 · Sphinx now interprets field lists with fields like :param foo: in
8634 description units.
8635 · The new staticmethod directive can be used to mark methods as static
8637 methods.
8638 · HTML output:
8640 · The "previous" and "next" links have a more logical structure, so
8642 that by following "next" links you can traverse the entire TOC
8643 tree.
8644 · The new event html-page-context can be used to include custom val‐
8646 ues into the context used when rendering an HTML template.
8647 · Document metadata is now in the default template context, under the
8649 name metadata.
8650 · The new config value html_favicon can be used to set a favicon for
8652 the HTML output. Thanks to Sebastian Wiesner.
8653 · The new config value html_use_index can be used to switch index
8655 generation in HTML documents off.
8656 · The new config value html_split_index can be used to create sepa‐
8658 rate index pages for each letter, to be used when the complete
8659 index is too large for one page.
8660 · The new config value html_short_title can be used to set a shorter
8662 title for the documentation which is then used in the navigation
8663 bar.
8664 · The new config value html_show_sphinx can be used to control
8666 whether a link to Sphinx is added to the HTML footer.
8667 · The new config value html_file_suffix can be used to set the HTML
8669 file suffix to e.g. .xhtml.
8670 · The directories in the html_static_path can now contain subdirecto‐
8672 ries.
8673 · The module index now isn't collapsed if the number of submodules is
8675 larger than the number of toplevel modules.
8676 · The image directive now supports specifying the extension as .*,
8678 which makes the builder select the one that matches best. Thanks to
8679 Sebastian Wiesner.
8680 · The new config value exclude_trees can be used to exclude whole sub‐
8682 trees from the search for source files.
8683 · Defaults for configuration values can now be callables, which allows
8685 dynamic defaults.
8686 · The new TextBuilder creates plain-text output.
8688 · Python 3-style signatures, giving a return annotation via ->, are now
8690 supported.
8691 · Extensions:
8693 · The autodoc extension now offers a much more flexible way to manip‐
8695 ulate docstrings before including them into the output, via the new
8696 autodoc-process-docstring event.
8697 · The autodoc extension accepts signatures for functions, methods and
8699 classes now that override the signature got via introspection from
8700 Python code.
8701 · The autodoc extension now offers a show-inheritance option for
8703 autoclass that inserts a list of bases after the signature.
8704 · The autodoc directives now support the noindex flag option.
8706 Bugs fixed
8708 · Correctly report the source location for docstrings included with
8709 autodoc.
8710 · Fix the LaTeX output of description units with multiple signatures.
8712 · Handle the figure directive in LaTeX output.
8714 · Handle raw admonitions in LaTeX output.
8716 · Fix determination of the title in HTML help output.
8718 · Handle project names containing spaces.
8720 · Don't write SSI-like comments in HTML output.
8722 · Rename the "sidebar" class to "sphinxsidebar" in order to stay dif‐
8724 ferent from reST sidebars.
8725 · Use a binary TOC in HTML help generation to fix issues links without
8727 explicit anchors.
8728 · Fix behavior of references to functions/methods with an explicit
8730 title.
8731 · Support citation, subscript and superscript nodes in LaTeX writer.
8733 · Provide the standard "class" directive as "cssclass"; else it is
8735 shadowed by the Sphinx-defined directive.
8736 · Fix the handling of explicit module names given to autoclass direc‐
8738 tives. They now show up with the correct module name in the gener‐
8739 ated docs.
8740 · Enable autodoc to process Unicode docstrings.
8742 · The LaTeX writer now translates line blocks with \raggedright, which
8744 plays nicer with tables.
8745 · Fix bug with directories in the HTML builder static path.
8747 Release 0.3 (May 6, 2008)
8749 New features added
8750 · The toctree directive now supports a glob option that allows
8751 glob-style entries in the content.
8752 · If the pygments_style config value contains a dot it's treated as the
8754 import path of a custom Pygments style class.
8755 · A new config value, exclude_dirs, can be used to exclude whole direc‐
8757 tories from the search for source files.
8758 · The configuration directory (containing conf.py) can now be set inde‐
8760 pendently from the source directory. For that, a new command-line
8761 option -c has been added.
8762 · A new directive tabularcolumns can be used to give a tabular column
8764 specification for LaTeX output. Tables now use the tabulary package.
8765 Literal blocks can now be placed in tables, with several caveats.
8766 · A new config value, latex_use_parts, can be used to enable parts in
8768 LaTeX documents.
8769 · Autodoc now skips inherited members for classes, unless you give the
8771 new inherited-members option.
8772 · A new config value, autoclass_content, selects if the docstring of
8774 the class' __init__ method is added to the directive's body.
8775 · Support for C++ class names (in the style Class::Function) in C func‐
8777 tion descriptions.
8778 · Support for a toctree_only item in items for the latex_documents con‐
8780 fig value. This only includes the documents referenced by TOC trees
8781 in the output, not the rest of the file containing the directive.
8782 Bugs fixed
8784 · sphinx.htmlwriter: Correctly write the TOC file for any structure of
8785 the master document. Also encode non-ASCII characters as entities in
8786 TOC and index file. Remove two remaining instances of hard-coded
8787 "documentation".
8788 · sphinx.ext.autodoc: descriptors are detected properly now.
8790 · sphinx.latexwriter: implement all reST admonitions, not just note and
8792 warning.
8793 · Lots of little fixes to the LaTeX output and style.
8795 · Fix OpenSearch template and make template URL absolute. The
8797 html_use_opensearch config value now must give the base URL.
8798 · Some unused files are now stripped from the HTML help file build.
8800 Release 0.2 (Apr 27, 2008)
8802 Incompatible changes
8803 · Jinja, the template engine used for the default HTML templates, is
8804 now no longer shipped with Sphinx. If it is not installed automati‐
8805 cally for you (it is now listed as a dependency in setup.py), install
8806 it manually from PyPI. This will also be needed if you're using
8807 Sphinx from a SVN checkout; in that case please also remove the
8808 sphinx/jinja directory that may be left over from old revisions.
8809 · The clumsy handling of the index.html template was removed. The con‐
8811 fig value html_index is gone, and html_additional_pages should be
8812 used instead. If you need it, the old index.html template is still
8813 there, called defindex.html, and you can port your html_index tem‐
8814 plate, using Jinja inheritance, by changing your template:
8815 {% extends "defindex.html" %}
8817 {% block tables %}
8818 ... old html_index template content ...
8819 {% endblock %}
8820 and putting 'index': name of your template in html_additional_pages.
8822 · In the layout template, redundant blocks were removed; you should use
8824 Jinja's standard {{ super() }} mechanism instead, as explained in the
8825 (newly written) templating docs.
8826 New features added
8828 · Extension API (Application object):
8829 · Support a new method, add_crossref_type. It works like
8831 add_description_unit but the directive will only create a target
8832 and no output.
8833 · Support a new method, add_transform. It takes a standard docutils
8835 Transform subclass which is then applied by Sphinx' reader on pars‐
8836 ing reST document trees.
8837 · Add support for other template engines than Jinja, by adding an
8839 abstraction called a "template bridge". This class handles render‐
8840 ing of templates and can be changed using the new configuration
8841 value "template_bridge".
8842 · The config file itself can be an extension (if it provides a set‐
8844 up() function).
8845 · Markup:
8847 · New directive, currentmodule. It can be used to indicate the mod‐
8849 ule name of the following documented things without creating index
8850 entries.
8851 · Allow giving a different title to documents in the toctree.
8853 · Allow giving multiple options in a cmdoption directive.
8855 · Fix display of class members without explicit class name given.
8857 · Templates (HTML output):
8859 · index.html renamed to defindex.html, see above.
8861 · There's a new config value, html_title, that controls the overall
8863 "title" of the set of Sphinx docs. It is used instead everywhere
8864 instead of "Projectname vX.Y documentation" now.
8865 · All references to "documentation" in the templates have been
8867 removed, so that it is now easier to use Sphinx for non-documenta‐
8868 tion documents with the default templates.
8869 · Templates now have an XHTML doctype, to be consistent with docu‐
8871 tils' HTML output.
8872 · You can now create an OpenSearch description file with the
8874 html_use_opensearch config value.
8875 · You can now quickly include a logo in the sidebar, using the
8877 html_logo config value.
8878 · There are new blocks in the sidebar, so that you can easily insert
8880 content into the sidebar.
8881 · LaTeX output:
8883 · The sphinx.sty package was cleaned of unused stuff.
8885 · You can include a logo in the title page with the latex_logo config
8887 value.
8888 · You can define the link colors and a border and background color
8890 for verbatim environments.
8891 Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and
8893 Sebastian Wiesner for suggestions.
8894 Bugs fixed
8896 · sphinx.ext.autodoc: Don't check __module__ for explicitly given mem‐
8897 bers. Remove "self" in class constructor argument list.
8898 · sphinx.htmlwriter: Don't use os.path for joining image HREFs.
8900 · sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values.
8902 · sphinx.latexwriter: Implement option lists. Also, some other changes
8904 were made to sphinx.sty in order to enhance compatibility and remove
8905 old unused stuff. Thanks to Gael Varoquaux for that!
8906 · sphinx.roles: Fix referencing glossary terms with explicit targets.
8908 · sphinx.environment: Don't swallow TOC entries when resolving sub‐
8910 trees.
8911 · sphinx.quickstart: Create a sensible default latex_documents setting.
8913 · sphinx.builder, sphinx.environment: Gracefully handle some user error
8915 cases.
8916 · sphinx.util: Follow symbolic links when searching for documents.
8918 Release 0.1.61950 (Mar 26, 2008)
8920 · sphinx.quickstart: Fix format string for Makefile.
8921 Release 0.1.61945 (Mar 26, 2008)
8923 · sphinx.htmlwriter, sphinx.latexwriter: Support the .. image:: direc‐
8924 tive by copying image files to the output directory.
8925 · sphinx.builder: Consistently name "special" HTML output directories
8927 with a leading underscore; this means _sources and _static.
8928 · sphinx.environment: Take dependent files into account when collecting
8930 the set of outdated sources.
8931 · sphinx.directives: Record files included with .. literalinclude:: as
8933 dependencies.
8934 · sphinx.ext.autodoc: Record files from which docstrings are included
8936 as dependencies.
8937 · sphinx.builder: Rebuild all HTML files in case of a template change.
8939 · sphinx.builder: Handle unavailability of TOC relations (previous/
8941 next chapter) more gracefully in the HTML builder.
8942 · sphinx.latexwriter: Include fncychap.sty which doesn't seem to be
8944 very common in TeX distributions. Add a clean target in the latex
8945 Makefile. Really pass the correct paper and size options to the
8946 LaTeX document class.
8947 · setup: On Python 2.4, don't egg-depend on docutils if a docutils is
8949 already installed -- else it will be overwritten.
8950 Release 0.1.61843 (Mar 24, 2008)
8952 · sphinx.quickstart: Really don't create a makefile if the user doesn't
8953 want one.
8954 · setup: Don't install scripts twice, via setuptools entry points and
8956 distutils scripts. Only install via entry points.
8957 · sphinx.builder: Don't recognize the HTML builder's copied source
8959 files (under _sources) as input files if the source suffix is .txt.
8960 · sphinx.highlighting: Generate correct markup for LaTeX Verbatim envi‐
8962 ronment escapes even if Pygments is not installed.
8963 · sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder.
8965 · sphinx.htmlwriter: Make parsed-literal blocks work as expected, not
8967 highlighting them via Pygments.
8968 · sphinx.environment: Don't error out on reading an empty source file.
8970 Release 0.1.61798 (Mar 23, 2008)
8972 · sphinx: Work with docutils SVN snapshots as well as 0.4.
8973 · sphinx.ext.doctest: Make the group in which doctest blocks are placed
8975 selectable, and default to 'default'.
8976 · sphinx.ext.doctest: Replace <BLANKLINE> in doctest blocks by real
8978 blank lines for presentation output, and remove doctest options given
8979 inline.
8980 · sphinx.environment: Move doctest_blocks out of block_quotes to sup‐
8982 port indented doctest blocks.
8983 · sphinx.ext.autodoc: Render .. automodule:: docstrings in a section
8985 node, so that module docstrings can contain proper sectioning.
8986 · sphinx.ext.autodoc: Use the module's encoding for decoding doc‐
8988 strings, rather than requiring ASCII.
8989 Release 0.1.61611 (Mar 21, 2008)
8991 · First public release.
8992
8994 This is an (incomplete) alphabetic list of projects that use Sphinx or
8995 are experimenting with using it for their documentation. If you like
8996 to be included, please mail to the Google group.
8997 I've grouped the list into sections to make it easier to find interest‐
8999 ing examples.
9000 Documentation using the default theme
9002 · APSW: http://apidoc.apsw.googlecode.com/hg/index.html
9003 · ASE: https://wiki.fysik.dtu.dk/ase/
9005 · boostmpi: http://documen.tician.de/boostmpi/
9007 · Calibre: http://calibre.kovidgoyal.net/user_manual/
9009 · CodePy: http://documen.tician.de/codepy/
9011 · Cython: http://docs.cython.org/
9013 · C\C++ Python language binding project:
9015 http://language-binding.net/index.html
9016 · Director: http://packages.python.org/director/
9018 · Dirigible: http://www.projectdirigible.com/documentation/
9020 · F2py: http://www.f2py.org/html/
9022 · GeoDjango: http://geodjango.org/docs/
9024 · gevent: http://www.gevent.org/
9026 · Google Wave API:
9028 http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
9029 · GSL Shell: http://www.nongnu.org/gsl-shell/
9031 · Hands-on Python Tutorial:
9033 http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
9034 · Hedge: http://documen.tician.de/hedge/
9036 · Kaa: http://doc.freevo.org/api/kaa/
9038 · Leo: http://webpages.charter.net/edreamleo/front.html
9040 · Lino: http://lino.saffre-rumma.ee/
9042 · MeshPy: http://documen.tician.de/meshpy/
9044 · mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
9046 · OpenEXR: http://excamera.com/articles/26/doc/index.html
9048 · OpenGDA: http://www.opengda.org/gdadoc/html/
9050 · openWNS: http://docs.openwns.org/
9052 · Paste: http://pythonpaste.org/script/
9054 · Paver: http://www.blueskyonmars.com/projects/paver/
9056 · Pyccuracy: http://www.pyccuracy.org/
9058 · PyCuda: http://documen.tician.de/pycuda/
9060 · Pyevolve: http://pyevolve.sourceforge.net/
9062 · Pylo: http://documen.tician.de/pylo/
9064 · PyMQI: http://packages.python.org/pymqi/
9066 · PyPubSub: http://pubsub.sourceforge.net/
9068 · pyrticle: http://documen.tician.de/pyrticle/
9070 · Python: http://docs.python.org/
9072 · python-apt: http://apt.alioth.debian.org/python-apt-doc/
9074 · PyUblas: http://documen.tician.de/pyublas/
9076 · Quex: http://quex.sourceforge.net/doc/html/main.html
9078 · Scapy: http://www.secdev.org/projects/scapy/doc/
9080 · SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
9082 · SymPy: http://docs.sympy.org/
9084 · WTForms: http://wtforms.simplecodes.com/docs/
9086 · z3c: http://docs.carduner.net/z3c-tutorial/
9088 Documentation using a customized version of the default theme
9090 · Advanced Generic Widgets:
9091 http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
9092 · Bazaar: http://doc.bazaar.canonical.com/en/
9094 · Chaco: http://code.enthought.com/projects/chaco/docs/html/
9096 · Djagios: http://djagios.org/
9098 · GetFEM++: http://home.gna.org/getfem/
9100 · GPAW: https://wiki.fysik.dtu.dk/gpaw/
9102 · Grok: http://grok.zope.org/doc/current/
9104 · IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
9106 · LEPL: http://www.acooke.org/lepl/
9108 · Mayavi:
9110 http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
9111 · NOC: http://trac.nocproject.org/trac/wiki/NocGuide
9113 · NumPy: http://docs.scipy.org/doc/numpy/reference/
9115 · Peach^3: http://peach3.nl/doc/latest/userdoc/
9117 · Py on Windows: http://timgolden.me.uk/python-on-windows/
9119 · PyLit: http://pylit.berlios.de/
9121 · Sage: http://sagemath.org/doc/
9123 · SciPy: http://docs.scipy.org/doc/scipy/reference/
9125 · simuPOP:
9127 http://simupop.sourceforge.net/manual_release/build/userGuide.html
9128 · Sprox: http://sprox.org/
9130 · TurboGears: http://turbogears.org/2.0/docs/
9132 · Zentyal: http://doc.zentyal.org/
9134 · Zope: http://docs.zope.org/zope2/index.html
9136 · zc.async: http://packages.python.org/zc.async/1.5.0/
9138 Documentation using the sphinxdoc theme
9140 · Fityk: http://www.unipress.waw.pl/fityk/
9141 · MapServer: http://mapserver.org/
9143 · Matplotlib: http://matplotlib.sourceforge.net/
9145 · Music21: http://mit.edu/music21/doc/html/contents.html
9147 · MyHDL: http://www.myhdl.org/doc/0.6/
9149 · NetworkX: http://networkx.lanl.gov/
9151 · Pweave: http://mpastell.com/pweave/
9153 · Pyre: http://docs.danse.us/pyre/sphinx/
9155 · Pysparse: http://pysparse.sourceforge.net/
9157 · PyTango:
9159 http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
9160 · Reteisi: http://docs.argolinux.org/reteisi/
9162 · Satchmo: http://www.satchmoproject.com/docs/svn/
9164 · Sphinx: http://sphinx.pocoo.org/
9166 · Sqlkit: http://sqlkit.argolinux.org/
9168 · Tau:
9170 http://www.tango-controls.org/static/tau/latest/doc/html/index.html
9171 · Total Open Station: http://tops.berlios.de/
9173 · WebFaction: http://docs.webfaction.com/
9175 Documentation using another builtin theme
9177 · C/C++ Development with Eclipse: http://book.dehlia.in/c-cpp-eclipse/
9178 (agogo)
9179 · Distribute: http://packages.python.org/distribute/ (nature)
9181 · Jinja: http://jinja.pocoo.org/2/documentation/ (scrolls)
9183 · pip: http://pip.openplans.org/ (nature)
9185 · Programmieren mit PyGTK und Glade (German):
9187 http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
9188 · pypol: http://pypol.altervista.org/ (nature)
9190 · Spring Python:
9192 http://springpython.webfactional.com/current/sphinx/index.html
9193 (nature)
9194 · sqlparse:
9196 http://python-sqlparse.googlecode.com/svn/docs/api/index.html (agogo)
9197 · libLAS: http://liblas.org/ (nature)
9199 Documentation using a custom theme/integrated in a site
9201 · Blender: http://www.blender.org/documentation/250PythonDoc/
9202 · Blinker: http://discorporate.us/projects/Blinker/docs/
9204 · Classy: classy: http://classy.pocoo.org/
9206 · Django: http://docs.djangoproject.com/
9208 · Flask: http://flask.pocoo.org/docs/
9210 · Flask-OpenID: http://packages.python.org/Flask-OpenID/
9212 · GeoServer: http://docs.geoserver.org/
9214 · Glashammer: http://glashammer.org/
9216 · MirrorBrain: http://mirrorbrain.org/docs/
9218 · nose: http://somethingaboutorange.com/mrl/projects/nose/
9220 · ObjectListView: http://objectlistview.sourceforge.net/python
9222 · Open ERP: http://doc.openerp.com/
9224 · OpenLayers: http://docs.openlayers.org/
9226 · PyEphem: http://rhodesmill.org/pyephem/
9228 · German Plone 4.0 user manual:
9230 http://www.hasecke.com/plone-benutzerhandbuch/4.0/
9231 · Pylons: http://pylonshq.com/docs/en/0.9.7/
9233 · PyMOTW: http://www.doughellmann.com/PyMOTW/
9235 · qooxdoo: http://manual.qooxdoo.org/current
9237 · Roundup: http://www.roundup-tracker.org/
9239 · Selenium: http://seleniumhq.org/docs/
9241 · Self: http://selflanguage.org/
9243 · SQLAlchemy: http://www.sqlalchemy.org/docs/
9245 · tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
9247 · tipfy: http://www.tipfy.org/docs/
9249 · Werkzeug: http://werkzeug.pocoo.org/documentation/dev/
9251 · WFront: http://discorporate.us/projects/WFront/
9253 Homepages and other non-documentation sites
9255 · Applied Mathematics at the Stellenbosch University:
9256 http://dip.sun.ac.za/
9257 · A personal page: http://www.dehlia.in/
9259 · Benoit Boissinot: http://perso.ens-lyon.fr/benoit.boissinot/
9261 · lunarsite: http://lunaryorn.de/
9263 · The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
9265 · VOR: http://www.vor-cycling.be/
9267 Books produced using Sphinx
9269 · "The repoze.bfg Web Application Framework":
9270 http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
9271 · A Theoretical Physics Reference book: http://theoretical-physics.net/
9273 · "Simple and Steady Way of Learning for Software Engineering" (in Ja‐
9275 panese): http://www.amazon.co.jp/dp/477414259X/
9276 · "Expert Python Programming" (Japanese translation):
9278 http://www.amazon.co.jp/dp/4048686291/
9279 · "Pomodoro Technique Illustrated" (Japanese translation):
9281 http://www.amazon.co.jp/dp/4048689525/
9282 · genindex
9284 · modindex
9286 · search
9288 · glossary
9290
9292 Georg Brandl
9293
9295 2007-2011, Georg Brandl
92961.0.7 January 18, 2011 SPHINX-ALL(1)