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 the Python Package Index.
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 · Christophe de Vienne wrote a tool to convert from Open/LibreOffice
40 documents to Sphinx: odt2sphinx.
41 · To convert different markups, Pandoc is a very helpful tool.
43 Use with other systems
45 See the pertinent section in the FAQ list.
46 Prerequisites
48 Sphinx needs at least Python 2.4 or Python 3.1 to run, as well as the
49 docutils and Jinja2 libraries. Sphinx should work with docutils ver‐
50 sion 0.7 or some (not broken) SVN trunk snapshot. If you like to have
51 source code highlighting support, you must also install the Pygments
52 library.
53 If you use Python 2.4 you also need uuid.
55 Usage
57 See tutorial for an introduction. It also contains links to more
58 advanced sections in this manual for the topics it discusses.
59
61 This document is meant to give a tutorial-like overview of all common
62 tasks while using Sphinx.
63 The green arrows designate "more info" links leading to advanced sec‐
65 tions about the described task.
66 Setting up the documentation sources
68 The root directory of a documentation collection is called the source
69 directory. This directory also contains the Sphinx configuration file
70 conf.py, where you can configure all aspects of how Sphinx reads your
71 sources and builds your documentation. [1]
72 Sphinx comes with a script called sphinx-quickstart that sets up a
74 source directory and creates a default conf.py with the most useful
75 configuration values from a few questions it asks you. Just run
76 $ sphinx-quickstart
78 and answer its questions. (Be sure to say yes to the "autodoc" exten‐
80 sion.)
81 There is also an automatic "API documentation" generator called
83 sphinx-apidoc; see invocation-apidoc for details.
84 Defining document structure
86 Let's assume you've run sphinx-quickstart. It created a source direc‐
87 tory with conf.py and a master document, index.rst (if you accepted the
88 defaults). The main function of the master document is to serve as a
89 welcome page, and to contain the root of the "table of contents tree"
90 (or toctree). This is one of the main things that Sphinx adds to
91 reStructuredText, a way to connect multiple files to a single hierarchy
92 of documents.
93 reStructuredText directives
95 toctree is a reStructuredText directive, a very versatile piece of
96 markup. Directives can have arguments, options and content.
97 Arguments are given directly after the double colon following the
99 directive's name. Each directive decides whether it can have argu‐
100 ments, and how many.
101 Options are given after the arguments, in form of a "field list". The
103 maxdepth is such an option for the toctree directive.
104 Content follows the options or arguments after a blank line. Each
106 directive decides whether to allow content, and what to do with it.
107 A common gotcha with directives is that the first line of the content
109 must be indented to the same level as the options are.
110 The toctree directive initially is empty, and looks like this:
112 .. toctree::
114 :maxdepth: 2
115 You add documents listing them in the content of the directive:
117 .. toctree::
119 :maxdepth: 2
120 intro
122 tutorial
123 ...
124 This is exactly how the toctree for this documentation looks. The doc‐
126 uments to include are given as document names, which in short means
127 that you leave off the file name extension and use slashes as directory
128 separators.
129 [image: more info] [image]
131 Read more about the toctree directive.
132 You can now create the files you listed in the toctree and add content,
134 and their section titles will be inserted (up to the "maxdepth" level)
135 at the place where the toctree directive is placed. Also, Sphinx now
136 knows about the order and hierarchy of your documents. (They may con‐
137 tain toctree directives themselves, which means you can create deeply
138 nested hierarchies if necessary.)
139 Adding content
141 In Sphinx source files, you can use most features of standard reStruc‐
142 turedText. There are also several features added by Sphinx. For exam‐
143 ple, you can add cross-file references in a portable way (which works
144 for all output types) using the ref role.
145 For an example, if you are viewing the HTML version you can look at the
147 source for this document -- use the "Show Source" link in the sidebar.
148 [image: more info] [image]
150 See rst-primer for a more in-depth introduction to reStructuredText
151 and sphinxmarkup for a full list of markup added by Sphinx.
152 Running the build
154 Now that you have added some files and content, let's make a first
155 build of the docs. A build is started with the sphinx-build program,
156 called like this:
157 $ sphinx-build -b html sourcedir builddir
159 where sourcedir is the source directory, and builddir is the directory
161 in which you want to place the built documentation. The -b option
162 selects a builder; in this example Sphinx will build HTML files.
163 [image: more info] [image]
165 See invocation for all options that sphinx-build supports.
166 However, sphinx-quickstart script creates a Makefile and a make.bat
168 which make life even easier for you: with them you only need to run
169 $ make html
171 to build HTML docs in the build directory you chose. Execute make
173 without an argument to see which targets are available.
174 How do I generate PDF documents?
176 make latexpdf runs the LaTeX builder and readily invokes the
178 pdfTeX toolchain for you.
179 Documenting objects
181 One of Sphinx' main objectives is easy documentation of objects (in a
182 very general sense) in any domain. A domain is a collection of object
183 types that belong together, complete with markup to create and refer‐
184 ence descriptions of these objects.
185 The most prominent domain is the Python domain. To e.g. document the
187 Python built-in function enumerate(), you would add this to one of your
188 source files:
189 .. py:function:: enumerate(sequence[, start=0])
191 Return an iterator that yields tuples of an index and an item of the
193 *sequence*. (And so on.)
194 This is rendered like this:
196 enumerate(sequence[, start=0])
198 Return an iterator that yields tuples of an index and an item of
199 the sequence. (And so on.)
200 The argument of the directive is the signature of the object you
202 describe, the content is the documentation for it. Multiple signatures
203 can be given, each in its own line.
204 The Python domain also happens to be the default domain, so you don't
206 need to prefix the markup with the domain name:
207 .. function:: enumerate(sequence[, start=0])
209 ...
211 does the same job if you keep the default setting for the default
213 domain.
214 There are several more directives for documenting other types of Python
216 objects, for example py:class or py:method. There is also a cross-ref‐
217 erencing role for each of these object types. This markup will create
218 a link to the documentation of enumerate():
219 The :py:func:`enumerate` function can be used for ...
221 And here is the proof: A link to enumerate().
223 Again, the py: can be left out if the Python domain is the default one.
225 It doesn't matter which file contains the actual documentation for enu‐
226 merate(); Sphinx will find it and create a link to it.
227 Each domain will have special rules for how the signatures can look
229 like, and make the formatted output look pretty, or add specific fea‐
230 tures like links to parameter types, e.g. in the C/C++ domains.
231 [image: more info] [image]
233 See domains for all the available domains and their directives/roles.
234 Basic configuration
236 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
237 cesses your documents. In that file, which is executed as a Python
238 source file, you assign configuration values. For advanced users:
239 since it is executed by Sphinx, you can do non-trivial tasks in it,
240 like extending sys.path or importing a module to find out the version
241 your are documenting.
242 The config values that you probably want to change are already put into
244 the conf.py by sphinx-quickstart and initially commented out (with
245 standard Python syntax: a # comments the rest of the line). To change
246 the default value, remove the hash sign and modify the value. To cus‐
247 tomize a config value that is not automatically added by sphinx-quick‐
248 start, just add an additional assignment.
249 Keep in mind that the file uses Python syntax for strings, numbers,
251 lists and so on. The file is saved in UTF-8 by default, as indicated
252 by the encoding declaration in the first line. If you use non-ASCII
253 characters in any string value, you need to use Python Unicode strings
254 (like project = u'Exposé').
255 [image: more info] [image]
257 See build-config for documentation of all available config values.
258 Autodoc
260 When documenting Python code, it is common to put a lot of documenta‐
261 tion in the source files, in documentation strings. Sphinx supports
262 the inclusion of docstrings from your modules with an extension (an
263 extension is a Python module that provides additional features for
264 Sphinx projects) called "autodoc".
265 In order to use autodoc, you need to activate it in conf.py by putting
267 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
268 sions config value. Then, you have a few additional directives at your
269 disposal.
270 For example, to document the function io.open(), reading its signature
272 and docstring from the source file, you'd write this:
273 .. autofunction:: io.open
275 You can also document whole classes or even modules automatically,
277 using member options for the auto directives, like
278 .. automodule:: io
280 :members:
281 autodoc needs to import your modules in order to extract the doc‐
283 strings. Therefore, you must add the appropriate path to sys.path in
284 your conf.py.
285 [image: more info] [image]
287 See sphinx.ext.autodoc for the complete description of the features of
288 autodoc.
289 More topics to be covered
291 · Other extensions (math, intersphinx, viewcode, doctest)
292 · Static files
294 · Selecting a theme
296 · Templating
298 · Using extensions
300 · Writing extensions
302
304 [1] This is the usual lay-out. However, conf.py can also live in
305 another directory, the configuration directory. See invocation.
306
308 The sphinx-build script builds a Sphinx documentation set. It is
309 called like this:
310 $ sphinx-build [options] sourcedir builddir [filenames]
312 where sourcedir is the source directory, and builddir is the directory
314 in which you want to place the built documentation. Most of the time,
315 you don't need to specify any filenames.
316 The sphinx-build script has several options:
318 -b buildername
320 The most important option: it selects a builder. The most com‐
321 mon builders are:
322 html Build HTML pages. This is the default builder.
324 dirhtml
326 Build HTML pages, but with a single directory per docu‐
327 ment. Makes for prettier URLs (no .html) if served from
328 a webserver.
329 singlehtml
331 Build a single HTML with the whole content.
332 htmlhelp, qthelp, devhelp, epub
334 Build HTML files with additional information for building
335 a documentation collection in one of these formats.
336 latex Build LaTeX sources that can be compiled to a PDF docu‐
338 ment using pdflatex.
339 man Build manual pages in groff format for UNIX systems.
341 texinfo
343 Build Texinfo files that can be processed into Info files
344 using makeinfo.
345 text Build plain text files.
347 gettext
349 Build gettext-style message catalogs (.pot files).
350 doctest
352 Run all doctests in the documentation, if the doctest
353 extension is enabled.
354 linkcheck
356 Check the integrity of all external links.
357 See builders for a list of all builders shipped with Sphinx.
359 Extensions can add their own builders.
360 -a If given, always write all output files. The default is to only
362 write output files for new and changed source files. (This may
363 not apply to all builders.)
364 -E Don't use a saved environment (the structure caching all
366 cross-references), but rebuild it completely. The default is to
367 only read and parse source files that are new or have changed
368 since the last run.
369 -t tag Define the tag tag. This is relevant for only directives that
371 only include their content if this tag is set.
372 New in version 0.6.
374 -d path
376 Since Sphinx has to read and parse all source files before it
377 can write an output file, the parsed source files are cached as
378 "doctree pickles". Normally, these files are put in a directory
379 called .doctrees under the build directory; with this option you
380 can select a different cache directory (the doctrees can be
381 shared between all builders).
382 -c path
384 Don't look for the conf.py in the source directory, but use the
385 given configuration directory instead. Note that various other
386 files and paths given by configuration values are expected to be
387 relative to the configuration directory, so they will have to be
388 present at this location too.
389 New in version 0.3.
391 -C Don't look for a configuration file; only take options via the
393 -D option.
394 New in version 0.5.
396 -D setting=value
398 Override a configuration value set in the conf.py file. The
399 value must be a string or dictionary value. For the latter,
400 supply the setting name and key like this: -D latex_ele‐
401 ments.docclass=scrartcl. For boolean values, use 0 or 1 as the
402 value.
403 Changed in version 0.6: The value can now be a dictionary value.
405 -A name=value
407 Make the name assigned to value in the HTML templates.
408 New in version 0.5.
410 -n Run in nit-picky mode. Currently, this generates warnings for
412 all missing references.
413 -N Do not emit colored output. (On Windows, colored output is dis‐
415 abled in any case.)
416 -q Do not output anything on standard output, only write warnings
418 and errors to standard error.
419 -Q Do not output anything on standard output, also suppress warn‐
421 ings. Only errors are written to standard error.
422 -w file
424 Write warnings (and errors) to the given file, in addition to
425 standard error.
426 -W Turn warnings into errors. This means that the build stops at
428 the first warning and sphinx-build exits with exit status 1.
429 -P (Useful for debugging only.) Run the Python debugger, pdb, if
431 an unhandled exception occurs while building.
432 You can also give one or more filenames on the command line after the
434 source and build directories. Sphinx will then try to build only these
435 output files (and their dependencies).
436 Makefile options
438 The Makefile and make.bat files created by sphinx-quickstart usually
439 run sphinx-build only with the -b and -d options. However, they sup‐
440 port the following variables to customize behavior:
441 PAPER The value for latex_paper_size.
443 SPHINXBUILD
445 The command to use instead of sphinx-build.
446 BUILDDIR
448 The build directory to use instead of the one chosen in
449 sphinx-quickstart.
450 SPHINXOPTS
452 Additional options for sphinx-build.
453
455 The sphinx-apidoc generates completely automatic API documentation for
456 a Python package. It is called like this:
457 $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
459 where packagedir is the path to the package to document, and outputdir
461 is the directory where the generated sources are placed. Any pathnames
462 given are paths to be excluded ignored during generation.
463 The sphinx-apidoc script has several options:
465 -o outputdir
467 Gives the directory in which to place the generated output.
468 -f, --force
470 Normally, sphinx-apidoc does not overwrite any files. Use this
471 option to force the overwrite of all files that it generates.
472 -n, --dry-run
474 With this option given, no files will be written at all.
475 -s suffix
477 This option selects the file name suffix of output files. By
478 default, this is rst.
479 -d maxdepth
481 This sets the maximum depth of the table of contents, if one is
482 generated.
483 -T, --no-toc
485 This prevents the generation of a table-of-contents file mod‐
486 ules.rst. This has no effect when --full is given.
487 -F, --full
489 This option makes sphinx-apidoc create a full Sphinx project,
490 using the same mechanism as sphinx-quickstart. Most configura‐
491 tion values are set to default values, but you can influence the
492 most important ones using the following options.
493 -H project
495 Sets the project name to put in generated files (see project).
496 -A author
498 Sets the author name(s) to put in generated files (see copy‐
499 right).
500 -V version
502 Sets the project version to put in generated files (see ver‐
503 sion).
504 -R release
506 Sets the project release to put in generated files (see
507 release).
508
510 This section is a brief introduction to reStructuredText (reST) con‐
511 cepts and syntax, intended to provide authors with enough information
512 to author documents productively. Since reST was designed to be a sim‐
513 ple, unobtrusive markup language, this will not take too long.
514 See also
516 The authoritative reStructuredText User Documentation. The
518 "ref" links in this document link to the description of the
519 individual constructs in the reST reference.
520 Paragraphs
522 The paragraph (ref) is the most basic block in a reST document. Para‐
523 graphs are simply chunks of text separated by one or more blank lines.
524 As in Python, indentation is significant in reST, so all lines of the
525 same paragraph must be left-aligned to the same level of indentation.
526 Inline markup
528 The standard reST inline markup is quite simple: use
529 · one asterisk: *text* for emphasis (italics),
531 · two asterisks: **text** for strong emphasis (boldface), and
533 · backquotes: ``text`` for code samples.
535 If asterisks or backquotes appear in running text and could be confused
537 with inline markup delimiters, they have to be escaped with a back‐
538 slash.
539 Be aware of some restrictions of this markup:
541 · it may not be nested,
543 · content may not start or end with whitespace: * text* is wrong,
545 · it must be separated from surrounding text by non-word characters.
547 Use a backslash escaped space to work around that: thisis\ *one*\
548 word.
549 These restrictions may be lifted in future versions of the docutils.
551 reST also allows for custom "interpreted text roles"', which signify
553 that the enclosed text should be interpreted in a specific way. Sphinx
554 uses this to provide semantic markup and cross-referencing of identi‐
555 fiers, as described in the appropriate section. The general syntax is
556 :rolename:`content`.
557 Standard reST provides the following roles:
559 · emphasis -- alternate spelling for *emphasis*
561 · strong -- alternate spelling for **strong**
563 · literal -- alternate spelling for ``literal``
565 · subscript -- subscript text
567 · superscript -- superscript text
569 · title-reference -- for titles of books, periodicals, and other mate‐
571 rials
572 See inline-markup for roles added by Sphinx.
574 Lists and Quote-like blocks
576 List markup (ref) is natural: just place an asterisk at the start of a
577 paragraph and indent properly. The same goes for numbered lists; they
578 can also be autonumbered using a # sign:
579 * This is a bulleted list.
581 * It has two items, the second
582 item uses two lines.
583 1. This is a numbered list.
585 2. It has two items too.
586 #. This is a numbered list.
588 #. It has two items too.
589 Nested lists are possible, but be aware that they must be separated
591 from the parent list items by blank lines:
592 * this is
594 * a list
595 * with a nested list
597 * and some subitems
598 * and here the parent list continues
600 Definition lists (ref) are created as follows:
602 term (up to a line of text)
604 Definition of the term, which must be indented
605 and can even consist of multiple paragraphs
607 next term
609 Description.
610 Note that the term cannot have more than one line of text.
612 Quoted paragraphs (ref) are created by just indenting them more than
614 the surrounding paragraphs.
615 Line blocks (ref) are a way of preserving line breaks:
617 | These lines are
619 | broken exactly like in
620 | the source file.
621 There are also several more special blocks available:
623 · field lists (ref)
625 · option lists (ref)
627 · quoted literal blocks (ref)
629 · doctest blocks (ref)
631 Source Code
633 Literal code blocks (ref) are introduced by ending a paragraph with the
634 special marker ::. The literal block must be indented (and, like all
635 paragraphs, separated from the surrounding ones by blank lines):
636 This is a normal text paragraph. The next paragraph is a code sample::
638 It is not processed in any way, except
640 that the indentation is removed.
641 It can span multiple lines.
643 This is a normal text paragraph again.
645 The handling of the :: marker is smart:
647 · If it occurs as a paragraph of its own, that paragraph is completely
649 left out of the document.
650 · If it is preceded by whitespace, the marker is removed.
652 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
654 gle colon.
655 That way, the second sentence in the above example's first paragraph
657 would be rendered as "The next paragraph is a code sample:".
658 Tables
660 Two forms of tables are supported. For grid tables (ref), you have to
661 "paint" the cell grid yourself. They look like this:
662 +------------------------+------------+----------+----------+
664 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
665 | (header rows optional) | | | |
666 +========================+============+==========+==========+
667 | body row 1, column 1 | column 2 | column 3 | column 4 |
668 +------------------------+------------+----------+----------+
669 | body row 2 | ... | ... | |
670 +------------------------+------------+----------+----------+
671 Simple tables (ref) are easier to write, but limited: they must contain
673 more than one row, and the first column cannot contain multiple lines.
674 They look like this:
675 ===== ===== =======
677 A B A and B
678 ===== ===== =======
679 False False False
680 True False False
681 False True False
682 True True True
683 ===== ===== =======
684 Hyperlinks
686 External links
687 Use `Link text <http://example.com/>`_ for inline web links. If the
688 link text should be the web address, you don't need special markup at
689 all, the parser finds links and mail addresses in ordinary text.
690 You can also separate the link and the target definition (ref), like
692 this:
693 This is a paragraph that contains `a link`_.
695 .. _a link: http://example.com/
697 Internal links
699 Internal linking is done via a special reST role provided by Sphinx,
700 see the section on specific markup, ref-role.
701 Sections
703 Section headers (ref) are created by underlining (and optionally over‐
704 lining) the section title with a punctuation character, at least as
705 long as the text:
706 =================
708 This is a heading
709 =================
710 Normally, there are no heading levels assigned to certain characters as
712 the structure is determined from the succession of headings. However,
713 for the Python documentation, this convention is used which you may
714 follow:
715 · # with overline, for parts
717 · * with overline, for chapters
719 · =, for sections
721 · -, for subsections
723 · ^, for subsubsections
725 · ", for paragraphs
727 Of course, you are free to use your own marker characters (see the reST
729 documentation), and use a deeper nesting level, but keep in mind that
730 most target formats (HTML, LaTeX) have a limited supported nesting
731 depth.
732 Explicit Markup
734 "Explicit markup" (ref) is used in reST for most constructs that need
735 special handling, such as footnotes, specially-highlighted paragraphs,
736 comments, and generic directives.
737 An explicit markup block begins with a line starting with .. followed
739 by whitespace and is terminated by the next paragraph at the same level
740 of indentation. (There needs to be a blank line between explicit
741 markup and normal paragraphs. This may all sound a bit complicated,
742 but it is intuitive enough when you write it.)
743 Directives
745 A directive (ref) is a generic block of explicit markup. Besides
746 roles, it is one of the extension mechanisms of reST, and Sphinx makes
747 heavy use of it.
748 Docutils supports the following directives:
750 · Admonitions: attention, caution, danger, error, hint, important,
752 note, tip, warning and the generic admonition. (Most themes style
753 only "note" and "warning" specially.)
754 · Images:
756 · image (see also Images below)
758 · figure (an image with caption and optional legend)
760 · Additional body elements:
762 · contents (a local, i.e. for the current file only, table of con‐
764 tents)
765 · container (a container with a custom class, useful to generate an
767 outer <div> in HTML)
768 · rubric (a heading without relation to the document sectioning)
770 · topic, sidebar (special highlighted body elements)
772 · parsed-literal (literal block that supports inline markup)
774 · epigraph (a block quote with optional attribution line)
776 · highlights, pull-quote (block quotes with their own class
778 attribute)
779 · compound (a compound paragraph)
781 · Special tables:
783 · table (a table with title)
785 · csv-table (a table generated from comma-separated values)
787 · list-table (a table generated from a list of lists)
789 · Special directives:
791 · raw (include raw target-format markup)
793 · include (include reStructuredText from another file) -- in Sphinx,
795 when given an absolute include file path, this directive takes it
796 as relative to the source directory
797 · class (assign a class attribute to the next element) [1]
799 · HTML specifics:
801 · meta (generation of HTML <meta> tags)
803 · title (override document title)
805 · Influencing markup:
807 · default-role (set a new default role)
809 · role (create a new role)
811 Since these are only per-file, better use Sphinx' facilities for set‐
813 ting the default_role.
814 Do not use the directives sectnum, header and footer.
816 Directives added by Sphinx are described in sphinxmarkup.
818 Basically, a directive consists of a name, arguments, options and con‐
820 tent. (Keep this terminology in mind, it is used in the next chapter
821 describing custom directives.) Looking at this example,
822 .. function:: foo(x)
824 foo(y, z)
825 :module: some.module.name
826 Return a line of text input from the user.
828 function is the directive name. It is given two arguments here, the
830 remainder of the first line and the second line, as well as one option
831 module (as you can see, options are given in the lines immediately fol‐
832 lowing the arguments and indicated by the colons). Options must be
833 indented to the same level as the directive content.
834 The directive content follows after a blank line and is indented rela‐
836 tive to the directive start.
837 Images
839 reST supports an image directive (ref), used like so:
840 .. image:: gnu.png
842 (options)
843 When used within Sphinx, the file name given (here gnu.png) must either
845 be relative to the source file, or absolute which means that they are
846 relative to the top source directory. For example, the file
847 sketch/spam.rst could refer to the image images/spam.png as
848 ../images/spam.png or /images/spam.png.
849 Sphinx will automatically copy image files over to a subdirectory of
851 the output directory on building (e.g. the _static directory for HTML
852 output.)
853 Interpretation of image size options (width and height) is as follows:
855 if the size has no unit or the unit is pixels, the given size will only
856 be respected for output channels that support pixels (i.e. not in LaTeX
857 output). Other units (like pt for points) will be used for HTML and
858 LaTeX output.
859 Sphinx extends the standard docutils behavior by allowing an asterisk
861 for the extension:
862 .. image:: gnu.*
864 Sphinx then searches for all images matching the provided pattern and
866 determines their type. Each builder then chooses the best image out of
867 these candidates. For instance, if the file name gnu.* was given and
868 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
869 builder would choose the former, while the HTML builder would prefer
870 the latter.
871 Changed in version 0.4: Added the support for file names ending in an
873 asterisk.
874 Changed in version 0.6: Image paths can now be absolute.
876 Footnotes
878 For footnotes (ref), use [#name]_ to mark the footnote location, and
879 add the footnote body at the bottom of the document after a "Footnotes"
880 rubric heading, like so:
881 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
883 .. rubric:: Footnotes
885 .. [#f1] Text of the first footnote.
887 .. [#f2] Text of the second footnote.
888 You can also explicitly number the footnotes ([1]_) or use auto-num‐
890 bered footnotes without names ([#]_).
891 Citations
893 Standard reST citations (ref) are supported, with the additional fea‐
894 ture that they are "global", i.e. all citations can be referenced from
895 all files. Use them like so:
896 Lorem ipsum [Ref]_ dolor sit amet.
898 .. [Ref] Book or article reference, URL or whatever.
900 Citation usage is similar to footnote usage, but with a label that is
902 not numeric or begins with #.
903 Substitutions
905 reST supports "substitutions" (ref), which are pieces of text and/or
906 markup referred to in the text by |name|. They are defined like foot‐
907 notes with explicit markup blocks, like this:
908 .. |name| replace:: replacement *text*
910 or this:
912 .. |caution| image:: warning.png
914 :alt: Warning!
915 See the reST reference for substitutions for details.
917 If you want to use some substitutions for all documents, put them into
919 rst_prolog or put them into a separate file and include it into all
920 documents you want to use them in, using the include directive. (Be
921 sure to give the include file a file name extension differing from that
922 of other source files, to avoid Sphinx finding it as a standalone docu‐
923 ment.)
924 Sphinx defines some default substitutions, see default-substitutions.
926 Comments
928 Every explicit markup block which isn't a valid markup construct (like
929 the footnotes above) is regarded as a comment (ref). For example:
930 .. This is a comment.
932 You can indent text after a comment start to form multiline comments:
934 ..
936 This whole indented block
937 is a comment.
938 Still in the comment.
940 Source encoding
942 Since the easiest way to include special characters like em dashes or
943 copyright signs in reST is to directly write them as Unicode charac‐
944 ters, one has to specify an encoding. Sphinx assumes source files to
945 be encoded in UTF-8 by default; you can change this with the
946 source_encoding config value.
947 Gotchas
949 There are some problems one commonly runs into while authoring reST
950 documents:
951 · Separation of inline markup: As said above, inline markup spans must
953 be separated from the surrounding text by non-word characters, you
954 have to use a backslash-escaped space to get around that. See the
955 reference for the details.
956 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
958 sible.
959
961 [1] When the default domain contains a class directive, this directive
962 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
963
965 Sphinx adds a lot of new directives and interpreted text roles to
966 standard reST markup. This section contains the reference material for
967 these facilities.
968 The TOC tree
970 Since reST does not have facilities to interconnect several documents,
971 or split documents into multiple output files, Sphinx uses a custom
972 directive to add relations between the single files the documentation
973 is made of, as well as tables of contents. The toctree directive is
974 the central element.
975 NOTE:
977 Simple "inclusion" of one file in another can be done with the
978 include directive.
979 .. toctree::
981 This directive inserts a "TOC tree" at the current location,
982 using the individual TOCs (including "sub-TOC trees") of the
983 documents given in the directive body. Relative document names
984 (not beginning with a slash) are relative to the document the
985 directive occurs in, absolute names are relative to the source
986 directory. A numeric maxdepth option may be given to indicate
987 the depth of the tree; by default, all levels are included. [1]
988 Consider this example (taken from the Python docs' library ref‐
990 erence index):
991 .. toctree::
993 :maxdepth: 2
994 intro
996 strings
997 datatypes
998 numeric
999 (many more documents listed here)
1000 This accomplishes two things:
1002 · Tables of contents from all those documents are inserted, with
1004 a maximum depth of two, that means one nested heading. toc‐
1005 tree directives in those documents are also taken into
1006 account.
1007 · Sphinx knows that the relative order of the documents intro,
1009 strings and so forth, and it knows that they are children of
1010 the shown document, the library index. From this information
1011 it generates "next chapter", "previous chapter" and "parent
1012 chapter" links.
1013 Entries
1015 Document titles in the toctree will be automatically read from
1017 the title of the referenced document. If that isn't what you
1018 want, you can specify an explicit title and target using a simi‐
1019 lar syntax to reST hyperlinks (and Sphinx's cross-referencing
1020 syntax). This looks like:
1021 .. toctree::
1023 intro
1025 All about strings <strings>
1026 datatypes
1027 The second line above will link to the strings document, but
1029 will use the title "All about strings" instead of the title of
1030 the strings document.
1031 You can also add external links, by giving an HTTP URL instead
1033 of a document name.
1034 Section numbering
1036 If you want to have section numbers even in HTML output, give
1038 the toctree a numbered option. For example:
1039 .. toctree::
1041 :numbered:
1042 foo
1044 bar
1045 Numbering then starts at the heading of foo. Sub-toctrees are
1047 automatically numbered (don't give the numbered flag to those).
1048 Numbering up to a specific depth is also possible, by giving the
1050 depth as a numeric argument to numbered.
1051 Additional options
1053 If you want only the titles of documents in the tree to show up,
1055 not other headings of the same level, you can use the titlesonly
1056 option:
1057 .. toctree::
1059 :titlesonly:
1060 foo
1062 bar
1063 You can use "globbing" in toctree directives, by giving the glob
1065 flag option. All entries are then matched against the list of
1066 available documents, and matches are inserted into the list
1067 alphabetically. Example:
1068 .. toctree::
1070 :glob:
1071 intro*
1073 recipe/*
1074 *
1075 This includes first all documents whose names start with intro,
1077 then all documents in the recipe folder, then all remaining doc‐
1078 uments (except the one containing the directive, of course.) [2]
1079 The special entry name self stands for the document containing
1081 the toctree directive. This is useful if you want to generate a
1082 "sitemap" from the toctree.
1083 You can also give a "hidden" option to the directive, like this:
1085 .. toctree::
1087 :hidden:
1088 doc_1
1090 doc_2
1091 This will still notify Sphinx of the document hierarchy, but not
1093 insert links into the document at the location of the directive
1094 -- this makes sense if you intend to insert these links your‐
1095 self, in a different style, or in the HTML sidebar.
1096 In the end, all documents in the source directory (or subdirec‐
1098 tories) must occur in some toctree directive; Sphinx will emit a
1099 warning if it finds a file that is not included, because that
1100 means that this file will not be reachable through standard nav‐
1101 igation. Use unused_docs to explicitly exclude documents from
1102 building, and exclude_trees to exclude whole directories.
1103 The "master document" (selected by master_doc) is the "root" of
1105 the TOC tree hierarchy. It can be used as the documentation's
1106 main page, or as a "full table of contents" if you don't give a
1107 maxdepth option.
1108 Changed in version 0.3: Added "globbing" option.
1110 Changed in version 0.6: Added "numbered" and "hidden" options as
1112 well as external links and support for "self" references.
1113 Changed in version 1.0: Added "titlesonly" option.
1115 Changed in version 1.1: Added numeric argument to "numbered".
1117 Special names
1119 Sphinx reserves some document names for its own use; you should not try
1120 to create documents with these names -- it will cause problems.
1121 The special document names (and pages generated for them) are:
1123 · genindex, modindex, search
1125 These are used for the general index, the Python module index, and
1127 the search page, respectively.
1128 The general index is populated with entries from modules, all
1130 index-generating object descriptions, and from index directives.
1131 The Python module index contains one entry per py:module directive.
1133 The search page contains a form that uses the generated JSON search
1135 index and JavaScript to full-text search the generated documents for
1136 search words; it should work on every major browser that supports
1137 modern JavaScript.
1138 · every name beginning with _
1140 Though only few such names are currently used by Sphinx, you should
1142 not create documents or document-containing directories with such
1143 names. (Using _ as a prefix for a custom template directory is
1144 fine.)
1145
1147 [1] The maxdepth option does not apply to the LaTeX writer, where the
1148 whole table of contents will always be presented at the begin of
1149 the document, and its depth is controlled by the tocdepth counter,
1150 which you can reset in your latex_preamble config value using e.g.
1151 \setcounter{tocdepth}{2}.
1152 [2] A note on available globbing syntax: you can use the standard
1154 shell constructs *, ?, [...] and [!...] with the feature that
1155 these all don't match slashes. A double star ** can be used to
1156 match any sequence of characters including slashes.
1157 Paragraph-level markup
1159 These directives create short paragraphs and can be used inside infor‐
1160 mation units as well as normal text:
1161 .. note::
1163 An especially important bit of information about an API that a
1164 user should be aware of when using whatever bit of API the note
1165 pertains to. The content of the directive should be written in
1166 complete sentences and include all appropriate punctuation.
1167 Example:
1169 .. note::
1171 This function is not suitable for sending spam e-mails.
1173 .. warning::
1175 An important bit of information about an API that a user should
1176 be very aware of when using whatever bit of API the warning per‐
1177 tains to. The content of the directive should be written in
1178 complete sentences and include all appropriate punctuation. This
1179 differs from note in that it is recommended over note for infor‐
1180 mation regarding security.
1181 .. versionadded:: version
1183 This directive documents the version of the project which added
1184 the described feature to the library or C API. When this applies
1185 to an entire module, it should be placed at the top of the mod‐
1186 ule section before any prose.
1187 The first argument must be given and is the version in question;
1189 you can add a second argument consisting of a brief explanation
1190 of the change.
1191 Example:
1193 .. versionadded:: 2.5
1195 The *spam* parameter.
1196 Note that there must be no blank line between the directive head
1198 and the explanation; this is to make these blocks visually con‐
1199 tinuous in the markup.
1200 .. versionchanged:: version
1202 Similar to versionadded, but describes when and what changed in
1203 the named feature in some way (new parameters, changed side
1204 effects, etc.).
1205 .. deprecated:: version
1207 Similar to versionchanged, but describes when the feature was
1208 deprecated. An explanation can also be given, for example to
1209 inform the reader what should be used instead. Example:
1210 .. deprecated:: 3.1
1212 Use :func:`spam` instead.
1213 ----
1216 .. seealso::
1220 Many sections include a list of references to module documenta‐
1221 tion or external documents. These lists are created using the
1222 seealso directive.
1223 The seealso directive is typically placed in a section just
1225 before any sub-sections. For the HTML output, it is shown boxed
1226 off from the main flow of the text.
1227 The content of the seealso directive should be a reST definition
1229 list. Example:
1230 .. seealso::
1232 Module :py:mod:`zipfile`
1234 Documentation of the :py:mod:`zipfile` standard module.
1235 `GNU tar manual, Basic Tar Format <http://link>`_
1237 Documentation for tar archive files, including GNU tar extensions.
1238 There's also a "short form" allowed that looks like this:
1240 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1242 New in version 0.5: The short form.
1244 .. rubric:: title
1246 This directive creates a paragraph heading that is not used to
1247 create a table of contents node.
1248 NOTE:
1250 If the title of the rubric is "Footnotes" (or the selected
1251 language's equivalent), this rubric is ignored by the LaTeX
1252 writer, since it is assumed to only contain footnote defini‐
1253 tions and therefore would create an empty heading.
1254 .. centered::
1256 This directive creates a centered boldfaced line of text. Use
1257 it as follows:
1258 .. centered:: LICENSE AGREEMENT
1260 Deprecated since version 1.1: This presentation-only directive
1262 is a legacy from older versions. Use a rst-class directive
1263 instead and add an appropriate style.
1264 .. hlist::
1266 This directive must contain a bullet list. It will transform it
1267 into a more compact list by either distributing more than one
1268 item horizontally, or reducing spacing between items, depending
1269 on the builder.
1270 For builders that support the horizontal distribution, there is
1272 a columns option that specifies the number of columns; it
1273 defaults to 2. Example:
1274 .. hlist::
1276 :columns: 3
1277 * A list of
1279 * short items
1280 * that should be
1281 * displayed
1282 * horizontally
1283 New in version 0.6.
1285 Table-of-contents markup
1287 The toctree directive, which generates tables of contents of subdocu‐
1288 ments, is described in toctree-directive.
1289 For local tables of contents, use the standard reST contents directive.
1291 Glossary
1293 .. glossary::
1294 This directive must contain a reST definition-list-like markup
1295 with terms and definitions. The definitions will then be refer‐
1296 encable with the term role. Example:
1297 .. glossary::
1299 environment
1301 A structure where information about all documents under the root is
1302 saved, and used for cross-referencing. The environment is pickled
1303 after the parsing stage, so that successive runs only need to read
1304 and parse new and changed documents.
1305 source directory
1307 The directory which, including its subdirectories, contains all
1308 source files for one Sphinx project.
1309 In contrast to regular definition lists, multiple terms per
1311 entry are allowed, and inline markup is allowed in terms. You
1312 can link to all of the terms. For example:
1313 .. glossary::
1315 term 1
1317 term 2
1318 Definition of both terms.
1319 (When the glossary is sorted, the first term determines the sort
1321 order.)
1322 New in version 0.6: You can now give the glossary directive a
1324 :sorted: flag that will automatically sort the entries alphabet‐
1325 ically.
1326 Changed in version 1.1: Now supports multiple terms and inline
1328 markup in terms.
1329 Grammar production displays
1331 Special markup is available for displaying the productions of a formal
1332 grammar. The markup is simple and does not attempt to model all
1333 aspects of BNF (or any derived forms), but provides enough to allow
1334 context-free grammars to be displayed in a way that causes uses of a
1335 symbol to be rendered as hyperlinks to the definition of the symbol.
1336 There is this directive:
1337 .. productionlist:: [name]
1339 This directive is used to enclose a group of productions. Each
1340 production is given on a single line and consists of a name,
1341 separated by a colon from the following definition. If the def‐
1342 inition spans multiple lines, each continuation line must begin
1343 with a colon placed at the same column as in the first line.
1344 The argument to productionlist serves to distinguish different
1346 sets of production lists that belong to different grammars.
1347 Blank lines are not allowed within productionlist directive
1349 arguments.
1350 The definition can contain token names which are marked as
1352 interpreted text (e.g. sum ::= `integer` "+" `integer`) -- this
1353 generates cross-references to the productions of these tokens.
1354 Outside of the production list, you can reference to token pro‐
1355 ductions using token.
1356 Note that no further reST parsing is done in the production, so
1358 that you don't have to escape * or | characters.
1359 The following is an example taken from the Python Reference Manual:
1361 .. productionlist::
1363 try_stmt: try1_stmt | try2_stmt
1364 try1_stmt: "try" ":" `suite`
1365 : ("except" [`expression` ["," `target`]] ":" `suite`)+
1366 : ["else" ":" `suite`]
1367 : ["finally" ":" `suite`]
1368 try2_stmt: "try" ":" `suite`
1369 : "finally" ":" `suite`
1370 Showing code examples
1372 Examples of Python source code or interactive sessions are represented
1373 using standard reST literal blocks. They are started by a :: at the
1374 end of the preceding paragraph and delimited by indentation.
1375 Representing an interactive session requires including the prompts and
1377 output along with the Python code. No special markup is required for
1378 interactive sessions. After the last line of input or output pre‐
1379 sented, there should not be an "unused" primary prompt; this is an
1380 example of what not to do:
1381 >>> 1 + 1
1383 2
1384 >>>
1385 Syntax highlighting is done with Pygments (if it's installed) and han‐
1387 dled in a smart way:
1388 · There is a "highlighting language" for each source file. Per
1390 default, this is 'python' as the majority of files will have to high‐
1391 light Python snippets, but the doc-wide default can be set with the
1392 highlight_language config value.
1393 · Within Python highlighting mode, interactive sessions are recognized
1395 automatically and highlighted appropriately. Normal Python code is
1396 only highlighted if it is parseable (so you can use Python as the
1397 default, but interspersed snippets of shell commands or other code
1398 blocks will not be highlighted as Python).
1399 · The highlighting language can be changed using the highlight direc‐
1401 tive, used as follows:
1402 .. highlight:: c
1404 This language is used until the next highlight directive is encoun‐
1406 tered.
1407 · For documents that have to show snippets in different languages,
1409 there's also a code-block directive that is given the highlighting
1410 language directly:
1411 .. code-block:: ruby
1413 Some Ruby code.
1415 The directive's alias name sourcecode works as well.
1417 · The valid values for the highlighting language are:
1419 · none (no highlighting)
1421 · python (the default when highlight_language isn't set)
1423 · guess (let Pygments guess the lexer based on contents, only works
1425 with certain well-recognizable languages)
1426 · rest
1428 · c
1430 · ... and any other lexer name that Pygments supports.
1432 · If highlighting with the selected language fails, the block is not
1434 highlighted in any way.
1435 Line numbers
1437 If installed, Pygments can generate line numbers for code blocks. For
1438 automatically-highlighted blocks (those started by ::), line numbers
1439 must be switched on in a highlight directive, with the linenothreshold
1440 option:
1441 .. highlight:: python
1443 :linenothreshold: 5
1444 This will produce line numbers for all code blocks longer than five
1446 lines.
1447 For code-block blocks, a linenos flag option can be given to switch on
1449 line numbers for the individual block:
1450 .. code-block:: ruby
1452 :linenos:
1453 Some more Ruby code.
1455 Additionally, an emphasize-lines option can be given to have Pygments
1457 emphasize particular lines:
1458 .. code-block:: python
1460 :emphasize-lines: 3,5
1461 def some_function():
1463 interesting = False
1464 print 'This line is highlighted.'
1465 print 'This one is not...'
1466 print '...but this one is.'
1467 Changed in version 1.1: emphasize-lines has been added.
1469 Includes
1471 .. literalinclude:: filename
1472 Longer displays of verbatim text may be included by storing the
1473 example text in an external file containing only plain text.
1474 The file may be included using the literalinclude directive. [1]
1475 For example, to include the Python source file example.py, use:
1476 .. literalinclude:: example.py
1478 The file name is usually relative to the current file's path.
1480 However, if it is absolute (starting with /), it is relative to
1481 the top source directory.
1482 Tabs in the input are expanded if you give a tab-width option
1484 with the desired tab width.
1485 The directive also supports the linenos flag option to switch on
1487 line numbers, the emphasize-lines option to emphasize particular
1488 lines, and a language option to select a language different from
1489 the current file's standard language. Example with options:
1490 .. literalinclude:: example.rb
1492 :language: ruby
1493 :emphasize-lines: 12,15-18
1494 :linenos:
1495 Include files are assumed to be encoded in the source_encoding.
1497 If the file has a different encoding, you can specify it with
1498 the encoding option:
1499 .. literalinclude:: example.py
1501 :encoding: latin-1
1502 The directive also supports including only parts of the file.
1504 If it is a Python module, you can select a class, function or
1505 method to include using the pyobject option:
1506 .. literalinclude:: example.py
1508 :pyobject: Timer.start
1509 This would only include the code lines belonging to the start()
1511 method in the Timer class within the file.
1512 Alternately, you can specify exactly which lines to include by
1514 giving a lines option:
1515 .. literalinclude:: example.py
1517 :lines: 1,3,5-10,20-
1518 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
1520 line.
1521 Another way to control which part of the file is included is to
1523 use the start-after and end-before options (or only one of
1524 them). If start-after is given as a string option, only lines
1525 that follow the first line containing that string are included.
1526 If end-before is given as a string option, only lines that pre‐
1527 cede the first lines containing that string are included.
1528 You can prepend and/or append a line to the included code, using
1530 the prepend and append option, respectively. This is useful
1531 e.g. for highlighting PHP code that doesn't include the <?php/?>
1532 markers.
1533 New in version 0.4.3: The encoding option.
1535 New in version 0.6: The pyobject, lines, start-after and
1537 end-before options, as well as support for absolute filenames.
1538 New in version 1.0: The prepend and append options, as well as
1540 tab-width.
1541
1543 [1] There is a standard .. include directive, but it raises errors if
1544 the file is not found. This one only emits a warning.
1545 Inline markup
1547 Sphinx uses interpreted text roles to insert semantic markup into docu‐
1548 ments. They are written as :rolename:`content`.
1549 NOTE:
1551 The default role (`content`) has no special meaning by default. You
1552 are free to use it for anything you like, e.g. variable names; use
1553 the default_role config value to set it to a known role.
1554 See domains for roles added by domains.
1556 Cross-referencing syntax
1558 Cross-references are generated by many semantic interpreted text roles.
1559 Basically, you only need to write :role:`target`, and a link will be
1560 created to the item named target of the type indicated by role. The
1561 links's text will be the same as target.
1562 There are some additional facilities, however, that make cross-refer‐
1564 encing roles more versatile:
1565 · You may supply an explicit title and reference target, like in reST
1567 direct hyperlinks: :role:`title <target>` will refer to target, but
1568 the link text will be title.
1569 · If you prefix the content with !, no reference/hyperlink will be cre‐
1571 ated.
1572 · If you prefix the content with ~, the link text will only be the last
1574 component of the target. For example, :py:meth:`~Queue.Queue.get`
1575 will refer to Queue.Queue.get but only display get as the link text.
1576 In HTML output, the link's title attribute (that is e.g. shown as a
1578 tool-tip on mouse-hover) will always be the full target name.
1579 Cross-referencing objects
1581 These roles are described with their respective domains:
1582 · Python
1584 · C
1586 · C++
1588 · JavaScript
1590 · ReST
1592 Cross-referencing arbitrary locations
1594 :ref: To support cross-referencing to arbitrary locations in any docu‐
1595 ment, the standard reST labels are used. For this to work label
1596 names must be unique throughout the entire documentation. There
1597 are two ways in which you can refer to labels:
1598 · If you place a label directly before a section title, you can
1600 reference to it with :ref:`label-name`. Example:
1601 .. _my-reference-label:
1603 Section to cross-reference
1605 --------------------------
1606 This is the text of the section.
1608 It refers to the section itself, see :ref:`my-reference-label`.
1610 The :ref: role would then generate a link to the section, with
1612 the link title being "Section to cross-reference". This works
1613 just as well when section and reference are in different
1614 source files.
1615 Automatic labels also work with figures: given
1617 .. _my-figure:
1619 .. figure:: whatever
1621 Figure caption
1623 a reference :ref:`my-figure` would insert a reference to the
1625 figure with link text "Figure caption".
1626 The same works for tables that are given an explicit caption
1628 using the table directive.
1629 · Labels that aren't placed before a section title can still be
1631 referenced to, but you must give the link an explicit title,
1632 using this syntax: :ref:`Link title <label-name>`.
1633 Using ref is advised over standard reStructuredText links to
1635 sections (like `Section title`_) because it works across files,
1636 when section headings are changed, and for all builders that
1637 support cross-references.
1638 Cross-referencing documents
1640 New in version 0.6.
1641 There is also a way to directly link to documents:
1643 :doc: Link to the specified document; the document name can be speci‐
1645 fied in absolute or relative fashion. For example, if the ref‐
1646 erence :doc:`parrot` occurs in the document sketches/index, then
1647 the link refers to sketches/parrot. If the reference is
1648 :doc:`/people` or :doc:`../people`, the link refers to people.
1649 If no explicit link text is given (like usual: :doc:`Monty
1651 Python members </people>`), the link caption will be the title
1652 of the given document.
1653 Referencing downloadable files
1655 New in version 0.6.
1656 :download:
1658 This role lets you link to files within your source tree that
1659 are not reST documents that can be viewed, but files that can be
1660 downloaded.
1661 When you use this role, the referenced file is automatically
1663 marked for inclusion in the output when building (obviously, for
1664 HTML output only). All downloadable files are put into the
1665 _downloads subdirectory of the output directory; duplicate file‐
1666 names are handled.
1667 An example:
1669 See :download:`this example script <../example.py>`.
1671 The given filename is usually relative to the directory the cur‐
1673 rent source file is contained in, but if it absolute (starting
1674 with /), it is taken as relative to the top source directory.
1675 The example.py file will be copied to the output directory, and
1677 a suitable link generated to it.
1678 Cross-referencing other items of interest
1680 The following roles do possibly create a cross-reference, but do not
1681 refer to objects:
1682 :envvar:
1684 An environment variable. Index entries are generated. Also
1685 generates a link to the matching envvar directive, if it exists.
1686 :token:
1688 The name of a grammar token (used to create links between pro‐
1689 ductionlist directives).
1690 :keyword:
1692 The name of a keyword in Python. This creates a link to a ref‐
1693 erence label with that name, if it exists.
1694 :option:
1696 A command-line option to an executable program. The leading
1697 hyphen(s) must be included. This generates a link to a option
1698 directive, if it exists.
1699 The following role creates a cross-reference to the term in the glos‐
1701 sary:
1702 :term: Reference to a term in the glossary. The glossary is created
1704 using the glossary directive containing a definition list with
1705 terms and definitions. It does not have to be in the same file
1706 as the term markup, for example the Python docs have one global
1707 glossary in the glossary.rst file.
1708 If you use a term that's not explained in a glossary, you'll get
1710 a warning during build.
1711 Other semantic markup
1713 The following roles don't do anything special except formatting the
1714 text in a different style:
1715 :abbr: An abbreviation. If the role content contains a parenthesized
1717 explanation, it will be treated specially: it will be shown in a
1718 tool-tip in HTML, and output only once in LaTeX.
1719 Example: :abbr:`LIFO (last-in, first-out)`.
1721 New in version 0.6.
1723 :command:
1725 The name of an OS-level command, such as rm.
1726 :dfn: Mark the defining instance of a term in the text. (No index
1728 entries are generated.)
1729 :file: The name of a file or directory. Within the contents, you can
1731 use curly braces to indicate a "variable" part, for example:
1732 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
1734 In the built documentation, the x will be displayed differently
1736 to indicate that it is to be replaced by the Python minor ver‐
1737 sion.
1738 :guilabel:
1740 Labels presented as part of an interactive user interface should
1741 be marked using guilabel. This includes labels from text-based
1742 interfaces such as those created using curses or other
1743 text-based libraries. Any label used in the interface should be
1744 marked with this role, including button labels, window titles,
1745 field names, menu and menu selection names, and even values in
1746 selection lists.
1747 Changed in version 1.0: An accelerator key for the GUI label can
1749 be included using an ampersand; this will be stripped and dis‐
1750 played underlined in the output (example: :guilabel:`&Cancel`).
1751 To include a literal ampersand, double it.
1752 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
1754 may depend on platform- or application-specific conventions.
1755 When there are no relevant conventions, the names of modifier
1756 keys should be spelled out, to improve accessibility for new
1757 users and non-native speakers. For example, an xemacs key
1758 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
1759 ence to a specific application or platform, the same sequence
1760 should be marked as :kbd:`Control-x Control-f`.
1761 :mailheader:
1763 The name of an RFC 822-style mail header. This markup does not
1764 imply that the header is being used in an email message, but can
1765 be used to refer to any header of the same "style." This is
1766 also used for headers defined by the various MIME specifica‐
1767 tions. The header name should be entered in the same way it
1768 would normally be found in practice, with the camel-casing con‐
1769 ventions being preferred where there is more than one common
1770 usage. For example: :mailheader:`Content-Type`.
1771 :makevar:
1773 The name of a make variable.
1774 :manpage:
1776 A reference to a Unix manual page including the section, e.g.
1777 :manpage:`ls(1)`.
1778 :menuselection:
1780 Menu selections should be marked using the menuselection role.
1781 This is used to mark a complete sequence of menu selections,
1782 including selecting submenus and choosing a specific operation,
1783 or any subsequence of such a sequence. The names of individual
1784 selections should be separated by -->.
1785 For example, to mark the selection "Start > Programs", use this
1787 markup:
1788 :menuselection:`Start --> Programs`
1790 When including a selection that includes some trailing indica‐
1792 tor, such as the ellipsis some operating systems use to indicate
1793 that the command opens a dialog, the indicator should be omitted
1794 from the selection name.
1795 menuselection also supports ampersand accelerators just like
1797 guilabel.
1798 :mimetype:
1800 The name of a MIME type, or a component of a MIME type (the
1801 major or minor portion, taken alone).
1802 :newsgroup:
1804 The name of a Usenet newsgroup.
1805 :program:
1807 The name of an executable program. This may differ from the
1808 file name for the executable for some platforms. In particular,
1809 the .exe (or other) extension should be omitted for Windows pro‐
1810 grams.
1811 :regexp:
1813 A regular expression. Quotes should not be included.
1814 :samp: A piece of literal text, such as code. Within the contents, you
1816 can use curly braces to indicate a "variable" part, as in file.
1817 For example, in :samp:`print 1+{variable}`, the part variable
1818 would be emphasized.
1819 If you don't need the "variable part" indication, use the stan‐
1821 dard ``code`` instead.
1822 There is also an index role to generate index entries.
1824 The following roles generate external links:
1826 :pep: A reference to a Python Enhancement Proposal. This generates
1828 appropriate index entries. The text "PEP number" is generated;
1829 in the HTML output, this text is a hyperlink to an online copy
1830 of the specified PEP. You can link to a specific section by
1831 saying :pep:`number#anchor`.
1832 :rfc: A reference to an Internet Request for Comments. This generates
1834 appropriate index entries. The text "RFC number" is generated;
1835 in the HTML output, this text is a hyperlink to an online copy
1836 of the specified RFC. You can link to a specific section by
1837 saying :rfc:`number#anchor`.
1838 Note that there are no special roles for including hyperlinks as you
1840 can use the standard reST markup for that purpose.
1841 Substitutions
1843 The documentation system provides three substitutions that are defined
1844 by default. They are set in the build configuration file.
1845 |release|
1847 Replaced by the project release the documentation refers to.
1848 This is meant to be the full version string including
1849 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
1850 release.
1851 |version|
1853 Replaced by the project version the documentation refers to.
1854 This is meant to consist only of the major and minor version
1855 parts, e.g. 2.5, even for version 2.5.1. Set by version.
1856 |today|
1858 Replaced by either today's date (the date on which the document
1859 is read), or the date set in the build configuration file. Nor‐
1860 mally has the format April 14, 2007. Set by today_fmt and
1861 today.
1862 Miscellaneous markup
1864 File-wide metadata
1865 reST has the concept of "field lists"; these are a sequence of fields
1866 marked up like this:
1867 :fieldname: Field content
1869 A field list near the top of a file is parsed by docutils as the
1871 "docinfo" which is normally used to record the author, date of publica‐
1872 tion and other metadata. In Sphinx, a field list preceding any other
1873 markup is moved from the docinfo to the Sphinx environment as document
1874 metadata and is not displayed in the output; a field list appearing
1875 after the document title will be part of the docinfo as normal and will
1876 be displayed in the output.
1877 At the moment, these metadata fields are recognized:
1879 tocdepth
1881 The maximum depth for a table of contents of this file.
1882 New in version 0.4.
1884 nocomments
1886 If set, the web application won't display a comment form for a
1887 page generated from this source file.
1888 orphan If set, warnings about this file not being included in any toc‐
1890 tree will be suppressed.
1891 New in version 1.0.
1893 Meta-information markup
1895 .. sectionauthor:: name <email>
1896 Identifies the author of the current section. The argument
1897 should include the author's name such that it can be used for
1898 presentation and email address. The domain name portion of the
1899 address should be lower case. Example:
1900 .. sectionauthor:: Guido van Rossum <guido@python.org>
1902 By default, this markup isn't reflected in the output in any way
1904 (it helps keep track of contributions), but you can set the con‐
1905 figuration value show_authors to True to make them produce a
1906 paragraph in the output.
1907 .. codeauthor:: name <email>
1909 The codeauthor directive, which can appear multiple times, names
1910 the authors of the described code, just like sectionauthor names
1911 the author(s) of a piece of documentation. It too only produces
1912 output if the show_authors configuration value is True.
1913 Index-generating markup
1915 Sphinx automatically creates index entries from all object descriptions
1916 (like functions, classes or attributes) like discussed in domains.
1917 However, there is also explicit markup available, to make the index
1919 more comprehensive and enable index entries in documents where informa‐
1920 tion is not mainly contained in information units, such as the language
1921 reference.
1922 .. index:: <entries>
1924 This directive contains one or more index entries. Each entry
1925 consists of a type and a value, separated by a colon.
1926 For example:
1928 .. index::
1930 single: execution; context
1931 module: __main__
1932 module: sys
1933 triple: module; search; path
1934 The execution context
1936 ---------------------
1937 ...
1939 This directive contains five entries, which will be converted to
1941 entries in the generated index which link to the exact location
1942 of the index statement (or, in case of offline media, the corre‐
1943 sponding page number).
1944 Since index directives generate cross-reference targets at their
1946 location in the source, it makes sense to put them before the
1947 thing they refer to -- e.g. a heading, as in the example above.
1948 The possible entry types are:
1950 single Creates a single index entry. Can be made a subentry by
1952 separating the subentry text with a semicolon (this nota‐
1953 tion is also used below to describe what entries are cre‐
1954 ated).
1955 pair pair: loop; statement is a shortcut that creates two
1957 index entries, namely loop; statement and statement;
1958 loop.
1959 triple Likewise, triple: module; search; path is a shortcut that
1961 creates three index entries, which are module; search
1962 path, search; path, module and path; module search.
1963 see see: entry; other creates an index entry that refers from
1965 entry to other.
1966 seealso
1968 Like see, but inserts "see also" instead of "see".
1969 module, keyword, operator, object, exception, statement, builtin
1971 These all create two index entries. For example, module:
1972 hashlib creates the entries module; hashlib and hashlib;
1973 module. (These are Python-specific and therefore depre‐
1974 cated.)
1975 You can mark up "main" index entries by prefixing them with an
1977 exclamation mark. The references to "main" entries are empha‐
1978 sized in the generated index. For example, if two pages contain
1979 .. index:: Python
1981 and one page contains
1983 .. index:: ! Python
1985 then the backlink to the latter page is emphasized among the
1987 three backlinks.
1988 For index directives containing only "single" entries, there is
1990 a shorthand notation:
1991 .. index:: BNF, grammar, syntax, notation
1993 This creates four index entries.
1995 Changed in version 1.1: Added see and seealso types, as well as
1997 marking main entries.
1998 :index:
2000 While the index directive is a block-level markup and links to
2001 the beginning of the next paragraph, there is also a correspond‐
2002 ing role that sets the link target directly where it is used.
2003 The content of the role can be a simple phrase, which is then
2005 kept in the text and used as an index entry. It can also be a
2006 combination of text and index entry, styled like with explicit
2007 targets of cross-references. In that case, the "target" part
2008 can be a full entry as described for the directive above. For
2009 example:
2010 This is a normal reST :index:`paragraph` that contains several
2012 :index:`index entries <pair: index; entry>`.
2013 New in version 1.1.
2015 Including content based on tags
2017 .. only:: <expression>
2018 Include the content of the directive only if the expression is
2019 true. The expression should consist of tags, like this:
2020 .. only:: html and draft
2022 Undefined tags are false, defined tags (via the -t command-line
2024 option or within conf.py) are true. Boolean expressions, also
2025 using parentheses (like html and (latex or draft)) are sup‐
2026 ported.
2027 The format of the current builder (html, latex or text) is
2029 always set as a tag.
2030 NOTE:
2032 Due to docutils' specifics of parsing of directive content,
2033 you cannot put a section with the same level as the main doc‐
2034 ument heading inside an only directive. Such sections will
2035 appear to be ignored in the parsed document.
2036 New in version 0.6.
2038 Tables
2040 Use standard reStructuredText tables. They work fine in HTML output,
2041 however there are some gotchas when using tables in LaTeX: the column
2042 width is hard to determine correctly automatically. For this reason,
2043 the following directive exists:
2044 .. tabularcolumns:: column spec
2046 This directive gives a "column spec" for the next table occur‐
2047 ring in the source file. The spec is the second argument to the
2048 LaTeX tabulary package's environment (which Sphinx uses to
2049 translate tables). It can have values like
2050 |l|l|l|
2052 which means three left-adjusted, nonbreaking columns. For col‐
2054 umns with longer text that should automatically be broken, use
2055 either the standard p{width} construct, or tabulary's automatic
2056 specifiers:
2057 ┌──┬────────────────────────────┐
2059 │L │ ragged-left column with │
2060 │ │ automatic width │
2061 ├──┼────────────────────────────┤
2062 │R │ ragged-right column with │
2063 │ │ automatic width │
2064 ├──┼────────────────────────────┤
2065 │C │ centered column with auto‐ │
2066 │ │ matic width │
2067 ├──┼────────────────────────────┤
2068 │J │ justified column with │
2069 │ │ automatic width │
2070 └──┴────────────────────────────┘
2071 The automatic width is determined by rendering the content in
2073 the table, and scaling them according to their share of the
2074 total width.
2075 By default, Sphinx uses a table layout with L for every column.
2077 New in version 0.3.
2079 WARNING:
2081 Tables that contain list-like elements such as object descriptions,
2082 blockquotes or any kind of lists cannot be set out of the box with
2083 tabulary. They are therefore set with the standard LaTeX tabular
2084 environment if you don't give a tabularcolumns directive. If you
2085 do, the table will be set with tabulary, but you must use the
2086 p{width} construct for the columns that contain these elements.
2087 Literal blocks do not work with tabulary at all, so tables contain‐
2089 ing a literal block are always set with tabular. Also, the verbatim
2090 environment used for literal blocks only works in p{width} columns,
2091 which means that by default, Sphinx generates such column specs for
2092 such tables. Use the tabularcolumns directive to get finer control
2093 over such tables.
2094 More markup is added by domains.
2096
2098 New in version 1.0.
2099 What is a Domain?
2101 Originally, Sphinx was conceived for a single project, the documenta‐
2102 tion of the Python language. Shortly afterwards, it was made available
2103 for everyone as a documentation tool, but the documentation of Python
2104 modules remained deeply built in -- the most fundamental directives,
2105 like function, were designed for Python objects. Since Sphinx has
2106 become somewhat popular, interest developed in using it for many dif‐
2107 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2108 markup (like in this documentation).
2109 While this was always possible, it is now much easier to easily support
2111 documentation of projects using different programming languages or even
2112 ones not supported by the main Sphinx distribution, by providing a
2113 domain for every such purpose.
2114 A domain is a collection of markup (reStructuredText directives and
2116 roles) to describe and link to objects belonging together, e.g. ele‐
2117 ments of a programming language. Directive and role names in a domain
2118 have names like domain:name, e.g. py:function. Domains can also pro‐
2119 vide custom indices (like the Python Module Index).
2120 Having domains means that there are no naming problems when one set of
2122 documentation wants to refer to e.g. C++ and Python classes. It also
2123 means that extensions that support the documentation of whole new lan‐
2124 guages are much easier to write.
2125 This section describes what the domains that come with Sphinx provide.
2127 The domain API is documented as well, in the section domain-api.
2128 Basic Markup
2130 Most domains provide a number of object description directives, used to
2131 describe specific objects provided by modules. Each directive requires
2132 one or more signatures to provide basic information about what is being
2133 described, and the content should be the description. The basic ver‐
2134 sion makes entries in the general index; if no index entry is desired,
2135 you can give the directive option flag :noindex:. An example using a
2136 Python domain directive:
2137 .. py:function:: spam(eggs)
2139 ham(eggs)
2140 Spam or ham the foo.
2142 This describes the two Python functions spam and ham. (Note that when
2144 signatures become too long, you can break them if you add a backslash
2145 to lines that are continued in the next line. Example:
2146 .. py:function:: filterwarnings(action, message='', category=Warning, \
2148 module='', lineno=0, append=False)
2149 :noindex:
2150 (This example also shows how to use the :noindex: flag.)
2152 The domains also provide roles that link back to these object descrip‐
2154 tions. For example, to link to one of the functions described in the
2155 example above, you could say
2156 The function :py:func:`spam` does a similar thing.
2158 As you can see, both directive and role names contain the domain name
2160 and the directive name. Default Domain
2161 To avoid having to writing the domain name all the time when you e.g.
2163 only describe Python objects, a default domain can be selected with
2164 either the config value primary_domain or this directive:
2165 .. default-domain:: name
2167 Select a new default domain. While the primary_domain selects a
2168 global default, this only has an effect within the same file.
2169 If no other default is selected, the Python domain (named py) is the
2171 default one, mostly for compatibility with documentation written for
2172 older versions of Sphinx.
2173 Directives and roles that belong to the default domain can be mentioned
2175 without giving the domain name, i.e.
2176 .. function:: pyfunc()
2178 Describes a Python function.
2180 Reference to :func:`pyfunc`.
2182 Cross-referencing syntax
2184 For cross-reference roles provided by domains, the same facilities
2185 exist as for general cross-references. See xref-syntax.
2186 In short:
2188 · You may supply an explicit title and reference target: :role:`title
2190 <target>` will refer to target, but the link text will be title.
2191 · If you prefix the content with !, no reference/hyperlink will be cre‐
2193 ated.
2194 · If you prefix the content with ~, the link text will only be the last
2196 component of the target. For example, :py:meth:`~Queue.Queue.get`
2197 will refer to Queue.Queue.get but only display get as the link text.
2198 The Python Domain
2200 The Python domain (name py) provides the following directives for mod‐
2201 ule declarations:
2202 .. py:module:: name
2204 This directive marks the beginning of the description of a mod‐
2205 ule (or package submodule, in which case the name should be
2206 fully qualified, including the package name). It does not cre‐
2207 ate content (like e.g. py:class does).
2208 This directive will also cause an entry in the global module
2210 index.
2211 The platform option, if present, is a comma-separated list of
2213 the platforms on which the module is available (if it is avail‐
2214 able on all platforms, the option should be omitted). The keys
2215 are short identifiers; examples that are in use include "IRIX",
2216 "Mac", "Windows", and "Unix". It is important to use a key
2217 which has already been used when applicable.
2218 The synopsis option should consist of one sentence describing
2220 the module's purpose -- it is currently only used in the Global
2221 Module Index.
2222 The deprecated option can be given (with no value) to mark a
2224 module as deprecated; it will be designated as such in various
2225 locations then.
2226 .. py:currentmodule:: name
2228 This directive tells Sphinx that the classes, functions etc.
2229 documented from here are in the given module (like py:module),
2230 but it will not create index entries, an entry in the Global
2231 Module Index, or a link target for py:mod. This is helpful in
2232 situations where documentation for things in a module is spread
2233 over multiple files or sections -- one location has the py:mod‐
2234 ule directive, the others only py:currentmodule.
2235 The following directives are provided for module and class contents:
2237 .. py:data:: name
2239 Describes global data in a module, including both variables and
2240 values used as "defined constants." Class and object attributes
2241 are not documented using this environment.
2242 .. py:exception:: name
2244 Describes an exception class. The signature can, but need not
2245 include parentheses with constructor arguments.
2246 .. py:function:: name(signature)
2248 Describes a module-level function. The signature should include
2249 the parameters, enclosing optional parameters in brackets.
2250 Default values can be given if it enhances clarity; see signa‐
2251 tures. For example:
2252 .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
2254 Object methods are not documented using this directive. Bound
2256 object methods placed in the module namespace as part of the
2257 public interface of the module are documented using this, as
2258 they are equivalent to normal functions for most purposes.
2259 The description should include information about the parameters
2261 required and how they are used (especially whether mutable
2262 objects passed as parameters are modified), side effects, and
2263 possible exceptions. A small example may be provided.
2264 .. py:class:: name[(signature)]
2266 Describes a class. The signature can include parentheses with
2267 parameters which will be shown as the constructor arguments.
2268 See also signatures.
2269 Methods and attributes belonging to the class should be placed
2271 in this directive's body. If they are placed outside, the sup‐
2272 plied name should contain the class name so that cross-refer‐
2273 ences still work. Example:
2274 .. py:class:: Foo
2276 .. py:method:: quux()
2277 -- or --
2279 .. py:class:: Bar
2281 .. py:method:: Bar.quux()
2283 The first way is the preferred one.
2285 .. py:attribute:: name
2287 Describes an object data attribute. The description should
2288 include information about the type of the data to be expected
2289 and whether it may be changed directly.
2290 .. py:method:: name(signature)
2292 Describes an object method. The parameters should not include
2293 the self parameter. The description should include similar
2294 information to that described for function. See also signa‐
2295 tures.
2296 .. py:staticmethod:: name(signature)
2298 Like py:method, but indicates that the method is a static
2299 method.
2300 New in version 0.4.
2302 .. py:classmethod:: name(signature)
2304 Like py:method, but indicates that the method is a class method.
2305 New in version 0.6.
2307 .. py:decorator:: name
2309 .. py:decorator:: name(signature)
2311 Describes a decorator function. The signature should not repre‐
2312 sent the signature of the actual function, but the usage as a
2313 decorator. For example, given the functions
2314 def removename(func):
2316 func.__name__ = ''
2317 return func
2318 def setnewname(name):
2320 def decorator(func):
2321 func.__name__ = name
2322 return func
2323 return decorator
2324 the descriptions should look like this:
2326 .. py:decorator:: removename
2328 Remove name of the decorated function.
2330 .. py:decorator:: setnewname(name)
2332 Set name of the decorated function to *name*.
2334 There is no py:deco role to link to a decorator that is marked
2336 up with this directive; rather, use the py:func role.
2337 .. py:decoratormethod:: name
2339 .. py:decoratormethod:: name(signature)
2341 Same as py:decorator, but for decorators that are methods.
2342 Refer to a decorator method using the py:meth role.
2344 Python Signatures
2346 Signatures of functions, methods and class constructors can be given
2347 like they would be written in Python, with the exception that optional
2348 parameters can be indicated by brackets:
2349 .. py:function:: compile(source[, filename[, symbol]])
2351 It is customary to put the opening bracket before the comma. In addi‐
2353 tion to this "nested" bracket style, a "flat" style can also be used,
2354 due to the fact that most optional parameters can be given indepen‐
2355 dently:
2356 .. py:function:: compile(source[, filename, symbol])
2358 Default values for optional arguments can be given (but if they contain
2360 commas, they will confuse the signature parser). Python 3-style argu‐
2361 ment annotations can also be given as well as return type annotations:
2362 .. py:function:: compile(source : string[, filename, symbol]) -> ast object
2364 Info field lists
2366 New in version 0.4.
2367 Inside Python object description directives, reST field lists with
2369 these fields are recognized and formatted nicely:
2370 · param, parameter, arg, argument, key, keyword: Description of a
2372 parameter.
2373 · type: Type of a parameter.
2375 · raises, raise, except, exception: That (and when) a specific excep‐
2377 tion is raised.
2378 · var, ivar, cvar: Description of a variable.
2380 · returns, return: Description of the return value.
2382 · rtype: Return type.
2384 The field names must consist of one of these keywords and an argument
2386 (except for returns and rtype, which do not need an argument). This is
2387 best explained by an example:
2388 .. py:function:: format_exception(etype, value, tb[, limit=None])
2390 Format the exception with a traceback.
2392 :param etype: exception type
2394 :param value: exception value
2395 :param tb: traceback object
2396 :param limit: maximum number of stack frames to show
2397 :type limit: integer or None
2398 :rtype: list of strings
2399 This will render like this:
2401 format_exception(etype, value, tb[, limit=None])
2403 Format the exception with a traceback.
2404 Parameters
2406 · etype -- exception type
2408 · value -- exception value
2410 · tb -- traceback object
2412 · limit (integer or None) -- maximum number of stack
2414 frames to show
2415 Return type
2417 list of strings
2418 It is also possible to combine parameter type and description, if the
2420 type is a single word, like this:
2421 :param integer limit: maximum number of stack frames to show
2423 Cross-referencing Python objects
2425 The following roles refer to objects in modules and are possibly hyper‐
2426 linked if a matching identifier is found:
2427 :py:mod:
2429 Reference a module; a dotted name may be used. This should also
2430 be used for package names.
2431 :py:func:
2433 Reference a Python function; dotted names may be used. The role
2434 text needs not include trailing parentheses to enhance readabil‐
2435 ity; they will be added automatically by Sphinx if the add_func‐
2436 tion_parentheses config value is true (the default).
2437 :py:data:
2439 Reference a module-level variable.
2440 :py:const:
2442 Reference a "defined" constant. This may be a C-language
2443 #define or a Python variable that is not intended to be changed.
2444 :py:class:
2446 Reference a class; a dotted name may be used.
2447 :py:meth:
2449 Reference a method of an object. The role text can include the
2450 type name and the method name; if it occurs within the descrip‐
2451 tion of a type, the type name can be omitted. A dotted name may
2452 be used.
2453 :py:attr:
2455 Reference a data attribute of an object.
2456 :py:exc:
2458 Reference an exception. A dotted name may be used.
2459 :py:obj:
2461 Reference an object of unspecified type. Useful e.g. as the
2462 default_role.
2463 New in version 0.4.
2465 The name enclosed in this markup can include a module name and/or a
2467 class name. For example, :py:func:`filter` could refer to a function
2468 named filter in the current module, or the built-in function of that
2469 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
2470 function in the foo module.
2471 Normally, names in these roles are searched first without any further
2473 qualification, then with the current module name prepended, then with
2474 the current module and class name (if any) prepended. If you prefix
2475 the name with a dot, this order is reversed. For example, in the docu‐
2476 mentation of Python's codecs module, :py:func:`open` always refers to
2477 the built-in function, while :py:func:`.open` refers to codecs.open().
2478 A similar heuristic is used to determine whether the name is an
2480 attribute of the currently documented class.
2481 Also, if the name is prefixed with a dot, and no exact match is found,
2483 the target is taken as a suffix and all object names with that suffix
2484 are searched. For example, :py:meth:`.TarFile.close` references the
2485 tarfile.TarFile.close() function, even if the current module is not
2486 tarfile. Since this can get ambiguous, if there is more than one pos‐
2487 sible match, you will get a warning from Sphinx.
2488 Note that you can combine the ~ and . prefixes:
2490 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
2491 method, but the visible link caption will only be close().
2492 The C Domain
2494 The C domain (name c) is suited for documentation of C API.
2495 .. c:function:: type name(signature)
2497 Describes a C function. The signature should be given as in C,
2498 e.g.:
2499 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
2501 This is also used to describe function-like preprocessor macros.
2503 The names of the arguments should be given so they may be used
2504 in the description.
2505 Note that you don't have to backslash-escape asterisks in the
2507 signature, as it is not parsed by the reST inliner.
2508 .. c:member:: type name
2510 Describes a C struct member. Example signature:
2511 .. c:member:: PyObject* PyTypeObject.tp_bases
2513 The text of the description should include the range of values
2515 allowed, how the value should be interpreted, and whether the
2516 value can be changed. References to structure members in text
2517 should use the member role.
2518 .. c:macro:: name
2520 Describes a "simple" C macro. Simple macros are macros which
2521 are used for code expansion, but which do not take arguments so
2522 cannot be described as functions. This is not to be used for
2523 simple constant definitions. Examples of its use in the Python
2524 documentation include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
2525 .. c:type:: name
2527 Describes a C type (whether defined by a typedef or struct). The
2528 signature should just be the type name.
2529 .. c:var:: type name
2531 Describes a global C variable. The signature should include the
2532 type, such as:
2533 .. c:var:: PyObject* PyClass_Type
2535 Cross-referencing C constructs
2537 The following roles create cross-references to C-language constructs if
2538 they are defined in the documentation:
2539 :c:data:
2541 Reference a C-language variable.
2542 :c:func:
2544 Reference a C-language function. Should include trailing paren‐
2545 theses.
2546 :c:macro:
2548 Reference a "simple" C macro, as defined above.
2549 :c:type:
2551 Reference a C-language type.
2552 The C++ Domain
2554 The C++ domain (name cpp) supports documenting C++ projects.
2555 The following directives are available:
2557 .. cpp:class:: signatures
2559 .. cpp:function:: signatures
2561 .. cpp:member:: signatures
2563 .. cpp:type:: signatures
2565 Describe a C++ object. Full signature specification is sup‐
2566 ported -- give the signature as you would in the declaration.
2567 Here some examples:
2568 .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
2570 Describes a method with parameters and types.
2572 .. cpp:function:: bool namespaced::theclass::method(arg1, arg2)
2574 Describes a method without types.
2576 .. cpp:function:: const T &array<T>::operator[]() const
2578 Describes the constant indexing operator of a templated array.
2580 .. cpp:function:: operator bool() const
2582 Describe a casting operator here.
2584 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
2586 Describe a constexpr function here.
2588 .. cpp:member:: std::string theclass::name
2590 .. cpp:member:: std::string theclass::name[N][M]
2592 .. cpp:type:: theclass::const_iterator
2594 Will be rendered like this:
2596 bool namespaced::theclass::method(int arg1, std::string arg2)
2598 Describes a method with parameters and types.
2599 bool namespaced::theclass::method(arg1, arg2)
2601 Describes a method without types.
2602 const T& array<T>::operator[]() const
2604 Describes the constant indexing operator of a tem‐
2605 plated array.
2606 operator bool() const
2608 Describe a casting operator here.
2609 constexpr void foo(std::string& bar[2]) noexcept
2611 Describe a constexpr function here.
2612 std::string theclass::name
2614 std::string theclass::name[N][M]
2616 type theclass::const_iterator
2618 .. cpp:namespace:: namespace
2620 Select the current C++ namespace for the following objects.
2621 These roles link to the given object types:
2623 :cpp:class:
2625 :cpp:func:
2627 :cpp:member:
2629 :cpp:type:
2631 Reference a C++ object. You can give the full signature (and
2632 need to, for overloaded functions.)
2633 NOTE:
2635 Sphinx' syntax to give references a custom title can inter‐
2636 fere with linking to template classes, if nothing follows the
2637 closing angle bracket, i.e. if the link looks like this:
2638 :cpp:class:`MyClass<T>`. This is interpreted as a link to T
2639 with a title of MyClass. In this case, please escape the
2640 opening angle bracket with a backslash, like this:
2641 :cpp:class:`MyClass\<T>`.
2642 Note on References
2644 It is currently impossible to link to a specific version of
2646 an overloaded method. Currently the C++ domain is the first
2647 domain that has basic support for overloaded methods and
2648 until there is more data for comparison we don't want to
2649 select a bad syntax to reference a specific overload. Cur‐
2650 rently Sphinx will link to the first overloaded version of
2651 the method / function.
2652 The Standard Domain
2654 The so-called "standard" domain collects all markup that doesn't war‐
2655 rant a domain of its own. Its directives and roles are not prefixed
2656 with a domain name.
2657 The standard domain is also where custom object descriptions, added
2659 using the add_object_type() API, are placed.
2660 There is a set of directives allowing documenting command-line pro‐
2662 grams:
2663 .. option:: name args, name args, ...
2665 Describes a command line option or switch. Option argument
2666 names should be enclosed in angle brackets. Example:
2667 .. option:: -m <module>, --module <module>
2669 Run a module as a script.
2671 The directive will create a cross-reference target named after
2673 the first option, referencable by option (in the example case,
2674 you'd use something like :option:`-m`).
2675 .. envvar:: name
2677 Describes an environment variable that the documented code or
2678 program uses or defines. Referencable by envvar.
2679 .. program:: name
2681 Like py:currentmodule, this directive produces no output.
2682 Instead, it serves to notify Sphinx that all following option
2683 directives document options for the program called name.
2684 If you use program, you have to qualify the references in your
2686 option roles by the program name, so if you have the following
2687 situation
2688 .. program:: rm
2690 .. option:: -r
2692 Work recursively.
2694 .. program:: svn
2696 .. option:: -r revision
2698 Specify the revision to work upon.
2700 then :option:`rm -r` would refer to the first option, while
2702 :option:`svn -r` would refer to the second one.
2703 The program name may contain spaces (in case you want to docu‐
2705 ment subcommands like svn add and svn commit separately).
2706 New in version 0.5.
2708 There is also a very generic object description directive, which is not
2710 tied to any domain:
2711 .. describe:: text
2713 .. object:: text
2715 This directive produces the same formatting as the specific ones
2716 provided by domains, but does not create index entries or
2717 cross-referencing targets. Example:
2718 .. describe:: PAPER
2720 You can set this variable to select a paper size.
2722 The JavaScript Domain
2724 The JavaScript domain (name js) provides the following directives:
2725 .. js:function:: name(signature)
2727 Describes a JavaScript function or method. If you want to
2728 describe arguments as optional use square brackets as documented
2729 for Python signatures.
2730 You can use fields to give more details about arguments and
2732 their expected types, errors which may be thrown by the func‐
2733 tion, and the value being returned:
2734 .. js:function:: $.getJSON(href, callback[, errback])
2736 :param string href: An URI to the location of the resource.
2738 :param callback: Get's called with the object.
2739 :param errback:
2740 Get's called in case the request fails. And a lot of other
2741 text so we need multiple lines
2742 :throws SomeError: For whatever reason in that case.
2743 :returns: Something
2744 This is rendered as:
2746 $.getJSON(href, callback[, errback])
2748 Arguments
2750 · href (string) -- An URI to the location of
2752 the resource.
2753 · callback -- Get's called with the object.
2755 · errback -- Get's called in case the request
2757 fails. And a lot of other text so we need
2758 multiple lines.
2759 Throws SomeError
2761 For whatever reason in that case.
2762 Returns
2764 Something
2765 .. js:class:: name
2767 Describes a constructor that creates an object. This is basi‐
2768 cally like a function but will show up with a class prefix:
2769 .. js:class:: MyAnimal(name[, age])
2771 :param string name: The name of the animal
2773 :param number age: an optional age for the animal
2774 This is rendered as:
2776 class MyAnimal(name[, age])
2778 Arguments
2780 · name (string) -- The name of the animal
2782 · age (number) -- an optional age for the ani‐
2784 mal
2785 .. js:data:: name
2787 Describes a global variable or constant.
2788 .. js:attribute:: object.name
2790 Describes the attribute name of object.
2791 These roles are provided to refer to the described objects:
2793 :js:func:
2795 :js:class:
2797 :js:data:
2799 :js:attr:
2801 The reStructuredText domain
2803 The reStructuredText domain (name rst) provides the following direc‐
2804 tives:
2805 .. rst:directive:: name
2807 Describes a reST directive. The name can be a single directive
2808 name or actual directive syntax (.. prefix and :: suffix) with
2809 arguments that will be rendered differently. For example:
2810 .. rst:directive:: foo
2812 Foo description.
2814 .. rst:directive:: .. bar:: baz
2816 Bar description.
2818 will be rendered as:
2820 .. foo::
2822 Foo description.
2823 .. bar:: baz
2825 Bar description.
2826 .. rst:role:: name
2828 Describes a reST role. For example:
2829 .. rst:role:: foo
2831 Foo description.
2833 will be rendered as:
2835 :foo: Foo description.
2837 These roles are provided to refer to the described objects:
2839 :rst:dir:
2841 :rst:role:
2843 More domains
2845 The sphinx-contrib repository contains more domains available as exten‐
2846 sions; currently a Ruby and an Erlang domain.
2847
2849 These are the built-in Sphinx builders. More builders can be added by
2850 extensions.
2851 The builder's "name" must be given to the -b command-line option of
2853 sphinx-build to select a builder.
2854 class sphinx.builders.html.StandaloneHTMLBuilder
2856 This is the standard HTML builder. Its output is a directory
2857 with HTML files, complete with style sheets and optionally the
2858 reST sources. There are quite a few configuration values that
2859 customize the output of this builder, see the chapter
2860 html-options for details.
2861 Its name is html.
2863 class sphinx.builders.html.DirectoryHTMLBuilder
2865 This is a subclass of the standard HTML builder. Its output is
2866 a directory with HTML files, where each file is called
2867 index.html and placed in a subdirectory named like its page
2868 name. For example, the document markup/rest.rst will not result
2869 in an output file markup/rest.html, but markup/rest/index.html.
2870 When generating links between pages, the index.html is omitted,
2871 so that the URL would look like markup/rest/.
2872 Its name is dirhtml.
2874 New in version 0.6.
2876 class sphinx.builders.html.SingleFileHTMLBuilder
2878 This is an HTML builder that combines the whole project in one
2879 output file. (Obviously this only works with smaller projects.)
2880 The file is named like the master document. No indices will be
2881 generated.
2882 Its name is singlehtml.
2884 New in version 1.0.
2886 class sphinx.builders.htmlhelp.HTMLHelpBuilder
2888 This builder produces the same output as the standalone HTML
2889 builder, but also generates HTML Help support files that allow
2890 the Microsoft HTML Help Workshop to compile them into a CHM
2891 file.
2892 Its name is htmlhelp.
2894 class sphinx.builders.qthelp.QtHelpBuilder
2896 This builder produces the same output as the standalone HTML
2897 builder, but also generates Qt help collection support files
2898 that allow the Qt collection generator to compile them.
2899 Its name is qthelp.
2901 class sphinx.builders.devhelp.DevhelpBuilder
2903 This builder produces the same output as the standalone HTML
2904 builder, but also generates GNOME Devhelp support file that
2905 allows the GNOME Devhelp reader to view them.
2906 Its name is devhelp.
2908 class sphinx.builders.epub.EpubBuilder
2910 This builder produces the same output as the standalone HTML
2911 builder, but also generates an epub file for ebook readers. See
2912 epub-faq for details about it. For definition of the epub for‐
2913 mat, have a look at http://www.idpf.org/specs.htm or
2914 http://en.wikipedia.org/wiki/EPUB.
2915 Some ebook readers do not show the link targets of references.
2917 Therefore this builder adds the targets after the link when nec‐
2918 essary. The display of the URLs can be customized by adding CSS
2919 rules for the class link-target.
2920 Its name is epub.
2922 class sphinx.builders.latex.LaTeXBuilder
2924 This builder produces a bunch of LaTeX files in the output
2925 directory. You have to specify which documents are to be
2926 included in which LaTeX files via the latex_documents configura‐
2927 tion value. There are a few configuration values that customize
2928 the output of this builder, see the chapter latex-options for
2929 details.
2930 NOTE:
2932 The produced LaTeX file uses several LaTeX packages that may
2933 not be present in a "minimal" TeX distribution installation.
2934 For TeXLive, the following packages need to be installed:
2935 · latex-recommended
2937 · latex-extra
2939 · fonts-recommended
2941 Its name is latex.
2943 Note that a direct PDF builder using ReportLab is available in rst2pdf
2945 version 0.12 or greater. You need to add 'rst2pdf.pdfbuilder' to your
2946 extensions to enable it, its name is pdf. Refer to the rst2pdf manual
2947 for details.
2948 class sphinx.builders.text.TextBuilder
2950 This builder produces a text file for each reST file -- this is
2951 almost the same as the reST source, but with much of the markup
2952 stripped for better readability.
2953 Its name is text.
2955 New in version 0.4.
2957 class sphinx.builders.manpage.ManualPageBuilder
2959 This builder produces manual pages in the groff format. You
2960 have to specify which documents are to be included in which man‐
2961 ual pages via the man_pages configuration value.
2962 Its name is man.
2964 NOTE:
2966 This builder requires the docutils manual page writer, which
2967 is only available as of docutils 0.6.
2968 New in version 1.0.
2970 class sphinx.builders.texinfo.TexinfoBuilder
2972 This builder produces Texinfo files that can be processed into
2973 Info files by the makeinfo program. You have to specify which
2974 documents are to be included in which Texinfo files via the tex‐
2975 info_documents configuration value.
2976 The Info format is the basis of the on-line help system used by
2978 GNU Emacs and the terminal-based program info. See texinfo-faq
2979 for more details. The Texinfo format is the official documenta‐
2980 tion system used by the GNU project. More information on Tex‐
2981 info can be found at http://www.gnu.org/software/texinfo/.
2982 Its name is texinfo.
2984 New in version 1.1.
2986 class sphinx.builders.html.SerializingHTMLBuilder
2988 This builder uses a module that implements the Python serializa‐
2989 tion API (pickle, simplejson, phpserialize, and others) to dump
2990 the generated HTML documentation. The pickle builder is a sub‐
2991 class of it.
2992 A concrete subclass of this builder serializing to the PHP seri‐
2994 alization format could look like this:
2995 import phpserialize
2997 class PHPSerializedBuilder(SerializingHTMLBuilder):
2999 name = 'phpserialized'
3000 implementation = phpserialize
3001 out_suffix = '.file.phpdump'
3002 globalcontext_filename = 'globalcontext.phpdump'
3003 searchindex_filename = 'searchindex.phpdump'
3004 implementation
3006 A module that implements dump(), load(), dumps() and
3007 loads() functions that conform to the functions with the
3008 same names from the pickle module. Known modules imple‐
3009 menting this interface are simplejson (or json in Python
3010 2.6), phpserialize, plistlib, and others.
3011 out_suffix
3013 The suffix for all regular files.
3014 globalcontext_filename
3016 The filename for the file that contains the "global con‐
3017 text". This is a dict with some general configuration
3018 values such as the name of the project.
3019 searchindex_filename
3021 The filename for the search index Sphinx generates.
3022 See serialization-details for details about the output format.
3024 New in version 0.5.
3026 class sphinx.builders.html.PickleHTMLBuilder
3028 This builder produces a directory with pickle files containing
3029 mostly HTML fragments and TOC information, for use of a web
3030 application (or custom postprocessing tool) that doesn't use the
3031 standard HTML templates.
3032 See serialization-details for details about the output format.
3034 Its name is pickle. (The old name web still works as well.)
3036 The file suffix is .fpickle. The global context is called glob‐
3038 alcontext.pickle, the search index searchindex.pickle.
3039 class sphinx.builders.html.JSONHTMLBuilder
3041 This builder produces a directory with JSON files containing
3042 mostly HTML fragments and TOC information, for use of a web
3043 application (or custom postprocessing tool) that doesn't use the
3044 standard HTML templates.
3045 See serialization-details for details about the output format.
3047 Its name is json.
3049 The file suffix is .fjson. The global context is called global‐
3051 context.json, the search index searchindex.json.
3052 New in version 0.5.
3054 class sphinx.builders.gettext.MessageCatalogBuilder
3056 This builder produces gettext-style message catalogs. Each
3057 top-level file or subdirectory grows a single .pot catalog tem‐
3058 plate.
3059 See the documentation on intl for further reference.
3061 Its name is gettext.
3063 New in version 1.1.
3065 class sphinx.builders.changes.ChangesBuilder
3067 This builder produces an HTML overview of all versionadded, ver‐
3068 sionchanged and deprecated directives for the current version.
3069 This is useful to generate a ChangeLog file, for example.
3070 Its name is changes.
3072 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
3074 This builder scans all documents for external links, tries to
3075 open them with urllib2, and writes an overview which ones are
3076 broken and redirected to standard output and to output.txt in
3077 the output directory.
3078 Its name is linkcheck.
3080 Built-in Sphinx extensions that offer more builders are:
3082 · doctest
3084 · coverage
3086 Serialization builder details
3088 All serialization builders outputs one file per source file and a few
3089 special files. They also copy the reST source files in the directory
3090 _sources under the output directory.
3091 The PickleHTMLBuilder is a builtin subclass that implements the pickle
3093 serialization interface.
3094 The files per source file have the extensions of out_suffix, and are
3096 arranged in directories just as the source files are. They unserialize
3097 to a dictionary (or dictionary like structure) with these keys:
3098 body The HTML "body" (that is, the HTML rendering of the source
3100 file), as rendered by the HTML translator.
3101 title The title of the document, as HTML (may contain markup).
3103 toc The table of contents for the file, rendered as an HTML <ul>.
3105 display_toc
3107 A boolean that is True if the toc contains more than one entry.
3108 current_page_name
3110 The document name of the current file.
3111 parents, prev and next
3113 Information about related chapters in the TOC tree. Each rela‐
3114 tion is a dictionary with the keys link (HREF for the relation)
3115 and title (title of the related document, as HTML). parents is
3116 a list of relations, while prev and next are a single relation.
3117 sourcename
3119 The name of the source file under _sources.
3120 The special files are located in the root output directory. They are:
3122 SerializingHTMLBuilder.globalcontext_filename
3124 A pickled dict with these keys:
3125 project, copyright, release, version
3127 The same values as given in the configuration file.
3128 style html_style.
3130 last_updated
3132 Date of last build.
3133 builder
3135 Name of the used builder, in the case of pickles this is
3136 always 'pickle'.
3137 titles A dictionary of all documents' titles, as HTML strings.
3139 SerializingHTMLBuilder.searchindex_filename
3141 An index that can be used for searching the documentation. It
3142 is a pickled list with these entries:
3143 · A list of indexed docnames.
3145 · A list of document titles, as HTML strings, in the same order
3147 as the first list.
3148 · A dict mapping word roots (processed by an English-language
3150 stemmer) to a list of integers, which are indices into the
3151 first list.
3152 environment.pickle
3154 The build environment. This is always a pickle file, indepen‐
3155 dent of the builder and a copy of the environment that was used
3156 when the builder was started.
3157 Todo
3159 Document common members.
3160 Unlike the other pickle files this pickle file requires that the
3162 sphinx package is available on unpickling.
3163
3165 The configuration directory must contain a file named conf.py. This
3166 file (containing Python code) is called the "build configuration file"
3167 and contains all configuration needed to customize Sphinx input and
3168 output behavior.
3169 The configuration file is executed as Python code at build time (using
3171 execfile(), and with the current directory set to its containing direc‐
3172 tory), and therefore can execute arbitrarily complex code. Sphinx then
3173 reads simple names from the file's namespace as its configuration.
3174 Important points to note:
3176 · If not otherwise documented, values must be strings, and their
3178 default is the empty string.
3179 · The term "fully-qualified name" refers to a string that names an
3181 importable Python object inside a module; for example, the FQN
3182 "sphinx.builders.Builder" means the Builder class in the
3183 sphinx.builders module.
3184 · Remember that document names use / as the path separator and don't
3186 contain the file name extension.
3187 · Since conf.py is read as a Python file, the usual rules apply for
3189 encodings and Unicode support: declare the encoding using an encoding
3190 cookie (a comment like # -*- coding: utf-8 -*-) and use Unicode
3191 string literals when you include non-ASCII characters in configura‐
3192 tion values.
3193 · The contents of the config namespace are pickled (so that Sphinx can
3195 find out when configuration changes), so it may not contain unpick‐
3196 leable values -- delete them from the namespace with del if appropri‐
3197 ate. Modules are removed automatically, so you don't need to del
3198 your imports after use.
3199 · There is a special object named tags available in the config file.
3201 It can be used to query and change the tags (see tags). Use
3202 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
3203 change.
3204 General configuration
3206 extensions
3207 A list of strings that are module names of Sphinx extensions.
3208 These can be extensions coming with Sphinx (named sphinx.ext.*)
3209 or custom ones.
3210 Note that you can extend sys.path within the conf file if your
3212 extensions live in another directory -- but make sure you use
3213 absolute paths. If your extension path is relative to the con‐
3214 figuration directory, use os.path.abspath() like so:
3215 import sys, os
3217 sys.path.append(os.path.abspath('sphinxext'))
3219 extensions = ['extname']
3221 That way, you can load an extension called extname from the sub‐
3223 directory sphinxext.
3224 The configuration file itself can be an extension; for that, you
3226 only need to provide a setup() function in it.
3227 source_suffix
3229 The file name extension of source files. Only files with this
3230 suffix will be read as sources. Default is '.rst'.
3231 source_encoding
3233 The encoding of all reST source files. The recommended encod‐
3234 ing, and the default value, is 'utf-8-sig'.
3235 New in version 0.5: Previously, Sphinx accepted only UTF-8
3237 encoded sources.
3238 master_doc
3240 The document name of the "master" document, that is, the docu‐
3241 ment that contains the root toctree directive. Default is 'con‐
3242 tents'.
3243 exclude_patterns
3245 A list of glob-style patterns that should be excluded when look‐
3246 ing for source files. [1] They are matched against the source
3247 file names relative to the source directory, using slashes as
3248 directory separators on all platforms.
3249 Example patterns:
3251 · 'library/xml.rst' -- ignores the library/xml.rst file
3253 (replaces entry in unused_docs)
3254 · 'library/xml' -- ignores the library/xml directory (replaces
3256 entry in exclude_trees)
3257 · 'library/xml*' -- ignores all files and directories starting
3259 with library/xml
3260 · '**/.svn' -- ignores all .svn directories (replaces entry in
3262 exclude_dirnames)
3263 exclude_patterns is also consulted when looking for static files
3265 in html_static_path.
3266 New in version 1.0.
3268 unused_docs
3270 A list of document names that are present, but not currently
3271 included in the toctree. Use this setting to suppress the warn‐
3272 ing that is normally emitted in that case.
3273 Deprecated since version 1.0: Use exclude_patterns instead.
3275 exclude_trees
3277 A list of directory paths, relative to the source directory,
3278 that are to be recursively excluded from the search for source
3279 files, that is, their subdirectories won't be searched too. The
3280 default is [].
3281 New in version 0.4.
3283 Deprecated since version 1.0: Use exclude_patterns instead.
3285 exclude_dirnames
3287 A list of directory names that are to be excluded from any
3288 recursive operation Sphinx performs (e.g. searching for source
3289 files or copying static files). This is useful, for example, to
3290 exclude version-control-specific directories like 'CVS'. The
3291 default is [].
3292 New in version 0.5.
3294 Deprecated since version 1.0: Use exclude_patterns instead.
3296 templates_path
3298 A list of paths that contain extra templates (or templates that
3299 overwrite builtin/theme-specific templates). Relative paths are
3300 taken as relative to the configuration directory.
3301 template_bridge
3303 A string with the fully-qualified name of a callable (or simply
3304 a class) that returns an instance of TemplateBridge. This
3305 instance is then used to render HTML documents, and possibly the
3306 output of other builders (currently the changes builder). (Note
3307 that the template bridge must be made theme-aware if HTML themes
3308 are to be used.)
3309 rst_epilog
3311 A string of reStructuredText that will be included at the end of
3312 every source file that is read. This is the right place to add
3313 substitutions that should be available in every file. An exam‐
3314 ple:
3315 rst_epilog = """
3317 .. |psf| replace:: Python Software Foundation
3318 """
3319 New in version 0.6.
3321 rst_prolog
3323 A string of reStructuredText that will be included at the begin‐
3324 ning of every source file that is read.
3325 New in version 1.0.
3327 primary_domain
3329 The name of the default domain. Can also be None to disable a
3330 default domain. The default is 'py'. Those objects in other
3331 domains (whether the domain name is given explicitly, or
3332 selected by a default-domain directive) will have the domain
3333 name explicitly prepended when named (e.g., when the default
3334 domain is C, Python functions will be named "Python function",
3335 not just "function").
3336 New in version 1.0.
3338 default_role
3340 The name of a reST role (builtin or Sphinx extension) to use as
3341 the default role, that is, for text marked up `like this`. This
3342 can be set to 'py:obj' to make `filter` a cross-reference to the
3343 Python function "filter". The default is None, which doesn't
3344 reassign the default role.
3345 The default role can always be set within individual documents
3347 using the standard reST default-role directive.
3348 New in version 0.4.
3350 keep_warnings
3352 If true, keep warnings as "system message" paragraphs in the
3353 built documents. Regardless of this setting, warnings are
3354 always written to the standard error stream when sphinx-build is
3355 run.
3356 The default is False, the pre-0.5 behavior was to always keep
3358 them.
3359 New in version 0.5.
3361 needs_sphinx
3363 If set to a major.minor version string like '1.1', Sphinx will
3364 compare it with its version and refuse to build if it is too
3365 old. Default is no requirement.
3366 New in version 1.0.
3368 nitpicky
3370 If true, Sphinx will warn about all references where the target
3371 cannot be found. Default is False. You can activate this mode
3372 temporarily using the -n command-line switch.
3373 New in version 1.0.
3375 nitpick_ignore
3377 A list of (type, target) tuples (by default empty) that should
3378 be ignored when generating warnings in "nitpicky mode". Note
3379 that type should include the domain name. An example entry
3380 would be ('py:func', 'int').
3381 New in version 1.1.
3383 Project information
3385 project
3386 The documented project's name.
3387 copyright
3389 A copyright statement in the style '2008, Author Name'.
3390 version
3392 The major project version, used as the replacement for |ver‐
3393 sion|. For example, for the Python documentation, this may be
3394 something like 2.6.
3395 release
3397 The full project version, used as the replacement for |release|
3398 and e.g. in the HTML templates. For example, for the Python
3399 documentation, this may be something like 2.6.0rc1.
3400 If you don't need the separation provided between version and
3402 release, just set them both to the same value.
3403 today
3405 today_fmt
3407 These values determine how to format the current date, used as
3408 the replacement for |today|.
3409 · If you set today to a non-empty value, it is used.
3411 · Otherwise, the current time is formatted using time.strftime()
3413 and the format given in today_fmt.
3414 The default is no today and a today_fmt of '%B %d, %Y' (or, if
3416 translation is enabled with language, am equivalent %format for
3417 the selected locale).
3418 highlight_language
3420 The default language to highlight source code in. The default
3421 is 'python'. The value should be a valid Pygments lexer name,
3422 see code-examples for more details.
3423 New in version 0.5.
3425 pygments_style
3427 The style name to use for Pygments highlighting of source code.
3428 The default style is selected by the theme for HTML output, and
3429 'sphinx' otherwise.
3430 Changed in version 0.3: If the value is a fully-qualified name
3432 of a custom Pygments style class, this is then used as custom
3433 style.
3434 add_function_parentheses
3436 A boolean that decides whether parentheses are appended to func‐
3437 tion and method role text (e.g. the content of :func:`input`) to
3438 signify that the name is callable. Default is True.
3439 add_module_names
3441 A boolean that decides whether module names are prepended to all
3442 object names (for object types where a "module" of some kind is
3443 defined), e.g. for py:function directives. Default is True.
3444 show_authors
3446 A boolean that decides whether codeauthor and sectionauthor
3447 directives produce any output in the built files.
3448 modindex_common_prefix
3450 A list of prefixes that are ignored for sorting the Python mod‐
3451 ule index (e.g., if this is set to ['foo.'], then foo.bar is
3452 shown under B, not F). This can be handy if you document a
3453 project that consists of a single package. Works only for the
3454 HTML builder currently. Default is [].
3455 New in version 0.6.
3457 trim_footnote_reference_space
3459 Trim spaces before footnote references that are necessary for
3460 the reST parser to recognize the footnote, but do not look too
3461 nice in the output.
3462 New in version 0.6.
3464 trim_doctest_flags
3466 If true, doctest flags (comments looking like # doctest: FLAG,
3467 ...) at the ends of lines and <BLANKLINE> markers are removed
3468 for all code blocks showing interactive Python sessions (i.e.
3469 doctests). Default is true. See the extension doctest for more
3470 possibilities of including doctests.
3471 New in version 1.0.
3473 Changed in version 1.1: Now also removes <BLANKLINE>.
3475 Options for internationalization
3477 These options influence Sphinx' Native Language Support. See the docu‐
3478 mentation on intl for details.
3479 language
3481 The code for the language the docs are written in. Any text
3482 automatically generated by Sphinx will be in that language.
3483 Also, Sphinx will try to substitute individual paragraphs from
3484 your documents with the translation sets obtained from
3485 locale_dirs. In the LaTeX builder, a suitable language will be
3486 selected as an option for the Babel package. Default is None,
3487 which means that no translation will be done.
3488 New in version 0.5.
3490 Currently supported languages by Sphinx are:
3492 · bn -- Bengali
3494 · ca -- Catalan
3496 · cs -- Czech
3498 · da -- Danish
3500 · de -- German
3502 · en -- English
3504 · es -- Spanish
3506 · et -- Estonian
3508 · fa -- Iranian
3510 · fi -- Finnish
3512 · fr -- French
3514 · hr -- Croatian
3516 · it -- Italian
3518 · ja -- Japanese
3520 · ko -- Korean
3522 · lt -- Lithuanian
3524 · lv -- Latvian
3526 · ne -- Nepali
3528 · nl -- Dutch
3530 · pl -- Polish
3532 · pt_BR -- Brazilian Portuguese
3534 · ru -- Russian
3536 · sl -- Slovenian
3538 · sv -- Swedish
3540 · tr -- Turkish
3542 · uk_UA -- Ukrainian
3544 · zh_CN -- Simplified Chinese
3546 · zh_TW -- Traditional Chinese
3548 locale_dirs
3550 New in version 0.5.
3551 Directories in which to search for additional message catalogs
3553 (see language), relative to the source directory. The directo‐
3554 ries on this path are searched by the standard gettext module.
3555 Internal messages are fetched from a text domain of sphinx; so
3557 if you add the directory ./locale to this settting, the message
3558 catalogs (compiled from .po format using msgfmt) must be in
3559 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
3560 individual documents depends on gettext_compact.
3561 The default is [].
3563 gettext_compact
3565 New in version 1.1.
3566 If true, a document's text domain is its docname if it is a
3568 top-level project file and its very base directory otherwise.
3569 By default, the document markup/code.rst ends up in the markup
3571 text domain. With this option set to False, it is markup/code.
3572 Options for HTML output
3574 These options influence HTML as well as HTML Help output, and other
3575 builders that use Sphinx' HTMLWriter class.
3576 html_theme
3578 The "theme" that the HTML output should use. See the section
3579 about theming. The default is 'default'.
3580 New in version 0.6.
3582 html_theme_options
3584 A dictionary of options that influence the look and feel of the
3585 selected theme. These are theme-specific. For the options
3586 understood by the builtin themes, see this section.
3587 New in version 0.6.
3589 html_theme_path
3591 A list of paths that contain custom themes, either as subdirec‐
3592 tories or as zip files. Relative paths are taken as relative to
3593 the configuration directory.
3594 New in version 0.6.
3596 html_style
3598 The style sheet to use for HTML pages. A file of that name must
3599 exist either in Sphinx' static/ path, or in one of the custom
3600 paths given in html_static_path. Default is the stylesheet
3601 given by the selected theme. If you only want to add or over‐
3602 ride a few things compared to the theme's stylesheet, use CSS
3603 @import to import the theme's stylesheet.
3604 html_title
3606 The "title" for HTML documentation generated with Sphinx' own
3607 templates. This is appended to the <title> tag of individual
3608 pages, and used in the navigation bar as the "topmost" element.
3609 It defaults to '<project> v<revision> documentation', where the
3610 placeholders are replaced by the config values of the same name.
3611 html_short_title
3613 A shorter "title" for the HTML docs. This is used in for links
3614 in the header and in the HTML Help docs. If not given, it
3615 defaults to the value of html_title.
3616 New in version 0.4.
3618 html_context
3620 A dictionary of values to pass into the template engine's con‐
3621 text for all pages. Single values can also be put in this dic‐
3622 tionary using the -A command-line option of sphinx-build.
3623 New in version 0.5.
3625 html_logo
3627 If given, this must be the name of an image file that is the
3628 logo of the docs. It is placed at the top of the sidebar; its
3629 width should therefore not exceed 200 pixels. Default: None.
3630 New in version 0.4.1: The image file will be copied to the
3632 _static directory of the output HTML, so an already existing
3633 file with that name will be overwritten.
3634 html_favicon
3636 If given, this must be the name of an image file (within the
3637 static path, see below) that is the favicon of the docs. Modern
3638 browsers use this as icon for tabs, windows and bookmarks. It
3639 should be a Windows-style icon file (.ico), which is 16x16 or
3640 32x32 pixels large. Default: None.
3641 New in version 0.4.
3643 html_static_path
3645 A list of paths that contain custom static files (such as style
3646 sheets or script files). Relative paths are taken as relative
3647 to the configuration directory. They are copied to the output
3648 directory after the theme's static files, so a file named
3649 default.css will overwrite the theme's default.css.
3650 Changed in version 0.4: The paths in html_static_path can now
3652 contain subdirectories.
3653 Changed in version 1.0: The entries in html_static_path can now
3655 be single files.
3656 html_last_updated_fmt
3658 If this is not the empty string, a 'Last updated on:' timestamp
3659 is inserted at every page bottom, using the given strftime()
3660 format. Default is '%b %d, %Y' (or a locale-dependent equiva‐
3661 lent).
3662 html_use_smartypants
3664 If true, SmartyPants will be used to convert quotes and dashes
3665 to typographically correct entities. Default: True.
3666 html_add_permalinks
3668 Sphinx will add "permalinks" for each heading and description
3669 environment as paragraph signs that become visible when the
3670 mouse hovers over them.
3671 This value determines the text for the permalink; it defaults to
3673 "¶". Set it to None or the empty string to disable permalinks.
3674 New in version 0.6: Previously, this was always activated.
3676 Changed in version 1.1: This can now be a string to select the
3678 actual text of the link. Previously, only boolean values were
3679 accepted.
3680 html_sidebars
3682 Custom sidebar templates, must be a dictionary that maps docu‐
3683 ment names to template names.
3684 The keys can contain glob-style patterns [1], in which case all
3686 matching documents will get the specified sidebars. (A warning
3687 is emitted when a more than one glob-style pattern matches for
3688 any document.)
3689 The values can be either lists or single strings.
3691 · If a value is a list, it specifies the complete list of side‐
3693 bar templates to include. If all or some of the default side‐
3694 bars are to be included, they must be put into this list as
3695 well.
3696 The default sidebars (for documents that don't match any pat‐
3698 tern) are: ['localtoc.html', 'relations.html',
3699 'sourcelink.html', 'searchbox.html'].
3700 · If a value is a single string, it specifies a custom sidebar
3702 to be added between the 'sourcelink.html' and 'searchbox.html'
3703 entries. This is for compatibility with Sphinx versions
3704 before 1.0.
3705 Builtin sidebar templates that can be rendered are:
3707 · localtoc.html -- a fine-grained table of contents of the cur‐
3709 rent document
3710 · globaltoc.html -- a coarse-grained table of contents for the
3712 whole documentation set, collapsed
3713 · relations.html -- two links to the previous and next documents
3715 · sourcelink.html -- a link to the source of the current docu‐
3717 ment, if enabled in html_show_sourcelink
3718 · searchbox.html -- the "quick search" box
3720 Example:
3722 html_sidebars = {
3724 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
3725 'using/windows': ['windowssidebar.html', 'searchbox.html'],
3726 }
3727 This will render the custom template windowssidebar.html and the
3729 quick search box within the sidebar of the given document, and
3730 render the default sidebars for all other pages (except that the
3731 local TOC is replaced by the global TOC).
3732 New in version 1.0: The ability to use globbing keys and to
3734 specify multiple sidebars.
3735 Note that this value only has no effect if the chosen theme does
3737 not possess a sidebar, like the builtin scrolls and haiku
3738 themes.
3739 html_additional_pages
3741 Additional templates that should be rendered to HTML pages, must
3742 be a dictionary that maps document names to template names.
3743 Example:
3745 html_additional_pages = {
3747 'download': 'customdownload.html',
3748 }
3749 This will render the template customdownload.html as the page
3751 download.html.
3752 html_domain_indices
3754 If true, generate domain-specific indices in addition to the
3755 general index. For e.g. the Python domain, this is the global
3756 module index. Default is True.
3757 This value can be a bool or a list of index names that should be
3759 generated. To find out the index name for a specific index,
3760 look at the HTML file name. For example, the Python module
3761 index has the name 'py-modindex'.
3762 New in version 1.0.
3764 html_use_modindex
3766 If true, add a module index to the HTML documents. Default is
3767 True.
3768 Deprecated since version 1.0: Use html_domain_indices.
3770 html_use_index
3772 If true, add an index to the HTML documents. Default is True.
3773 New in version 0.4.
3775 html_split_index
3777 If true, the index is generated twice: once as a single page
3778 with all the entries, and once as one page per starting letter.
3779 Default is False.
3780 New in version 0.4.
3782 html_copy_source
3784 If true, the reST sources are included in the HTML build as
3785 _sources/name. The default is True.
3786 WARNING:
3788 If this config value is set to False, the JavaScript search
3789 function will only display the titles of matching documents,
3790 and no excerpt from the matching contents.
3791 html_show_sourcelink
3793 If true (and html_copy_source is true as well), links to the
3794 reST sources will be added to the sidebar. The default is True.
3795 New in version 0.6.
3797 html_use_opensearch
3799 If nonempty, an OpenSearch <http://opensearch.org> description
3800 file will be output, and all pages will contain a <link> tag
3801 referring to it. Since OpenSearch doesn't support relative URLs
3802 for its search page location, the value of this option must be
3803 the base URL from which these documents are served (without
3804 trailing slash), e.g. "http://docs.python.org". The default is
3805 ''.
3806 html_file_suffix
3808 This is the file name suffix for generated HTML files. The
3809 default is ".html".
3810 New in version 0.4.
3812 html_link_suffix
3814 Suffix for generated links to HTML files. The default is what‐
3815 ever html_file_suffix is set to; it can be set differently (e.g.
3816 to support different web server setups).
3817 New in version 0.6.
3819 html_translator_class
3821 A string with the fully-qualified name of a HTML Translator
3822 class, that is, a subclass of Sphinx' HTMLTranslator, that is
3823 used to translate document trees to HTML. Default is None (use
3824 the builtin translator).
3825 html_show_copyright
3827 If true, "(C) Copyright ..." is shown in the HTML footer.
3828 Default is True.
3829 New in version 1.0.
3831 html_show_sphinx
3833 If true, "Created using Sphinx" is shown in the HTML footer.
3834 Default is True.
3835 New in version 0.4.
3837 html_output_encoding
3839 Encoding of HTML output files. Default is 'utf-8'. Note that
3840 this encoding name must both be a valid Python encoding name and
3841 a valid HTML charset value.
3842 New in version 1.0.
3844 html_compact_lists
3846 If true, list items containing only a single paragraph will not
3847 be rendered with a <p> element. This is standard docutils
3848 behavior. Default: True.
3849 New in version 1.0.
3851 html_secnumber_suffix
3853 Suffix for section numbers. Default: ". ". Set to " " to sup‐
3854 press the final dot on section numbers.
3855 New in version 1.0.
3857 html_search_language
3859 Language to be used for generating the HTML full-text search
3860 index. This defaults to the global language selected with lan‐
3861 guage. If there is no support for this language, "en" is used
3862 which selects the English language.
3863 Support is present for these languages:
3865 · en -- English
3867 · ja -- Japanese
3869 New in version 1.1.
3871 html_search_options
3873 A dictionary with options for the search language support, empty
3874 by default. The meaning of these options depends on the lan‐
3875 guage selected.
3876 The English support has no options.
3878 The Japanese support has these options:
3880 · type -- 'mecab' or 'default' (selects either MeCab or TinySeg‐
3882 menter word splitter algorithm)
3883 · dic_enc -- the encoding for the MeCab algorithm
3885 · dict -- the dictionary to use for the MeCab algorithm
3887 · lib -- the library name for finding the MeCab library via
3889 ctypes if the Python binding is not installed
3890 New in version 1.1.
3892 htmlhelp_basename
3894 Output file base name for HTML help builder. Default is
3895 'pydoc'.
3896 Options for epub output
3898 These options influence the epub output. As this builder derives from
3899 the HTML builder, the HTML options also apply where appropriate. The
3900 actual values for some of the options is not really important, they
3901 just have to be entered into the Dublin Core metadata.
3902 epub_basename
3904 The basename for the epub file. It defaults to the project
3905 name.
3906 epub_theme
3908 The HTML theme for the epub output. Since the default themes
3909 are not optimized for small screen space, using the same theme
3910 for HTML and epub output is usually not wise. This defaults to
3911 'epub', a theme designed to save visual space.
3912 epub_title
3914 The title of the document. It defaults to the html_title option
3915 but can be set independently for epub creation.
3916 epub_author
3918 The author of the document. This is put in the Dublin Core
3919 metadata. The default value is 'unknown'.
3920 epub_language
3922 The language of the document. This is put in the Dublin Core
3923 metadata. The default is the language option or 'en' if unset.
3924 epub_publisher
3926 The publisher of the document. This is put in the Dublin Core
3927 metadata. You may use any sensible string, e.g. the project
3928 homepage. The default value is 'unknown'.
3929 epub_copyright
3931 The copyright of the document. It defaults to the copyright
3932 option but can be set independently for epub creation.
3933 epub_identifier
3935 An identifier for the document. This is put in the Dublin Core
3936 metadata. For published documents this is the ISBN number, but
3937 you can also use an alternative scheme, e.g. the project home‐
3938 page. The default value is 'unknown'.
3939 epub_scheme
3941 The publication scheme for the epub_identifier. This is put in
3942 the Dublin Core metadata. For published books the scheme is
3943 'ISBN'. If you use the project homepage, 'URL' seems reason‐
3944 able. The default value is 'unknown'.
3945 epub_uid
3947 A unique identifier for the document. This is put in the Dublin
3948 Core metadata. You may use a random string. The default value
3949 is 'unknown'.
3950 epub_cover
3952 The cover page information. This is a tuple containing the
3953 filenames of the cover image and the html template. The ren‐
3954 dered html cover page is inserted as the first item in the spine
3955 in content.opf. If the template filename is empty, no html
3956 cover page is created. No cover at all is created if the tuple
3957 is empty. Examples:
3958 epub_cover = ('_static/cover.png', 'epub-cover.html')
3960 epub_cover = ('_static/cover.png', '')
3961 epub_cover = ()
3962 The default value is ().
3964 New in version 1.1.
3966 epub_pre_files
3968 Additional files that should be inserted before the text gener‐
3969 ated by Sphinx. It is a list of tuples containing the file name
3970 and the title. If the title is empty, no entry is added to
3971 toc.ncx. Example:
3972 epub_pre_files = [
3974 ('index.html', 'Welcome'),
3975 ]
3976 The default value is [].
3978 epub_post_files
3980 Additional files that should be inserted after the text gener‐
3981 ated by Sphinx. It is a list of tuples containing the file name
3982 and the title. This option can be used to add an appendix. If
3983 the title is empty, no entry is added to toc.ncx. The default
3984 value is [].
3985 epub_exclude_files
3987 A list of files that are generated/copied in the build directory
3988 but should not be included in the epub file. The default value
3989 is [].
3990 epub_tocdepth
3992 The depth of the table of contents in the file toc.ncx. It
3993 should be an integer greater than zero. The default value is 3.
3994 Note: A deeply nested table of contents may be difficult to nav‐
3995 igate.
3996 epub_tocdup
3998 This flag determines if a toc entry is inserted again at the
3999 beginning of it's nested toc listing. This allows easier navi‐
4000 tation to the top of a chapter, but can be confusing because it
4001 mixes entries of differnet depth in one list. The default value
4002 is True.
4003 Options for LaTeX output
4005 These options influence LaTeX output.
4006 latex_documents
4008 This value determines how to group the document tree into LaTeX
4009 source files. It must be a list of tuples (startdocname, tar‐
4010 getname, title, author, documentclass, toctree_only), where the
4011 items are:
4012 · startdocname: document name that is the "root" of the LaTeX
4014 file. All documents referenced by it in TOC trees will be
4015 included in the LaTeX file too. (If you want only one LaTeX
4016 file, use your master_doc here.)
4017 · targetname: file name of the LaTeX file in the output direc‐
4019 tory.
4020 · title: LaTeX document title. Can be empty to use the title of
4022 the startdoc. This is inserted as LaTeX markup, so special
4023 characters like a backslash or ampersand must be represented
4024 by the proper LaTeX commands if they are to be inserted liter‐
4025 ally.
4026 · author: Author for the LaTeX document. The same LaTeX markup
4028 caveat as for title applies. Use \and to separate multiple
4029 authors, as in: 'John \and Sarah'.
4030 · documentclass: Normally, one of 'manual' or 'howto' (provided
4032 by Sphinx). Other document classes can be given, but they
4033 must include the "sphinx" package in order to define Sphinx'
4034 custom LaTeX commands. "howto" documents will not get appen‐
4035 dices. Also, howtos will have a simpler title page.
4036 · toctree_only: Must be True or False. If True, the startdoc
4038 document itself is not included in the output, only the docu‐
4039 ments referenced by it via TOC trees. With this option, you
4040 can put extra stuff in the master document that shows up in
4041 the HTML, but not the LaTeX output.
4042 New in version 0.3: The 6th item toctree_only. Tuples with 5
4044 items are still accepted.
4045 latex_logo
4047 If given, this must be the name of an image file (relative to
4048 the configuration directory) that is the logo of the docs. It
4049 is placed at the top of the title page. Default: None.
4050 latex_use_parts
4052 If true, the topmost sectioning unit is parts, else it is chap‐
4053 ters. Default: False.
4054 New in version 0.3.
4056 latex_appendices
4058 A list of document names to append as an appendix to all manu‐
4059 als.
4060 latex_domain_indices
4062 If true, generate domain-specific indices in addition to the
4063 general index. For e.g. the Python domain, this is the global
4064 module index. Default is True.
4065 This value can be a bool or a list of index names that should be
4067 generated, like for html_domain_indices.
4068 New in version 1.0.
4070 latex_use_modindex
4072 If true, add a module index to LaTeX documents. Default is
4073 True.
4074 Deprecated since version 1.0: Use latex_domain_indices.
4076 latex_show_pagerefs
4078 If true, add page references after internal references. This is
4079 very useful for printed copies of the manual. Default is False.
4080 New in version 1.0.
4082 latex_show_urls
4084 Control whether to display URL addresses. This is very useful
4085 for printed copies of the manual. The setting can have the fol‐
4086 lowing values:
4087 · 'no' -- do not display URLs (default)
4089 · 'footnote' -- display URLs in footnotes
4091 · 'inline' -- display URLs inline in parentheses
4093 New in version 1.0.
4095 Changed in version 1.1: This value is now a string; previously
4097 it was a boolean value, and a true value selected the 'inline'
4098 display. For backwards compatibility, True is still accepted.
4099 latex_elements
4101 New in version 0.5.
4102 A dictionary that contains LaTeX snippets that override those
4104 Sphinx usually puts into the generated .tex files.
4105 Keep in mind that backslashes must be doubled in Python string
4107 literals to avoid interpretation as escape sequences.
4108 · Keys that you may want to override include:
4110 'papersize'
4112 Paper size option of the document class ('a4paper' or
4113 'letterpaper'), default 'letterpaper'.
4114 'pointsize'
4116 Point size option of the document class ('10pt', '11pt'
4117 or '12pt'), default '10pt'.
4118 'babel'
4120 "babel" package inclusion, default '\\usepack‐
4121 age{babel}'.
4122 'fontpkg'
4124 Font package inclusion, default '\\usepackage{times}'
4125 (which uses Times and Helvetica). You can set this to
4126 '' to use the Computer Modern fonts.
4127 'fncychap'
4129 Inclusion of the "fncychap" package (which makes fancy
4130 chapter titles), default '\\usepackage[Bjarne]{fncy‐
4131 chap}' for English documentation, '\\usepack‐
4132 age[Sonny]{fncychap}' for internationalized docs
4133 (because the "Bjarne" style uses numbers spelled out in
4134 English). Other "fncychap" styles you can try include
4135 "Lenny", "Glenn", "Conny" and "Rejne". You can also
4136 set this to '' to disable fncychap.
4137 'preamble'
4139 Additional preamble content, default empty.
4140 'footer'`
4142 Additional footer content (before the indices), default
4143 empty.
4144 · Keys that don't need be overridden unless in special cases
4146 are:
4147 'inputenc'
4149 "inputenc" package inclusion, default '\\usepack‐
4150 age[utf8]{inputenc}'.
4151 'fontenc'
4153 "fontenc" package inclusion, default '\\usepack‐
4154 age[T1]{fontenc}'.
4155 'maketitle'
4157 "maketitle" call, default '\\maketitle'. Override if
4158 you want to generate a differently-styled title page.
4159 'tableofcontents'
4161 "tableofcontents" call, default '\\tableofcontents'.
4162 Override if you want to generate a different table of
4163 contents or put content between the title page and the
4164 TOC.
4165 'printindex'
4167 "printindex" call, the last thing in the file, default
4168 '\\printindex'. Override if you want to generate the
4169 index differently or append some content after the
4170 index.
4171 · Keys that are set by other options and therefore should not be
4173 overridden are:
4174 'docclass' 'classoptions' 'title' 'date' 'release' 'author'
4176 'logo' 'releasename' 'makeindex' 'shorthandoff'
4177 latex_docclass
4179 A dictionary mapping 'howto' and 'manual' to names of real docu‐
4180 ment classes that will be used as the base for the two Sphinx
4181 classes. Default is to use 'article' for 'howto' and 'report'
4182 for 'manual'.
4183 New in version 1.0.
4185 latex_additional_files
4187 A list of file names, relative to the configuration directory,
4188 to copy to the build directory when building LaTeX output. This
4189 is useful to copy files that Sphinx doesn't copy automatically,
4190 e.g. if they are referenced in custom LaTeX added in latex_ele‐
4191 ments. Image files that are referenced in source files (e.g.
4192 via .. image::) are copied automatically.
4193 You have to make sure yourself that the filenames don't collide
4195 with those of any automatically copied files.
4196 New in version 0.6.
4198 latex_preamble
4200 Additional LaTeX markup for the preamble.
4201 Deprecated since version 0.5: Use the 'preamble' key in the
4203 latex_elements value.
4204 latex_paper_size
4206 The output paper size ('letter' or 'a4'). Default is 'letter'.
4207 Deprecated since version 0.5: Use the 'papersize' key in the
4209 latex_elements value.
4210 latex_font_size
4212 The font size ('10pt', '11pt' or '12pt'). Default is '10pt'.
4213 Deprecated since version 0.5: Use the 'pointsize' key in the
4215 latex_elements value.
4216 Options for text output
4218 These options influence text output.
4219 text_newlines
4221 Determines which end-of-line character(s) are used in text out‐
4222 put.
4223 · 'unix': use Unix-style line endings (\n)
4225 · 'windows': use Windows-style line endings (\r\n)
4227 · 'native': use the line ending style of the platform the docu‐
4229 mentation is built on
4230 Default: 'unix'.
4232 New in version 1.1.
4234 text_sectionchars
4236 A string of 7 characters that should be used for underlining
4237 sections. The first character is used for first-level headings,
4238 the second for second-level headings and so on.
4239 The default is '*=-~"+`'.
4241 New in version 1.1.
4243 Options for manual page output
4245 These options influence manual page output.
4246 man_pages
4248 This value determines how to group the document tree into manual
4249 pages. It must be a list of tuples (startdocname, name,
4250 description, authors, section), where the items are:
4251 · startdocname: document name that is the "root" of the manual
4253 page. All documents referenced by it in TOC trees will be
4254 included in the manual file too. (If you want one master man‐
4255 ual page, use your master_doc here.)
4256 · name: name of the manual page. This should be a short string
4258 without spaces or special characters. It is used to determine
4259 the file name as well as the name of the manual page (in the
4260 NAME section).
4261 · description: description of the manual page. This is used in
4263 the NAME section.
4264 · authors: A list of strings with authors, or a single string.
4266 Can be an empty string or list if you do not want to automati‐
4267 cally generate an AUTHORS section in the manual page.
4268 · section: The manual page section. Used for the output file
4270 name as well as in the manual page header.
4271 New in version 1.0.
4273 man_show_urls
4275 If true, add URL addresses after links. Default is False.
4276 New in version 1.1.
4278 Options for Texinfo output
4280 These options influence Texinfo output.
4281 texinfo_documents
4283 This value determines how to group the document tree into Tex‐
4284 info source files. It must be a list of tuples (startdocname,
4285 targetname, title, author, dir_entry, description, category,
4286 toctree_only), where the items are:
4287 · startdocname: document name that is the "root" of the Texinfo
4289 file. All documents referenced by it in TOC trees will be
4290 included in the Texinfo file too. (If you want only one Tex‐
4291 info file, use your master_doc here.)
4292 · targetname: file name (no extension) of the Texinfo file in
4294 the output directory.
4295 · title: Texinfo document title. Can be empty to use the title
4297 of the startdoc. Inserted as Texinfo markup, so special char‐
4298 acters like @ and {} will need to be escaped to be inserted
4299 literally.
4300 · author: Author for the Texinfo document. Inserted as Texinfo
4302 markup. Use @* to separate multiple authors, as in:
4303 'John@*Sarah'.
4304 · dir_entry: The name that will appear in the top-level DIR menu
4306 file.
4307 · description: Descriptive text to appear in the top-level DIR
4309 menu file.
4310 · category: Specifies the section which this entry will appear
4312 in the top-level DIR menu file.
4313 · toctree_only: Must be True or False. If True, the startdoc
4315 document itself is not included in the output, only the docu‐
4316 ments referenced by it via TOC trees. With this option, you
4317 can put extra stuff in the master document that shows up in
4318 the HTML, but not the Texinfo output.
4319 New in version 1.1.
4321 texinfo_appendices
4323 A list of document names to append as an appendix to all manu‐
4324 als.
4325 New in version 1.1.
4327 texinfo_domain_indices
4329 If true, generate domain-specific indices in addition to the
4330 general index. For e.g. the Python domain, this is the global
4331 module index. Default is True.
4332 This value can be a bool or a list of index names that should be
4334 generated, like for html_domain_indices.
4335 New in version 1.1.
4337 texinfo_show_urls
4339 Control how to display URL addresses.
4340 · 'footnote' -- display URLs in footnotes (default)
4342 · 'no' -- do not display URLs
4344 · 'inline' -- display URLs inline in parentheses
4346 New in version 1.1.
4348 texinfo_elements
4350 A dictionary that contains Texinfo snippets that override those
4351 Sphinx usually puts into the generated .texi files.
4352 · Keys that you may want to override include:
4354 'paragraphindent'
4356 Number of spaces to indent the first line of each para‐
4357 graph, default 2. Specify 0 for no indentation.
4358 'exampleindent'
4360 Number of spaces to indent the lines for examples or
4361 literal blocks, default 4. Specify 0 for no indenta‐
4362 tion.
4363 'preamble'
4365 Texinfo markup inserted near the beginning of the file.
4366 'copying'
4368 Texinfo markup inserted within the @copying block and
4369 displayed after the title. The default value consists
4370 of a simple title page identifying the project.
4371 · Keys that are set by other options and therefore should not be
4373 overridden are:
4374 'author' 'body' 'date' 'direntry' 'filename' 'project'
4376 'release' 'title' 'direntry'
4377 New in version 1.1.
4379 Options for the linkcheck builder
4381 linkcheck_ignore
4382 A list of regular expressions that match URIs that should not be
4383 checked when doing a linkcheck build. Example:
4384 linkcheck_ignore = [r'http://localhost:\d+/']
4386 New in version 1.1.
4388 linkcheck_timeout
4390 A timeout value, in seconds, for the linkcheck builder. Only
4391 works in Python 2.6 and higher. The default is to use Python's
4392 global socket timeout.
4393 New in version 1.1.
4395 linkcheck_workers
4397 The number of worker threads to use when checking links.
4398 Default is 5 threads.
4399 New in version 1.1.
4401
4403 [1] A note on available globbing syntax: you can use the standard
4404 shell constructs *, ?, [...] and [!...] with the feature that
4405 these all don't match slashes. A double star ** can be used to
4406 match any sequence of characters including slashes.
4407
4409 New in version 1.1.
4410 Complementary to translations provided for Sphinx-generated messages
4412 such as navigation bars, Sphinx provides mechanisms facilitating docu‐
4413 ment translations in itself. See the intl-options for details on con‐
4414 figuration.
4415 [image] Workflow visualization of translations in Sphinx. (The
4416 stick-figure is taken from an XKCD comic.).UNINDENT
4417 gettext [1] is an established standard for internationalization and
4419 localization. It naïvely maps messages in a program to a translated
4420 string. Sphinx uses these facilities to translate whole documents.
4421 Initially project maintainers have to collect all translatable
4423 strings (also referred to as messages) to make them known to transla‐
4424 tors. Sphinx extracts these through invocation of sphinx-build -b
4425 gettext.
4426 Every single element in the doctree will end up in a single message
4428 which results in lists being equally split into different chunks
4429 while large paragraphs will remain as coarsely-grained as they were
4430 in the original document. This grants seamless document updates
4431 while still providing a little bit of context for translators in
4432 free-text passages. It is the maintainer's task to split up para‐
4433 graphs which are too large as there is no sane automated way to do
4434 that.
4435 After Sphinx successfully ran the MessageCatalogBuilder you will find
4437 a collection of .pot files in your output directory. These are cata‐
4438 log templates and contain messages in your original language only.
4439 They can be delivered to translators which will transform them to .po
4441 files --- so called message catalogs --- containing a mapping from
4442 the original messages to foreign-language strings.
4443 Gettext compiles them into a binary format known as binary catalogs
4445 through msgfmt for efficiency reasons. If you make these files dis‐
4446 coverable with locale_dirs for your language, Sphinx will pick them
4447 up automatically.
4448 An example: you have a document usage.rst in your Sphinx project.
4450 The gettext builder will put its messages into usage.pot. Imagine
4451 you have Spanish translations [2] on your hands in usage.po --- for
4452 your builds to be translated you need to follow these instructions:
4453 · Compile your message catalog to a locale directory, say translated,
4455 so it ends up in ./translated/es/LC_MESSAGES/usage.mo in your source
4456 directory (where es is the language code for Spanish.)
4457 msgfmt "usage.po" -o "translated/es/LC_MESSAGES/usage.mo"
4459 · Set locale_dirs to ["translated/"].
4461 · Set language to es (also possible via -D).
4463 · Run your desired build.
4465
4467 [1] See the GNU gettext utilites for details on that software suite.
4468 [2] Because nobody expects the Spanish Inquisition!
4470
4472 New in version 0.6.
4473 Sphinx supports changing the appearance of its HTML output via themes.
4475 A theme is a collection of HTML templates, stylesheet(s) and other
4476 static files. Additionally, it has a configuration file which speci‐
4477 fies from which theme to inherit, which highlighting style to use, and
4478 what options exist for customizing the theme's look and feel.
4479 Themes are meant to be project-unaware, so they can be used for differ‐
4481 ent projects without change.
4482 Using a theme
4484 Using an existing theme is easy. If the theme is builtin to Sphinx,
4485 you only need to set the html_theme config value. With the
4486 html_theme_options config value you can set theme-specific options that
4487 change the look and feel. For example, you could have the following in
4488 your conf.py:
4489 html_theme = "default"
4491 html_theme_options = {
4492 "rightsidebar": "true",
4493 "relbarbgcolor": "black"
4494 }
4495 That would give you the default theme, but with a sidebar on the right
4497 side and a black background for the relation bar (the bar with the nav‐
4498 igation links at the page's top and bottom).
4499 If the theme does not come with Sphinx, it can be in two forms: either
4501 a directory (containing theme.conf and other needed files), or a zip
4502 file with the same contents. Either of them must be put where Sphinx
4503 can find it; for this there is the config value html_theme_path. It
4504 gives a list of directories, relative to the directory containing
4505 conf.py, that can contain theme directories or zip files. For example,
4506 if you have a theme in the file blue.zip, you can put it right in the
4507 directory containing conf.py and use this configuration:
4508 html_theme = "blue"
4510 html_theme_path = ["."]
4511 Builtin themes
4513 ┌───────────────────────────┬────────────────────────────┐
4514 │Theme overview │ │
4515 ├───────────────────────────┼────────────────────────────┤
4516 │[image: default] [image] │ [image: sphinxdoc] [image] │
4517 │ │ │
4518 │ │ │
4519 │default │ sphinxdoc │
4520 ├───────────────────────────┼────────────────────────────┤
4521 │[image: scrolls] [image] │ [image: agogo] [image] │
4522 │ │ │
4523 │ │ │
4524 │scrolls │ agogo │
4525 ├───────────────────────────┼────────────────────────────┤
4526 │[image: traditional] │ [image: nature] [image] │
4527 │[image] │ │
4528 │ │ │
4529 │ │ nature │
4530 │traditional │ │
4531 ├───────────────────────────┼────────────────────────────┤
4532 │[image: haiku] [image] │ [image: pyramid] [image] │
4533 │ │ │
4534 │ │ │
4535 │haiku │ pyramid │
4536 └───────────────────────────┴────────────────────────────┘
4537 Sphinx comes with a selection of themes to choose from.
4539 These themes are:
4541 · basic -- This is a basically unstyled layout used as the base for the
4543 other themes, and usable as the base for custom themes as well. The
4544 HTML contains all important elements like sidebar and relation bar.
4545 There are these options (which are inherited by the other themes):
4546 · nosidebar (true or false): Don't include the sidebar. Defaults to
4548 false.
4549 · sidebarwidth (an integer): Width of the sidebar in pixels. (Do not
4551 include px in the value.) Defaults to 230 pixels.
4552 · default -- This is the default theme, which looks like the Python
4554 documentation. It can be customized via these options:
4555 · rightsidebar (true or false): Put the sidebar on the right side.
4557 Defaults to false.
4558 · stickysidebar (true or false): Make the sidebar "fixed" so that it
4560 doesn't scroll out of view for long body content. This may not
4561 work well with all browsers. Defaults to false.
4562 · collapsiblesidebar (true or false): Add an experimental JavaScript
4564 snippet that makes the sidebar collapsible via a button on its
4565 side. Doesn't work together with "rightsidebar" or "stickyside‐
4566 bar". Defaults to false.
4567 · externalrefs (true or false): Display external links differently
4569 from internal links. Defaults to false.
4570 There are also various color and font options that can change the
4572 color scheme without having to write a custom stylesheet:
4573 · footerbgcolor (CSS color): Background color for the footer line.
4575 · footertextcolor (CSS color): Text color for the footer line.
4577 · sidebarbgcolor (CSS color): Background color for the sidebar.
4579 · sidebarbtncolor (CSS color): Background color for the sidebar col‐
4581 lapse button (used when collapsiblesidebar is true).
4582 · sidebartextcolor (CSS color): Text color for the sidebar.
4584 · sidebarlinkcolor (CSS color): Link color for the sidebar.
4586 · relbarbgcolor (CSS color): Background color for the relation bar.
4588 · relbartextcolor (CSS color): Text color for the relation bar.
4590 · relbarlinkcolor (CSS color): Link color for the relation bar.
4592 · bgcolor (CSS color): Body background color.
4594 · textcolor (CSS color): Body text color.
4596 · linkcolor (CSS color): Body link color.
4598 · visitedlinkcolor (CSS color): Body color for visited links.
4600 · headbgcolor (CSS color): Background color for headings.
4602 · headtextcolor (CSS color): Text color for headings.
4604 · headlinkcolor (CSS color): Link color for headings.
4606 · codebgcolor (CSS color): Background color for code blocks.
4608 · codetextcolor (CSS color): Default text color for code blocks, if
4610 not set differently by the highlighting style.
4611 · bodyfont (CSS font-family): Font for normal text.
4613 · headfont (CSS font-family): Font for headings.
4615 · sphinxdoc -- The theme used for this documentation. It features a
4617 sidebar on the right side. There are currently no options beyond
4618 nosidebar and sidebarwidth.
4619 · scrolls -- A more lightweight theme, based on the Jinja documenta‐
4621 tion. The following color options are available:
4622 · headerbordercolor
4624 · subheadlinecolor
4626 · linkcolor
4628 · visitedlinkcolor
4630 · admonitioncolor
4632 · agogo -- A theme created by Andi Albrecht. The following options are
4634 supported:
4635 · bodyfont (CSS font family): Font for normal text.
4637 · headerfont (CSS font family): Font for headings.
4639 · pagewidth (CSS length): Width of the page content, default 70em.
4641 · documentwidth (CSS length): Width of the document (without side‐
4643 bar), default 50em.
4644 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
4646 · bgcolor (CSS color): Background color.
4648 · headerbg (CSS value for "background"): background for the header
4650 area, default a grayish gradient.
4651 · footerbg (CSS value for "background"): background for the footer
4653 area, default a light gray gradient.
4654 · linkcolor (CSS color): Body link color.
4656 · headercolor1, headercolor2 (CSS color): colors for <h1> and <h2>
4658 headings.
4659 · headerlinkcolor (CSS color): Color for the backreference link in
4661 headings.
4662 · textalign (CSS text-align value): Text alignment for the body,
4664 default is justify.
4665 · nature -- A greenish theme. There are currently no options beyond
4667 nosidebar and sidebarwidth.
4668 · pyramid -- A theme from the Pyramid web framework project, designed
4670 by Blaise Laflamme. There are currently no options beyond nosidebar
4671 and sidebarwidth.
4672 · haiku -- A theme without sidebar inspired by the Haiku OS user guide.
4674 The following options are supported:
4675 · full_logo (true or false, default false): If this is true, the
4677 header will only show the html_logo. Use this for large logos. If
4678 this is false, the logo (if present) will be shown floating right,
4679 and the documentation title will be put in the header.
4680 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlink‐
4682 color (CSS colors): Colors for various body elements.
4683 · traditional -- A theme resembling the old Python documentation.
4685 There are currently no options beyond nosidebar and sidebarwidth.
4686 · epub -- A theme for the epub builder. There are currently no
4688 options. This theme tries to save visual space which is a sparse
4689 resource on ebook readers.
4690 Creating themes
4692 As said, themes are either a directory or a zipfile (whose name is the
4693 theme name), containing the following:
4694 · A theme.conf file, see below.
4696 · HTML templates, if needed.
4698 · A static/ directory containing any static files that will be copied
4700 to the output static directory on build. These can be images,
4701 styles, script files.
4702 The theme.conf file is in INI format [1] (readable by the standard
4704 Python ConfigParser module) and has the following structure:
4705 [theme]
4707 inherit = base theme
4708 stylesheet = main CSS name
4709 pygments_style = stylename
4710 [options]
4712 variable = default value
4713 · The inherit setting gives the name of a "base theme", or none. The
4715 base theme will be used to locate missing templates (most themes will
4716 not have to supply most templates if they use basic as the base
4717 theme), its options will be inherited, and all of its static files
4718 will be used as well.
4719 · The stylesheet setting gives the name of a CSS file which will be
4721 referenced in the HTML header. If you need more than one CSS file,
4722 either include one from the other via CSS' @import, or use a custom
4723 HTML template that adds <link rel="stylesheet"> tags as necessary.
4724 Setting the html_style config value will override this setting.
4725 · The pygments_style setting gives the name of a Pygments style to use
4727 for highlighting. This can be overridden by the user in the pyg‐
4728 ments_style config value.
4729 · The options section contains pairs of variable names and default val‐
4731 ues. These options can be overridden by the user in
4732 html_theme_options and are accessible from all templates as
4733 theme_<name>.
4734 Templating
4736 The guide to templating is helpful if you want to write your own tem‐
4737 plates. What is important to keep in mind is the order in which Sphinx
4738 searches for templates:
4739 · First, in the user's templates_path directories.
4741 · Then, in the selected theme.
4743 · Then, in its base theme, its base's base theme, etc.
4745 When extending a template in the base theme with the same name, use the
4747 theme name as an explicit directory: {% extends "basic/layout.html" %}.
4748 From a user templates_path template, you can still use the "exclamation
4749 mark" syntax as described in the templating document.
4750 Static templates
4752 Since theme options are meant for the user to configure a theme more
4753 easily, without having to write a custom stylesheet, it is necessary to
4754 be able to template static files as well as HTML files. Therefore,
4755 Sphinx supports so-called "static templates", like this:
4756 If the name of a file in the static/ directory of a theme (or in the
4758 user's static path, for that matter) ends with _t, it will be processed
4759 by the template engine. The _t will be left from the final file name.
4760 For example, the default theme has a file static/default.css_t which
4761 uses templating to put the color options into the stylesheet. When a
4762 documentation is built with the default theme, the output directory
4763 will contain a _static/default.css file where all template tags have
4764 been processed.
4765 [1] It is not an executable Python file, as opposed to conf.py,
4767 because that would pose an unnecessary security risk if themes are
4768 shared.
4769
4771 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
4772 is a text-based engine, and inspired by Django templates, so anyone
4773 having used Django will already be familiar with it. It also has
4774 excellent documentation for those who need to make themselves familiar
4775 with it.
4776 Do I need to use Sphinx' templates to produce HTML?
4778 No. You have several other options:
4779 · You can write a TemplateBridge subclass that calls your template
4781 engine of choice, and set the template_bridge configuration value
4782 accordingly.
4783 · You can write a custom builder that derives from StandaloneHTML‐
4785 Builder and calls your template engine of choice.
4786 · You can use the PickleHTMLBuilder that produces pickle files with the
4788 page contents, and postprocess them using a custom tool, or use them
4789 in your Web application.
4790 Jinja/Sphinx Templating Primer
4792 The default templating language in Sphinx is Jinja. It's Django/Smarty
4793 inspired and easy to understand. The most important concept in Jinja
4794 is template inheritance, which means that you can overwrite only spe‐
4795 cific blocks within a template, customizing it while also keeping the
4796 changes at a minimum.
4797 To customize the output of your documentation you can override all the
4799 templates (both the layout templates and the child templates) by adding
4800 files with the same name as the original filename into the template
4801 directory of the structure the Sphinx quickstart generated for you.
4802 Sphinx will look for templates in the folders of templates_path first,
4804 and if it can't find the template it's looking for there, it falls back
4805 to the selected theme's templates.
4806 A template contains variables, which are replaced with values when the
4808 template is evaluated, tags, which control the logic of the template
4809 and blocks which are used for template inheritance.
4810 Sphinx' basic theme provides base templates with a couple of blocks it
4812 will fill with data. These are located in the themes/basic subdirec‐
4813 tory of the Sphinx installation directory, and used by all builtin
4814 Sphinx themes. Templates with the same name in the templates_path
4815 override templates supplied by the selected theme.
4816 For example, to add a new link to the template area containing related
4818 links all you have to do is to add a new template called layout.html
4819 with the following contents:
4820 {% extends "!layout.html" %}
4822 {% block rootrellink %}
4823 <li><a href="http://project.invalid/">Project Homepage</a> »</li>
4824 {{ super() }}
4825 {% endblock %}
4826 By prefixing the name of the overridden template with an exclamation
4828 mark, Sphinx will load the layout template from the underlying HTML
4829 theme.
4830 Important: If you override a block, call {{ super() }} somewhere to
4832 render the block's content in the extended template -- unless you don't
4833 want that content to show up.
4834 Working with the builtin templates
4836 The builtin basic theme supplies the templates that all builtin Sphinx
4837 themes are based on. It has the following elements you can override or
4838 use:
4839 Blocks
4841 The following blocks exist in the layout.html template:
4842 doctype
4844 The doctype of the output format. By default this is XHTML 1.0
4845 Transitional as this is the closest to what Sphinx and Docutils
4846 generate and it's a good idea not to change it unless you want
4847 to switch to HTML 5 or a different but compatible XHTML doctype.
4848 linktags
4850 This block adds a couple of <link> tags to the head section of
4851 the template.
4852 extrahead
4854 This block is empty by default and can be used to add extra con‐
4855 tents into the <head> tag of the generated HTML file. This is
4856 the right place to add references to JavaScript or extra CSS
4857 files.
4858 relbar1 / relbar2
4860 This block contains the relation bar, the list of related links
4861 (the parent documents on the left, and the links to index, mod‐
4862 ules etc. on the right). relbar1 appears before the document,
4863 relbar2 after the document. By default, both blocks are filled;
4864 to show the relbar only before the document, you would override
4865 relbar2 like this:
4866 {% block relbar2 %}{% endblock %}
4868 rootrellink / relbaritems
4870 Inside the relbar there are three sections: The rootrellink, the
4871 links from the documentation and the custom relbaritems. The
4872 rootrellink is a block that by default contains a list item
4873 pointing to the master document by default, the relbaritems is
4874 an empty block. If you override them to add extra links into
4875 the bar make sure that they are list items and end with the
4876 reldelim1.
4877 document
4879 The contents of the document itself. It contains the block
4880 "body" where the individual content is put by subtemplates like
4881 page.html.
4882 sidebar1 / sidebar2
4884 A possible location for a sidebar. sidebar1 appears before the
4885 document and is empty by default, sidebar2 after the document
4886 and contains the default sidebar. If you want to swap the side‐
4887 bar location override this and call the sidebar helper:
4888 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
4890 {% block sidebar2 %}{% endblock %}
4891 (The sidebar2 location for the sidebar is needed by the sphinx‐
4893 doc.css stylesheet, for example.)
4894 sidebarlogo
4896 The logo location within the sidebar. Override this if you want
4897 to place some content at the top of the sidebar.
4898 footer The block for the footer div. If you want a custom footer or
4900 markup before or after it, override this one.
4901 The following four blocks are only used for pages that do not have
4903 assigned a list of custom sidebars in the html_sidebars config value.
4904 Their use is deprecated in favor of separate sidebar templates, which
4905 can be included via html_sidebars.
4906 sidebartoc
4908 The table of contents within the sidebar.
4909 Deprecated since version 1.0.
4911 sidebarrel
4913 The relation links (previous, next document) within the sidebar.
4914 Deprecated since version 1.0.
4916 sidebarsourcelink
4918 The "Show source" link within the sidebar (normally only shown
4919 if this is enabled by html_show_sourcelink).
4920 Deprecated since version 1.0.
4922 sidebarsearch
4924 The search box within the sidebar. Override this if you want to
4925 place some content at the bottom of the sidebar.
4926 Deprecated since version 1.0.
4928 Configuration Variables
4930 Inside templates you can set a couple of variables used by the layout
4931 template using the {% set %} tag:
4932 reldelim1
4934 The delimiter for the items on the left side of the related bar.
4935 This defaults to ' »' Each item in the related bar ends
4936 with the value of this variable.
4937 reldelim2
4939 The delimiter for the items on the right side of the related
4940 bar. This defaults to ' |'. Each item except of the last one
4941 in the related bar ends with the value of this variable.
4942 Overriding works like this:
4944 {% extends "!layout.html" %}
4946 {% set reldelim1 = ' >' %}
4947 script_files
4949 Add additional script files here, like this:
4950 {% set script_files = script_files + ["_static/myscript.js"] %}
4952 css_files
4954 Similar to script_files, for CSS files.
4955 Helper Functions
4957 Sphinx provides various Jinja functions as helpers in the template.
4958 You can use them to generate links or output multiply used elements.
4959 pathto(document)
4961 Return the path to a Sphinx document as a URL. Use this to
4962 refer to built documents.
4963 pathto(file, 1)
4965 Return the path to a file which is a filename relative to the
4966 root of the generated output. Use this to refer to static
4967 files.
4968 hasdoc(document)
4970 Check if a document with the name document exists.
4971 sidebar()
4973 Return the rendered sidebar.
4974 relbar()
4976 Return the rendered relation bar.
4977 Global Variables
4979 These global variables are available in every template and are safe to
4980 use. There are more, but most of them are an implementation detail and
4981 might change in the future.
4982 builder
4984 The name of the builder (e.g. html or htmlhelp).
4985 copyright
4987 The value of copyright.
4988 docstitle
4990 The title of the documentation (the value of html_title).
4991 embedded
4993 True if the built HTML is meant to be embedded in some viewing
4994 application that handles navigation, not the web browser, such
4995 as for HTML help or Qt help formats. In this case, the sidebar
4996 is not included.
4997 favicon
4999 The path to the HTML favicon in the static path, or ''.
5000 file_suffix
5002 The value of the builder's out_suffix attribute, i.e. the file
5003 name extension that the output files will get. For a standard
5004 HTML builder, this is usually .html.
5005 has_source
5007 True if the reST document sources are copied (if
5008 html_copy_source is true).
5009 last_updated
5011 The build date.
5012 logo The path to the HTML logo image in the static path, or ''.
5014 master_doc
5016 The value of master_doc, for usage with pathto().
5017 next The next document for the navigation. This variable is either
5019 false or has two attributes link and title. The title contains
5020 HTML markup. For example, to generate a link to the next page,
5021 you can use this snippet:
5022 {% if next %}
5024 <a href="{{ next.link|e }}">{{ next.title }}</a>
5025 {% endif %}
5026 pagename
5028 The "page name" of the current file, i.e. either the document
5029 name if the file is generated from a reST source, or the equiva‐
5030 lent hierarchical name relative to the output directory ([direc‐
5031 tory/]filename_without_extension).
5032 parents
5034 A list of parent documents for navigation, structured like the
5035 next item.
5036 prev Like next, but for the previous page.
5038 project
5040 The value of project.
5041 release
5043 The value of release.
5044 rellinks
5046 A list of links to put at the left side of the relbar, next to
5047 "next" and "prev". This usually contains links to the general
5048 index and other indices, such as the Python module index. If
5049 you add something yourself, it must be a tuple (pagename, link
5050 title, accesskey, link text).
5051 shorttitle
5053 The value of html_short_title.
5054 show_source
5056 True if html_show_sourcelink is true.
5057 sphinx_version
5059 The version of Sphinx used to build.
5060 style The name of the main stylesheet, as given by the theme or
5062 html_style.
5063 title The title of the current document, as used in the <title> tag.
5065 use_opensearch
5067 The value of html_use_opensearch.
5068 version
5070 The value of version.
5071 In addition to these values, there are also all theme options available
5073 (prefixed by theme_), as well as the values given by the user in
5074 html_context.
5075 In documents that are created from source files (as opposed to automat‐
5077 ically-generated files like the module index, or documents that already
5078 are in HTML form), these variables are also available:
5079 meta Document metadata (a dictionary), see metadata.
5081 sourcename
5083 The name of the copied source file for the current document.
5084 This is only nonempty if the html_copy_source value is true.
5085 toc The local table of contents for the current page, rendered as
5087 HTML bullet lists.
5088 toctree
5090 A callable yielding the global TOC tree containing the current
5091 page, rendered as HTML bullet lists. Optional keyword argu‐
5092 ments:
5093 · collapse (true by default): if true, all TOC entries that are
5095 not ancestors of the current page are collapsed
5096 · maxdepth (defaults to the max depth selected in the toctree
5098 directive): the maximum depth of the tree; set it to -1 to
5099 allow unlimited depth
5100 · titles_only (false by default): if true, put only toplevel
5102 document titles in the tree
5103
5105 Since many projects will need special features in their documentation,
5106 Sphinx is designed to be extensible on several levels.
5107 This is what you can do in an extension: First, you can add new
5109 builders to support new output formats or actions on the parsed docu‐
5110 ments. Then, it is possible to register custom reStructuredText roles
5111 and directives, extending the markup. And finally, there are so-called
5112 "hook points" at strategic places throughout the build process, where
5113 an extension can register a hook and run specialized code.
5114 An extension is simply a Python module. When an extension is loaded,
5116 Sphinx imports this module and executes its setup() function, which in
5117 turn notifies Sphinx of everything the extension offers -- see the
5118 extension tutorial for examples.
5119 The configuration file itself can be treated as an extension if it con‐
5121 tains a setup() function. All other extensions to load must be listed
5122 in the extensions configuration value.
5123 Tutorial: Writing a simple extension
5125 This section is intended as a walkthrough for the creation of custom
5126 extensions. It covers the basics of writing and activating an exten‐
5127 sions, as well as commonly used features of extensions.
5128 As an example, we will cover a "todo" extension that adds capabilities
5130 to include todo entries in the documentation, and collecting these in a
5131 central place. (A similar "todo" extension is distributed with
5132 Sphinx.)
5133 Build Phases
5135 One thing that is vital in order to understand extension mechanisms is
5136 the way in which a Sphinx project is built: this works in several
5137 phases.
5138 Phase 0: Initialization
5140 In this phase, almost nothing interesting for us happens. The
5141 source directory is searched for source files, and extensions are
5142 initialized. Should a stored build environment exist, it is loaded,
5143 otherwise a new one is created.
5144 Phase 1: Reading
5146 In Phase 1, all source files (and on subsequent builds, those that
5147 are new or changed) are read and parsed. This is the phase where
5148 directives and roles are encountered by the docutils, and the corre‐
5149 sponding functions are called. The output of this phase is a doc‐
5150 tree for each source files, that is a tree of docutils nodes. For
5151 document elements that aren't fully known until all existing files
5152 are read, temporary nodes are created.
5153 During reading, the build environment is updated with all meta- and
5155 cross reference data of the read documents, such as labels, the
5156 names of headings, described Python objects and index entries. This
5157 will later be used to replace the temporary nodes.
5158 The parsed doctrees are stored on the disk, because it is not possi‐
5160 ble to hold all of them in memory.
5161 Phase 2: Consistency checks
5163 Some checking is done to ensure no surprises in the built documents.
5164 Phase 3: Resolving
5166 Now that the metadata and cross-reference data of all existing docu‐
5167 ments is known, all temporary nodes are replaced by nodes that can
5168 be converted into output. For example, links are created for object
5169 references that exist, and simple literal nodes are created for
5170 those that don't.
5171 Phase 4: Writing
5173 This phase converts the resolved doctrees to the desired output for‐
5174 mat, such as HTML or LaTeX. This happens via a so-called docutils
5175 writer that visits the individual nodes of each doctree and produces
5176 some output in the process.
5177 NOTE:
5179 Some builders deviate from this general build plan, for example, the
5180 builder that checks external links does not need anything more than
5181 the parsed doctrees and therefore does not have phases 2--4.
5182 Extension Design
5184 We want the extension to add the following to Sphinx:
5185 · A "todo" directive, containing some content that is marked with
5187 "TODO", and only shown in the output if a new config value is set.
5188 (Todo entries should not be in the output by default.)
5189 · A "todolist" directive that creates a list of all todo entries
5191 throughout the documentation.
5192 For that, we will need to add the following elements to Sphinx:
5194 · New directives, called todo and todolist.
5196 · New document tree nodes to represent these directives, conventionally
5198 also called todo and todolist. We wouldn't need new nodes if the new
5199 directives only produced some content representable by existing
5200 nodes.
5201 · A new config value todo_include_todos (config value names should
5203 start with the extension name, in order to stay unique) that controls
5204 whether todo entries make it into the output.
5205 · New event handlers: one for the doctree-resolved event, to replace
5207 the todo and todolist nodes, and one for env-purge-doc (the reason
5208 for that will be covered later).
5209 The Setup Function
5211 The new elements are added in the extension's setup function. Let us
5212 create a new Python module called todo.py and add the setup function:
5213 def setup(app):
5215 app.add_config_value('todo_include_todos', False, False)
5216 app.add_node(todolist)
5218 app.add_node(todo,
5219 html=(visit_todo_node, depart_todo_node),
5220 latex=(visit_todo_node, depart_todo_node),
5221 text=(visit_todo_node, depart_todo_node))
5222 app.add_directive('todo', TodoDirective)
5224 app.add_directive('todolist', TodolistDirective)
5225 app.connect('doctree-resolved', process_todo_nodes)
5226 app.connect('env-purge-doc', purge_todos)
5227 The calls in this function refer to classes and functions not yet writ‐
5229 ten. What the individual calls do is the following:
5230 · add_config_value() lets Sphinx know that it should recognize the new
5232 config value todo_include_todos, whose default value should be False
5233 (this also tells Sphinx that it is a boolean value).
5234 If the third argument was True, all documents would be re-read if the
5236 config value changed its value. This is needed for config values
5237 that influence reading (build phase 1).
5238 · add_node() adds a new node class to the build system. It also can
5240 specify visitor functions for each supported output format. These
5241 visitor functions are needed when the new nodes stay until phase 4 --
5242 since the todolist node is always replaced in phase 3, it doesn't
5243 need any.
5244 We need to create the two node classes todo and todolist later.
5246 · add_directive() adds a new directive, given by name and class.
5248 The handler functions are created later.
5250 · Finally, connect() adds an event handler to the event whose name is
5252 given by the first argument. The event handler function is called
5253 with several arguments which are documented with the event.
5254 The Node Classes
5256 Let's start with the node classes:
5257 from docutils import nodes
5259 class todo(nodes.Admonition, nodes.Element):
5261 pass
5262 class todolist(nodes.General, nodes.Element):
5264 pass
5265 def visit_todo_node(self, node):
5267 self.visit_admonition(node)
5268 def depart_todo_node(self, node):
5270 self.depart_admonition(node)
5271 Node classes usually don't have to do anything except inherit from the
5273 standard docutils classes defined in docutils.nodes. todo inherits
5274 from Admonition because it should be handled like a note or warning,
5275 todolist is just a "general" node.
5276 The Directive Classes
5278 A directive class is a class deriving usually from docu‐
5279 tils.parsers.rst.Directive. Since the class-based directive interface
5280 doesn't exist yet in Docutils 0.4, Sphinx has another base class called
5281 sphinx.util.compat.Directive that you can derive your directive from,
5282 and it will work with both Docutils 0.4 and 0.5 upwards. The directive
5283 interface is covered in detail in the docutils documentation; the
5284 important thing is that the class has a method run that returns a list
5285 of nodes.
5286 The todolist directive is quite simple:
5288 from sphinx.util.compat import Directive
5290 class TodolistDirective(Directive):
5292 def run(self):
5294 return [todolist('')]
5295 An instance of our todolist node class is created and returned. The
5297 todolist directive has neither content nor arguments that need to be
5298 handled.
5299 The todo directive function looks like this:
5301 from sphinx.util.compat import make_admonition
5303 class TodoDirective(Directive):
5305 # this enables content in the directive
5307 has_content = True
5308 def run(self):
5310 env = self.state.document.settings.env
5311 targetid = "todo-%d" % env.new_serialno('todo')
5313 targetnode = nodes.target('', '', ids=[targetid])
5314 ad = make_admonition(todo, self.name, [_('Todo')], self.options,
5316 self.content, self.lineno, self.content_offset,
5317 self.block_text, self.state, self.state_machine)
5318 if not hasattr(env, 'todo_all_todos'):
5320 env.todo_all_todos = []
5321 env.todo_all_todos.append({
5322 'docname': env.docname,
5323 'lineno': self.lineno,
5324 'todo': ad[0].deepcopy(),
5325 'target': targetnode,
5326 })
5327 return [targetnode] + ad
5329 Several important things are covered here. First, as you can see, you
5331 can refer to the build environment instance using self.state.docu‐
5332 ment.settings.env.
5333 Then, to act as a link target (from the todolist), the todo directive
5335 needs to return a target node in addition to the todo node. The target
5336 ID (in HTML, this will be the anchor name) is generated by using
5337 env.new_serialno which is returns a new integer directive on each call
5338 and therefore leads to unique target names. The target node is instan‐
5339 tiated without any text (the first two arguments).
5340 An admonition is created using a standard docutils function (wrapped in
5342 Sphinx for docutils cross-version compatibility). The first argument
5343 gives the node class, in our case todo. The third argument gives the
5344 admonition title (use arguments here to let the user specify the
5345 title). A list of nodes is returned from make_admonition.
5346 Then, the todo node is added to the environment. This is needed to be
5348 able to create a list of all todo entries throughout the documentation,
5349 in the place where the author puts a todolist directive. For this
5350 case, the environment attribute todo_all_todos is used (again, the name
5351 should be unique, so it is prefixed by the extension name). It does
5352 not exist when a new environment is created, so the directive must
5353 check and create it if necessary. Various information about the todo
5354 entry's location are stored along with a copy of the node.
5355 In the last line, the nodes that should be put into the doctree are
5357 returned: the target node and the admonition node.
5358 The node structure that the directive returns looks like this:
5360 +--------------------+
5362 | target node |
5363 +--------------------+
5364 +--------------------+
5365 | todo node |
5366 +--------------------+
5367 \__+--------------------+
5368 | admonition title |
5369 +--------------------+
5370 | paragraph |
5371 +--------------------+
5372 | ... |
5373 +--------------------+
5374 The Event Handlers
5376 Finally, let's look at the event handlers. First, the one for the
5377 env-purge-doc event:
5378 def purge_todos(app, env, docname):
5380 if not hasattr(env, 'todo_all_todos'):
5381 return
5382 env.todo_all_todos = [todo for todo in env.todo_all_todos
5383 if todo['docname'] != docname]
5384 Since we store information from source files in the environment, which
5386 is persistent, it may become out of date when the source file changes.
5387 Therefore, before each source file is read, the environment's records
5388 of it are cleared, and the env-purge-doc event gives extensions a
5389 chance to do the same. Here we clear out all todos whose docname
5390 matches the given one from the todo_all_todos list. If there are todos
5391 left in the document, they will be added again during parsing.
5392 The other handler belongs to the doctree-resolved event. This event is
5394 emitted at the end of phase 3 and allows custom resolving to be done:
5395 def process_todo_nodes(app, doctree, fromdocname):
5397 if not app.config.todo_include_todos:
5398 for node in doctree.traverse(todo):
5399 node.parent.remove(node)
5400 # Replace all todolist nodes with a list of the collected todos.
5402 # Augment each todo with a backlink to the original location.
5403 env = app.builder.env
5404 for node in doctree.traverse(todolist):
5406 if not app.config.todo_include_todos:
5407 node.replace_self([])
5408 continue
5409 content = []
5411 for todo_info in env.todo_all_todos:
5413 para = nodes.paragraph()
5414 filename = env.doc2path(todo_info['docname'], base=None)
5415 description = (
5416 _('(The original entry is located in %s, line %d and can be found ') %
5417 (filename, todo_info['lineno']))
5418 para += nodes.Text(description, description)
5419 # Create a reference
5421 newnode = nodes.reference('', '')
5422 innernode = nodes.emphasis(_('here'), _('here'))
5423 newnode['refdocname'] = todo_info['docname']
5424 newnode['refuri'] = app.builder.get_relative_uri(
5425 fromdocname, todo_info['docname'])
5426 newnode['refuri'] += '#' + todo_info['target']['refid']
5427 newnode.append(innernode)
5428 para += newnode
5429 para += nodes.Text('.)', '.)')
5430 # Insert into the todolist
5432 content.append(todo_info['todo'])
5433 content.append(para)
5434 node.replace_self(content)
5436 It is a bit more involved. If our new "todo_include_todos" config
5438 value is false, all todo and todolist nodes are removed from the docu‐
5439 ments.
5440 If not, todo nodes just stay where and how they are. Todolist nodes
5442 are replaced by a list of todo entries, complete with backlinks to the
5443 location where they come from. The list items are composed of the
5444 nodes from the todo entry and docutils nodes created on the fly: a
5445 paragraph for each entry, containing text that gives the location, and
5446 a link (reference node containing an italic node) with the backrefer‐
5447 ence. The reference URI is built by app.builder.get_relative_uri which
5448 creates a suitable URI depending on the used builder, and appending the
5449 todo node's (the target's) ID as the anchor name.
5450 Extension API
5452 Each Sphinx extension is a Python module with at least a setup() func‐
5453 tion. This function is called at initialization time with one argu‐
5454 ment, the application object representing the Sphinx process. This
5455 application object has the following public API:
5456 Sphinx.setup_extension(name)
5458 Load the extension given by the module name. Use this if your
5459 extension needs the features provided by another extension.
5460 Sphinx.add_builder(builder)
5462 Register a new builder. builder must be a class that inherits
5463 from Builder.
5464 Sphinx.add_config_value(name, default, rebuild)
5466 Register a configuration value. This is necessary for Sphinx to
5467 recognize new values and set default values accordingly. The
5468 name should be prefixed with the extension name, to avoid
5469 clashes. The default value can be any Python object. The
5470 string value rebuild must be one of those values:
5471 · 'env' if a change in the setting only takes effect when a doc‐
5473 ument is parsed -- this means that the whole environment must
5474 be rebuilt.
5475 · 'html' if a change in the setting needs a full rebuild of HTML
5477 documents.
5478 · '' if a change in the setting will not need any special
5480 rebuild.
5481 Changed in version 0.4: If the default value is a callable, it
5483 will be called with the config object as its argument in order
5484 to get the default value. This can be used to implement config
5485 values whose default depends on other values.
5486 Changed in version 0.6: Changed rebuild from a simple boolean
5488 (equivalent to '' or 'env') to a string. However, booleans are
5489 still accepted and converted internally.
5490 Sphinx.add_domain(domain)
5492 Make the given domain (which must be a class; more precisely, a
5493 subclass of Domain) known to Sphinx.
5494 New in version 1.0.
5496 Sphinx.override_domain(domain)
5498 Make the given domain class known to Sphinx, assuming that there
5499 is already a domain with its .name. The new domain must be a
5500 subclass of the existing one.
5501 New in version 1.0.
5503 Sphinx.add_index_to_domain(domain, index)
5505 Add a custom index class to the domain named domain. index must
5506 be a subclass of Index.
5507 New in version 1.0.
5509 Sphinx.add_event(name)
5511 Register an event called name. This is needed to be able to
5512 emit it.
5513 Sphinx.add_node(node, **kwds)
5515 Register a Docutils node class. This is necessary for Docutils
5516 internals. It may also be used in the future to validate nodes
5517 in the parsed documents.
5518 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
5520 page writers can be given as keyword arguments: the keyword must
5521 be one or more of 'html', 'latex', 'text', 'man', 'texinfo', the
5522 value a 2-tuple of (visit, depart) methods. depart can be None
5523 if the visit function raises docutils.nodes.SkipNode. Example:
5524 class math(docutils.nodes.Element): pass
5526 def visit_math_html(self, node):
5528 self.body.append(self.starttag(node, 'math'))
5529 def depart_math_html(self, node):
5530 self.body.append('</math>')
5531 app.add_node(math, html=(visit_math_html, depart_math_html))
5533 Obviously, translators for which you don't specify visitor meth‐
5535 ods will choke on the node when encountered in a document to
5536 translate.
5537 Changed in version 0.5: Added the support for keyword arguments
5539 giving visit functions.
5540 Sphinx.add_directive(name, func, content, arguments, **options)
5542 Sphinx.add_directive(name, directiveclass)
5544 Register a Docutils directive. name must be the prospective
5545 directive name. There are two possible ways to write a direc‐
5546 tive:
5547 · In the docutils 0.4 style, obj is the directive function.
5549 content, arguments and options are set as attributes on the
5550 function and determine whether the directive has content,
5551 arguments and options, respectively. This style is depre‐
5552 cated.
5553 · In the docutils 0.5 style, directiveclass is the directive
5555 class. It must already have attributes named has_content,
5556 required_arguments, optional_arguments, final_argument_white‐
5557 space and option_spec that correspond to the options for the
5558 function way. See the Docutils docs for details.
5559 The directive class must inherit from the class docu‐
5561 tils.parsers.rst.Directive.
5562 For example, the (already existing) literalinclude directive
5564 would be added like this:
5565 from docutils.parsers.rst import directives
5567 add_directive('literalinclude', literalinclude_directive,
5568 content = 0, arguments = (1, 0, 0),
5569 linenos = directives.flag,
5570 language = direcitves.unchanged,
5571 encoding = directives.encoding)
5572 Changed in version 0.6: Docutils 0.5-style directive classes are
5574 now supported.
5575 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
5577 **options)
5578 Sphinx.add_directive_to_domain(domain, name, directiveclass)
5580 Like add_directive(), but the directive is added to the domain
5581 named domain.
5582 New in version 1.0.
5584 Sphinx.add_role(name, role)
5586 Register a Docutils role. name must be the role name that
5587 occurs in the source, role the role function (see the Docutils
5588 documentation on details).
5589 Sphinx.add_role_to_domain(domain, name, role)
5591 Like add_role(), but the role is added to the domain named
5592 domain.
5593 New in version 1.0.
5595 Sphinx.add_generic_role(name, nodeclass)
5597 Register a Docutils role that does nothing but wrap its contents
5598 in the node given by nodeclass.
5599 New in version 0.6.
5601 Sphinx.add_object_type(directivename, rolename, indextemplate='',
5603 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
5604 This method is a very convenient way to add a new object type
5605 that can be cross-referenced. It will do this:
5606 · Create a new directive (called directivename) for documenting
5608 an object. It will automatically add index entries if index‐
5609 template is nonempty; if given, it must contain exactly one
5610 instance of %s. See the example below for how the template
5611 will be interpreted.
5612 · Create a new role (called rolename) to cross-reference to
5614 these object descriptions.
5615 · If you provide parse_node, it must be a function that takes a
5617 string and a docutils node, and it must populate the node with
5618 children parsed from the string. It must then return the name
5619 of the item to be used in cross-referencing and index entries.
5620 See the conf.py file in the source for this documentation for
5621 an example.
5622 · The objname (if not given, will default to directivename)
5624 names the type of object. It is used when listing objects,
5625 e.g. in search results.
5626 For example, if you have this call in a custom Sphinx extension:
5628 app.add_object_type('directive', 'dir', 'pair: %s; directive')
5630 you can use this markup in your documents:
5632 .. rst:directive:: function
5634 Document a function.
5636 <...>
5638 See also the :rst:dir:`function` directive.
5640 For the directive, an index entry will be generated as if you
5642 had prepended
5643 .. index:: pair: function; directive
5645 The reference node will be of class literal (so it will be ren‐
5647 dered in a proportional font, as appropriate for code) unless
5648 you give the ref_nodeclass argument, which must be a docutils
5649 node class (most useful are docutils.nodes.emphasis or docu‐
5650 tils.nodes.strong -- you can also use docutils.nodes.generated
5651 if you want no further text decoration).
5652 For the role content, you have the same syntactical possibili‐
5654 ties as for standard Sphinx roles (see xref-syntax).
5655 This method is also available under the deprecated alias
5657 add_description_unit.
5658 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
5660 ref_nodeclass=None, objname='')
5661 This method is very similar to add_object_type() except that the
5662 directive it generates must be empty, and will produce no out‐
5663 put.
5664 That means that you can add semantic targets to your sources,
5666 and refer to them using custom roles instead of generic ones
5667 (like ref). Example call:
5668 app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
5670 Example usage:
5672 .. topic:: application API
5674 The application API
5676 -------------------
5677 <...>
5679 See also :topic:`this section <application API>`.
5681 (Of course, the element following the topic directive needn't be
5683 a section.)
5684 Sphinx.add_transform(transform)
5686 Add the standard docutils Transform subclass transform to the
5687 list of transforms that are applied after Sphinx parses a reST
5688 document.
5689 Sphinx.add_javascript(filename)
5691 Add filename to the list of JavaScript files that the default
5692 HTML template will include. The filename must be relative to
5693 the HTML static path, see the docs for the config value. A full
5694 URI with scheme, like http://example.org/foo.js, is also sup‐
5695 ported.
5696 New in version 0.5.
5698 Sphinx.add_stylesheet(filename)
5700 Add filename to the list of CSS files that the default HTML tem‐
5701 plate will include. Like for add_javascript(), the filename
5702 must be relative to the HTML static path, or a full URI with
5703 scheme.
5704 New in version 1.0.
5706 Sphinx.add_lexer(alias, lexer)
5708 Use lexer, which must be an instance of a Pygments lexer class,
5709 to highlight code blocks with the given language alias.
5710 New in version 0.6.
5712 Sphinx.add_autodocumenter(cls)
5714 Add cls as a new documenter class for the sphinx.ext.autodoc
5715 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
5716 menter. This allows to auto-document new types of objects. See
5717 the source of the autodoc module for examples on how to subclass
5718 Documenter.
5719 New in version 0.6.
5721 Sphinx.add_autodoc_attrgetter(type, getter)
5723 Add getter, which must be a function with an interface compati‐
5724 ble to the getattr() builtin, as the autodoc attribute getter
5725 for objects that are instances of type. All cases where autodoc
5726 needs to get an attribute of a type are then handled by this
5727 function instead of getattr().
5728 New in version 0.6.
5730 Sphinx.add_search_language(cls)
5732 Add cls, which must be a subclass of sphinx.search.Search‐
5733 Language, as a support language for building the HTML full-text
5734 search index. The class must have a lang attribute that indi‐
5735 cates the language it should be used for. See html_search_lan‐
5736 guage.
5737 New in version 1.1.
5739 Sphinx.connect(event, callback)
5741 Register callback to be called when event is emitted. For
5742 details on available core events and the arguments of callback
5743 functions, please see events.
5744 The method returns a "listener ID" that can be used as an argu‐
5746 ment to disconnect().
5747 Sphinx.disconnect(listener_id)
5749 Unregister callback listener_id.
5750 Sphinx.emit(event, *arguments)
5752 Emit event and pass arguments to the callback functions. Return
5753 the return values of all callbacks as a list. Do not emit core
5754 Sphinx events in extensions!
5755 Sphinx.emit_firstresult(event, *arguments)
5757 Emit event and pass arguments to the callback functions. Return
5758 the result of the first callback that doesn't return None.
5759 New in version 0.5.
5761 Sphinx.require_sphinx(version)
5763 Compare version (which must be a major.minor version string,
5764 e.g. '1.1') with the version of the running Sphinx, and abort
5765 the build when it is too old.
5766 New in version 1.0.
5768 exception sphinx.application.ExtensionError
5770 All these functions raise this exception if something went wrong
5771 with the extension API.
5772 Examples of using the Sphinx extension API can be seen in the
5774 sphinx.ext package.
5775 Sphinx core events
5777 These events are known to the core. The arguments shown are given to
5778 the registered event handlers.
5779 builder-inited(app)
5781 Emitted when the builder object has been created. It is avail‐
5782 able as app.builder.
5783 env-get-outdated(app, env, added, changed, removed)
5785 Emitted when the environment determines which source files have
5786 changed and should be re-read. added, changed and removed are
5787 sets of docnames that the environment has determined. You can
5788 return a list of docnames to re-read in addition to these.
5789 New in version 1.1.
5791 env-purge-doc(app, env, docname)
5793 Emitted when all traces of a source file should be cleaned from
5794 the environment, that is, if the source file is removed or
5795 before it is freshly read. This is for extensions that keep
5796 their own caches in attributes of the environment.
5797 For example, there is a cache of all modules on the environment.
5799 When a source file has been changed, the cache's entries for the
5800 file are cleared, since the module declarations could have been
5801 removed from the file.
5802 New in version 0.5.
5804 source-read(app, docname, source)
5806 Emitted when a source file has been read. The source argument
5807 is a list whose single element is the contents of the source
5808 file. You can process the contents and replace this item to
5809 implement source-level transformations.
5810 For example, if you want to use $ signs to delimit inline math,
5812 like in LaTeX, you can use a regular expression to replace $...$
5813 by :math:`...`.
5814 New in version 0.5.
5816 doctree-read(app, doctree)
5818 Emitted when a doctree has been parsed and read by the environ‐
5819 ment, and is about to be pickled. The doctree can be modified
5820 in-place.
5821 missing-reference(app, env, node, contnode)
5823 Emitted when a cross-reference to a Python module or object can‐
5824 not be resolved. If the event handler can resolve the refer‐
5825 ence, it should return a new docutils node to be inserted in the
5826 document tree in place of the node node. Usually this node is a
5827 reference node containing contnode as a child.
5828 Parameters
5830 · env -- The build environment (app.builder.env).
5832 · node -- The pending_xref node to be resolved. Its
5834 attributes reftype, reftarget, modname and classname
5835 attributes determine the type and target of the refer‐
5836 ence.
5837 · contnode -- The node that carries the text and format‐
5839 ting inside the future reference and should be a child
5840 of the returned reference node.
5841 New in version 0.5.
5843 doctree-resolved(app, doctree, docname)
5845 Emitted when a doctree has been "resolved" by the environment,
5846 that is, all references have been resolved and TOCs have been
5847 inserted. The doctree can be modified in place.
5848 Here is the place to replace custom nodes that don't have visi‐
5850 tor methods in the writers, so that they don't cause errors when
5851 the writers encounter them.
5852 env-updated(app, env)
5854 Emitted when the update() method of the build environment has
5855 completed, that is, the environment and all doctrees are now
5856 up-to-date.
5857 New in version 0.5.
5859 html-collect-pages(app)
5861 Emitted when the HTML builder is starting to write non-document
5862 pages. You can add pages to write by returning an iterable from
5863 this event consisting of (pagename, context, templatename).
5864 New in version 1.0.
5866 html-page-context(app, pagename, templatename, context, doctree)
5868 Emitted when the HTML builder has created a context dictionary
5869 to render a template with -- this can be used to add custom ele‐
5870 ments to the context.
5871 The pagename argument is the canonical name of the page being
5873 rendered, that is, without .html suffix and using slashes as
5874 path separators. The templatename is the name of the template
5875 to render, this will be 'page.html' for all pages from reST doc‐
5876 uments.
5877 The context argument is a dictionary of values that are given to
5879 the template engine to render the page and can be modified to
5880 include custom values. Keys must be strings.
5881 The doctree argument will be a doctree when the page is created
5883 from a reST documents; it will be None when the page is created
5884 from an HTML template alone.
5885 New in version 0.4.
5887 build-finished(app, exception)
5889 Emitted when a build has finished, before Sphinx exits, usually
5890 used for cleanup. This event is emitted even when the build
5891 process raised an exception, given as the exception argument.
5892 The exception is reraised in the application after the event
5893 handlers have run. If the build process raised no exception,
5894 exception will be None. This allows to customize cleanup
5895 actions depending on the exception status.
5896 New in version 0.5.
5898 The template bridge
5900 class sphinx.application.TemplateBridge
5901 This class defines the interface for a "template bridge", that
5902 is, a class that renders templates given a template name and a
5903 context.
5904 init(builder, theme=None, dirs=None)
5906 Called by the builder to initialize the template system.
5907 builder is the builder object; you'll probably want to
5909 look at the value of builder.config.templates_path.
5910 theme is a sphinx.theming.Theme object or None; in the
5912 latter case, dirs can be list of fixed directories to
5913 look for templates.
5914 newest_template_mtime()
5916 Called by the builder to determine if output files are
5917 outdated because of template changes. Return the mtime
5918 of the newest template file that was changed. The
5919 default implementation returns 0.
5920 render(template, context)
5922 Called by the builder to render a template given as a
5923 filename with a specified context (a Python dictionary).
5924 render_string(template, context)
5926 Called by the builder to render a template given as a
5927 string with a specified context (a Python dictionary).
5928 Domain API
5930 class sphinx.domains.Domain(env)
5931 A Domain is meant to be a group of "object" description direc‐
5932 tives for objects of a similar nature, and corresponding roles
5933 to create references to them. Examples would be Python modules,
5934 classes, functions etc., elements of a templating language,
5935 Sphinx roles and directives, etc.
5936 Each domain has a separate storage for information about exist‐
5938 ing objects and how to reference them in self.data, which must
5939 be a dictionary. It also must implement several functions that
5940 expose the object information in a uniform way to parts of
5941 Sphinx that allow the user to reference or search for objects in
5942 a domain-agnostic way.
5943 About self.data: since all object and cross-referencing informa‐
5945 tion is stored on a BuildEnvironment instance, the domain.data
5946 object is also stored in the env.domaindata dict under the key
5947 domain.name. Before the build process starts, every active
5948 domain is instantiated and given the environment object; the
5949 domaindata dict must then either be nonexistent or a dictionary
5950 whose 'version' key is equal to the domain class' data_version
5951 attribute. Otherwise, IOError is raised and the pickled envi‐
5952 ronment is discarded.
5953 clear_doc(docname)
5955 Remove traces of a document in the domain-specific inven‐
5956 tories.
5957 directive(name)
5959 Return a directive adapter class that always gives the
5960 registered directive its full name ('domain:name') as
5961 self.name.
5962 get_objects()
5964 Return an iterable of "object descriptions", which are
5965 tuples with five items:
5966 · name -- fully qualified name
5968 · dispname -- name to display when searching/linking
5970 · type -- object type, a key in self.object_types
5972 · docname -- the document where it is to be found
5974 · anchor -- the anchor name for the object
5976 · priority -- how "important" the object is (determines
5978 placement in search results)
5979 · 1: default priority (placed before full-text matches)
5981 · 0: object is important (placed before default-prior‐
5983 ity objects)
5984 · 2: object is unimportant (placed after full-text
5986 matches)
5987 · -1: object should not show up in search at all
5989 get_type_name(type, primary=False)
5991 Return full name for given ObjType.
5992 process_doc(env, docname, document)
5994 Process a document after it is read by the environment.
5995 resolve_xref(env, fromdocname, builder, typ, target, node, con‐
5997 tnode)
5998 Resolve the pending_xref node with the given typ and tar‐
5999 get.
6000 This method should return a new node, to replace the xref
6002 node, containing the contnode which is the markup content
6003 of the cross-reference.
6004 If no resolution can be found, None can be returned; the
6006 xref node will then given to the 'missing-reference'
6007 event, and if that yields no resolution, replaced by con‐
6008 tnode.
6009 The method can also raise sphinx.environment.NoUri to
6011 suppress the 'missing-reference' event being emitted.
6012 role(name)
6014 Return a role adapter function that always gives the reg‐
6015 istered role its full name ('domain:name') as the first
6016 argument.
6017 dangling_warnings = {}
6019 role name -> a warning message if reference is missing
6020 data_version = 0
6022 data version, bump this when the format of self.data
6023 changes
6024 directives = {}
6026 directive name -> directive class
6027 indices = []
6029 a list of Index subclasses
6030 initial_data = {}
6032 data value for a fresh environment
6033 label = ''
6035 domain label: longer, more descriptive (used in messages)
6036 name = ''
6038 domain name: should be short, but unique
6039 object_types = {}
6041 type (usually directive) name -> ObjType instance
6042 roles = {}
6044 role name -> role callable
6045 class sphinx.domains.ObjType(lname, *roles, **attrs)
6047 An ObjType is the description for a type of object that a domain
6048 can document. In the object_types attribute of Domain sub‐
6049 classes, object type names are mapped to instances of this
6050 class.
6051 Constructor arguments:
6053 · lname: localized name of the type (do not include domain name)
6055 · roles: all the roles that can refer to an object of this type
6057 · attrs: object attributes -- currently only "searchprio" is
6059 known, which defines the object's priority in the full-text
6060 search index, see Domain.get_objects().
6061 class sphinx.domains.Index(domain)
6063 An Index is the description for a domain-specific index. To add
6064 an index to a domain, subclass Index, overriding the three name
6065 attributes:
6066 · name is an identifier used for generating file names.
6068 · localname is the section title for the index.
6070 · shortname is a short name for the index, for use in the rela‐
6072 tion bar in HTML output. Can be empty to disable entries in
6073 the relation bar.
6074 and providing a generate() method. Then, add the index class to
6076 your domain's indices list. Extensions can add indices to
6077 existing domains using add_index_to_domain().
6078 generate(docnames=None)
6080 Return entries for the index given by name. If docnames
6081 is given, restrict to entries referring to these doc‐
6082 names.
6083 The return value is a tuple of (content, collapse), where
6085 collapse is a boolean that determines if sub-entries
6086 should start collapsed (for output formats that support
6087 collapsing sub-entries).
6088 content is a sequence of (letter, entries) tuples, where
6090 letter is the "heading" for the given entries, usually
6091 the starting letter.
6092 entries is a sequence of single entries, where a single
6094 entry is a sequence [name, subtype, docname, anchor,
6095 extra, qualifier, descr]. The items in this sequence
6096 have the following meaning:
6097 · name -- the name of the index entry to be displayed
6099 · subtype -- sub-entry related type: 0 -- normal entry 1
6101 -- entry with sub-entries 2 -- sub-entry
6102 · docname -- docname where the entry is located
6104 · anchor -- anchor for the entry within docname
6106 · extra -- extra info for the entry
6108 · qualifier -- qualifier for the description
6110 · descr -- description for the entry
6112 Qualifier and description are not rendered e.g. in LaTeX
6114 output.
6115 Writing new builders
6117 Todo
6118 Expand this.
6119 class sphinx.builders.Builder
6121 This is the base class for all builders.
6122 These methods are predefined and will be called from the appli‐
6124 cation:
6125 get_relative_uri(from_, to, typ=None)
6127 Return a relative URI between two source filenames.
6128 May raise environment.NoUri if there's no way to return a
6130 sensible URI.
6131 build_all()
6133 Build all source files.
6134 build_specific(filenames)
6136 Only rebuild as much as needed for changes in the file‐
6137 names.
6138 build_update()
6140 Only rebuild what was changed or added since last build.
6141 build(docnames, summary=None, method='update')
6143 Main build method.
6144 First updates the environment, and then calls write().
6146 These methods can be overridden in concrete builder classes:
6148 init() Load necessary templates and perform initialization. The
6150 default implementation does nothing.
6151 get_outdated_docs()
6153 Return an iterable of output files that are outdated, or
6154 a string describing what an update build will build.
6155 If the builder does not output individual files corre‐
6157 sponding to source files, return a string here. If it
6158 does, return an iterable of those files that need to be
6159 written.
6160 get_target_uri(docname, typ=None)
6162 Return the target URI for a document name.
6163 typ can be used to qualify the link characteristic for
6165 individual builders.
6166 prepare_writing(docnames)
6168 write_doc(docname, doctree)
6170 finish()
6172 Finish the building process.
6173 The default implementation does nothing.
6175 Builtin Sphinx extensions
6177 These extensions are built in and can be activated by respective
6178 entries in the extensions configuration value:
6179 sphinx.ext.autodoc -- Include documentation from docstrings
6181 This extension can import the modules you are documenting, and pull in
6182 documentation from docstrings in a semi-automatic way.
6183 NOTE:
6185 For Sphinx (actually, the Python interpreter that executes Sphinx)
6186 to find your module, it must be importable. That means that the
6187 module or the package must be in one of the directories on sys.path
6188 -- adapt your sys.path in the configuration file accordingly.
6189 For this to work, the docstrings must of course be written in correct
6191 reStructuredText. You can then use all of the usual Sphinx markup in
6192 the docstrings, and it will end up correctly in the documentation.
6193 Together with hand-written documentation, this technique eases the pain
6194 of having to maintain two locations for documentation, while at the
6195 same time avoiding auto-generated-looking pure API documentation.
6196 autodoc provides several directives that are versions of the usual
6198 py:module, py:class and so forth. On parsing time, they import the
6199 corresponding module and extract the docstring of the given objects,
6200 inserting them into the page source under a suitable py:module,
6201 py:class etc. directive.
6202 NOTE:
6204 Just as py:class respects the current py:module, autoclass will also
6205 do so. Likewise, automethod will respect the current py:class.
6206 .. automodule::
6208 .. autoclass::
6210 .. autoexception::
6212 Document a module, class or exception. All three directives
6213 will by default only insert the docstring of the object itself:
6214 .. autoclass:: Noodle
6216 will produce source like this:
6218 .. class:: Noodle
6220 Noodle's docstring.
6222 The "auto" directives can also contain content of their own, it
6224 will be inserted into the resulting non-auto directive source
6225 after the docstring (but before any automatic member documenta‐
6226 tion).
6227 Therefore, you can also mix automatic and non-automatic member
6229 documentation, like so:
6230 .. autoclass:: Noodle
6232 :members: eat, slurp
6233 .. method:: boil(time=10)
6235 Boil the noodle *time* minutes.
6237 Options and advanced usage
6239 · If you want to automatically document members, there's a mem‐
6241 bers option:
6242 .. automodule:: noodle
6244 :members:
6245 will document all module members (recursively), and
6247 .. autoclass:: Noodle
6249 :members:
6250 will document all non-private member functions and properties
6252 (that is, those whose name doesn't start with _).
6253 For modules, __all__ will be respected when looking for mem‐
6255 bers; the order of the members will also be the order in
6256 __all__.
6257 You can also give an explicit list of members; only these will
6259 then be documented:
6260 .. autoclass:: Noodle
6262 :members: eat, slurp
6263 · If you want to make the members option (or other flag options
6265 described below) the default, see autodoc_default_flags.
6266 · Members without docstrings will be left out, unless you give
6268 the undoc-members flag option:
6269 .. automodule:: noodle
6271 :members:
6272 :undoc-members:
6273 · "Private" members (that is, those named like _private or
6275 __private) will be included if the private-members flag option
6276 is given.
6277 New in version 1.1.
6279 · Python "special" members (that is, those named like __spe‐
6281 cial__) will be included if the special-members flag option is
6282 given:
6283 .. autoclass:: my.Class
6285 :members:
6286 :private-members:
6287 :special-members:
6288 would document both "private" and "special" members of the
6290 class.
6291 New in version 1.1.
6293 · For classes and exceptions, members inherited from base
6295 classes will be left out when documenting all members, unless
6296 you give the inherited-members flag option, in addition to
6297 members:
6298 .. autoclass:: Noodle
6300 :members:
6301 :inherited-members:
6302 This can be combined with undoc-members to document all avail‐
6304 able members of the class or module.
6305 Note: this will lead to markup errors if the inherited members
6307 come from a module whose docstrings are not reST formatted.
6308 New in version 0.3.
6310 · It's possible to override the signature for explicitly docu‐
6312 mented callable objects (functions, methods, classes) with the
6313 regular syntax that will override the signature gained from
6314 introspection:
6315 .. autoclass:: Noodle(type)
6317 .. automethod:: eat(persona)
6319 This is useful if the signature from the method is hidden by a
6321 decorator.
6322 New in version 0.4.
6324 · The automodule, autoclass and autoexception directives also
6326 support a flag option called show-inheritance. When given, a
6327 list of base classes will be inserted just below the class
6328 signature (when used with automodule, this will be inserted
6329 for every class that is documented in the module).
6330 New in version 0.4.
6332 · All autodoc directives support the noindex flag option that
6334 has the same effect as for standard py:function etc. direc‐
6335 tives: no index entries are generated for the documented
6336 object (and all autodocumented members).
6337 New in version 0.4.
6339 · automodule also recognizes the synopsis, platform and depre‐
6341 cated options that the standard py:module directive supports.
6342 New in version 0.5.
6344 · automodule and autoclass also has an member-order option that
6346 can be used to override the global value of autodoc_mem‐
6347 ber_order for one directive.
6348 New in version 0.6.
6350 · The directives supporting member documentation also have a
6352 exclude-members option that can be used to exclude single mem‐
6353 ber names from documentation, if all members are to be docu‐
6354 mented.
6355 New in version 0.6.
6357 NOTE:
6359 In an automodule directive with the members option set, only
6360 module members whose __module__ attribute is equal to the
6361 module name as given to automodule will be documented. This
6362 is to prevent documentation of imported classes or functions.
6363 .. autofunction::
6365 .. autodata::
6367 .. automethod::
6369 .. autoattribute::
6371 These work exactly like autoclass etc., but do not offer the
6372 options used for automatic member documentation.
6373 For module data members and class attributes, documentation can
6375 either be put into a special-formatted comment, or in a doc‐
6376 string after the definition. Comments need to be either on a
6377 line of their own before the definition, or immediately after
6378 the assignment on the same line. The latter form is restricted
6379 to one line only.
6380 This means that in the following class definition, all
6382 attributes can be autodocumented:
6383 class Foo:
6385 """Docstring for class Foo."""
6386 #: Doc comment for class attribute Foo.bar.
6388 #: It can have multiple lines.
6389 bar = 1
6390 flox = 1.5 #: Doc comment for Foo.flox. One line only.
6392 baz = 2
6394 """Docstring for class attribute Foo.baz."""
6395 def __init__(self):
6397 #: Doc comment for instance attribute qux.
6398 self.qux = 3
6399 self.spam = 4
6401 """Docstring for instance attribute spam."""
6402 Changed in version 0.6: autodata and autoattribute can now
6404 extract docstrings.
6405 Changed in version 1.1: Comment docs are now allowed on the same
6407 line after an assignment.
6408 NOTE:
6410 If you document decorated functions or methods, keep in mind
6411 that autodoc retrieves its docstrings by importing the module
6412 and inspecting the __doc__ attribute of the given function or
6413 method. That means that if a decorator replaces the deco‐
6414 rated function with another, it must copy the original
6415 __doc__ to the new function.
6416 From Python 2.5, functools.wraps() can be used to create
6418 well-behaved decorating functions.
6419 There are also new config values that you can set:
6421 autoclass_content
6423 This value selects what content will be inserted into the main
6424 body of an autoclass directive. The possible values are:
6425 "class"
6427 Only the class' docstring is inserted. This is the
6428 default. You can still document __init__ as a separate
6429 method using automethod or the members option to auto‐
6430 class.
6431 "both" Both the class' and the __init__ method's docstring are
6433 concatenated and inserted.
6434 "init" Only the __init__ method's docstring is inserted.
6436 New in version 0.3.
6438 autodoc_member_order
6440 This value selects if automatically documented members are
6441 sorted alphabetical (value 'alphabetical'), by member type
6442 (value 'groupwise') or by source order (value 'bysource'). The
6443 default is alphabetical.
6444 Note that for source order, the module must be a Python module
6446 with the source code available.
6447 New in version 0.6.
6449 Changed in version 1.0: Support for 'bysource'.
6451 autodoc_default_flags
6453 This value is a list of autodoc directive flags that should be
6454 automatically applied to all autodoc directives. The supported
6455 flags are 'members', 'undoc-members', 'private-members', 'spe‐
6456 cial-members', 'inherited-members' and 'show-inheritance'.
6457 If you set one of these flags in this config value, you can use
6459 a negated form, 'no-flag', in an autodoc directive, to disable
6460 it once. For example, if autodoc_default_flags is set to ['mem‐
6461 bers', 'undoc-members'], and you write a directive like this:
6462 .. automodule:: foo
6464 :no-undoc-members:
6465 the directive will be interpreted as if only :members: was
6467 given.
6468 New in version 1.0.
6470 autodoc_docstring_signature
6472 Functions imported from C modules cannot be introspected, and
6473 therefore the signature for such functions cannot be automati‐
6474 cally determined. However, it is an often-used convention to
6475 put the signature into the first line of the function's doc‐
6476 string.
6477 If this boolean value is set to True (which is the default),
6479 autodoc will look at the first line of the docstring for func‐
6480 tions and methods, and if it looks like a signature, use the
6481 line as the signature and remove it from the docstring content.
6482 New in version 1.1.
6484 Docstring preprocessing
6486 autodoc provides the following additional events:
6487 autodoc-process-docstring(app, what, name, obj, options, lines)
6489 New in version 0.4.
6490 Emitted when autodoc has read and processed a docstring. lines
6492 is a list of strings -- the lines of the processed docstring --
6493 that the event handler can modify in place to change what Sphinx
6494 puts into the output.
6495 Parameters
6497 · app -- the Sphinx application object
6499 · what -- the type of the object which the docstring
6501 belongs to (one of "module", "class", "exception",
6502 "function", "method", "attribute")
6503 · name -- the fully qualified name of the object
6505 · obj -- the object itself
6507 · options -- the options given to the directive: an
6509 object with attributes inherited_members, undoc_mem‐
6510 bers, show_inheritance and noindex that are true if the
6511 flag option of same name was given to the auto direc‐
6512 tive
6513 · lines -- the lines of the docstring, see above
6515 autodoc-process-signature(app, what, name, obj, options, signature,
6517 return_annotation)
6518 New in version 0.5.
6519 Emitted when autodoc has formatted a signature for an object.
6521 The event handler can return a new tuple (signature,
6522 return_annotation) to change what Sphinx puts into the output.
6523 Parameters
6525 · app -- the Sphinx application object
6527 · what -- the type of the object which the docstring
6529 belongs to (one of "module", "class", "exception",
6530 "function", "method", "attribute")
6531 · name -- the fully qualified name of the object
6533 · obj -- the object itself
6535 · options -- the options given to the directive: an
6537 object with attributes inherited_members, undoc_mem‐
6538 bers, show_inheritance and noindex that are true if the
6539 flag option of same name was given to the auto direc‐
6540 tive
6541 · signature -- function signature, as a string of the
6543 form "(parameter_1, parameter_2)", or None if intro‐
6544 spection didn't succeed and signature wasn't specified
6545 in the directive.
6546 · return_annotation -- function return annotation as a
6548 string of the form " -> annotation", or None if there
6549 is no return annotation
6550 The sphinx.ext.autodoc module provides factory functions for commonly
6552 needed docstring processing in event autodoc-process-docstring:
6553 sphinx.ext.autodoc.cut_lines(pre, post=0, what=None)
6555 Return a listener that removes the first pre and last post lines
6556 of every docstring. If what is a sequence of strings, only doc‐
6557 strings of a type in what will be processed.
6558 Use like this (e.g. in the setup() function of conf.py):
6560 from sphinx.ext.autodoc import cut_lines
6562 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
6563 This can (and should) be used in place of automodule_skip_lines.
6565 sphinx.ext.autodoc.between(marker, what=None, keepempty=False,
6567 exclude=False)
6568 Return a listener that either keeps, or if exclude is True
6569 excludes, lines between lines that match the marker regular
6570 expression. If no line matches, the resulting docstring would
6571 be empty, so no change will be made unless keepempty is true.
6572 If what is a sequence of strings, only docstrings of a type in
6574 what will be processed.
6575 Skipping members
6577 autodoc allows the user to define a custom method for determining
6578 whether a member should be included in the documentation by using the
6579 following event:
6580 autodoc-skip-member(app, what, name, obj, skip, options)
6582 New in version 0.5.
6583 Emitted when autodoc has to decide whether a member should be
6585 included in the documentation. The member is excluded if a han‐
6586 dler returns True. It is included if the handler returns False.
6587 Parameters
6589 · app -- the Sphinx application object
6591 · what -- the type of the object which the docstring
6593 belongs to (one of "module", "class", "exception",
6594 "function", "method", "attribute")
6595 · name -- the fully qualified name of the object
6597 · obj -- the object itself
6599 · skip -- a boolean indicating if autodoc will skip this
6601 member if the user handler does not override the deci‐
6602 sion
6603 · options -- the options given to the directive: an
6605 object with attributes inherited_members, undoc_mem‐
6606 bers, show_inheritance and noindex that are true if the
6607 flag option of same name was given to the auto direc‐
6608 tive
6609 sphinx.ext.autosummary -- Generate autodoc summaries
6611 New in version 0.6.
6612 This extension generates function/method/attribute summary lists, simi‐
6614 lar to those output e.g. by Epydoc and other API doc generation tools.
6615 This is especially useful when your docstrings are long and detailed,
6616 and putting each one of them on a separate page makes them easier to
6617 read.
6618 The sphinx.ext.autosummary extension does this in two parts:
6620 1. There is an autosummary directive for generating summary listings
6622 that contain links to the documented items, and short summary blurbs
6623 extracted from their docstrings.
6624 2. Optionally, the convenience script sphinx-autogen or the new auto‐
6626 summary_generate config value can be used to generate short "stub"
6627 files for the entries listed in the autosummary directives. These
6628 files by default contain only the corresponding sphinx.ext.autodoc
6629 directive, but can be customized with templates.
6630 .. autosummary::
6632 Insert a table that contains links to documented items, and a
6633 short summary blurb (the first sentence of the docstring) for
6634 each of them.
6635 The autosummary directive can also optionally serve as a toctree
6637 entry for the included items. Optionally, stub .rst files for
6638 these items can also be automatically generated.
6639 For example,
6641 .. currentmodule:: sphinx
6643 .. autosummary::
6645 environment.BuildEnvironment
6647 util.relative_uri
6648 produces a table like this:
6650 ┌──────────────────────────┬────────────────────────────┐
6652 │environment.BuildEnviron‐ │ The environment in which │
6653 │ment(srcdir, ...) │ the ReST files are trans‐ │
6654 │ │ lated. │
6655 ├──────────────────────────┼────────────────────────────┤
6656 │util.relative_uri(base, │ Return a relative URL from │
6657 │to) │ base to to. │
6658 └──────────────────────────┴────────────────────────────┘
6659 Autosummary preprocesses the docstrings and signatures with the
6661 same autodoc-process-docstring and autodoc-process-signature
6662 hooks as autodoc.
6663 Options
6665 · If you want the autosummary table to also serve as a toctree
6667 entry, use the toctree option, for example:
6668 .. autosummary::
6670 :toctree: DIRNAME
6671 sphinx.environment.BuildEnvironment
6673 sphinx.util.relative_uri
6674 The toctree option also signals to the sphinx-autogen script
6676 that stub pages should be generated for the entries listed in
6677 this directive. The option accepts a directory name as an
6678 argument; sphinx-autogen will by default place its output in
6679 this directory. If no argument is given, output is placed in
6680 the same directory as the file that contains the directive.
6681 · If you don't want the autosummary to show function signatures
6683 in the listing, include the nosignatures option:
6684 .. autosummary::
6686 :nosignatures:
6687 sphinx.environment.BuildEnvironment
6689 sphinx.util.relative_uri
6690 · You can specify a custom template with the template option.
6692 For example,
6693 .. autosummary::
6695 :template: mytemplate.rst
6696 sphinx.environment.BuildEnvironment
6698 would use the template mytemplate.rst in your templates_path
6700 to generate the pages for all entries listed. See Customizing
6701 templates below.
6702 New in version 1.0.
6704 sphinx-autogen -- generate autodoc stub pages
6706 The sphinx-autogen script can be used to conveniently generate stub
6707 documentation pages for items included in autosummary listings.
6708 For example, the command
6710 $ sphinx-autogen -o generated *.rst
6712 will read all autosummary tables in the *.rst files that have the :toc‐
6714 tree: option set, and output corresponding stub pages in directory gen‐
6715 erated for all documented items. The generated pages by default con‐
6716 tain text of the form:
6717 sphinx.util.relative_uri
6719 ========================
6720 .. autofunction:: sphinx.util.relative_uri
6722 If the -o option is not given, the script will place the output files
6724 in the directories specified in the :toctree: options.
6725 Generating stub pages automatically
6727 If you do not want to create stub pages with sphinx-autogen, you can
6728 also use this new config value:
6729 autosummary_generate
6731 Boolean indicating whether to scan all found documents for auto‐
6732 summary directives, and to generate stub pages for each.
6733 Can also be a list of documents for which stub pages should be
6735 generated.
6736 The new files will be placed in the directories specified in the
6738 :toctree: options of the directives.
6739 Customizing templates
6741 New in version 1.0.
6742 You can customize the stub page templates, in a similar way as the HTML
6744 Jinja templates, see templating. (TemplateBridge is not supported.)
6745 NOTE:
6747 If you find yourself spending much time tailoring the stub tem‐
6748 plates, this may indicate that it's a better idea to write custom
6749 narrative documentation instead.
6750 Autosummary uses the following template files:
6752 · autosummary/base.rst -- fallback template
6754 · autosummary/module.rst -- template for modules
6756 · autosummary/class.rst -- template for classes
6758 · autosummary/function.rst -- template for functions
6760 · autosummary/attribute.rst -- template for class attributes
6762 · autosummary/method.rst -- template for class methods
6764 The following variables available in the templates:
6766 name Name of the documented object, excluding the module and class
6768 parts.
6769 objname
6771 Name of the documented object, excluding the module parts.
6772 fullname
6774 Full name of the documented object, including module and class
6775 parts.
6776 module Name of the module the documented object belongs to.
6778 class Name of the class the documented object belongs to. Only avail‐
6780 able for methods and attributes.
6781 underline
6783 A string containing len(full_name) * '='.
6784 members
6786 List containing names of all members of the module or class.
6787 Only available for modules and classes.
6788 functions
6790 List containing names of "public" functions in the module.
6791 Here, "public" here means that the name does not start with an
6792 underscore. Only available for modules.
6793 classes
6795 List containing names of "public" classes in the module. Only
6796 available for modules.
6797 exceptions
6799 List containing names of "public" exceptions in the module.
6800 Only available for modules.
6801 methods
6803 List containing names of "public" methods in the class. Only
6804 available for classes.
6805 attributes
6807 List containing names of "public" attributes in the class. Only
6808 available for classes.
6809 NOTE:
6811 You can use the autosummary directive in the stub pages. Stub pages
6812 are generated also based on these directives.
6813 sphinx.ext.doctest -- Test snippets in the documentation
6815 This extension allows you to test snippets in the documentation in a
6816 natural way. It works by collecting specially-marked up code blocks
6817 and running them as doctest tests.
6818 Within one document, test code is partitioned in groups, where each
6820 group consists of:
6821 · zero or more setup code blocks (e.g. importing the module to test)
6823 · one or more test blocks
6825 When building the docs with the doctest builder, groups are collected
6827 for each document and run one after the other, first executing setup
6828 code blocks, then the test blocks in the order they appear in the file.
6829 There are two kinds of test blocks:
6831 · doctest-style blocks mimic interactive sessions by interleaving
6833 Python code (including the interpreter prompt) and output.
6834 · code-output-style blocks consist of an ordinary piece of Python code,
6836 and optionally, a piece of output for that code.
6837 The doctest extension provides four directives. The group argument is
6839 interpreted as follows: if it is empty, the block is assigned to the
6840 group named default. If it is *, the block is assigned to all groups
6841 (including the default group). Otherwise, it must be a comma-separated
6842 list of group names.
6843 .. testsetup:: [group]
6845 A setup code block. This code is not shown in the output for
6846 other builders, but executed before the doctests of the group(s)
6847 it belongs to.
6848 .. testcleanup:: [group]
6850 A cleanup code block. This code is not shown in the output for
6851 other builders, but executed after the doctests of the group(s)
6852 it belongs to.
6853 New in version 1.1.
6855 .. doctest:: [group]
6857 A doctest-style code block. You can use standard doctest flags
6858 for controlling how actual output is compared with what you give
6859 as output. By default, these options are enabled: ELLIPSIS
6860 (allowing you to put ellipses in the expected output that match
6861 anything in the actual output), IGNORE_EXCEPTION_DETAIL (not
6862 comparing tracebacks), DONT_ACCEPT_TRUE_FOR_1 (by default,
6863 doctest accepts "True" in the output where "1" is given -- this
6864 is a relic of pre-Python 2.2 times).
6865 This directive supports two options:
6867 · hide, a flag option, hides the doctest block in other
6869 builders. By default it is shown as a highlighted doctest
6870 block.
6871 · options, a string option, can be used to give a comma-sepa‐
6873 rated list of doctest flags that apply to each example in the
6874 tests. (You still can give explicit flags per example, with
6875 doctest comments, but they will show up in other builders
6876 too.)
6877 Note that like with standard doctests, you have to use
6879 <BLANKLINE> to signal a blank line in the expected output. The
6880 <BLANKLINE> is removed when building presentation output (HTML,
6881 LaTeX etc.).
6882 Also, you can give inline doctest options, like in doctest:
6884 >>> datetime.date.now() # doctest: +SKIP
6886 datetime.date(2008, 1, 1)
6887 They will be respected when the test is run, but stripped from
6889 presentation output.
6890 .. testcode:: [group]
6892 A code block for a code-output-style test.
6893 This directive supports one option:
6895 · hide, a flag option, hides the code block in other builders.
6897 By default it is shown as a highlighted code block.
6898 NOTE:
6900 Code in a testcode block is always executed all at once, no
6901 matter how many statements it contains. Therefore, output
6902 will not be generated for bare expressions -- use print.
6903 Example:
6904 .. testcode::
6906 1+1 # this will give no output!
6908 print 2+2 # this will give output
6909 .. testoutput::
6911 4
6913 Also, please be aware that since the doctest module does not
6915 support mixing regular output and an exception message in the
6916 same snippet, this applies to testcode/testoutput as well.
6917 .. testoutput:: [group]
6919 The corresponding output, or the exception message, for the last
6920 testcode block.
6921 This directive supports two options:
6923 · hide, a flag option, hides the output block in other builders.
6925 By default it is shown as a literal block without highlight‐
6926 ing.
6927 · options, a string option, can be used to give doctest flags
6929 (comma-separated) just like in normal doctest blocks.
6930 Example:
6932 .. testcode::
6934 print 'Output text.'
6936 .. testoutput::
6938 :hide:
6939 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
6940 Output text.
6942 The following is an example for the usage of the directives. The test
6944 via doctest and the test via testcode and testoutput are equivalent.
6945 The parrot module
6947 =================
6948 .. testsetup:: *
6950 import parrot
6952 The parrot module is a module about parrots.
6954 Doctest example:
6956 .. doctest::
6958 >>> parrot.voom(3000)
6960 This parrot wouldn't voom if you put 3000 volts through it!
6961 Test-Output example:
6963 .. testcode::
6965 parrot.voom(3000)
6967 This would output:
6969 .. testoutput::
6971 This parrot wouldn't voom if you put 3000 volts through it!
6973 There are also these config values for customizing the doctest exten‐
6975 sion:
6976 doctest_path
6978 A list of directories that will be added to sys.path when the
6979 doctest builder is used. (Make sure it contains absolute
6980 paths.)
6981 doctest_global_setup
6983 Python code that is treated like it were put in a testsetup
6984 directive for every file that is tested, and for every group.
6985 You can use this to e.g. import modules you will always need in
6986 your doctests.
6987 New in version 0.6.
6989 doctest_global_cleanup
6991 Python code that is treated like it were put in a testcleanup
6992 directive for every file that is tested, and for every group.
6993 You can use this to e.g. remove any temporary files that the
6994 tests leave behind.
6995 New in version 1.1.
6997 doctest_test_doctest_blocks
6999 If this is a nonempty string (the default is 'default'), stan‐
7000 dard reST doctest blocks will be tested too. They will be
7001 assigned to the group name given.
7002 reST doctest blocks are simply doctests put into a paragraph of
7004 their own, like so:
7005 Some documentation text.
7007 >>> print 1
7009 1
7010 Some more documentation text.
7012 (Note that no special :: is used to introduce a doctest block;
7014 docutils recognizes them from the leading >>>. Also, no addi‐
7015 tional indentation is used, though it doesn't hurt.)
7016 If this value is left at its default value, the above snippet is
7018 interpreted by the doctest builder exactly like the following:
7019 Some documentation text.
7021 .. doctest::
7023 >>> print 1
7025 1
7026 Some more documentation text.
7028 This feature makes it easy for you to test doctests in doc‐
7030 strings included with the autodoc extension without marking them
7031 up with a special directive.
7032 Note though that you can't have blank lines in reST doctest
7034 blocks. They will be interpreted as one block ending and
7035 another one starting. Also, removal of <BLANKLINE> and #
7036 doctest: options only works in doctest blocks, though you may
7037 set trim_doctest_flags to achieve that in all code blocks with
7038 Python console content.
7039 sphinx.ext.intersphinx -- Link to other projects' documentation
7041 New in version 0.5.
7042 This extension can generate automatic links to the documentation of
7044 objects in other projects.
7045 Usage is simple: whenever Sphinx encounters a cross-reference that has
7047 no matching target in the current documentation set, it looks for tar‐
7048 gets in the documentation sets configured in intersphinx_mapping. A
7049 reference like :py:class:`zipfile.ZipFile` can then link to the Python
7050 documentation for the ZipFile class, without you having to specify
7051 where it is located exactly.
7052 When using the "new" format (see below), you can even force lookup in a
7054 foreign set by prefixing the link target appropriately. A link like
7055 :ref:`comparison manual <python:comparisons>` will then link to the
7056 label "comparisons" in the doc set "python", if it exists.
7057 Behind the scenes, this works as follows:
7059 · Each Sphinx HTML build creates a file named objects.inv that contains
7061 a mapping from object names to URIs relative to the HTML set's root.
7062 · Projects using the Intersphinx extension can specify the location of
7064 such mapping files in the intersphinx_mapping config value. The map‐
7065 ping will then be used to resolve otherwise missing references to
7066 objects into links to the other documentation.
7067 · By default, the mapping file is assumed to be at the same location as
7069 the rest of the documentation; however, the location of the mapping
7070 file can also be specified individually, e.g. if the docs should be
7071 buildable without Internet access.
7072 To use intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
7074 sions config value, and use these new config values to activate link‐
7075 ing:
7076 intersphinx_mapping
7078 This config value contains the locations and names of other
7079 projects that should be linked to in this documentation.
7080 Relative local paths for target locations are taken as relative
7082 to the base of the built documentation, while relative local
7083 paths for inventory locations are taken as relative to the
7084 source directory.
7085 When fetching remote inventory files, proxy settings will be
7087 read from the $HTTP_PROXY environment variable.
7088 Old format for this config value
7090 This is the format used before Sphinx 1.0. It is still recog‐
7092 nized.
7093 A dictionary mapping URIs to either None or an URI. The keys
7095 are the base URI of the foreign Sphinx documentation sets and
7096 can be local paths or HTTP URIs. The values indicate where the
7097 inventory file can be found: they can be None (at the same loca‐
7098 tion as the base URI) or another local or HTTP URI.
7099 New format for this config value
7101 New in version 1.0.
7103 A dictionary mapping unique identifiers to a tuple (target,
7105 inventory). Each target is the base URI of a foreign Sphinx
7106 documentation set and can be a local path or an HTTP URI. The
7107 inventory indicates where the inventory file can be found: it
7108 can be None (at the same location as the base URI) or another
7109 local or HTTP URI.
7110 The unique identifier can be used to prefix cross-reference tar‐
7112 gets, so that it is clear which intersphinx set the target
7113 belongs to. A link like :ref:`comparison manual <python:compar‐
7114 isons>` will link to the label "comparisons" in the doc set
7115 "python", if it exists.
7116 Example
7118 To add links to modules and objects in the Python standard
7120 library documentation, use:
7121 intersphinx_mapping = {'python': ('http://docs.python.org/3.2', None)}
7123 This will download the corresponding objects.inv file from the
7125 Internet and generate links to the pages under the given URI.
7126 The downloaded inventory is cached in the Sphinx environment, so
7127 it must be redownloaded whenever you do a full rebuild.
7128 A second example, showing the meaning of a non-None value of the
7130 second tuple item:
7131 intersphinx_mapping = {'python': ('http://docs.python.org/3.2',
7133 'python-inv.txt')}
7134 This will read the inventory from python-inv.txt in the source
7136 directory, but still generate links to the pages under
7137 http://docs.python.org/3.2. It is up to you to update the
7138 inventory file as new objects are added to the Python documenta‐
7139 tion.
7140 intersphinx_cache_limit
7142 The maximum number of days to cache remote inventories. The
7143 default is 5, meaning five days. Set this to a negative value
7144 to cache inventories for unlimited time.
7145 Math support in Sphinx
7147 New in version 0.5.
7148 Since mathematical notation isn't natively supported by HTML in any
7150 way, Sphinx supports math in documentation with several extensions.
7151 The basic math support is contained in sphinx.ext.mathbase. Other math
7153 support extensions should, if possible, reuse that support too.
7154 NOTE:
7156 mathbase is not meant to be added to the extensions config value,
7157 instead, use either sphinx.ext.pngmath or sphinx.ext.mathjax as
7158 described below.
7159 The input language for mathematics is LaTeX markup. This is the
7161 de-facto standard for plain-text math notation and has the added advan‐
7162 tage that no further translation is necessary when building LaTeX out‐
7163 put.
7164 Keep in mind that when you put math markup in Python docstrings read by
7166 autodoc, you either have to double all backslashes, or use Python raw
7167 strings (r"raw").
7168 mathbase defines these new markup elements:
7170 :math: Role for inline math. Use like this:
7172 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
7174 .. math::
7176 Directive for displayed math (math that takes the whole line for
7177 itself).
7178 The directive supports multiple equations, which should be sepa‐
7180 rated by a blank line:
7181 .. math::
7183 (a + b)^2 = a^2 + 2ab + b^2
7185 (a - b)^2 = a^2 - 2ab + b^2
7187 In addition, each single equation is set within a split environ‐
7189 ment, which means that you can have multiple aligned lines in an
7190 equation, aligned at & and separated by \\:
7191 .. math::
7193 (a + b)^2 &= (a + b)(a + b) \\
7195 &= a^2 + 2ab + b^2
7196 For more details, look into the documentation of the AmSMath
7198 LaTeX package.
7199 When the math is only one line of text, it can also be given as
7201 a directive argument:
7202 .. math:: (a + b)^2 = a^2 + 2ab + b^2
7204 Normally, equations are not numbered. If you want your equation
7206 to get a number, use the label option. When given, it selects
7207 an internal label for the equation, by which it can be
7208 cross-referenced, and causes an equation number to be issued.
7209 See eqref for an example. The numbering style depends on the
7210 output format.
7211 There is also an option nowrap that prevents any wrapping of the
7213 given math in a math environment. When you give this option,
7214 you must make sure yourself that the math is properly set up.
7215 For example:
7216 .. math::
7218 :nowrap:
7219 \begin{eqnarray}
7221 y & = & ax^2 + bx + c \\
7222 f(x) & = & x^2 + 2xy + y^2
7223 \end{eqnarray}
7224 :eq: Role for cross-referencing equations via their label. This cur‐
7226 rently works only within the same document. Example:
7227 .. math:: e^{i\pi} + 1 = 0
7229 :label: euler
7230 Euler's identity, equation :eq:`euler`, was elected one of the most
7232 beautiful mathematical formulas.
7233 sphinx.ext.pngmath -- Render math as PNG images
7235 This extension renders math via LaTeX and dvipng into PNG images. This
7236 of course means that the computer where the docs are built must have
7237 both programs available.
7238 There are various config values you can set to influence how the images
7240 are built:
7241 pngmath_latex
7243 The command name with which to invoke LaTeX. The default is
7244 'latex'; you may need to set this to a full path if latex is not
7245 in the executable search path.
7246 Since this setting is not portable from system to system, it is
7248 normally not useful to set it in conf.py; rather, giving it on
7249 the sphinx-build command line via the -D option should be
7250 preferable, like this:
7251 sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
7253 Changed in version 0.5.1: This value should only contain the
7255 path to the latex executable, not further arguments; use png‐
7256 math_latex_args for that purpose.
7257 pngmath_dvipng
7259 The command name with which to invoke dvipng. The default is
7260 'dvipng'; you may need to set this to a full path if dvipng is
7261 not in the executable search path.
7262 pngmath_latex_args
7264 Additional arguments to give to latex, as a list. The default
7265 is an empty list.
7266 New in version 0.5.1.
7268 pngmath_latex_preamble
7270 Additional LaTeX code to put into the preamble of the short
7271 LaTeX files that are used to translate the math snippets. This
7272 is empty by default. Use it e.g. to add more packages whose
7273 commands you want to use in the math.
7274 pngmath_dvipng_args
7276 Additional arguments to give to dvipng, as a list. The default
7277 value is ['-gamma 1.5', '-D 110'] which makes the image a bit
7278 darker and larger then it is by default.
7279 An arguments you might want to add here is e.g. '-bg Transpar‐
7281 ent', which produces PNGs with a transparent background. This
7282 is not enabled by default because some Internet Explorer ver‐
7283 sions don't like transparent PNGs.
7284 NOTE:
7286 When you "add" an argument, you need to reproduce the default
7287 arguments if you want to keep them; that is, like this:
7288 pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']
7290 pngmath_use_preview
7292 dvipng has the ability to determine the "depth" of the rendered
7293 text: for example, when typesetting a fraction inline, the base‐
7294 line of surrounding text should not be flush with the bottom of
7295 the image, rather the image should extend a bit below the base‐
7296 line. This is what TeX calls "depth". When this is enabled,
7297 the images put into the HTML document will get a vertical-align
7298 style that correctly aligns the baselines.
7299 Unfortunately, this only works when the preview-latex package is
7301 installed. Therefore, the default for this option is False.
7302 pngmath_add_tooltips
7304 Default: true. If false, do not add the LaTeX code as an "alt"
7305 attribute for math images.
7306 New in version 1.1.
7308 sphinx.ext.mathjax -- Render math via JavaScript
7310 New in version 1.1.
7311 This extension puts math as-is into the HTML files. The JavaScript
7313 package MathJax is then loaded and transforms the LaTeX markup to read‐
7314 able math live in the browser.
7315 Because MathJax (and the necessary fonts) is very large, it is not
7317 included in Sphinx.
7318 mathjax_path
7320 The path to the JavaScript file to include in the HTML files in
7321 order to load MathJax.
7322 The default is the http:// URL that loads the JS files from the
7324 MathJax CDN. If you want MathJax to be available offline, you
7325 have to donwload it and set this value to a different path.
7326 The path can be absolute or relative; if it is relative, it is
7328 relative to the _static directory of the built docs.
7329 For example, if you put MathJax into the static path of the
7331 Sphinx docs, this value would be MathJax/MathJax.js. If you
7332 host more than one Sphinx documentation set on one server, it is
7333 advisable to install MathJax in a shared location.
7334 You can also give a full http:// URL different from the CDN URL.
7336 sphinx.ext.jsmath -- Render math via JavaScript
7338 This extension works just as the MathJax extension does, but uses the
7339 older package jsMath. It provides this config value:
7340 jsmath_path
7342 The path to the JavaScript file to include in the HTML files in
7343 order to load JSMath. There is no default.
7344 The path can be absolute or relative; if it is relative, it is
7346 relative to the _static directory of the built docs.
7347 For example, if you put JSMath into the static path of the
7349 Sphinx docs, this value would be jsMath/easy/load.js. If you
7350 host more than one Sphinx documentation set on one server, it is
7351 advisable to install jsMath in a shared location.
7352 sphinx.ext.graphviz -- Add Graphviz graphs
7354 New in version 0.6.
7355 This extension allows you to embed Graphviz graphs in your documents.
7357 It adds these directives:
7359 .. graphviz::
7361 Directive to embed graphviz code. The input code for dot is
7362 given as the content. For example:
7363 .. graphviz::
7365 digraph foo {
7367 "bar" -> "baz";
7368 }
7369 In HTML output, the code will be rendered to a PNG or SVG image
7371 (see graphviz_output_format). In LaTeX output, the code will be
7372 rendered to an embeddable PDF file.
7373 You can also embed external dot files, by giving the file name
7375 as an argument to graphviz and no additional content:
7376 .. graphviz:: external.dot
7378 As for all file references in Sphinx, if the filename is abso‐
7380 lute, it is taken as relative to the source directory.
7381 Changed in version 1.1: Added support for external files.
7383 .. graph::
7385 Directive for embedding a single undirected graph. The name is
7386 given as a directive argument, the contents of the graph are the
7387 directive content. This is a convenience directive to generate
7388 graph <name> { <content> }.
7389 For example:
7391 .. graph:: foo
7393 "bar" -- "baz";
7395 .. digraph::
7397 Directive for embedding a single directed graph. The name is
7398 given as a directive argument, the contents of the graph are the
7399 directive content. This is a convenience directive to generate
7400 digraph <name> { <content> }.
7401 For example:
7403 .. digraph:: foo
7405 "bar" -> "baz" -> "quux";
7407 New in version 1.0: All three directives support an alt option that
7409 determines the image's alternate text for HTML output. If not given,
7410 the alternate text defaults to the graphviz code.
7411 New in version 1.1: All three directives support an inline flag that
7413 controls paragraph breaks in the output. When set, the graph is
7414 inserted into the current paragraph. If the flag is not given, para‐
7415 graph breaks are introduced before and after the image (the default).
7416 New in version 1.1: All three directives support a caption option that
7418 can be used to give a caption to the diagram. Naturally, diagrams
7419 marked as "inline" cannot have a caption.
7420 There are also these new config values:
7422 graphviz_dot
7424 The command name with which to invoke dot. The default is
7425 'dot'; you may need to set this to a full path if dot is not in
7426 the executable search path.
7427 Since this setting is not portable from system to system, it is
7429 normally not useful to set it in conf.py; rather, giving it on
7430 the sphinx-build command line via the -D option should be
7431 preferable, like this:
7432 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
7434 graphviz_dot_args
7436 Additional command-line arguments to give to dot, as a list.
7437 The default is an empty list. This is the right place to set
7438 global graph, node or edge attributes via dot's -G, -N and -E
7439 options.
7440 graphviz_output_format
7442 The output format for Graphviz when building HTML files. This
7443 must be either 'png' or 'svg'; the default is 'png'.
7444 New in version 1.0: Previously, output always was PNG.
7446 sphinx.ext.inheritance_diagram -- Include inheritance diagrams
7448 New in version 0.6.
7449 This extension allows you to include inheritance diagrams, rendered via
7451 the Graphviz extension.
7452 It adds this directive:
7454 .. inheritance-diagram::
7456 This directive has one or more arguments, each giving a module
7457 or class name. Class names can be unqualified; in that case
7458 they are taken to exist in the currently described module (see
7459 py:module).
7460 For each given class, and each class in each given module, the
7462 base classes are determined. Then, from all classes and their
7463 base classes, a graph is generated which is then rendered via
7464 the graphviz extension to a directed graph.
7465 This directive supports an option called parts that, if given,
7467 must be an integer, advising the directive to remove that many
7468 parts of module names from the displayed names. (For example,
7469 if all your class names start with lib., you can give :parts: 1
7470 to remove that prefix from the displayed node names.)
7471 It also supports a private-bases flag option; if given, private
7473 base classes (those whose name starts with _) will be included.
7474 Changed in version 1.1: Added private-bases option; previously,
7476 all bases were always included.
7477 New config values are:
7479 inheritance_graph_attrs
7481 A dictionary of graphviz graph attributes for inheritance dia‐
7482 grams.
7483 For example:
7485 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
7487 fontsize=14, ratio='compress')
7488 inheritance_node_attrs
7490 A dictionary of graphviz node attributes for inheritance dia‐
7491 grams.
7492 For example:
7494 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
7496 color='dodgerblue1', style='filled')
7497 inheritance_edge_attrs
7499 A dictionary of graphviz edge attributes for inheritance dia‐
7500 grams.
7501 sphinx.ext.refcounting -- Keep track of reference counting behavior
7503 Todo
7504 Write this section.
7505 sphinx.ext.ifconfig -- Include content based on configuration
7507 This extension is quite simple, and features only one directive:
7508 .. ifconfig::
7510 Include content of the directive only if the Python expression
7511 given as an argument is True, evaluated in the namespace of the
7512 project's configuration (that is, all registered variables from
7513 conf.py are available).
7514 For example, one could write
7516 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
7518 This stuff is only included in the built docs for unstable versions.
7520 To make a custom config value known to Sphinx, use add_con‐
7522 fig_value() in the setup function in conf.py, e.g.:
7523 def setup(app):
7525 app.add_config_value('releaselevel', '', True)
7526 The second argument is the default value, the third should
7528 always be True for such values (it selects if Sphinx re-reads
7529 the documents if the value changes).
7530 sphinx.ext.coverage -- Collect doc coverage stats
7532 This extension features one additional builder, the CoverageBuilder.
7533 class sphinx.ext.coverage.CoverageBuilder
7535 To use this builder, activate the coverage extension in your
7536 configuration file and give -b coverage on the command line.
7537 Todo
7539 Write this section.
7540 Several new configuration values can be used to specify what the
7542 builder should check:
7543 coverage_ignore_modules
7545 coverage_ignore_functions
7547 coverage_ignore_classes
7549 coverage_c_path
7551 coverage_c_regexes
7553 coverage_ignore_c_items
7555 coverage_write_headline
7557 Set to False to not write headlines.
7558 New in version 1.1.
7560 coverage_skip_undoc_in_source
7562 Skip objects that are not documented in the source with a doc‐
7563 string. False by default.
7564 New in version 1.1.
7566 sphinx.ext.todo -- Support for todo items
7568 Module author: Daniel Bültmann
7569 New in version 0.5.
7571 There are two additional directives when using this extension:
7573 .. todo::
7575 Use this directive like, for example, note.
7576 It will only show up in the output if todo_include_todos is
7578 true.
7579 .. todolist::
7581 This directive is replaced by a list of all todo directives in
7582 the whole documentation, if todo_include_todos is true.
7583 There is also an additional config value:
7585 todo_include_todos
7587 If this is True, todo and todolist produce output, else they
7588 produce nothing. The default is False.
7589 sphinx.ext.extlinks -- Markup to shorten external links
7591 Module author: Georg Brandl
7592 New in version 1.0.
7594 This extension is meant to help with the common pattern of having many
7596 external links that point to URLs on one and the same site, e.g. links
7597 to bug trackers, version control web interfaces, or simply subpages in
7598 other websites. It does so by providing aliases to base URLs, so that
7599 you only need to give the subpage name when creating a link.
7600 Let's assume that you want to include many links to issues at the
7602 Sphinx tracker, at http://bitbucket.org/birkenfeld/sphinx/issue/num.
7603 Typing this URL again and again is tedious, so you can use extlinks to
7604 avoid repeating yourself.
7605 The extension adds one new config value:
7607 extlinks
7609 This config value must be a dictionary of external sites, map‐
7610 ping unique short alias names to a base URL and a prefix. For
7611 example, to create an alias for the above mentioned issues, you
7612 would add
7613 extlinks = {'issue': ('https://bitbucket.org/birkenfeld/sphinx/issue/%s',
7615 'issue ')}
7616 Now, you can use the alias name as a new role, e.g.
7618 :issue:`123`. This then inserts a link to
7619 https://bitbucket.org/birkenfeld/sphinx/issue/123. As you can
7620 see, the target given in the role is substituted in the base URL
7621 in the place of %s.
7622 The link caption depends on the second item in the tuple, the
7624 prefix:
7625 · If the prefix is None, the link caption is the full URL.
7627 · If the prefix is the empty string, the link caption is the
7629 partial URL given in the role content (123 in this case.)
7630 · If the prefix is a non-empty string, the link caption is the
7632 partial URL, prepended by the prefix -- in the above example,
7633 the link caption would be issue 123.
7634 You can also use the usual "explicit title" syntax supported by
7636 other roles that generate links, i.e. :issue:`this issue <123>`.
7637 In this case, the prefix is not relevant.
7638 NOTE:
7640 Since links are generated from the role in the reading stage, they
7641 appear as ordinary links to e.g. the linkcheck builder.
7642 sphinx.ext.viewcode -- Add links to highlighted source code
7644 Module author: Georg Brandl
7645 New in version 1.0.
7647 This extension looks at your Python object descriptions (.. class::, ..
7649 function:: etc.) and tries to find the source files where the objects
7650 are contained. When found, a separate HTML page will be output for
7651 each module with a highlighted version of the source code, and a link
7652 will be added to all object descriptions that leads to the source code
7653 of the described object. A link back from the source to the descrip‐
7654 tion will also be inserted.
7655 There are currently no configuration values for this extension; you
7657 just need to add 'sphinx.ext.viewcode' to your extensions value for it
7658 to work.
7659 sphinx.ext.oldcmarkup -- Compatibility extension for old C markup
7661 Module author: Georg Brandl
7662 New in version 1.0.
7664 This extension is a transition helper for projects that used the old
7666 (pre-domain) C markup, i.e. the directives like cfunction and roles
7667 like cfunc. Since the introduction of domains, they must be called by
7668 their fully-qualified name (c:function and c:func, respectively) or,
7669 with the default domain set to c, by their new name (function and
7670 func). (See c-domain for the details.)
7671 If you activate this extension, it will register the old names, and you
7673 can use them like before Sphinx 1.0. The directives are:
7674 · cfunction
7676 · cmember
7678 · cmacro
7680 · ctype
7682 · cvar
7684 The roles are:
7686 · cdata
7688 · cfunc
7690 · cmacro
7692 · ctype
7694 However, it is advised to migrate to the new markup -- this extension
7696 is a compatibility convenience and will disappear in a future version
7697 of Sphinx.
7698 Third-party extensions
7700 You can find several extensions contributed by users in the Sphinx Con‐
7701 trib repository. It is open for anyone who wants to maintain an exten‐
7702 sion publicly; just send a short message asking for write permissions.
7703 There are also several extensions hosted elsewhere. The Wiki at Bit‐
7705 Bucket maintains a list of those.
7706 If you write an extension that you think others will find useful or you
7708 think should be included as a part of Sphinx, please write to the
7709 project mailing list (join here).
7710 Where to put your own extensions?
7712 Extensions local to a project should be put within the project's direc‐
7713 tory structure. Set Python's module search path, sys.path, accordingly
7714 so that Sphinx can find them. E.g., if your extension foo.py lies in
7715 the exts subdirectory of the project root, put into conf.py:
7716 import sys, os
7718 sys.path.append(os.path.abspath('exts'))
7720 extensions = ['foo']
7722 You can also install extensions anywhere else on sys.path, e.g. in the
7724 site-packages directory.
7725
7727 New in version 1.1.
7728 Sphinx provides a Python API to easily integrate Sphinx documentation
7730 into your web application. To learn more read the websupportquick‐
7731 start.
7732 Web Support Quick Start
7734 Building Documentation Data
7735 To make use of the web support package in your application you'll need
7736 to build the data it uses. This data includes pickle files represent‐
7737 ing documents, search indices, and node data that is used to track
7738 where comments and other things are in a document. To do this you will
7739 need to create an instance of the WebSupport class and call its build()
7740 method:
7741 from sphinx.websupport import WebSupport
7743 support = WebSupport(srcdir='/path/to/rst/sources/',
7745 builddir='/path/to/build/outdir',
7746 search='xapian')
7747 support.build()
7749 This will read reStructuredText sources from srcdir and place the nec‐
7751 essary data in builddir. The builddir will contain two sub-directo‐
7752 ries: one named "data" that contains all the data needed to display
7753 documents, search through documents, and add comments to documents.
7754 The other directory will be called "static" and contains static files
7755 that should be served from "/static".
7756 NOTE:
7758 If you wish to serve static files from a path other than "/static",
7759 you can do so by providing the staticdir keyword argument when cre‐
7760 ating the WebSupport object.
7761 Integrating Sphinx Documents Into Your Webapp
7763 Now that the data is built, it's time to do something useful with it.
7764 Start off by creating a WebSupport object for your application:
7765 from sphinx.websupport import WebSupport
7767 support = WebSupport(datadir='/path/to/the/data',
7769 search='xapian')
7770 You'll only need one of these for each set of documentation you will be
7772 working with. You can then call it's get_document() method to access
7773 individual documents:
7774 contents = support.get_document('contents')
7776 This will return a dictionary containing the following items:
7778 · body: The main body of the document as HTML
7780 · sidebar: The sidebar of the document as HTML
7782 · relbar: A div containing links to related documents
7784 · title: The title of the document
7786 · css: Links to css files used by Sphinx
7788 · js: Javascript containing comment options
7790 This dict can then be used as context for templates. The goal is to be
7792 easy to integrate with your existing templating system. An example
7793 using Jinja2 is:
7794 {%- extends "layout.html" %}
7796 {%- block title %}
7798 {{ document.title }}
7799 {%- endblock %}
7800 {% block css %}
7802 {{ super() }}
7803 {{ document.css|safe }}
7804 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
7805 {% endblock %}
7806 {%- block js %}
7808 {{ super() }}
7809 {{ document.js|safe }}
7810 {%- endblock %}
7811 {%- block relbar %}
7813 {{ document.relbar|safe }}
7814 {%- endblock %}
7815 {%- block body %}
7817 {{ document.body|safe }}
7818 {%- endblock %}
7819 {%- block sidebar %}
7821 {{ document.sidebar|safe }}
7822 {%- endblock %}
7823 Authentication
7825 To use certain features such as voting, it must be possible to authen‐
7826 ticate users. The details of the authentication are left to your
7827 application. Once a user has been authenticated you can pass the
7828 user's details to certain WebSupport methods using the username and
7829 moderator keyword arguments. The web support package will store the
7830 username with comments and votes. The only caveat is that if you allow
7831 users to change their username you must update the websupport package's
7832 data:
7833 support.update_username(old_username, new_username)
7835 username should be a unique string which identifies a user, and modera‐
7837 tor should be a boolean representing whether the user has moderation
7838 privilieges. The default value for moderator is False.
7839 An example Flask function that checks whether a user is logged in and
7841 then retrieves a document is:
7842 from sphinx.websupport.errors import *
7844 @app.route('/<path:docname>')
7846 def doc(docname):
7847 username = g.user.name if g.user else ''
7848 moderator = g.user.moderator if g.user else False
7849 try:
7850 document = support.get_document(docname, username, moderator)
7851 except DocumentNotFoundError:
7852 abort(404)
7853 return render_template('doc.html', document=document)
7854 The first thing to notice is that the docname is just the request path.
7856 This makes accessing the correct document easy from a single view. If
7857 the user is authenticated, then the username and moderation status are
7858 passed along with the docname to get_document(). The web support pack‐
7859 age will then add this data to the COMMENT_OPTIONS that are used in the
7860 template.
7861 NOTE:
7863 This only works works if your documentation is served from your doc‐
7864 ument root. If it is served from another directory, you will need to
7865 prefix the url route with that directory, and give the docroot key‐
7866 word argument when creating the web support object:
7867 support = WebSupport(..., docroot='docs')
7869 @app.route('/docs/<path:docname>')
7871 Performing Searches
7873 To use the search form built-in to the Sphinx sidebar, create a func‐
7874 tion to handle requests to the url 'search' relative to the documenta‐
7875 tion root. The user's search query will be in the GET parameters, with
7876 the key q. Then use the get_search_results() method to retrieve search
7877 results. In Flask that would be like this:
7878 @app.route('/search')
7880 def search():
7881 q = request.args.get('q')
7882 document = support.get_search_results(q)
7883 return render_template('doc.html', document=document)
7884 Note that we used the same template to render our search results as we
7886 did to render our documents. That's because get_search_results()
7887 returns a context dict in the same format that get_document() does.
7888 Comments & Proposals
7890 Now that this is done it's time to define the functions that handle the
7891 AJAX calls from the script. You will need three functions. The first
7892 function is used to add a new comment, and will call the web support
7893 method add_comment():
7894 @app.route('/docs/add_comment', methods=['POST'])
7896 def add_comment():
7897 parent_id = request.form.get('parent', '')
7898 node_id = request.form.get('node', '')
7899 text = request.form.get('text', '')
7900 proposal = request.form.get('proposal', '')
7901 username = g.user.name if g.user is not None else 'Anonymous'
7902 comment = support.add_comment(text, node_id='node_id',
7903 parent_id='parent_id',
7904 username=username, proposal=proposal)
7905 return jsonify(comment=comment)
7906 You'll notice that both a parent_id and node_id are sent with the
7908 request. If the comment is being attached directly to a node, parent_id
7909 will be empty. If the comment is a child of another comment, then
7910 node_id will be empty. Then next function handles the retrieval of com‐
7911 ments for a specific node, and is aptly named get_data():
7912 @app.route('/docs/get_comments')
7914 def get_comments():
7915 username = g.user.name if g.user else None
7916 moderator = g.user.moderator if g.user else False
7917 node_id = request.args.get('node', '')
7918 data = support.get_data(node_id, username, moderator)
7919 return jsonify(**data)
7920 The final function that is needed will call process_vote(), and will
7922 handle user votes on comments:
7923 @app.route('/docs/process_vote', methods=['POST'])
7925 def process_vote():
7926 if g.user is None:
7927 abort(401)
7928 comment_id = request.form.get('comment_id')
7929 value = request.form.get('value')
7930 if value is None or comment_id is None:
7931 abort(400)
7932 support.process_vote(comment_id, g.user.id, value)
7933 return "success"
7934 Comment Moderation
7936 By default, all comments added through add_comment() are automatically
7937 displayed. If you wish to have some form of moderation, you can pass
7938 the displayed keyword argument:
7939 comment = support.add_comment(text, node_id='node_id',
7941 parent_id='parent_id',
7942 username=username, proposal=proposal,
7943 displayed=False)
7944 You can then create a new view to handle the moderation of comments.
7946 It will be called when a moderator decides a comment should be accepted
7947 and displayed:
7948 @app.route('/docs/accept_comment', methods=['POST'])
7950 def accept_comment():
7951 moderator = g.user.moderator if g.user else False
7952 comment_id = request.form.get('id')
7953 support.accept_comment(comment_id, moderator=moderator)
7954 return 'OK'
7955 Rejecting comments happens via comment deletion.
7957 To perform a custom action (such as emailing a moderator) when a new
7959 comment is added but not displayed, you can pass callable to the Web‐
7960 Support class when instantiating your support object:
7961 def moderation_callback(comment):
7963 """Do something..."""
7964 support = WebSupport(..., moderation_callback=moderation_callback)
7966 The moderation callback must take one argument, which will be the same
7968 comment dict that is returned by add_comment().
7969 The WebSupport Class
7971 class sphinx.websupport.WebSupport
7972 The main API class for the web support package. All interac‐
7973 tions with the web support package should occur through this
7974 class.
7975 The class takes the following keyword arguments:
7977 srcdir The directory containing reStructuredText source files.
7979 builddir
7981 The directory that build data and static files should be
7982 placed in. This should be used when creating a WebSup‐
7983 port object that will be used to build data.
7984 datadir
7986 The directory that the web support data is in. This
7987 should be used when creating a WebSupport object that
7988 will be used to retrieve data.
7989 search This may contain either a string (e.g. 'xapian') refer‐
7991 encing a built-in search adapter to use, or an instance
7992 of a subclass of BaseSearch.
7993 storage
7995 This may contain either a string representing a database
7996 uri, or an instance of a subclass of StorageBackend. If
7997 this is not provided, a new sqlite database will be cre‐
7998 ated.
7999 moderation_callback
8001 A callable to be called when a new comment is added that
8002 is not displayed. It must accept one argument: a dictio‐
8003 nary representing the comment that was added.
8004 staticdir
8006 If static files are served from a location besides
8007 '/static', this should be a string with the name of that
8008 location (e.g. '/static_files').
8009 docroot
8011 If the documentation is not served from the base path of
8012 a URL, this should be a string specifying that path (e.g.
8013 'docs').
8014 Methods
8016 WebSupport.build()
8017 Build the documentation. Places the data into the outdir direc‐
8018 tory. Use it like this:
8019 support = WebSupport(srcdir, builddir, search='xapian')
8021 support.build()
8022 This will read reStructured text files from srcdir. Then it will
8024 build the pickles and search index, placing them into builddir.
8025 It will also save node data to the database.
8026 WebSupport.get_document(docname, username='', moderator=False)
8028 Load and return a document from a pickle. The document will be a
8029 dict object which can be used to render a template:
8030 support = WebSupport(datadir=datadir)
8032 support.get_document('index', username, moderator)
8033 In most cases docname will be taken from the request path and
8035 passed directly to this function. In Flask, that would be some‐
8036 thing like this:
8037 @app.route('/<path:docname>')
8039 def index(docname):
8040 username = g.user.name if g.user else ''
8041 moderator = g.user.moderator if g.user else False
8042 try:
8043 document = support.get_document(docname, username,
8044 moderator)
8045 except DocumentNotFoundError:
8046 abort(404)
8047 render_template('doc.html', document=document)
8048 The document dict that is returned contains the following items
8050 to be used during template rendering.
8051 · body: The main body of the document as HTML
8053 · sidebar: The sidebar of the document as HTML
8055 · relbar: A div containing links to related documents
8057 · title: The title of the document
8059 · css: Links to css files used by Sphinx
8061 · script: Javascript containing comment options
8063 This raises DocumentNotFoundError if a document matching docname
8065 is not found.
8066 Parameters
8068 docname -- the name of the document to load.
8069 WebSupport.get_data(node_id, username=None, moderator=False)
8071 Get the comments and source associated with node_id. If username
8072 is given vote information will be included with the returned
8073 comments. The default CommentBackend returns a dict with two
8074 keys, source, and comments. source is raw source of the node and
8075 is used as the starting point for proposals a user can add. com‐
8076 ments is a list of dicts that represent a comment, each having
8077 the following items:
8078 ┌──────────────┬────────────────────────────┐
8080 │Key │ Contents │
8081 ├──────────────┼────────────────────────────┤
8082 │text │ The comment text. │
8083 ├──────────────┼────────────────────────────┤
8084 │username │ The username that was │
8085 │ │ stored with the comment. │
8086 ├──────────────┼────────────────────────────┤
8087 │id │ The comment's unique iden‐ │
8088 │ │ tifier. │
8089 ├──────────────┼────────────────────────────┤
8090 │rating │ The comment's current rat‐ │
8091 │ │ ing. │
8092 ├──────────────┼────────────────────────────┤
8093 │age │ The time in seconds since │
8094 │ │ the comment was added. │
8095 ├──────────────┼────────────────────────────┤
8096 │time │ A dict containing time │
8097 │ │ information. It contains │
8098 │ │ the following keys: year, │
8099 │ │ month, day, hour, minute, │
8100 │ │ second, iso, and delta. │
8101 │ │ iso is the time formatted │
8102 │ │ in ISO 8601 format. delta │
8103 │ │ is a printable form of how │
8104 │ │ old the comment is (e.g. │
8105 │ │ "3 hours ago"). │
8106 ├──────────────┼────────────────────────────┤
8107 │vote │ If user_id was given, this │
8108 │ │ will be an integer repre‐ │
8109 │ │ senting the vote. 1 for an │
8110 │ │ upvote, -1 for a downvote, │
8111 │ │ or 0 if unvoted. │
8112 ├──────────────┼────────────────────────────┤
8113 │node │ The id of the node that │
8114 │ │ the comment is attached │
8115 │ │ to. If the comment's par‐ │
8116 │ │ ent is another comment │
8117 │ │ rather than a node, this │
8118 │ │ will be null. │
8119 ├──────────────┼────────────────────────────┤
8120 │parent │ The id of the comment that │
8121 │ │ this comment is attached │
8122 │ │ to if it is not attached │
8123 │ │ to a node. │
8124 ├──────────────┼────────────────────────────┤
8125 │children │ A list of all children, in │
8126 │ │ this format. │
8127 ├──────────────┼────────────────────────────┤
8128 │proposal_diff │ An HTML representation of │
8129 │ │ the differences between │
8130 │ │ the the current source and │
8131 │ │ the user's proposed │
8132 │ │ source. │
8133 └──────────────┴────────────────────────────┘
8134 Parameters
8136 · node_id -- the id of the node to get comments for.
8138 · username -- the username of the user viewing the com‐
8140 ments.
8141 · moderator -- whether the user is a moderator.
8143 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
8145 username=None, time=None, proposal=None, moderator=False)
8146 Add a comment to a node or another comment. Returns the comment
8147 in the same format as get_comments(). If the comment is being
8148 attached to a node, pass in the node's id (as a string) with the
8149 node keyword argument:
8150 comment = support.add_comment(text, node_id=node_id)
8152 If the comment is the child of another comment, provide the par‐
8154 ent's id (as a string) with the parent keyword argument:
8155 comment = support.add_comment(text, parent_id=parent_id)
8157 If you would like to store a username with the comment, pass in
8159 the optional username keyword argument:
8160 comment = support.add_comment(text, node=node_id,
8162 username=username)
8163 Parameters
8165 · parent_id -- the prefixed id of the comment's parent.
8167 · text -- the text of the comment.
8169 · displayed -- for moderation purposes
8171 · username -- the username of the user making the com‐
8173 ment.
8174 · time -- the time the comment was created, defaults to
8176 now.
8177 WebSupport.process_vote(comment_id, username, value)
8179 Process a user's vote. The web support package relies on the API
8180 user to perform authentication. The API user will typically
8181 receive a comment_id and value from a form, and then make sure
8182 the user is authenticated. A unique username must be passed in,
8183 which will also be used to retrieve the user's past voting data.
8184 An example, once again in Flask:
8185 @app.route('/docs/process_vote', methods=['POST'])
8187 def process_vote():
8188 if g.user is None:
8189 abort(401)
8190 comment_id = request.form.get('comment_id')
8191 value = request.form.get('value')
8192 if value is None or comment_id is None:
8193 abort(400)
8194 support.process_vote(comment_id, g.user.name, value)
8195 return "success"
8196 Parameters
8198 · comment_id -- the comment being voted on
8200 · username -- the unique username of the user voting
8202 · value -- 1 for an upvote, -1 for a downvote, 0 for an
8204 unvote.
8205 WebSupport.get_search_results(q)
8207 Perform a search for the query q, and create a set of search
8208 results. Then render the search results as html and return a
8209 context dict like the one created by get_document():
8210 document = support.get_search_results(q)
8212 Parameters
8214 q -- the search query
8215 Search Adapters
8217 To create a custom search adapter you will need to subclass the
8218 BaseSearch class. Then create an instance of the new class and pass
8219 that as the search keyword argument when you create the WebSupport
8220 object:
8221 support = WebSupport(srcdir=srcdir,
8223 builddir=builddir,
8224 search=MySearch())
8225 For more information about creating a custom search adapter, please see
8227 the documentation of the BaseSearch class below.
8228 class sphinx.websupport.search.BaseSearch
8230 Defines an interface for search adapters.
8231 BaseSearch Methods
8233 The following methods are defined in the BaseSearch class. Some
8234 methods do not need to be overridden, but some (add_document() and
8235 handle_query()) must be overridden in your subclass. For a working
8236 example, look at the built-in adapter for whoosh.
8237 BaseSearch.init_indexing(changed=[])
8239 Called by the builder to initialize the search indexer. changed
8240 is a list of pagenames that will be reindexed. You may want to
8241 remove these from the search index before indexing begins.
8242 Parameters
8244 changed -- a list of pagenames that will be re-indexed
8245 BaseSearch.finish_indexing()
8247 Called by the builder when writing has been completed. Use this
8248 to perform any finalization or cleanup actions after indexing is
8249 complete.
8250 BaseSearch.feed(pagename, title, doctree)
8252 Called by the builder to add a doctree to the index. Converts
8253 the doctree to text and passes it to add_document(). You proba‐
8254 bly won't want to override this unless you need access to the
8255 doctree. Override add_document() instead.
8256 Parameters
8258 · pagename -- the name of the page to be indexed
8260 · title -- the title of the page to be indexed
8262 · doctree -- is the docutils doctree representation of
8264 the page
8265 BaseSearch.add_document(pagename, title, text)
8267 Called by feed() to add a document to the search index. This
8268 method should should do everything necessary to add a single
8269 document to the search index.
8270 pagename is name of the page being indexed. It is the combina‐
8272 tion of the source files relative path and filename, minus the
8273 extension. For example, if the source file is
8274 "ext/builders.rst", the pagename would be "ext/builders". This
8275 will need to be returned with search results when processing a
8276 query.
8277 Parameters
8279 · pagename -- the name of the page being indexed
8281 · title -- the page's title
8283 · text -- the full text of the page
8285 BaseSearch.query(q)
8287 Called by the web support api to get search results. This method
8288 compiles the regular expression to be used when extracting con‐
8289 text, then calls handle_query(). You won't want to override
8290 this unless you don't want to use the included extract_context()
8291 method. Override handle_query() instead.
8292 Parameters
8294 q -- the search query string.
8295 BaseSearch.handle_query(q)
8297 Called by query() to retrieve search results for a search query
8298 q. This should return an iterable containing tuples of the fol‐
8299 lowing format:
8300 (<path>, <title>, <context>)
8302 path and title are the same values that were passed to add_docu‐
8304 ment(), and context should be a short text snippet of the text
8305 surrounding the search query in the document.
8306 The extract_context() method is provided as a simple way to cre‐
8308 ate the context.
8309 Parameters
8311 q -- the search query
8312 BaseSearch.extract_context(text, length=240)
8314 Extract the context for the search query from the document's
8315 full text.
8316 Parameters
8318 · text -- the full text of the document to create the
8320 context for
8321 · length -- the length of the context snippet to return.
8323 Storage Backends
8325 To create a custom storage backend you will need to subclass the Stor‐
8326 ageBackend class. Then create an instance of the new class and pass
8327 that as the storage keyword argument when you create the WebSupport
8328 object:
8329 support = WebSupport(srcdir=srcdir,
8331 builddir=builddir,
8332 storage=MyStorage())
8333 For more information about creating a custom storage backend, please
8335 see the documentation of the StorageBackend class below.
8336 class sphinx.websupport.storage.StorageBackend
8338 Defines an interface for storage backends.
8339 StorageBackend Methods
8341 StorageBackend.pre_build()
8342 Called immediately before the build process begins. Use this to
8343 prepare the StorageBackend for the addition of nodes.
8344 StorageBackend.add_node(id, document, source)
8346 Add a node to the StorageBackend.
8347 Parameters
8349 · id -- a unique id for the comment.
8351 · document -- the name of the document the node belongs
8353 to.
8354 · source -- the source files name.
8356 StorageBackend.post_build()
8358 Called after a build has completed. Use this to finalize the
8359 addition of nodes if needed.
8360 StorageBackend.add_comment(text, displayed, username, time, proposal,
8362 node_id, parent_id, moderator)
8363 Called when a comment is being added.
8364 Parameters
8366 · text -- the text of the comment
8368 · displayed -- whether the comment should be displayed
8370 · username -- the name of the user adding the comment
8372 · time -- a date object with the time the comment was
8374 added
8375 · proposal -- the text of the proposal the user made
8377 · node_id -- the id of the node that the comment is being
8379 added to
8380 · parent_id -- the id of the comment's parent comment.
8382 · moderator -- whether the user adding the comment is a
8384 moderator
8385 StorageBackend.delete_comment(comment_id, username, moderator)
8387 Delete a comment.
8388 Raises UserNotAuthorizedError if moderator is False and username
8390 doesn't match the username on the comment.
8391 Parameters
8393 · comment_id -- The id of the comment being deleted.
8395 · username -- The username of the user requesting the
8397 deletion.
8398 · moderator -- Whether the user is a moderator.
8400 StorageBackend.get_data(node_id, username, moderator)
8402 Called to retrieve all data for a node. This should return a
8403 dict with two keys, source and comments as described by WebSup‐
8404 port's get_data() method.
8405 Parameters
8407 · node_id -- The id of the node to get data for.
8409 · username -- The name of the user requesting the data.
8411 · moderator -- Whether the requestor is a moderator.
8413 StorageBackend.process_vote(comment_id, username, value)
8415 Process a vote that is being cast. value will be either -1, 0,
8416 or 1.
8417 Parameters
8419 · comment_id -- The id of the comment being voted on.
8421 · username -- The username of the user casting the vote.
8423 · value -- The value of the vote being cast.
8425 StorageBackend.update_username(old_username, new_username)
8427 If a user is allowed to change their username this method should
8428 be called so that there is not stagnate data in the storage sys‐
8429 tem.
8430 Parameters
8432 · old_username -- The username being changed.
8434 · new_username -- What the username is being changed to.
8436 StorageBackend.accept_comment(comment_id)
8438 Called when a moderator accepts a comment. After the method is
8439 called the comment should be displayed to all users.
8440 Parameters
8442 comment_id -- The id of the comment being accepted.
8443
8445 This is a list of Frequently Asked Questions about Sphinx. Feel free
8446 to suggest new entries!
8447 How do I...
8449 ... create PDF files without LaTeX?
8450 You can use rst2pdf version 0.12 or greater which comes with
8451 built-in Sphinx integration. See the builders section for
8452 details.
8453 ... get section numbers?
8455 They are automatic in LaTeX output; for HTML, give a :numbered:
8456 option to the toctree directive where you want to start number‐
8457 ing.
8458 ... customize the look of the built HTML files?
8460 Use themes, see theming.
8461 ... add global substitutions or includes?
8463 Add them in the rst_epilog config value.
8464 ... display the whole TOC tree in the sidebar?
8466 Use the toctree callable in a custom layout template, probably
8467 in the sidebartoc block.
8468 ... write my own extension?
8470 See the extension tutorial.
8471 ... convert from my existing docs using MoinMoin markup?
8473 The easiest way is to convert to xhtml, then convert xhtml to
8474 reST. You'll still need to mark up classes and such, but the
8475 headings and code examples come through cleanly.
8476 Using Sphinx with...
8478 Read the Docs
8479 http://readthedocs.org is a documentation hosting service based
8480 around Sphinx. They will host sphinx documentation, along with
8481 supporting a number of other features including version support,
8482 PDF generation, and more. The Getting Started guide is a good
8483 place to start.
8484 Epydoc There's a third-party extension providing an api role which
8486 refers to Epydoc's API docs for a given identifier.
8487 Doxygen
8489 Michael Jones is developing a reST/Sphinx bridge to doxygen
8490 called breathe.
8491 SCons Glenn Hutchings has written a SCons build script to build Sphinx
8493 documentation; it is hosted here:
8494 https://bitbucket.org/zondo/sphinx-scons
8495 PyPI Jannis Leidel wrote a setuptools command that automatically
8497 uploads Sphinx documentation to the PyPI package documentation
8498 area at http://packages.python.org/.
8499 GitHub Pages
8501 Directories starting with underscores are ignored by default
8502 which breaks static files in Sphinx. GitHub's preprocessor can
8503 be disabled to support Sphinx HTML output properly.
8504 MediaWiki
8506 See https://bitbucket.org/kevindunn/sphinx-wiki, a project by
8507 Kevin Dunn.
8508 Google Analytics
8510 You can use a custom layout.html template, like this:
8511 {% extends "!layout.html" %}
8513 {%- block extrahead %}
8515 {{ super() }}
8516 <script type="text/javascript">
8517 var _gaq = _gaq || [];
8518 _gaq.push(['_setAccount', 'XXX account number XXX']);
8519 _gaq.push(['_trackPageview']);
8520 </script>
8521 {% endblock %}
8522 {% block footer %}
8524 {{ super() }}
8525 <div class="footer">This page uses <a href="http://analytics.google.com/">
8526 Google Analytics</a> to collect statistics. You can disable it by blocking
8527 the JavaScript coming from www.google-analytics.com.
8528 <script type="text/javascript">
8529 (function() {
8530 var ga = document.createElement('script');
8531 ga.src = ('https:' == document.location.protocol ?
8532 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
8533 ga.setAttribute('async', 'true');
8534 document.documentElement.firstChild.appendChild(ga);
8535 })();
8536 </script>
8537 </div>
8538 {% endblock %}
8539 Epub info
8541 The epub builder is currently in an experimental stage. It has only
8542 been tested with the Sphinx documentation itself. If you want to cre‐
8543 ate epubs, here are some notes:
8544 · Split the text into several files. The longer the individual HTML
8546 files are, the longer it takes the ebook reader to render them. In
8547 extreme cases, the rendering can take up to one minute.
8548 · Try to minimize the markup. This also pays in rendering time.
8550 · For some readers you can use embedded or external fonts using the CSS
8552 @font-face directive. This is extremely useful for code listings
8553 which are often cut at the right margin. The default Courier font
8554 (or variant) is quite wide and you can only display up to 60 charac‐
8555 ters on a line. If you replace it with a narrower font, you can get
8556 more characters on a line. You may even use FontForge and create
8557 narrow variants of some free font. In my case I get up to 70 charac‐
8558 ters on a line.
8559 You may have to experiment a little until you get reasonable results.
8561 · Test the created epubs. You can use several alternatives. The ones I
8563 am aware of are Epubcheck, Calibre, FBreader (although it does not
8564 render the CSS), and Bookworm. For bookworm you can download the
8565 source from http://code.google.com/p/threepress/ and run your own
8566 local server.
8567 · Large floating divs are not displayed properly. If they cover more
8569 than one page, the div is only shown on the first page. In that case
8570 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
8571 tory to your local _static/ directory and remove the float settings.
8572 · Files that are inserted outside of the toctree directive must be man‐
8574 ually included. This sometimes applies to appendixes, e.g. the glos‐
8575 sary or the indices. You can add them with the epub_post_files
8576 option.
8577 Texinfo info
8579 The Texinfo builder is currently in an experimental stage but has suc‐
8580 cessfully been used to build the documentation for both Sphinx and
8581 Python. The intended use of this builder is to generate Texinfo that
8582 is then processed into Info files.
8583 There are two main programs for reading Info files, info and GNU Emacs.
8585 The info program has less features but is available in most Unix envi‐
8586 ronments and can be quickly accessed from the terminal. Emacs provides
8587 better font and color display and supports extensive customization (of
8588 course).
8589 Displaying Links
8591 One noticeable problem you may encounter with the generated Info files
8592 is how references are displayed. If you read the source of an Info
8593 file, a reference to this section would look like:
8594 * note Displaying Links: target-id
8596 In the stand-alone reader, info, references are displayed just as they
8598 appear in the source. Emacs, on the other-hand, will by default
8599 replace \*note: with see and hide the target-id. For example:
8600 texinfo-links
8601 The exact behavior of how Emacs displays references is dependent on the
8603 variable Info-hide-note-references. If set to the value of hide, Emacs
8604 will hide both the \*note: part and the target-id. This is generally
8605 the best way to view Sphinx-based documents since they often make fre‐
8606 quent use of links and do not take this limitation into account. How‐
8607 ever, changing this variable affects how all Info documents are dis‐
8608 played and most due take this behavior into account.
8609 If you want Emacs to display Info files produced by Sphinx using the
8611 value hide for Info-hide-note-references and the default value for all
8612 other Info files, try adding the following Emacs Lisp code to your
8613 start-up file, ~/.emacs.d/init.el.
8614 (defadvice info-insert-file-contents (after
8616 sphinx-info-insert-file-contents
8617 activate)
8618 "Hack to make `Info-hide-note-references' buffer-local and
8619 automatically set to `hide' iff it can be determined that this file
8620 was created from a Texinfo file generated by Docutils or Sphinx."
8621 (set (make-local-variable 'Info-hide-note-references)
8622 (default-value 'Info-hide-note-references))
8623 (save-excursion
8624 (save-restriction
8625 (widen) (goto-char (point-min))
8626 (when (re-search-forward
8627 "^Generated by \\(Sphinx\\|Docutils\\)"
8628 (save-excursion (search-forward "\x1f" nil t)) t)
8629 (set (make-local-variable 'Info-hide-note-references)
8630 'hide)))))
8631 Notes
8633 The following notes may be helpful if you want to create Texinfo files:
8634 · Each section corresponds to a different node in the Info file.
8636 · Colons (:) cannot be properly escaped in menu entries and xrefs.
8638 They will be replaced with semicolons (;).
8639 · In the HTML and Tex output, the word see is automatically inserted
8641 before all xrefs.
8642 · Links to external Info files can be created using the somewhat offi‐
8644 cial URI scheme info. For example:
8645 info:Texinfo#makeinfo_options
8647 which produces:
8649 info:Texinfo#makeinfo_options
8650 · Inline markup appears as follows in Info:
8652 · strong -- *strong*
8654 · emphasis -- _emphasis_
8656 · literal -- `literal'
8658 It is possible to change this behavior using the Texinfo command
8660 @definfoenclose. For example, to make inline markup more closely
8661 resemble reST, add the following to your conf.py:
8662 texinfo_elements = {'preamble': """\
8664 @definfoenclose strong,**,**
8665 @definfoenclose emph,*,*
8666 @definfoenclose code,`@w{}`,`@w{}`
8667 """}
8668
8670 builder
8671 A class (inheriting from Builder) that takes parsed documents
8672 and performs an action on them. Normally, builders translate
8673 the documents to an output format, but it is also possible to
8674 use the builder builders that e.g. check for broken links in the
8675 documentation, or build coverage information.
8676 See builders for an overview over Sphinx' built-in builders.
8678 configuration directory
8680 The directory containing conf.py. By default, this is the same
8681 as the source directory, but can be set differently with the -c
8682 command-line option.
8683 directive
8685 A reStructuredText markup element that allows marking a block of
8686 content with special meaning. Directives are supplied not only
8687 by docutils, but Sphinx and custom extensions can add their own.
8688 The basic directive syntax looks like this:
8689 .. directivename:: argument ...
8691 :option: value
8692 Content of the directive.
8694 See directives for more information.
8696 document name
8698 Since reST source files can have different extensions (some peo‐
8699 ple like .txt, some like .rst -- the extension can be configured
8700 with source_suffix) and different OSes have different path sepa‐
8701 rators, Sphinx abstracts them: document names are always rela‐
8702 tive to the source directory, the extension is stripped, and
8703 path separators are converted to slashes. All values, parame‐
8704 ters and such referring to "documents" expect such document
8705 names.
8706 Examples for document names are index, library/zipfile, or ref‐
8708 erence/datamodel/types. Note that there is no leading or trail‐
8709 ing slash.
8710 domain A domain is a collection of markup (reStructuredText directives
8712 and roles) to describe and link to objects belonging together,
8713 e.g. elements of a programming language. Directive and role
8714 names in a domain have names like domain:name, e.g. py:function.
8715 Having domains means that there are no naming problems when one
8717 set of documentation wants to refer to e.g. C++ and Python
8718 classes. It also means that extensions that support the docu‐
8719 mentation of whole new languages are much easier to write. For
8720 more information about domains, see the chapter domains.
8721 environment
8723 A structure where information about all documents under the root
8724 is saved, and used for cross-referencing. The environment is
8725 pickled after the parsing stage, so that successive runs only
8726 need to read and parse new and changed documents.
8727 master document
8729 The document that contains the root toctree directive.
8730 object The basic building block of Sphinx documentation. Every "object
8732 directive" (e.g. function or object) creates such a block; and
8733 most objects can be cross-referenced to.
8734 role A reStructuredText markup element that allows marking a piece of
8736 text. Like directives, roles are extensible. The basic syntax
8737 looks like this: :rolename:`content`. See inlinemarkup for
8738 details.
8739 source directory
8741 The directory which, including its subdirectories, contains all
8742 source files for one Sphinx project.
8743
8745 Release 1.1.3 (Mar 10, 2012)
8746 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
8747 characters correctly.
8748 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
8750 · PR#34: Restore Python 2.4 compatibility.
8752 · PR#36: Make the "bibliography to TOC" fix in LaTeX output specific to
8754 the document class.
8755 · #695: When the highlight language "python" is specified explicitly,
8757 do not try to parse the code to recognize non-Python snippets.
8758 · #859: Fix exception under certain circumstances when not finding
8760 appropriate objects to link to.
8761 · #860: Do not crash when encountering invalid doctest examples, just
8763 emit a warning.
8764 · #864: Fix crash with some settings of modindex_common_prefix.
8766 · #862: Fix handling of -D and -A options on Python 3.
8768 · #851: Recognize and warn about circular toctrees, instead of running
8770 into recursion errors.
8771 · #853: Restore compatibility with docutils trunk.
8773 · #852: Fix HtmlHelp index entry links again.
8775 · #854: Fix inheritance_diagram raising attribute errors on builtins.
8777 · #832: Fix crashes when putting comments or lone terms in a glossary.
8779 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
8781 supported languages.
8782 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
8784 sion.
8785 · #831: Provide --project flag in setup_command as advertised.
8787 · #875: Fix reading config files under Python 3.
8789 · #876: Fix quickstart test under Python 3.
8791 · #870: Fix spurious KeyErrors when removing documents.
8793 · #892: Fix single-HTML builder misbehaving with the master document in
8795 a subdirectory.
8796 · #873: Fix assertion errors with empty only directives.
8798 · #816: Fix encoding issues in the Qt help builder.
8800 Release 1.1.2 (Nov 1, 2011) -- 1.1.1 is a silly version number anyway!
8802 · #809: Include custom fixers in the source distribution.
8803 Release 1.1.1 (Nov 1, 2011)
8805 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
8806 · #792: Include "sphinx-apidoc" in the source distribution.
8808 · #797: Don't crash on a misformatted glossary.
8810 · #801: Make intersphinx work properly without SSL support.
8812 · #805: Make the Sphinx.add_index_to_domain method work correctly.
8814 · #780: Fix Python 2.5 compatibility.
8816 Release 1.1 (Oct 9, 2011)
8818 Incompatible changes
8819 · The py:module directive doesn't output its platform option value any‐
8820 more. (It was the only thing that the directive did output, and
8821 therefore quite inconsistent.)
8822 · Removed support for old dependency versions; requirements are now:
8824 · Pygments >= 1.2
8826 · Docutils >= 0.7
8828 · Jinja2 >= 2.3
8830 Features added
8832 · Added Python 3.x support.
8833 · New builders and subsystems:
8835 · Added a Texinfo builder.
8837 · Added i18n support for content, a gettext builder and related util‐
8839 ities.
8840 · Added the websupport library and builder.
8842 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
8844 source files containing autodoc directives to document modules and
8845 packages.
8846 · #273: Add an API for adding full-text search support for languages
8848 other than English. Add support for Japanese.
8849 · Markup:
8851 · #138: Added an index role, to make inline index entries.
8853 · #454: Added more index markup capabilities: marking see/seealso
8855 entries, and main entries for a given key.
8856 · #460: Allowed limiting the depth of section numbers for HTML using
8858 the toctree's numbered option.
8859 · #586: Implemented improved glossary markup which allows multiple
8861 terms per definition.
8862 · #478: Added py:decorator directive to describe decorators.
8864 · C++ domain now supports array definitions.
8866 · C++ domain now supports doc fields (:param x: inside directives).
8868 · Section headings in only directives are now correctly handled.
8870 · Added emphasize-lines option to source code directives.
8872 · #678: C++ domain now supports superclasses.
8874 · HTML builder:
8876 · Added pyramid theme.
8878 · #559: html_add_permalinks is now a string giving the text to dis‐
8880 play in permalinks.
8881 · #259: HTML table rows now have even/odd CSS classes to enable
8883 "Zebra styling".
8884 · #554: Add theme option sidebarwidth to the basic theme.
8886 · Other builders:
8888 · #516: Added new value of the latex_show_urls option to show the
8890 URLs in footnotes.
8891 · #209: Added text_newlines and text_sectionchars config values.
8893 · Added man_show_urls config value.
8895 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
8897 requests and allow configuring the timeout. New config values:
8898 linkcheck_timeout and linkcheck_workers.
8899 · #521: Added linkcheck_ignore config value.
8901 · #28: Support row/colspans in tables in the LaTeX builder.
8903 · Configuration and extensibility:
8905 · #537: Added nitpick_ignore.
8907 · #306: Added env-get-outdated event.
8909 · Application.add_stylesheet() now accepts full URIs.
8911 · Autodoc:
8913 · #564: Add autodoc_docstring_signature. When enabled (the default),
8915 autodoc retrieves the signature from the first line of the doc‐
8916 string, if it is found there.
8917 · #176: Provide private-members option for autodoc directives.
8919 · #520: Provide special-members option for autodoc directives.
8921 · #431: Doc comments for attributes can now be given on the same line
8923 as the assignment.
8924 · #437: autodoc now shows values of class data attributes.
8926 · autodoc now supports documenting the signatures of functools.par‐
8928 tial objects.
8929 · Other extensions:
8931 · Added the sphinx.ext.mathjax extension.
8933 · #443: Allow referencing external graphviz files.
8935 · Added inline option to graphviz directives, and fixed the default
8937 (block-style) in LaTeX output.
8938 · #590: Added caption option to graphviz directives.
8940 · #553: Added testcleanup blocks in the doctest extension.
8942 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
8944 · #367: Added automatic exclusion of hidden members in inheritance
8946 diagrams, and an option to selectively enable it.
8947 · Added pngmath_add_tooltips.
8949 · The math extension displaymath directives now support name in addi‐
8951 tion to label for giving the equation label, for compatibility with
8952 Docutils.
8953 · New locales:
8955 · #221: Added Swedish locale.
8957 · #526: Added Iranian locale.
8959 · #694: Added Latvian locale.
8961 · Added Nepali locale.
8963 · #714: Added Korean locale.
8965 · #766: Added Estonian locale.
8967 · Bugs fixed:
8969 · #778: Fix "hide search matches" link on pages linked by search.
8971 · Fix the source positions referenced by the "viewcode" extension.
8973 Release 1.0.8 (Sep 23, 2011)
8975 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
8976 · Fix the abbr role when the abbreviation has newlines in it.
8978 · #727: Fix the links to search results with custom object types.
8980 · #648: Fix line numbers reported in warnings about undefined refer‐
8982 ences.
8983 · #696, #666: Fix C++ array definitions and template arguments that are
8985 not type names.
8986 · #633: Allow footnotes in section headers in LaTeX output.
8988 · #616: Allow keywords to be linked via intersphinx.
8990 · #613: Allow Unicode characters in production list token names.
8992 · #720: Add dummy visitors for graphviz nodes for text and man.
8994 · #704: Fix image file duplication bug.
8996 · #677: Fix parsing of multiple signatures in C++ domain.
8998 · #637: Ignore Emacs lock files when looking for source files.
9000 · #544: Allow .pyw extension for importable modules in autodoc.
9002 · #700: Use $(MAKE) in quickstart-generated Makefiles.
9004 · #734: Make sidebar search box width consistent in browsers.
9006 · #644: Fix spacing of centered figures in HTML output.
9008 · #767: Safely encode SphinxError messages when printing them to
9010 sys.stderr.
9011 · #611: Fix LaTeX output error with a document with no sections but a
9013 link target.
9014 · Correctly treat built-in method descriptors as methods in autodoc.
9016 · #706: Stop monkeypatching the Python textwrap module.
9018 · #657: viewcode now works correctly with source files that have
9020 non-ASCII encoding.
9021 · #669: Respect the noindex flag option in py:module directives.
9023 · #675: Fix IndexErrors when including nonexisting lines with literal‐
9025 include.
9026 · #676: Respect custom function/method parameter separator strings.
9028 · #682: Fix JS incompatibility with jQuery >= 1.5.
9030 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
9032 · #647: Do not apply SmartyPants in parsed-literal blocks.
9034 · C++ domain now supports array definitions.
9036 Release 1.0.7 (Jan 15, 2011)
9038 · #347: Fix wrong generation of directives of static methods in auto‐
9039 summary.
9040 · #599: Import PIL as from PIL import Image.
9042 · #558: Fix longtables with captions in LaTeX output.
9044 · Make token references work as hyperlinks again in LaTeX output.
9046 · #572: Show warnings by default when reference labels cannot be found.
9048 · #536: Include line number when complaining about missing reference
9050 targets in nitpicky mode.
9051 · #590: Fix inline display of graphviz diagrams in LaTeX output.
9053 · #589: Build using app.build() in setup command.
9055 · Fix a bug in the inheritance diagram exception that caused base
9057 classes to be skipped if one of them is a builtin.
9058 · Fix general index links for C++ domain objects.
9060 · #332: Make admonition boundaries in LaTeX output visible.
9062 · #573: Fix KeyErrors occurring on rebuild after removing a file.
9064 · Fix a traceback when removing files with globbed toctrees.
9066 · If an autodoc object cannot be imported, always re-read the document
9068 containing the directive on next build.
9069 · If an autodoc object cannot be imported, show the full traceback of
9071 the import error.
9072 · Fix a bug where the removal of download files and images wasn't
9074 noticed.
9075 · #571: Implement ~ cross-reference prefix for the C domain.
9077 · Fix regression of LaTeX output with the fix of #556.
9079 · #568: Fix lookup of class attribute documentation on descriptors so
9081 that comment documentation now works.
9082 · Fix traceback with only directives preceded by targets.
9084 · Fix tracebacks occurring for duplicate C++ domain objects.
9086 · Fix JavaScript domain links to objects with $ in their name.
9088 Release 1.0.6 (Jan 04, 2011)
9090 · #581: Fix traceback in Python domain for empty cross-reference tar‐
9091 gets.
9092 · #283: Fix literal block display issues on Chrome browsers.
9094 · #383, #148: Support sorting a limited range of accented characters in
9096 the general index and the glossary.
9097 · #570: Try decoding -D and -A command-line arguments with the locale's
9099 preferred encoding.
9100 · #528: Observe locale_dirs when looking for the JS translations file.
9102 · #574: Add special code for better support of Japanese documents in
9104 the LaTeX builder.
9105 · Regression of #77: If there is only one parameter given with :param:
9107 markup, the bullet list is now suppressed again.
9108 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
9110 tions.
9111 · #567: Emit the autodoc-process-docstring event even for objects with‐
9113 out a docstring so that it can add content.
9114 · #565: In the LaTeX builder, not only literal blocks require different
9116 table handling, but also quite a few other list-like block elements.
9117 · #515: Fix tracebacks in the viewcode extension for Python objects
9119 that do not have a valid signature.
9120 · Fix strange reportings of line numbers for warnings generated from
9122 autodoc-included docstrings, due to different behavior depending on
9123 docutils version.
9124 · Several fixes to the C++ domain.
9126 Release 1.0.5 (Nov 12, 2010)
9128 · #557: Add CSS styles required by docutils 0.7 for aligned images and
9129 figures.
9130 · In the Makefile generated by LaTeX output, do not delete pdf files on
9132 clean; they might be required images.
9133 · #535: Fix LaTeX output generated for line blocks.
9135 · #544: Allow .pyw as a source file extension.
9137 Release 1.0.4 (Sep 17, 2010)
9139 · #524: Open intersphinx inventories in binary mode on Windows, since
9140 version 2 contains zlib-compressed data.
9141 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
9143 JSMath extension.
9144 · #512: Fix traceback when intersphinx_mapping is empty.
9146 Release 1.0.3 (Aug 23, 2010)
9148 · #495: Fix internal vs. external link distinction for links coming
9149 from a docutils table-of-contents.
9150 · #494: Fix the maxdepth option for the toctree() template callable
9152 when used with collapse=True.
9153 · #507: Fix crash parsing Python argument lists containing brackets in
9155 string literals.
9156 · #501: Fix regression when building LaTeX docs with figures that don't
9158 have captions.
9159 · #510: Fix inheritance diagrams for classes that are not picklable.
9161 · #497: Introduce separate background color for the sidebar collapse
9163 button, making it easier to see.
9164 · #502, #503, #496: Fix small layout bugs in several builtin themes.
9166 Release 1.0.2 (Aug 14, 2010)
9168 · #490: Fix cross-references to objects of types added by the
9169 add_object_type() API function.
9170 · Fix handling of doc field types for different directive types.
9172 · Allow breaking long signatures, continuing with backlash-escaped new‐
9174 lines.
9175 · Fix unwanted styling of C domain references (because of a namespace
9177 clash with Pygments styles).
9178 · Allow references to PEPs and RFCs with explicit anchors.
9180 · #471: Fix LaTeX references to figures.
9182 · #482: When doing a non-exact search, match only the given type of
9184 object.
9185 · #481: Apply non-exact search for Python reference targets with .name
9187 for modules too.
9188 · #484: Fix crash when duplicating a parameter in an info field list.
9190 · #487: Fix setting the default role to one provided by the oldcmarkup
9192 extension.
9193 · #488: Fix crash when json-py is installed, which provides a json mod‐
9195 ule but is incompatible to simplejson.
9196 · #480: Fix handling of target naming in intersphinx.
9198 · #486: Fix removal of ! for all cross-reference roles.
9200 Release 1.0.1 (Jul 27, 2010)
9202 · #470: Fix generated target names for reST domain objects; they are
9203 not in the same namespace.
9204 · #266: Add Bengali language.
9206 · #473: Fix a bug in parsing JavaScript object names.
9208 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
9210 · Fix display names for objects linked to by intersphinx with explicit
9212 targets.
9213 · Fix building with the JSON builder.
9215 · Fix hyperrefs in object descriptions for LaTeX.
9217 Release 1.0 (Jul 23, 2010)
9219 Incompatible changes
9220 · Support for domains has been added. A domain is a collection of
9221 directives and roles that all describe objects belonging together,
9222 e.g. elements of a programming language. A few builtin domains are
9223 provided:
9224 · Python
9226 · C
9228 · C++
9230 · JavaScript
9232 · reStructuredText
9234 · The old markup for defining and linking to C directives is now depre‐
9236 cated. It will not work anymore in future versions without activat‐
9237 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
9238 default.
9239 · Removed support for old dependency versions; requirements are now:
9241 · docutils >= 0.5
9243 · Jinja2 >= 2.2
9245 · Removed deprecated elements:
9247 · exclude_dirs config value
9249 · sphinx.builder module
9251 Features added
9253 · General:
9254 · Added a "nitpicky" mode that emits warnings for all missing refer‐
9256 ences. It is activated by the -n command-line switch or the nit‐
9257 picky config value.
9258 · Added latexpdf target in quickstart Makefile.
9260 · Markup:
9262 · The menuselection and guilabel roles now support ampersand acceler‐
9264 ators.
9265 · New more compact doc field syntax is now recognized: :param type
9267 name: description.
9268 · Added tab-width option to literalinclude directive.
9270 · Added titlesonly option to toctree directive.
9272 · Added the prepend and append options to the literalinclude direc‐
9274 tive.
9275 · #284: All docinfo metadata is now put into the document metadata,
9277 not just the author.
9278 · The ref role can now also reference tables by caption.
9280 · The include directive now supports absolute paths, which are inter‐
9282 preted as relative to the source directory.
9283 · In the Python domain, references like :func:`.name` now look for
9285 matching names with any prefix if no direct match is found.
9286 · Configuration:
9288 · Added rst_prolog config value.
9290 · Added html_secnumber_suffix config value to control section number‐
9292 ing format.
9293 · Added html_compact_lists config value to control docutils' compact
9295 lists feature.
9296 · The html_sidebars config value can now contain patterns as keys,
9298 and the values can be lists that explicitly select which sidebar
9299 templates should be rendered. That means that the builtin sidebar
9300 contents can be included only selectively.
9301 · html_static_path can now contain single file entries.
9303 · The new universal config value exclude_patterns makes the old
9305 unused_docs, exclude_trees and exclude_dirnames obsolete.
9306 · Added html_output_encoding config value.
9308 · Added the latex_docclass config value and made the "twoside" docu‐
9310 mentclass option overridable by "oneside".
9311 · Added the trim_doctest_flags config value, which is true by
9313 default.
9314 · Added html_show_copyright config value.
9316 · Added latex_show_pagerefs and latex_show_urls config values.
9318 · The behavior of html_file_suffix changed slightly: the empty string
9320 now means "no suffix" instead of "default suffix", use None for
9321 "default suffix".
9322 · New builders:
9324 · Added a builder for the Epub format.
9326 · Added a builder for manual pages.
9328 · Added a single-file HTML builder.
9330 · HTML output:
9332 · Inline roles now get a CSS class with their name, allowing styles
9334 to customize their appearance. Domain-specific roles get two
9335 classes, domain and domain-rolename.
9336 · References now get the class internal if they are internal to the
9338 whole project, as opposed to internal to the current page.
9339 · External references can be styled differently with the new exter‐
9341 nalrefs theme option for the default theme.
9342 · In the default theme, the sidebar can experimentally now be made
9344 collapsible using the new collapsiblesidebar theme option.
9345 · #129: Toctrees are now wrapped in a div tag with class toc‐
9347 tree-wrapper in HTML output.
9348 · The toctree callable in templates now has a maxdepth keyword argu‐
9350 ment to control the depth of the generated tree.
9351 · The toctree callable in templates now accepts a titles_only keyword
9353 argument.
9354 · Added htmltitle block in layout template.
9356 · In the JavaScript search, allow searching for object names includ‐
9358 ing the module name, like sys.argv.
9359 · Added new theme haiku, inspired by the Haiku OS user guide.
9361 · Added new theme nature.
9363 · Added new theme agogo, created by Andi Albrecht.
9365 · Added new theme scrolls, created by Armin Ronacher.
9367 · #193: Added a visitedlinkcolor theme option to the default theme.
9369 · #322: Improved responsiveness of the search page by loading the
9371 search index asynchronously.
9372 · Extension API:
9374 · Added html-collect-pages.
9376 · Added needs_sphinx config value and require_sphinx() application
9378 API method.
9379 · #200: Added add_stylesheet() application API method.
9381 · Extensions:
9383 · Added the viewcode extension.
9385 · Added the extlinks extension.
9387 · Added support for source ordering of members in autodoc, with
9389 autodoc_member_order = 'bysource'.
9390 · Added autodoc_default_flags config value, which can be used to
9392 select default flags for all autodoc directives.
9393 · Added a way for intersphinx to refer to named labels in other
9395 projects, and to specify the project you want to link to.
9396 · #280: Autodoc can now document instance attributes assigned in
9398 __init__ methods.
9399 · Many improvements and fixes to the autosummary extension, thanks to
9401 Pauli Virtanen.
9402 · #309: The graphviz extension can now output SVG instead of PNG
9404 images, controlled by the graphviz_output_format config value.
9405 · Added alt option to graphviz extension directives.
9407 · Added exclude argument to autodoc.between().
9409 · Translations:
9411 · Added Croatian translation, thanks to Bojan Mihelač.
9413 · Added Turkish translation, thanks to Firat Ozgul.
9415 · Added Catalan translation, thanks to Pau Fernández.
9417 · Added simplified Chinese translation.
9419 · Added Danish translation, thanks to Hjorth Larsen.
9421 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
9423 · Bugs fixed:
9425 · #445: Fix links to result pages when using the search function of
9427 HTML built with the dirhtml builder.
9428 · #444: In templates, properly re-escape values treated with the
9430 "striptags" Jinja filter.
9431 Release 0.6.7 (Jun 05, 2010)
9433 · #440: Remove usage of a Python >= 2.5 API in the literalinclude
9434 directive.
9435 · Fix a bug that prevented some references being generated in the LaTeX
9437 builder.
9438 · #428: Add some missing CSS styles for standard docutils classes.
9440 · #432: Fix UnicodeErrors while building LaTeX in translated locale.
9442 Release 0.6.6 (May 25, 2010)
9444 · Handle raw nodes in the text writer.
9445 · Fix a problem the Qt help project generated by the qthelp builder
9447 that would lead to no content being displayed in the Qt Assistant.
9448 · #393: Fix the usage of Unicode characters in mathematic formulas when
9450 using the pngmath extension.
9451 · #404: Make \and work properly in the author field of the latex_docu‐
9453 ments setting.
9454 · #409: Make the highlight_language config value work properly in the
9456 LaTeX builder.
9457 · #418: Allow relocation of the translation JavaScript files to the
9459 system directory on Unix systems.
9460 · #414: Fix handling of Windows newlines in files included with the
9462 literalinclude directive.
9463 · #377: Fix crash in linkcheck builder.
9465 · #387: Fix the display of search results in dirhtml output.
9467 · #376: In autodoc, fix display of parameter defaults containing back‐
9469 slashes.
9470 · #370: Fix handling of complex list item labels in LaTeX output.
9472 · #374: Make the doctest_path config value of the doctest extension
9474 actually work.
9475 · Fix the handling of multiple toctrees when creating the global TOC
9477 for the toctree() template function.
9478 · Fix the handling of hidden toctrees when creating the global TOC for
9480 the toctree() template function.
9481 · Fix the handling of nested lists in the text writer.
9483 · #362: In autodoc, check for the existence of __self__ on function
9485 objects before accessing it.
9486 · #353: Strip leading and trailing whitespace when extracting search
9488 words in the search function.
9489 Release 0.6.5 (Mar 01, 2010)
9491 · In autodoc, fix the omission of some module members explicitly docu‐
9492 mented using documentation comments.
9493 · #345: Fix cropping of sidebar scroll bar with stickysidebar option of
9495 the default theme.
9496 · #341: Always generate UNIX newlines in the quickstart Makefile.
9498 · #338: Fix running with -C under Windows.
9500 · In autodoc, allow customizing the signature of an object where the
9502 built-in mechanism fails.
9503 · #331: Fix output for enumerated lists with start values in LaTeX.
9505 · Make the start-after and end-before options to the literalinclude
9507 directive work correctly if not used together.
9508 · #321: Fix link generation in the LaTeX builder.
9510 Release 0.6.4 (Jan 12, 2010)
9512 · Improve the handling of non-Unicode strings in the configuration.
9513 · #316: Catch OSErrors occurring when calling graphviz with arguments
9515 it doesn't understand.
9516 · Restore compatibility with Pygments >= 1.2.
9518 · #295: Fix escaping of hyperref targets in LaTeX output.
9520 · #302: Fix links generated by the :doc: role for LaTeX output.
9522 · #286: collect todo nodes after the whole document has been read; this
9524 allows placing substitution references in todo items.
9525 · #294: do not ignore an explicit today config value in a LaTeX build.
9527 · The alt text of inheritance diagrams is now much cleaner.
9529 · Ignore images in section titles when generating link captions.
9531 · #310: support exception messages in the testoutput blocks of the
9533 doctest extension.
9534 · #293: line blocks are styled properly in HTML output.
9536 · #285: make the locale_dirs config value work again.
9538 · #303: html_context values given on the command line via -A should not
9540 override other values given in conf.py.
9541 · Fix a bug preventing incremental rebuilds for the dirhtml builder.
9543 · #299: Fix the mangling of quotes in some literal blocks.
9545 · #292: Fix path to the search index for the dirhtml builder.
9547 · Fix a Jython compatibility issue: make the dependence on the parser
9549 module optional.
9550 · #238: In autodoc, catch all errors that occur on module import, not
9552 just ImportError.
9553 · Fix the handling of non-data, but non-method descriptors in autodoc.
9555 · When copying file times, ignore OSErrors raised by os.utime().
9557 Release 0.6.3 (Sep 03, 2009)
9559 · Properly add C module filenames as dependencies in autodoc.
9560 · #253: Ignore graphviz directives without content instead of raising
9562 an unhandled exception.
9563 · #241: Fix a crash building LaTeX output for documents that contain a
9565 todolist directive.
9566 · #252: Make it easier to change the build dir in the Makefiles gener‐
9568 ated by quickstart.
9569 · #220: Fix CSS so that displaymath really is centered.
9571 · #222: Allow the "Footnotes" header to be translated.
9573 · #225: Don't add whitespace in generated HTML after inline tags.
9575 · #227: Make literalinclude work when the document's path name contains
9577 non-ASCII characters.
9578 · #229: Fix autodoc failures with members that raise errors on
9580 getattr().
9581 · #205: When copying files, don't copy full stat info, only modifica‐
9583 tion times.
9584 · #232: Support non-ASCII metadata in Qt help builder.
9586 · Properly format bullet lists nested in definition lists for LaTeX.
9588 · Section titles are now allowed inside only directives.
9590 · #201: Make centered directive work in LaTeX output.
9592 · #206: Refuse to overwrite an existing master document in
9594 sphinx-quickstart.
9595 · #208: Use MS-sanctioned locale settings, determined by the language
9597 config option, in the HTML help builder.
9598 · #210: Fix nesting of HTML tags for displayed math from pngmath exten‐
9600 sion.
9601 · #213: Fix centering of images in LaTeX output.
9603 · #211: Fix compatibility with docutils 0.5.
9605 Release 0.6.2 (Jun 16, 2009)
9607 · #130: Fix obscure IndexError in doctest extension.
9608 · #167: Make glossary sorting case-independent.
9610 · #196: Add a warning if an extension module doesn't have a setup()
9612 function.
9613 · #158: Allow '..' in template names, and absolute template paths;
9615 Jinja 2 by default disables both.
9616 · When highlighting Python code, ignore extra indentation before trying
9618 to parse it as Python.
9619 · #191: Don't escape the tilde in URIs in LaTeX.
9621 · Don't consider contents of source comments for the search index.
9623 · Set the default encoding to utf-8-sig to handle files with a UTF-8
9625 BOM correctly.
9626 · #178: apply add_function_parentheses config value to C functions as
9628 promised.
9629 · #173: Respect the docutils title directive.
9631 · #172: The obj role now links to modules as promised.
9633 · #19: Tables now can have a "longtable" class, in order to get cor‐
9635 rectly broken into pages in LaTeX output.
9636 · Look for Sphinx message catalogs in the system default path before
9638 trying sphinx/locale.
9639 · Fix the search for methods via "classname.methodname".
9641 · #155: Fix Python 2.4 compatibility: exceptions are old-style classes
9643 there.
9644 · #150: Fix display of the "sphinxdoc" theme on Internet Explorer ver‐
9646 sions 6 and 7.
9647 · #146: Don't fail to generate LaTeX when the user has an active .docu‐
9649 tils configuration.
9650 · #29: Don't generate visible "-{-}" in option lists in LaTeX.
9652 · Fix cross-reference roles when put into substitutions.
9654 · Don't put image "alt" text into table-of-contents entries.
9656 · In the LaTeX writer, do not raise an exception on too many section
9658 levels, just use the "subparagraph" level for all of them.
9659 · #145: Fix autodoc problem with automatic members that refuse to be
9661 getattr()'d from their parent.
9662 · If specific filenames to build are given on the command line, check
9664 that they are within the source directory.
9665 · Fix autodoc crash for objects without a __name__.
9667 · Fix intersphinx for installations without urllib2.HTTPSHandler.
9669 · #134: Fix pending_xref leftover nodes when using the todolist direc‐
9671 tive from the todo extension.
9672 Release 0.6.1 (Mar 26, 2009)
9674 · #135: Fix problems with LaTeX output and the graphviz extension.
9675 · #132: Include the autosummary "module" template in the distribution.
9677 Release 0.6 (Mar 24, 2009)
9679 New features added
9680 · Incompatible changes:
9681 · Templating now requires the Jinja2 library, which is an enhanced
9683 version of the old Jinja1 engine. Since the syntax and semantic is
9684 largely the same, very few fixes should be necessary in custom tem‐
9685 plates.
9686 · The "document" div tag has been moved out of the layout.html tem‐
9688 plate's "document" block, because the closing tag was already out‐
9689 side. If you overwrite this block, you need to remove your "docu‐
9690 ment" div tag as well.
9691 · The autodoc_skip_member event now also gets to decide whether to
9693 skip members whose name starts with underscores. Previously, these
9694 members were always automatically skipped. Therefore, if you han‐
9695 dle this event, add something like this to your event handler to
9696 restore the old behavior:
9697 if name.startswith('_'):
9699 return True
9700 · Theming support, see the new section in the documentation.
9702 · Markup:
9704 · Due to popular demand, added a :doc: role which directly links to
9706 another document without the need of creating a label to which a
9707 :ref: could link to.
9708 · #4: Added a :download: role that marks a non-document file for
9710 inclusion into the HTML output and links to it.
9711 · Added an only directive that can selectively include text based on
9713 enabled "tags". Tags can be given on the command line. Also, the
9714 current builder output format (e.g. "html" or "latex") is always a
9715 defined tag.
9716 · #10: Added HTML section numbers, enabled by giving a :numbered:
9718 flag to the toctree directive.
9719 · #114: Added an abbr role to markup abbreviations and acronyms.
9721 · The literalinclude directive now supports several more options, to
9723 include only parts of a file.
9724 · The toctree directive now supports a :hidden: flag, which will pre‐
9726 vent links from being generated in place of the directive -- this
9727 allows you to define your document structure, but place the links
9728 yourself.
9729 · #123: The glossary directive now supports a :sorted: flag that
9731 sorts glossary entries alphabetically.
9732 · Paths to images, literal include files and download files can now
9734 be absolute (like /images/foo.png). They are treated as relative
9735 to the top source directory.
9736 · #52: There is now a hlist directive, creating a compact list by
9738 placing distributing items into multiple columns.
9739 · #77: If a description environment with info field list only con‐
9741 tains one :param: entry, no bullet list is generated.
9742 · #6: Don't generate redundant <ul> for top-level TOC tree items,
9744 which leads to a visual separation of TOC entries.
9745 · #23: Added a classmethod directive along with method and stat‐
9747 icmethod.
9748 · Scaled images now get a link to the unscaled version.
9750 · SVG images are now supported in HTML (via <object> and <embed>
9752 tags).
9753 · Added a toctree callable to the templates, and the ability to
9755 include external links in toctrees. The 'collapse' keyword argument
9756 indicates whether or not to only display subitems of the current
9757 page. (Defaults to True.)
9758 · Configuration:
9760 · The new config value rst_epilog can contain reST that is appended
9762 to each source file that is read. This is the right place for
9763 global substitutions.
9764 · The new html_add_permalinks config value can be used to switch off
9766 the generated "paragraph sign" permalinks for each heading and def‐
9767 inition environment.
9768 · The new html_show_sourcelink config value can be used to switch off
9770 the links to the reST sources in the sidebar.
9771 · The default value for htmlhelp_basename is now the project title,
9773 cleaned up as a filename.
9774 · The new modindex_common_prefix config value can be used to ignore
9776 certain package names for module index sorting.
9777 · The new trim_footnote_reference_space config value mirrors the
9779 docutils config value of the same name and removes the space before
9780 a footnote reference that is necessary for reST to recognize the
9781 reference.
9782 · The new latex_additional_files config value can be used to copy
9784 files (that Sphinx doesn't copy automatically, e.g. if they are
9785 referenced in custom LaTeX added in latex_elements) to the build
9786 directory.
9787 · Builders:
9789 · The HTML builder now stores a small file named .buildinfo in its
9791 output directory. It stores a hash of config values that can be
9792 used to determine if a full rebuild needs to be done (e.g. after
9793 changing html_theme).
9794 · New builder for Qt help collections, by Antonio Valentino.
9796 · The new DirectoryHTMLBuilder (short name dirhtml) creates a sepa‐
9798 rate directory for every page, and places the page there in a file
9799 called index.html. Therefore, page URLs and links don't need to
9800 contain .html.
9801 · The new html_link_suffix config value can be used to select the
9803 suffix of generated links between HTML files.
9804 · #96: The LaTeX builder now supports figures wrapped by text, when
9806 using the figwidth option and right/left alignment.
9807 · New translations:
9809 · Italian by Sandro Dentella.
9811 · Ukrainian by Petro Sasnyk.
9813 · Finnish by Jukka Inkeri.
9815 · Russian by Alexander Smishlajev.
9817 · Extensions and API:
9819 · New graphviz extension to embed graphviz graphs.
9821 · New inheritance_diagram extension to embed... inheritance diagrams!
9823 · New autosummary extension that generates summaries of modules and
9825 automatic documentation of modules.
9826 · Autodoc now has a reusable Python API, which can be used to create
9828 custom types of objects to auto-document (e.g. Zope interfaces).
9829 See also Sphinx.add_autodocumenter().
9830 · Autodoc now handles documented attributes.
9832 · Autodoc now handles inner classes and their methods.
9834 · Autodoc can document classes as functions now if explicitly marked
9836 with autofunction.
9837 · Autodoc can now exclude single members from documentation via the
9839 exclude-members option.
9840 · Autodoc can now order members either alphabetically (like previ‐
9842 ously) or by member type; configurable either with the config value
9843 autodoc_member_order or a member-order option per directive.
9844 · The function Sphinx.add_directive() now also supports docutils
9846 0.5-style directive classes. If they inherit from sphinx.util.com‐
9847 pat.Directive, they also work with docutils 0.4.
9848 · There is now a Sphinx.add_lexer() method to be able to use custom
9850 Pygments lexers easily.
9851 · There is now Sphinx.add_generic_role() to mirror the docutils' own
9853 function.
9854 · Other changes:
9856 · Config overrides for single dict keys can now be given on the com‐
9858 mand line.
9859 · There is now a doctest_global_setup config value that can be used
9861 to give setup code for all doctests in the documentation.
9862 · Source links in HTML are now generated with rel="nofollow".
9864 · Quickstart can now generate a Windows make.bat file.
9866 · #62: There is now a -w option for sphinx-build that writes warnings
9868 to a file, in addition to stderr.
9869 · There is now a -W option for sphinx-build that turns warnings into
9871 errors.
9872 Release 0.5.2 (Mar 24, 2009)
9874 · Properly escape | in LaTeX output.
9875 · #71: If a decoding error occurs in source files, print a warning and
9877 replace the characters by "?".
9878 · Fix a problem in the HTML search if the index takes too long to load.
9880 · Don't output system messages while resolving, because they would stay
9882 in the doctrees even if keep_warnings is false.
9883 · #82: Determine the correct path for dependencies noted by docutils.
9885 This fixes behavior where a source with dependent files was always
9886 reported as changed.
9887 · Recognize toctree directives that are not on section toplevel, but
9889 within block items, such as tables.
9890 · Use a new RFC base URL, since rfc.org seems down.
9892 · Fix a crash in the todolist directive when no todo items are defined.
9894 · Don't call LaTeX or dvipng over and over again if it was not found
9896 once, and use text-only latex as a substitute in that case.
9897 · Fix problems with footnotes in the LaTeX output.
9899 · Prevent double hyphens becoming en-dashes in literal code in the
9901 LaTeX output.
9902 · Open literalinclude files in universal newline mode to allow arbi‐
9904 trary newline conventions.
9905 · Actually make the -Q option work.
9907 · #86: Fix explicit document titles in toctrees.
9909 · #81: Write environment and search index in a manner that is safe from
9911 exceptions that occur during dumping.
9912 · #80: Fix UnicodeErrors when a locale is set with setlocale().
9914 Release 0.5.1 (Dec 15, 2008)
9916 · #67: Output warnings about failed doctests in the doctest extension
9917 even when running in quiet mode.
9918 · #72: In pngmath, make it possible to give a full path to LaTeX and
9920 dvipng on Windows. For that to work, the pngmath_latex and png‐
9921 math_dvipng options are no longer split into command and additional
9922 arguments; use pngmath_latex_args and pngmath_dvipng_args to give
9923 additional arguments.
9924 · Don't crash on failing doctests with non-ASCII characters.
9926 · Don't crash on writing status messages and warnings containing unen‐
9928 codable characters.
9929 · Warn if a doctest extension block doesn't contain any code.
9931 · Fix the handling of :param: and :type: doc fields when they contain
9933 markup (especially cross-referencing roles).
9934 · #65: Fix storage of depth information for PNGs generated by the png‐
9936 math extension.
9937 · Fix autodoc crash when automethod is used outside a class context.
9939 · #68: Fix LaTeX writer output for images with specified height.
9941 · #60: Fix wrong generated image path when including images in sources
9943 in subdirectories.
9944 · Fix the JavaScript search when html_copy_source is off.
9946 · Fix an indentation problem in autodoc when documenting classes with
9948 the option autoclass_content = "both" set.
9949 · Don't crash on empty index entries, only emit a warning.
9951 · Fix a typo in the search JavaScript code, leading to unusable search
9953 function in some setups.
9954 Release 0.5 (Nov 23, 2008) -- Birthday release!
9956 New features added
9957 · Markup features:
9958 · Citations are now global: all citation defined in any file can be
9960 referenced from any file. Citations are collected in a bibliogra‐
9961 phy for LaTeX output.
9962 · Footnotes are now properly handled in the LaTeX builder: they
9964 appear at the location of the footnote reference in text, not at
9965 the end of a section. Thanks to Andrew McNamara for the initial
9966 patch.
9967 · "System Message" warnings are now automatically removed from the
9969 built documentation, and only written to stderr. If you want the
9970 old behavior, set the new config value keep_warnings to True.
9971 · Glossary entries are now automatically added to the index.
9973 · Figures with captions can now be referred to like section titles,
9975 using the :ref: role without an explicit link text.
9976 · Added cmember role for consistency.
9978 · Lists enumerated by letters or roman numerals are now handled like
9980 in standard reST.
9981 · The seealso directive can now also be given arguments, as a short
9983 form.
9984 · You can now document several programs and their options with the
9986 new program directive.
9987 · HTML output and templates:
9989 · Incompatible change: The "root" relation link (top left in the rel‐
9991 bar) now points to the master_doc by default, no longer to a docu‐
9992 ment called "index". The old behavior, while useful in some situa‐
9993 tions, was somewhat unexpected. Override the "rootrellink" block
9994 in the template to customize where it refers to.
9995 · The JavaScript search now searches for objects before searching in
9997 the full text.
9998 · TOC tree entries now have CSS classes that make it possible to
10000 style them depending on their depth.
10001 · Highlighted code blocks now have CSS classes that make it possible
10003 to style them depending on their language.
10004 · HTML <meta> tags via the docutils meta directive are now supported.
10006 · SerializingHTMLBuilder was added as new abstract builder that can
10008 be subclassed to serialize build HTML in a specific format. The
10009 PickleHTMLBuilder is a concrete subclass of it that uses pickle as
10010 serialization implementation.
10011 · JSONHTMLBuilder was added as another SerializingHTMLBuilder sub‐
10013 class that dumps the generated HTML into JSON files for further
10014 processing.
10015 · The rellinks block in the layout template is now called linktags to
10017 avoid confusion with the relbar links.
10018 · The HTML builders have two additional attributes now that can be
10020 used to disable the anchor-link creation after headlines and defi‐
10021 nition links.
10022 · Only generate a module index if there are some modules in the docu‐
10024 mentation.
10025 · New and changed config values:
10027 · Added support for internationalization in generated text with the
10029 language and locale_dirs config values. Many thanks to language
10030 contributors:
10031 · Horst Gutmann -- German
10033 · Pavel Kosina -- Czech
10035 · David Larlet -- French
10037 · Michał Kandulski -- Polish
10039 · Yasushi Masuda -- Japanese
10041 · Guillem Borrell -- Spanish
10043 · Luc Saffre and Peter Bertels -- Dutch
10045 · Fred Lin -- Traditional Chinese
10047 · Roger Demetrescu -- Brazilian Portuguese
10049 · Rok Garbas -- Slovenian
10051 · The new config value highlight_language set a global default for
10053 highlighting. When 'python3' is selected, console output blocks
10054 are recognized like for 'python'.
10055 · Exposed Pygments' lexer guessing as a highlight "language" guess.
10057 · The new config value latex_elements allows to override all LaTeX
10059 snippets that Sphinx puts into the generated .tex file by default.
10060 · Added exclude_dirnames config value that can be used to exclude
10062 e.g. CVS directories from source file search.
10063 · Added source_encoding config value to select input encoding.
10065 · Extensions:
10067 · The new extensions sphinx.ext.jsmath and sphinx.ext.pngmath provide
10069 math support for both HTML and LaTeX builders.
10070 · The new extension sphinx.ext.intersphinx half-automatically creates
10072 links to Sphinx documentation of Python objects in other projects.
10073 · The new extension sphinx.ext.todo allows the insertion of "To do"
10075 directives whose visibility in the output can be toggled. It also
10076 adds a directive to compile a list of all todo items.
10077 · sphinx.ext.autodoc has a new event autodoc-process-signature that
10079 allows tuning function signature introspection.
10080 · sphinx.ext.autodoc has a new event autodoc-skip-member that allows
10082 tuning which members are included in the generated content.
10083 · Respect __all__ when autodocumenting module members.
10085 · The automodule directive now supports the synopsis, deprecated and
10087 platform options.
10088 · Extension API:
10090 · Sphinx.add_node() now takes optional visitor methods for the HTML,
10092 LaTeX and text translators; this prevents having to manually patch
10093 the classes.
10094 · Added Sphinx.add_javascript() that adds scripts to load in the
10096 default HTML template.
10097 · Added new events: source-read, env-updated, env-purge-doc, miss‐
10099 ing-reference, build-finished.
10100 · Other changes:
10102 · Added a command-line switch -Q: it will suppress warnings.
10104 · Added a command-line switch -A: it can be used to supply additional
10106 values into the HTML templates.
10107 · Added a command-line switch -C: if it is given, no configuration
10109 file conf.py is required.
10110 · Added a distutils command build_sphinx: When Sphinx is installed,
10112 you can call python setup.py build_sphinx for projects that have
10113 Sphinx documentation, which will build the docs and place them in
10114 the standard distutils build directory.
10115 · In quickstart, if the selected root path already contains a Sphinx
10117 project, complain and abort.
10118 Bugs fixed
10120 · #51: Escape configuration values placed in HTML templates.
10121 · #44: Fix small problems in HTML help index generation.
10123 · Fix LaTeX output for line blocks in tables.
10125 · #38: Fix "illegal unit" error when using pixel image widths/heights.
10127 · Support table captions in LaTeX output.
10129 · #39: Work around a bug in Jinja that caused "<generator ...>" to be
10131 emitted in HTML output.
10132 · Fix a problem with module links not being generated in LaTeX output.
10134 · Fix the handling of images in different directories.
10136 · #29: Support option lists in the text writer. Make sure that dashes
10138 introducing long option names are not contracted to en-dashes.
10139 · Support the "scale" option for images in HTML output.
10141 · #25: Properly escape quotes in HTML help attribute values.
10143 · Fix LaTeX build for some description environments with :noindex:.
10145 · #24: Don't crash on uncommon casing of role names (like :Class:).
10147 · Only output ANSI colors on color terminals.
10149 · Update to newest fncychap.sty, to fix problems with non-ASCII charac‐
10151 ters at the start of chapter titles.
10152 · Fix a problem with index generation in LaTeX output, caused by hyper‐
10154 ref not being included last.
10155 · Don't disregard return annotations for functions without any parame‐
10157 ters.
10158 · Don't throw away labels for code blocks.
10160 Release 0.4.3 (Oct 8, 2008)
10162 · Fix a bug in autodoc with directly given autodoc members.
10163 · Fix a bug in autodoc that would import a module twice, once as "mod‐
10165 ule", once as "module.".
10166 · Fix a bug in the HTML writer that created duplicate id attributes for
10168 section titles with docutils 0.5.
10169 · Properly call super() in overridden blocks in templates.
10171 · Add a fix when using XeTeX.
10173 · Unify handling of LaTeX escaping.
10175 · Rebuild everything when the extensions config value changes.
10177 · Don't try to remove a nonexisting static directory.
10179 · Fix an indentation problem in production lists.
10181 · Fix encoding handling for literal include files: literalinclude now
10183 has an encoding option that defaults to UTF-8.
10184 · Fix the handling of non-ASCII characters entered in quickstart.
10186 · Fix a crash with nonexisting image URIs.
10188 Release 0.4.2 (Jul 29, 2008)
10190 · Fix rendering of the samp role in HTML.
10191 · Fix a bug with LaTeX links to headings leading to a wrong page.
10193 · Reread documents with globbed toctrees when source files are added or
10195 removed.
10196 · Add a missing parameter to PickleHTMLBuilder.handle_page().
10198 · Put inheritance info always on its own line.
10200 · Don't automatically enclose code with whitespace in it in quotes;
10202 only do this for the samp role.
10203 · autodoc now emits a more precise error message when a module can't be
10205 imported or an attribute can't be found.
10206 · The JavaScript search now uses the correct file name suffix when
10208 referring to found items.
10209 · The automodule directive now accepts the inherited-members and
10211 show-inheritance options again.
10212 · You can now rebuild the docs normally after relocating the source
10214 and/or doctree directory.
10215 Release 0.4.1 (Jul 5, 2008)
10217 · Added sub-/superscript node handling to TextBuilder.
10218 · Label names in references are now case-insensitive, since reST label
10220 names are always lowercased.
10221 · Fix linkcheck builder crash for malformed URLs.
10223 · Add compatibility for admonitions and docutils 0.5.
10225 · Remove the silly restriction on "rubric" in the LaTeX writer: you can
10227 now write arbitrary "rubric" directives, and only those with a title
10228 of "Footnotes" will be ignored.
10229 · Copy the HTML logo to the output _static directory.
10231 · Fix LaTeX code for modules with underscores in names and platforms.
10233 · Fix a crash with nonlocal image URIs.
10235 · Allow the usage of :noindex: in automodule directives, as documented.
10237 · Fix the delete() docstring processor function in autodoc.
10239 · Fix warning message for nonexisting images.
10241 · Fix JavaScript search in Internet Explorer.
10243 Release 0.4 (Jun 23, 2008)
10245 New features added
10246 · tocdepth can be given as a file-wide metadata entry, and specifies
10247 the maximum depth of a TOC of this file.
10248 · The new config value default_role can be used to select the default
10250 role for all documents.
10251 · Sphinx now interprets field lists with fields like :param foo: in
10253 description units.
10254 · The new staticmethod directive can be used to mark methods as static
10256 methods.
10257 · HTML output:
10259 · The "previous" and "next" links have a more logical structure, so
10261 that by following "next" links you can traverse the entire TOC
10262 tree.
10263 · The new event html-page-context can be used to include custom val‐
10265 ues into the context used when rendering an HTML template.
10266 · Document metadata is now in the default template context, under the
10268 name metadata.
10269 · The new config value html_favicon can be used to set a favicon for
10271 the HTML output. Thanks to Sebastian Wiesner.
10272 · The new config value html_use_index can be used to switch index
10274 generation in HTML documents off.
10275 · The new config value html_split_index can be used to create sepa‐
10277 rate index pages for each letter, to be used when the complete
10278 index is too large for one page.
10279 · The new config value html_short_title can be used to set a shorter
10281 title for the documentation which is then used in the navigation
10282 bar.
10283 · The new config value html_show_sphinx can be used to control
10285 whether a link to Sphinx is added to the HTML footer.
10286 · The new config value html_file_suffix can be used to set the HTML
10288 file suffix to e.g. .xhtml.
10289 · The directories in the html_static_path can now contain subdirecto‐
10291 ries.
10292 · The module index now isn't collapsed if the number of submodules is
10294 larger than the number of toplevel modules.
10295 · The image directive now supports specifying the extension as .*,
10297 which makes the builder select the one that matches best. Thanks to
10298 Sebastian Wiesner.
10299 · The new config value exclude_trees can be used to exclude whole sub‐
10301 trees from the search for source files.
10302 · Defaults for configuration values can now be callables, which allows
10304 dynamic defaults.
10305 · The new TextBuilder creates plain-text output.
10307 · Python 3-style signatures, giving a return annotation via ->, are now
10309 supported.
10310 · Extensions:
10312 · The autodoc extension now offers a much more flexible way to manip‐
10314 ulate docstrings before including them into the output, via the new
10315 autodoc-process-docstring event.
10316 · The autodoc extension accepts signatures for functions, methods and
10318 classes now that override the signature got via introspection from
10319 Python code.
10320 · The autodoc extension now offers a show-inheritance option for
10322 autoclass that inserts a list of bases after the signature.
10323 · The autodoc directives now support the noindex flag option.
10325 Bugs fixed
10327 · Correctly report the source location for docstrings included with
10328 autodoc.
10329 · Fix the LaTeX output of description units with multiple signatures.
10331 · Handle the figure directive in LaTeX output.
10333 · Handle raw admonitions in LaTeX output.
10335 · Fix determination of the title in HTML help output.
10337 · Handle project names containing spaces.
10339 · Don't write SSI-like comments in HTML output.
10341 · Rename the "sidebar" class to "sphinxsidebar" in order to stay dif‐
10343 ferent from reST sidebars.
10344 · Use a binary TOC in HTML help generation to fix issues links without
10346 explicit anchors.
10347 · Fix behavior of references to functions/methods with an explicit
10349 title.
10350 · Support citation, subscript and superscript nodes in LaTeX writer.
10352 · Provide the standard "class" directive as "cssclass"; else it is
10354 shadowed by the Sphinx-defined directive.
10355 · Fix the handling of explicit module names given to autoclass direc‐
10357 tives. They now show up with the correct module name in the gener‐
10358 ated docs.
10359 · Enable autodoc to process Unicode docstrings.
10361 · The LaTeX writer now translates line blocks with \raggedright, which
10363 plays nicer with tables.
10364 · Fix bug with directories in the HTML builder static path.
10366 Release 0.3 (May 6, 2008)
10368 New features added
10369 · The toctree directive now supports a glob option that allows
10370 glob-style entries in the content.
10371 · If the pygments_style config value contains a dot it's treated as the
10373 import path of a custom Pygments style class.
10374 · A new config value, exclude_dirs, can be used to exclude whole direc‐
10376 tories from the search for source files.
10377 · The configuration directory (containing conf.py) can now be set inde‐
10379 pendently from the source directory. For that, a new command-line
10380 option -c has been added.
10381 · A new directive tabularcolumns can be used to give a tabular column
10383 specification for LaTeX output. Tables now use the tabulary package.
10384 Literal blocks can now be placed in tables, with several caveats.
10385 · A new config value, latex_use_parts, can be used to enable parts in
10387 LaTeX documents.
10388 · Autodoc now skips inherited members for classes, unless you give the
10390 new inherited-members option.
10391 · A new config value, autoclass_content, selects if the docstring of
10393 the class' __init__ method is added to the directive's body.
10394 · Support for C++ class names (in the style Class::Function) in C func‐
10396 tion descriptions.
10397 · Support for a toctree_only item in items for the latex_documents con‐
10399 fig value. This only includes the documents referenced by TOC trees
10400 in the output, not the rest of the file containing the directive.
10401 Bugs fixed
10403 · sphinx.htmlwriter: Correctly write the TOC file for any structure of
10404 the master document. Also encode non-ASCII characters as entities in
10405 TOC and index file. Remove two remaining instances of hard-coded
10406 "documentation".
10407 · sphinx.ext.autodoc: descriptors are detected properly now.
10409 · sphinx.latexwriter: implement all reST admonitions, not just note and
10411 warning.
10412 · Lots of little fixes to the LaTeX output and style.
10414 · Fix OpenSearch template and make template URL absolute. The
10416 html_use_opensearch config value now must give the base URL.
10417 · Some unused files are now stripped from the HTML help file build.
10419 Release 0.2 (Apr 27, 2008)
10421 Incompatible changes
10422 · Jinja, the template engine used for the default HTML templates, is
10423 now no longer shipped with Sphinx. If it is not installed automati‐
10424 cally for you (it is now listed as a dependency in setup.py), install
10425 it manually from PyPI. This will also be needed if you're using
10426 Sphinx from a SVN checkout; in that case please also remove the
10427 sphinx/jinja directory that may be left over from old revisions.
10428 · The clumsy handling of the index.html template was removed. The con‐
10430 fig value html_index is gone, and html_additional_pages should be
10431 used instead. If you need it, the old index.html template is still
10432 there, called defindex.html, and you can port your html_index tem‐
10433 plate, using Jinja inheritance, by changing your template:
10434 {% extends "defindex.html" %}
10436 {% block tables %}
10437 ... old html_index template content ...
10438 {% endblock %}
10439 and putting 'index': name of your template in html_additional_pages.
10441 · In the layout template, redundant blocks were removed; you should use
10443 Jinja's standard {{ super() }} mechanism instead, as explained in the
10444 (newly written) templating docs.
10445 New features added
10447 · Extension API (Application object):
10448 · Support a new method, add_crossref_type. It works like
10450 add_description_unit but the directive will only create a target
10451 and no output.
10452 · Support a new method, add_transform. It takes a standard docutils
10454 Transform subclass which is then applied by Sphinx' reader on pars‐
10455 ing reST document trees.
10456 · Add support for other template engines than Jinja, by adding an
10458 abstraction called a "template bridge". This class handles render‐
10459 ing of templates and can be changed using the new configuration
10460 value "template_bridge".
10461 · The config file itself can be an extension (if it provides a set‐
10463 up() function).
10464 · Markup:
10466 · New directive, currentmodule. It can be used to indicate the mod‐
10468 ule name of the following documented things without creating index
10469 entries.
10470 · Allow giving a different title to documents in the toctree.
10472 · Allow giving multiple options in a cmdoption directive.
10474 · Fix display of class members without explicit class name given.
10476 · Templates (HTML output):
10478 · index.html renamed to defindex.html, see above.
10480 · There's a new config value, html_title, that controls the overall
10482 "title" of the set of Sphinx docs. It is used instead everywhere
10483 instead of "Projectname vX.Y documentation" now.
10484 · All references to "documentation" in the templates have been
10486 removed, so that it is now easier to use Sphinx for non-documenta‐
10487 tion documents with the default templates.
10488 · Templates now have an XHTML doctype, to be consistent with docu‐
10490 tils' HTML output.
10491 · You can now create an OpenSearch description file with the
10493 html_use_opensearch config value.
10494 · You can now quickly include a logo in the sidebar, using the
10496 html_logo config value.
10497 · There are new blocks in the sidebar, so that you can easily insert
10499 content into the sidebar.
10500 · LaTeX output:
10502 · The sphinx.sty package was cleaned of unused stuff.
10504 · You can include a logo in the title page with the latex_logo config
10506 value.
10507 · You can define the link colors and a border and background color
10509 for verbatim environments.
10510 Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and
10512 Sebastian Wiesner for suggestions.
10513 Bugs fixed
10515 · sphinx.ext.autodoc: Don't check __module__ for explicitly given mem‐
10516 bers. Remove "self" in class constructor argument list.
10517 · sphinx.htmlwriter: Don't use os.path for joining image HREFs.
10519 · sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values.
10521 · sphinx.latexwriter: Implement option lists. Also, some other changes
10523 were made to sphinx.sty in order to enhance compatibility and remove
10524 old unused stuff. Thanks to Gael Varoquaux for that!
10525 · sphinx.roles: Fix referencing glossary terms with explicit targets.
10527 · sphinx.environment: Don't swallow TOC entries when resolving sub‐
10529 trees.
10530 · sphinx.quickstart: Create a sensible default latex_documents setting.
10532 · sphinx.builder, sphinx.environment: Gracefully handle some user error
10534 cases.
10535 · sphinx.util: Follow symbolic links when searching for documents.
10537 Release 0.1.61950 (Mar 26, 2008)
10539 · sphinx.quickstart: Fix format string for Makefile.
10540 Release 0.1.61945 (Mar 26, 2008)
10542 · sphinx.htmlwriter, sphinx.latexwriter: Support the .. image:: direc‐
10543 tive by copying image files to the output directory.
10544 · sphinx.builder: Consistently name "special" HTML output directories
10546 with a leading underscore; this means _sources and _static.
10547 · sphinx.environment: Take dependent files into account when collecting
10549 the set of outdated sources.
10550 · sphinx.directives: Record files included with .. literalinclude:: as
10552 dependencies.
10553 · sphinx.ext.autodoc: Record files from which docstrings are included
10555 as dependencies.
10556 · sphinx.builder: Rebuild all HTML files in case of a template change.
10558 · sphinx.builder: Handle unavailability of TOC relations (previous/
10560 next chapter) more gracefully in the HTML builder.
10561 · sphinx.latexwriter: Include fncychap.sty which doesn't seem to be
10563 very common in TeX distributions. Add a clean target in the latex
10564 Makefile. Really pass the correct paper and size options to the
10565 LaTeX document class.
10566 · setup: On Python 2.4, don't egg-depend on docutils if a docutils is
10568 already installed -- else it will be overwritten.
10569 Release 0.1.61843 (Mar 24, 2008)
10571 · sphinx.quickstart: Really don't create a makefile if the user doesn't
10572 want one.
10573 · setup: Don't install scripts twice, via setuptools entry points and
10575 distutils scripts. Only install via entry points.
10576 · sphinx.builder: Don't recognize the HTML builder's copied source
10578 files (under _sources) as input files if the source suffix is .txt.
10579 · sphinx.highlighting: Generate correct markup for LaTeX Verbatim envi‐
10581 ronment escapes even if Pygments is not installed.
10582 · sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder.
10584 · sphinx.htmlwriter: Make parsed-literal blocks work as expected, not
10586 highlighting them via Pygments.
10587 · sphinx.environment: Don't error out on reading an empty source file.
10589 Release 0.1.61798 (Mar 23, 2008)
10591 · sphinx: Work with docutils SVN snapshots as well as 0.4.
10592 · sphinx.ext.doctest: Make the group in which doctest blocks are placed
10594 selectable, and default to 'default'.
10595 · sphinx.ext.doctest: Replace <BLANKLINE> in doctest blocks by real
10597 blank lines for presentation output, and remove doctest options given
10598 inline.
10599 · sphinx.environment: Move doctest_blocks out of block_quotes to sup‐
10601 port indented doctest blocks.
10602 · sphinx.ext.autodoc: Render .. automodule:: docstrings in a section
10604 node, so that module docstrings can contain proper sectioning.
10605 · sphinx.ext.autodoc: Use the module's encoding for decoding doc‐
10607 strings, rather than requiring ASCII.
10608 Release 0.1.61611 (Mar 21, 2008)
10610 · First public release.
10611
10613 This is an (incomplete) alphabetic list of projects that use Sphinx or
10614 are experimenting with using it for their documentation. If you like
10615 to be included, please mail to the Google group.
10616 I've grouped the list into sections to make it easier to find interest‐
10618 ing examples.
10619 Documentation using the default theme
10621 · APSW: http://apidoc.apsw.googlecode.com/hg/index.html
10622 · ASE: https://wiki.fysik.dtu.dk/ase/
10624 · boostmpi: http://documen.tician.de/boostmpi/
10626 · Calibre: http://calibre-ebook.com/user_manual/
10628 · CodePy: http://documen.tician.de/codepy/
10630 · Cython: http://docs.cython.org/
10632 · C\C++ Python language binding project:
10634 http://language-binding.net/index.html
10635 · Cormoran: http://cormoran.nhopkg.org/docs/
10637 · Director: http://packages.python.org/director/
10639 · Dirigible: http://www.projectdirigible.com/documentation/
10641 · Elemental:
10643 http://elemental.googlecode.com/hg/doc/build/html/index.html
10644 · F2py: http://f2py.sourceforge.net/docs/
10646 · GeoDjango: http://geodjango.org/docs/
10648 · Genomedata:
10650 http://noble.gs.washington.edu/proj/genomedata/doc/1.2.2/genomedata.html
10651 · gevent: http://www.gevent.org/
10653 · Google Wave API:
10655 http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
10656 · GSL Shell: http://www.nongnu.org/gsl-shell/
10658 · Heapkeeper: http://heapkeeper.org/
10660 · Hands-on Python Tutorial:
10662 http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
10663 · Hedge: http://documen.tician.de/hedge/
10665 · Kaa: http://doc.freevo.org/api/kaa/
10667 · Leo: http://webpages.charter.net/edreamleo/front.html
10669 · Lino: http://lino.saffre-rumma.net/
10671 · MeshPy: http://documen.tician.de/meshpy/
10673 · mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
10675 · OpenEXR: http://excamera.com/articles/26/doc/index.html
10677 · OpenGDA: http://www.opengda.org/gdadoc/html/
10679 · openWNS: http://docs.openwns.org/
10681 · Paste: http://pythonpaste.org/script/
10683 · Paver: http://paver.github.com/paver/
10685 · Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
10687 · PyCuda: http://documen.tician.de/pycuda/
10689 · Pyevolve: http://pyevolve.sourceforge.net/
10691 · Pylo: http://documen.tician.de/pylo/
10693 · PyMQI: http://packages.python.org/pymqi/
10695 · PyPubSub: http://pubsub.sourceforge.net/
10697 · pyrticle: http://documen.tician.de/pyrticle/
10699 · Python: http://docs.python.org/
10701 · python-apt: http://apt.alioth.debian.org/python-apt-doc/
10703 · PyUblas: http://documen.tician.de/pyublas/
10705 · Quex: http://quex.sourceforge.net/doc/html/main.html
10707 · Scapy: http://www.secdev.org/projects/scapy/doc/
10709 · Segway:
10711 http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
10712 · SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
10714 · SymPy: http://docs.sympy.org/
10716 · WTForms: http://wtforms.simplecodes.com/docs/
10718 · z3c: http://docs.carduner.net/z3c-tutorial/
10720 Documentation using a customized version of the default theme
10722 · Advanced Generic Widgets:
10723 http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
10724 · Bazaar: http://doc.bazaar.canonical.com/en/
10726 · Chaco: http://code.enthought.com/projects/chaco/docs/html/
10728 · Djagios: http://djagios.org/
10730 · GetFEM++: http://home.gna.org/getfem/
10732 · GPAW: https://wiki.fysik.dtu.dk/gpaw/
10734 · Grok: http://grok.zope.org/doc/current/
10736 · IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
10738 · LEPL: http://www.acooke.org/lepl/
10740 · Mayavi:
10742 http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
10743 · NOC: http://redmine.nocproject.org/projects/noc
10745 · NumPy: http://docs.scipy.org/doc/numpy/reference/
10747 · Peach^3: http://peach3.nl/doc/latest/userdoc/
10749 · PyLit: http://pylit.berlios.de/
10751 · Sage: http://sagemath.org/doc/
10753 · SciPy: http://docs.scipy.org/doc/scipy/reference/
10755 · simuPOP:
10757 http://simupop.sourceforge.net/manual_release/build/userGuide.html
10758 · Sprox: http://sprox.org/
10760 · TurboGears: http://turbogears.org/2.0/docs/
10762 · Zentyal: http://doc.zentyal.org/
10764 · Zope: http://docs.zope.org/zope2/index.html
10766 · zc.async: http://packages.python.org/zc.async/1.5.0/
10768 Documentation using the sphinxdoc theme
10770 · Fityk: http://fityk.nieto.pl/
10771 · MapServer: http://mapserver.org/
10773 · Matplotlib: http://matplotlib.sourceforge.net/
10775 · Music21: http://mit.edu/music21/doc/html/contents.html
10777 · MyHDL: http://www.myhdl.org/doc/0.6/
10779 · NetworkX: http://networkx.lanl.gov/
10781 · Pweave: http://mpastell.com/pweave/
10783 · Pyre: http://docs.danse.us/pyre/sphinx/
10785 · Pysparse: http://pysparse.sourceforge.net/
10787 · PyTango:
10789 http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
10790 · Reteisi: http://www.reteisi.org/contents.html
10792 · Satchmo: http://www.satchmoproject.com/docs/dev/
10794 · Sphinx: http://sphinx.pocoo.org/
10796 · Sqlkit: http://sqlkit.argolinux.org/
10798 · Tau:
10800 http://www.tango-controls.org/static/tau/latest/doc/html/index.html
10801 · Total Open Station: http://tops.berlios.de/
10803 · WebFaction: http://docs.webfaction.com/
10805 Documentation using another builtin theme
10807 · C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
10808 · Distribute: http://packages.python.org/distribute/ (nature)
10810 · Jinja: http://jinja.pocoo.org/ (scrolls)
10812 · jsFiddle: http://doc.jsfiddle.net/ (nature)
10814 · pip: http://pip.openplans.org/ (nature)
10816 · Programmieren mit PyGTK und Glade (German):
10818 http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
10819 · Spring Python:
10821 http://springpython.webfactional.com/current/sphinx/index.html
10822 (nature)
10823 · sqlparse:
10825 http://python-sqlparse.googlecode.com/svn/docs/api/index.html (agogo)
10826 · Sylli: http://sylli.sourceforge.net/ (nature)
10828 · libLAS: http://liblas.org/ (nature)
10830 Documentation using a custom theme/integrated in a site
10832 · Blender: http://www.blender.org/documentation/250PythonDoc/
10833 · Blinker: http://discorporate.us/projects/Blinker/docs/
10835 · Classy: classy: http://classy.pocoo.org/
10837 · Django: http://docs.djangoproject.com/
10839 · e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
10841 · Flask: http://flask.pocoo.org/docs/
10843 · Flask-OpenID: http://packages.python.org/Flask-OpenID/
10845 · Gameduino: http://excamera.com/sphinx/gameduino/
10847 · GeoServer: http://docs.geoserver.org/
10849 · Glashammer: http://glashammer.org/
10851 · MirrorBrain: http://mirrorbrain.org/docs/
10853 · nose: http://somethingaboutorange.com/mrl/projects/nose/
10855 · ObjectListView: http://objectlistview.sourceforge.net/python
10857 · Open ERP: http://doc.openerp.com/
10859 · OpenLayers: http://docs.openlayers.org/
10861 · PyEphem: http://rhodesmill.org/pyephem/
10863 · German Plone 4.0 user manual:
10865 http://www.hasecke.com/plone-benutzerhandbuch/4.0/
10866 · Pylons: http://pylonshq.com/docs/en/0.9.7/
10868 · PyMOTW: http://www.doughellmann.com/PyMOTW/
10870 · pypol: http://pypol.altervista.org/ (celery)
10872 · qooxdoo: http://manual.qooxdoo.org/current
10874 · Roundup: http://www.roundup-tracker.org/
10876 · Selenium: http://seleniumhq.org/docs/
10878 · Self: http://selflanguage.org/
10880 · Tablib: http://tablib.org/
10882 · SQLAlchemy: http://www.sqlalchemy.org/docs/
10884 · tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
10886 · tipfy: http://www.tipfy.org/docs/
10888 · Werkzeug: http://werkzeug.pocoo.org/docs/
10890 · WFront: http://discorporate.us/projects/WFront/
10892 Homepages and other non-documentation sites
10894 · Applied Mathematics at the Stellenbosch University:
10895 http://dip.sun.ac.za/
10896 · A personal page: http://www.dehlia.in/
10898 · Benoit Boissinot: http://bboissin.appspot.com/
10900 · lunarsite: http://lunaryorn.de/
10902 · Red Hot Chili Python: http://redhotchilipython.com/
10904 · The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
10906 · VOR: http://www.vor-cycling.be/
10908 Books produced using Sphinx
10910 · "The repoze.bfg Web Application Framework":
10911 http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
10912 · A Theoretical Physics Reference book: http://theoretical-physics.net/
10914 · "Simple and Steady Way of Learning for Software Engineering" (in Ja‐
10916 panese): http://www.amazon.co.jp/dp/477414259X/
10917 · "Expert Python Programming" (Japanese translation):
10919 http://www.amazon.co.jp/dp/4048686291/
10920 · "Pomodoro Technique Illustrated" (Japanese translation):
10922 http://www.amazon.co.jp/dp/4048689525/
10923 · genindex
10925 · modindex
10927 · search
10929 · glossary
10931
10933 Georg Brandl
10934
10936 2007-2011, Georg Brandl
109371.1.3 November 05, 2016 SPHINX-ALL(1)