1SPHINX-ALL(1) Sphinx SPHINX-ALL(1)
2
6 sphinx-all - Sphinx documentation generator system manual
7
9 This is the documentation for the Sphinx documentation builder. Sphinx
10 is a tool that translates a set of reStructuredText source files into
11 various output formats, automatically producing cross-references,
12 indices, etc. That is, if you have a directory containing a bunch of
13 reST-formatted documents (and possibly subdirectories of docs in there
14 as well), Sphinx can generate a nicely-organized arrangement of HTML
15 files (in some other directory) for easy browsing and navigation. But
16 from the same source, it can also generate a PDF file using LaTeX,
17 rinohtype or rst2pdf (see builders).
18 The focus is on hand-written documentation, rather than auto-generated
20 API docs. Though there is support for that kind of documentation as
21 well (which is intended to be freely mixed with hand-written content),
22 if you need pure API docs have a look at Epydoc, which also understands
23 reST.
24 For a great “introduction” to writing docs in general – the whys and
26 hows, see also Write the docs, written by Eric Holscher.
27 Conversion from other systems
29 This section is intended to collect helpful hints for those wanting to
30 migrate to reStructuredText/Sphinx from other documentation systems.
31 · Gerard Flanagan has written a script to convert pure HTML to reST; it
33 can be found at the Python Package Index.
34 · For converting the old Python docs to Sphinx, a converter was written
36 which can be found at the Python SVN repository. It contains generic
37 code to convert Python-doc-style LaTeX markup to Sphinx reST.
38 · Marcin Wojdyr has written a script to convert Docbook to reST with
40 Sphinx markup; it is at GitHub.
41 · Christophe de Vienne wrote a tool to convert from Open/LibreOffice
43 documents to Sphinx: odt2sphinx.
44 · To convert different markups, Pandoc is a very helpful tool.
46 Use with other systems
48 See the pertinent section in the FAQ list.
49 Prerequisites
51 Sphinx needs at least Python 2.7 or Python 3.4 to run, as well as the
52 docutils and Jinja2 libraries. Sphinx should work with docutils ver‐
53 sion 0.10 or some (not broken) SVN trunk snapshot. If you like to have
54 source code highlighting support, you must also install the Pygments
55 library.
56 Usage
58 See tutorial for an introduction. It also contains links to more
59 advanced sections in this manual for the topics it discusses.
60
62 This document is meant to give a tutorial-like overview of all common
63 tasks while using Sphinx.
64 The green arrows designate “more info” links leading to advanced sec‐
66 tions about the described task.
67 Install Sphinx
69 Install Sphinx, either from a distribution package or from PyPI with
70 $ pip install Sphinx
72 Setting up the documentation sources
74 The root directory of a Sphinx collection of reStructuredText document
75 sources is called the source directory. This directory also contains
76 the Sphinx configuration file conf.py, where you can configure all
77 aspects of how Sphinx reads your sources and builds your documentation.
78 [1]
79 Sphinx comes with a script called sphinx-quickstart that sets up a
81 source directory and creates a default conf.py with the most useful
82 configuration values from a few questions it asks you. Just run
83 $ sphinx-quickstart
85 and answer its questions. (Be sure to say yes to the “autodoc” exten‐
87 sion.)
88 There is also an automatic “API documentation” generator called
90 sphinx-apidoc; see /man/sphinx-apidoc for details.
91 Defining document structure
93 Let’s assume you’ve run sphinx-quickstart. It created a source direc‐
94 tory with conf.py and a master document, index.rst (if you accepted the
95 defaults). The main function of the master document is to serve as a
96 welcome page, and to contain the root of the “table of contents tree”
97 (or toctree). This is one of the main things that Sphinx adds to
98 reStructuredText, a way to connect multiple files to a single hierarchy
99 of documents.
100 reStructuredText directives
102 toctree is a reStructuredText directive, a very versatile piece of
103 markup. Directives can have arguments, options and content.
104 Arguments are given directly after the double colon following the
106 directive’s name. Each directive decides whether it can have argu‐
107 ments, and how many.
108 Options are given after the arguments, in form of a “field list”. The
110 maxdepth is such an option for the toctree directive.
111 Content follows the options or arguments after a blank line. Each
113 directive decides whether to allow content, and what to do with it.
114 A common gotcha with directives is that the first line of the content
116 must be indented to the same level as the options are.
117 The toctree directive initially is empty, and looks like this:
119 .. toctree::
121 :maxdepth: 2
122 You add documents listing them in the content of the directive:
124 .. toctree::
126 :maxdepth: 2
127 intro
129 tutorial
130 ...
131 This is exactly how the toctree for this documentation looks. The doc‐
133 uments to include are given as document names, which in short means
134 that you leave off the file name extension and use slashes as directory
135 separators.
136 [image: more info] [image]
138 Read more about the toctree directive.
139 You can now create the files you listed in the toctree and add content,
141 and their section titles will be inserted (up to the “maxdepth” level)
142 at the place where the toctree directive is placed. Also, Sphinx now
143 knows about the order and hierarchy of your documents. (They may con‐
144 tain toctree directives themselves, which means you can create deeply
145 nested hierarchies if necessary.)
146 Adding content
148 In Sphinx source files, you can use most features of standard reStruc‐
149 turedText. There are also several features added by Sphinx. For exam‐
150 ple, you can add cross-file references in a portable way (which works
151 for all output types) using the ref role.
152 For an example, if you are viewing the HTML version you can look at the
154 source for this document – use the “Show Source” link in the sidebar.
155 [image: more info] [image]
157 See rst-primer for a more in-depth introduction to reStructuredText
158 and sphinxmarkup for a full list of markup added by Sphinx.
159 Running the build
161 Now that you have added some files and content, let’s make a first
162 build of the docs. A build is started with the sphinx-build program,
163 called like this:
164 $ sphinx-build -b html sourcedir builddir
166 where sourcedir is the source directory, and builddir is the directory
168 in which you want to place the built documentation. The -b option
169 selects a builder; in this example Sphinx will build HTML files.
170 [image: more info] [image]
172 Refer to the sphinx-build man page <sphinx-build> for all options that
173 sphinx-build supports.
174 However, sphinx-quickstart script creates a Makefile and a make.bat
176 which make life even easier for you: with them you only need to run
177 $ make html
179 to build HTML docs in the build directory you chose. Execute make
181 without an argument to see which targets are available.
182 How do I generate PDF documents?
184 make latexpdf runs the LaTeX builder and readily invokes the
186 pdfTeX toolchain for you.
187 Documenting objects
189 One of Sphinx’s main objectives is easy documentation of objects (in a
190 very general sense) in any domain. A domain is a collection of object
191 types that belong together, complete with markup to create and refer‐
192 ence descriptions of these objects.
193 The most prominent domain is the Python domain. For example, to docu‐
195 ment Python’s built-in function enumerate(), you would add this to one
196 of your source files:
197 .. py:function:: enumerate(sequence[, start=0])
199 Return an iterator that yields tuples of an index and an item of the
201 *sequence*. (And so on.)
202 This is rendered like this:
204 enumerate(sequence[, start=0])
206 Return an iterator that yields tuples of an index and an item of
207 the sequence. (And so on.)
208 The argument of the directive is the signature of the object you
210 describe, the content is the documentation for it. Multiple signatures
211 can be given, each in its own line.
212 The Python domain also happens to be the default domain, so you don’t
214 need to prefix the markup with the domain name:
215 .. function:: enumerate(sequence[, start=0])
217 ...
219 does the same job if you keep the default setting for the default
221 domain.
222 There are several more directives for documenting other types of Python
224 objects, for example py:class or py:method. There is also a cross-ref‐
225 erencing role for each of these object types. This markup will create
226 a link to the documentation of enumerate():
227 The :py:func:`enumerate` function can be used for ...
229 And here is the proof: A link to enumerate().
231 Again, the py: can be left out if the Python domain is the default one.
233 It doesn’t matter which file contains the actual documentation for enu‐
234 merate(); Sphinx will find it and create a link to it.
235 Each domain will have special rules for how the signatures can look
237 like, and make the formatted output look pretty, or add specific fea‐
238 tures like links to parameter types, e.g. in the C/C++ domains.
239 [image: more info] [image]
241 See domains for all the available domains and their directives/roles.
242 Basic configuration
244 Earlier we mentioned that the conf.py file controls how Sphinx pro‐
245 cesses your documents. In that file, which is executed as a Python
246 source file, you assign configuration values. For advanced users:
247 since it is executed by Sphinx, you can do non-trivial tasks in it,
248 like extending sys.path or importing a module to find out the version
249 you are documenting.
250 The config values that you probably want to change are already put into
252 the conf.py by sphinx-quickstart and initially commented out (with
253 standard Python syntax: a # comments the rest of the line). To change
254 the default value, remove the hash sign and modify the value. To cus‐
255 tomize a config value that is not automatically added by sphinx-quick‐
256 start, just add an additional assignment.
257 Keep in mind that the file uses Python syntax for strings, numbers,
259 lists and so on. The file is saved in UTF-8 by default, as indicated
260 by the encoding declaration in the first line. If you use non-ASCII
261 characters in any string value, you need to use Python Unicode strings
262 (like project = u'Exposé').
263 [image: more info] [image]
265 See build-config for documentation of all available config values.
266 Autodoc
268 When documenting Python code, it is common to put a lot of documenta‐
269 tion in the source files, in documentation strings. Sphinx supports
270 the inclusion of docstrings from your modules with an extension (an
271 extension is a Python module that provides additional features for
272 Sphinx projects) called “autodoc”.
273 In order to use autodoc, you need to activate it in conf.py by putting
275 the string 'sphinx.ext.autodoc' into the list assigned to the exten‐
276 sions config value. Then, you have a few additional directives at your
277 disposal.
278 For example, to document the function io.open(), reading its signature
280 and docstring from the source file, you’d write this:
281 .. autofunction:: io.open
283 You can also document whole classes or even modules automatically,
285 using member options for the auto directives, like
286 .. automodule:: io
288 :members:
289 autodoc needs to import your modules in order to extract the doc‐
291 strings. Therefore, you must add the appropriate path to sys.path in
292 your conf.py.
293 WARNING:
295 autodoc imports the modules to be documented. If any modules have
296 side effects on import, these will be executed by autodoc when
297 sphinx-build is run.
298 If you document scripts (as opposed to library modules), make sure
300 their main routine is protected by a if __name__ == '__main__' con‐
301 dition.
302 [image: more info] [image]
304 See sphinx.ext.autodoc for the complete description of the features of
305 autodoc.
306 Intersphinx
308 Many Sphinx documents including the Python documentation are published
309 on the internet. When you want to make links to such documents from
310 your documentation, you can do it with sphinx.ext.intersphinx.
311 In order to use intersphinx, you need to activate it in conf.py by
313 putting the string 'sphinx.ext.intersphinx' into the extensions list
314 and set up the intersphinx_mapping config value.
315 For example, to link to io.open() in the Python library manual, you
317 need to setup your intersphinx_mapping like:
318 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
320 And now, you can write a cross-reference like :py:func:`io.open`. Any
322 cross-reference that has no matching target in the current documenta‐
323 tion set, will be looked up in the documentation sets configured in
324 intersphinx_mapping (this needs access to the URL in order to download
325 the list of valid targets). Intersphinx also works for some other
326 domains’ roles including :ref:, however it doesn’t work for :doc: as
327 that is non-domain role.
328 [image: more info] [image]
330 See sphinx.ext.intersphinx for the complete description of the fea‐
331 tures of intersphinx.
332 More topics to be covered
334 · Other extensions:
335 · ext/math,
337 · ext/viewcode,
339 · ext/doctest,
341 · …
343 · Static files
345 · Selecting a theme
347 · setuptools
349 · Templating
351 · Using extensions
353 · Writing extensions
355
357 [1] This is the usual layout. However, conf.py can also live in
358 another directory, the configuration directory. Refer to the
359 sphinx-build man page <sphinx-build> for more information.
360
362 These are the applications provided as part of Sphinx.
363 Core Applications
365 sphinx-quickstart
366 Synopsis
367 sphinx-quickstart
368 Description
370 sphinx-quickstart is an interactive tool that asks some questions about
371 your project and then generates a complete documentation directory and
372 sample Makefile to be used with sphinx-build(1).
373 Options
375 -q, --quiet
376 Quiet mode that will skips interactive wizard to specify
377 options. This option requires -p, -a and -v options.
378 -h, --help, --version
380 Display usage summary or Sphinx version.
381 Structure Options.INDENT 0.0
382 --sep If specified, separate source and build directories.
384 --dot=DOT
386 Inside the root directory, two more directories will be created;
387 “_templates” for custom HTML templates and “_static” for custom
388 stylesheets and other static files. You can enter another prefix
389 (such as “.”) to replace the underscore.
390 Project Basic Options.INDENT 0.0
391 -p PROJECT, --project=PROJECT
393 Project name will be set. (see project).
394 -a AUTHOR, --author=AUTHOR
396 Author names. (see copyright).
397 -v VERSION
399 Version of project. (see version).
400 -r RELEASE, --release=RELEASE
402 Release of project. (see release).
403 -l LANGUAGE, --language=LANGUAGE
405 Document language. (see language).
406 --suffix=SUFFIX
408 Source file suffix. (see source_suffix).
409 --master=MASTER
411 Master document name. (see master_doc).
412 --epub Use epub.
414 Extension Options.INDENT 0.0
415 --ext-autodoc
417 Enable sphinx.ext.autodoc extension.
418 --ext-doctest
420 Enable sphinx.ext.doctest extension.
421 --ext-intersphinx
423 Enable sphinx.ext.intersphinx extension.
424 --ext-todo
426 Enable sphinx.ext.todo extension.
427 --ext-coverage
429 Enable sphinx.ext.coverage extension.
430 --ext-imgmath
432 Enable sphinx.ext.imgmath extension.
433 --ext-mathjax
435 Enable sphinx.ext.mathjax extension.
436 --ext-ifconfig
438 Enable sphinx.ext.ifconfig extension.
439 --ext-viewcode
441 Enable sphinx.ext.viewcode extension.
442 --extensions=EXTENSIONS
444 Enable arbitary extensions.
445 Makefile and Batchfile Creation Options.INDENT 0.0
446 --use-make-mode, --no-use-make-mode
448 Makefile/make.bat uses (or doesn’t use) make-mode. Default is
449 use, which generates a more concise Makefile/make.bat.
450 Changed in version 1.5: make-mode is default.
452 --makefile, --no-makefile
455 Create (or not create) makefile.
456 --batchfile, --no-batchfile
458 Create (or not create) batchfile
459 Project templating
460 New in version 1.5: Project templating options for sphinx-quickstart
462 -t, --templatedir=TEMPLATEDIR
465 Template directory for template files. You can modify the tem‐
466 plates of sphinx project files generated by quickstart. Follow‐
467 ing Jinja2 template files are allowed:
468 · master_doc.rst_t
470 · conf.py_t
472 · Makefile_t
474 · Makefile.new_t
476 · make.bat_t
478 · make.bat.new_t
480 In detail, please refer the system template files Sphinx pro‐
482 vides. (sphinx/templates/quickstart)
483 -d NAME=VALUE
485 Define a template variable
486 See also
488 sphinx-build(1)
489 sphinx-build
491 Synopsis
492 sphinx-build [options] <sourcedir> <outputdir> [filenames …]
493 Description
495 sphinx-build generates documentation from the files in <sourcedir> and
496 places it in the <outputdir>.
497 sphinx-build looks for <sourcedir>/conf.py for the configuration set‐
499 tings. sphinx-quickstart(1) may be used to generate template files,
500 including conf.py.
501 sphinx-build can create documentation in different formats. A format
503 is selected by specifying the builder name on the command line; it
504 defaults to HTML. Builders can also perform other tasks related to
505 documentation processing.
506 By default, everything that is outdated is built. Output only for
508 selected files can be built by specifying individual filenames.
509 For a list of available options, refer to sphinx-build -b.
511 Options
513 -b buildername
514 The most important option: it selects a builder. The most com‐
515 mon builders are:
516 html Build HTML pages. This is the default builder.
518 dirhtml
520 Build HTML pages, but with a single directory per docu‐
521 ment. Makes for prettier URLs (no .html) if served from
522 a webserver.
523 singlehtml
525 Build a single HTML with the whole content.
526 htmlhelp, qthelp, devhelp, epub
528 Build HTML files with additional information for building
529 a documentation collection in one of these formats.
530 applehelp
532 Build an Apple Help Book. Requires hiutil and codesign,
533 which are not Open Source and presently only available on
534 Mac OS X 10.6 and higher.
535 latex Build LaTeX sources that can be compiled to a PDF docu‐
537 ment using pdflatex.
538 man Build manual pages in groff format for UNIX systems.
540 texinfo
542 Build Texinfo files that can be processed into Info files
543 using makeinfo.
544 text Build plain text files.
546 gettext
548 Build gettext-style message catalogs (.pot files).
549 doctest
551 Run all doctests in the documentation, if the doctest
552 extension is enabled.
553 linkcheck
555 Check the integrity of all external links.
556 xml Build Docutils-native XML files.
558 pseudoxml
560 Build compact pretty-printed “pseudo-XML” files display‐
561 ing the internal structure of the intermediate document
562 trees.
563 See builders for a list of all builders shipped with Sphinx.
565 Extensions can add their own builders.
566 -M buildername
568 Alternative to -b. Uses the Sphinx make_mode module, which pro‐
569 vides the same build functionality as a default Makefile or
570 Make.bat. In addition to all Sphinx builders, the following
571 build pipelines are available:
572 latexpdf
574 Build LaTeX files and run them through pdflatex, or as
575 per latex_engine setting. If language is set to 'ja',
576 will use automatically the platex/dvipdfmx latex to PDF
577 pipeline.
578 info Build Texinfo files and run them through makeinfo.
580 IMPORTANT:
582 Sphinx only recognizes the -M option if it is placed first.
583 New in version 1.2.1.
585 -a If given, always write all output files. The default is to only
588 write output files for new and changed source files. (This may
589 not apply to all builders.)
590 -E Don’t use a saved environment (the structure caching all
592 cross-references), but rebuild it completely. The default is to
593 only read and parse source files that are new or have changed
594 since the last run.
595 -t tag Define the tag tag. This is relevant for only directives that
597 only include their content if this tag is set.
598 New in version 0.6.
600 -d path
603 Since Sphinx has to read and parse all source files before it
604 can write an output file, the parsed source files are cached as
605 “doctree pickles”. Normally, these files are put in a directory
606 called .doctrees under the build directory; with this option you
607 can select a different cache directory (the doctrees can be
608 shared between all builders).
609 -j N Distribute the build over N processes in parallel, to make
611 building on multiprocessor machines more effective. Note that
612 not all parts and not all builders of Sphinx can be paral‐
613 lelized. If auto argument is given, Sphinx uses the number of
614 CPUs as N.
615 New in version 1.2: This option should be considered experimen‐
617 tal.
618 Changed in version 1.7: Support auto argument.
621 -c path
624 Don’t look for the conf.py in the source directory, but use the
625 given configuration directory instead. Note that various other
626 files and paths given by configuration values are expected to be
627 relative to the configuration directory, so they will have to be
628 present at this location too.
629 New in version 0.3.
631 -C Don’t look for a configuration file; only take options via the
634 -D option.
635 New in version 0.5.
637 -D setting=value
640 Override a configuration value set in the conf.py file. The
641 value must be a number, string, list or dictionary value.
642 For lists, you can separate elements with a comma like this: -D
644 html_theme_path=path1,path2.
645 For dictionary values, supply the setting name and key like
647 this: -D latex_elements.docclass=scrartcl.
648 For boolean values, use 0 or 1 as the value.
650 Changed in version 0.6: The value can now be a dictionary value.
652 Changed in version 1.3: The value can now also be a list value.
655 -A name=value
658 Make the name assigned to value in the HTML templates.
659 New in version 0.5.
661 -n Run in nit-picky mode. Currently, this generates warnings for
664 all missing references. See the config value nitpick_ignore for
665 a way to exclude some references as “known missing”.
666 -N Do not emit colored output.
668 -v Increase verbosity (loglevel). This option can be given up to
670 three times to get more debug logging output. It implies -T.
671 New in version 1.2.
673 -q Do not output anything on standard output, only write warnings
676 and errors to standard error.
677 -Q Do not output anything on standard output, also suppress warn‐
679 ings. Only errors are written to standard error.
680 -w file
682 Write warnings (and errors) to the given file, in addition to
683 standard error.
684 -W Turn warnings into errors. This means that the build stops at
686 the first warning and sphinx-build exits with exit status 1.
687 -T Display the full traceback when an unhandled exception occurs.
689 Otherwise, only a summary is displayed and the traceback infor‐
690 mation is saved to a file for further analysis.
691 New in version 1.2.
693 -P (Useful for debugging only.) Run the Python debugger, pdb, if
696 an unhandled exception occurs while building.
697 -h, --help, --version
699 Display usage summary or Sphinx version.
700 New in version 1.2.
702 You can also give one or more filenames on the command line after the
705 source and build directories. Sphinx will then try to build only these
706 output files (and their dependencies).
707 Environment Variables
709 The sphinx-build refers following environment variables:
710 MAKE A path to make command. A command name is also allowed.
712 sphinx-build uses it to invoke sub-build process on make-mode.
713 Makefile Options
714 The Makefile and make.bat files created by sphinx-quickstart usually
716 run sphinx-build only with the -b and -d options. However, they sup‐
717 port the following variables to customize behavior:
718 PAPER The value for ‘“papersize”` key of latex_elements.
720 SPHINXBUILD
722 The command to use instead of sphinx-build.
723 BUILDDIR
725 The build directory to use instead of the one chosen in
726 sphinx-quickstart.
727 SPHINXOPTS
729 Additional options for sphinx-build.
730 Deprecation Warnings
732 If any deprecation warning like RemovedInSphinxXXXWarning are displayed
733 when building a user’s document, some Sphinx extension is using depre‐
734 cated features. In that case, please report it to author of the exten‐
735 sion.
736 To disable the deprecation warnings, please set PYTHONWARNINGS= envi‐
738 ronment variable to your environment. For example:
739 · PYTHONWARNINGS= make html (Linux/Mac)
741 · export PYTHONWARNINGS= and do make html (Linux/Mac)
743 · set PYTHONWARNINGS= and do make html (Windows)
745 · modify your Makefile/make.bat and set the environment variable
747 See also
749 sphinx-quickstart(1)
750 Additional Applications
752 sphinx-apidoc
753 Synopsis
754 sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames …]
755 Description
757 sphinx-apidoc is a tool for automatic generation of Sphinx sources
758 that, using the autodoc extension, document a whole package in the
759 style of other automatic API documentation tools.
760 sourcedir is the path to a Python package to document, and outputdir is
762 the directory where the generated sources are placed. Any pathnames
763 given are paths to be excluded from the generation.
764 WARNING:
766 sphinx-apidoc generates source files that use sphinx.ext.autodoc to
767 document all found modules. If any modules have side effects on
768 import, these will be executed by autodoc when sphinx-build is run.
769 If you document scripts (as opposed to library modules), make sure
771 their main routine is protected by a if __name__ == '__main__' con‐
772 dition.
773 Options
775 -o <outputdir>
776 Directory to place the output files. If it does not exist, it is
777 created.
778 -f, --force
780 Force overwritting of any existing generated files.
781 -l, --follow-links
783 Follow symbolic links.
784 -n, --dry-run
786 Do not create any files.
787 -s <suffix>
789 Suffix for the source files generated. Defaults to rst.
790 -d <maxdepth>
792 Maximum depth for the generated table of contents file.
793 -T, --no-toc
795 Do not create a table of contents file. Ignored when --full is
796 provided.
797 -F, --full
799 Generate a full Sphinx project (conf.py, Makefile etc.) using
800 the same mechanism as sphinx-quickstart.
801 -e, --separate
803 Put documentation for each module on its own page.
804 New in version 1.2.
806 -E, --no-headings
809 Do not create headings for the modules/packages. This is useful,
810 for example, when docstrings already contain headings.
811 -P, --private
813 Include “_private” modules.
814 New in version 1.2.
816 --implicit-namespaces
819 By default sphinx-apidoc processes sys.path searching for mod‐
820 ules only. Python 3.3 introduced PEP 420 implicit namespaces
821 that allow module path structures such as foo/bar/module.py or
822 foo/bar/baz/__init__.py (notice that bar and foo are namespaces,
823 not modules).
824 Interpret paths recursively according to PEP-0420.
826 -M, --module-first
828 Put module documentation before submodule documentation.
829 These options are used when --full is specified:
831 -a Append module_path to sys.path.
833 -H <project>
835 Sets the project name to put in generated files (see project).
836 -A <author>
838 Sets the author name(s) to put in generated files (see copy‐
839 right).
840 -V <version>
842 Sets the project version to put in generated files (see ver‐
843 sion).
844 -R <release>
846 Sets the project release to put in generated files (see
847 release).
848 Environment
850 SPHINX_APIDOC_OPTIONS
851 A comma-separated list of option to append to generated automod‐
852 ule directives. Defaults to members,undoc-members,show-inheri‐
853 tance.
854 See also
856 sphinx-build(1), sphinx-autogen(1)
857 sphinx-autogen
859 Synopsis
860 sphinx-autogen [options] <sourcefile> …
861 Description
863 sphinx-autogen is a tool for automatic generation of Sphinx sources
864 that, using the autodoc extension, document items included in autosum‐
865 mary listing(s).
866 sourcefile is the path to one or more reStructuredText documents con‐
868 taining autosummary entries with the :toctree:: option set. sourcefile
869 can be an fnmatch-style pattern.
870 Options
872 -o <outputdir>
873 Directory to place the output file. If it does not exist, it is
874 created. Defaults to the value passed to the :toctree: option.
875 -s <suffix>, --suffix <suffix>
877 Default suffix to use for generated files. Defaults to rst.
878 -t <templates>, --templates <templates>
880 Custom template directory. Defaults to None.
881 -i, --imported-members
883 Document imported members.
884 Example
886 Given the following directory structure:
887 docs
889 ├── index.rst
890 └── ...
891 foobar
892 ├── foo
893 │ └── __init__.py
894 └── bar
895 ├── __init__.py
896 └── baz
897 └── __init__.py
898 and assuming docs/index.rst contained the following:
900 Modules
902 =======
903 .. autosummary::
905 :toctree: modules
906 foobar.foo
908 foobar.bar
909 foobar.bar.baz
910 If you run the following:
912 $ PYTHONPATH=. sphinx-autodoc doc/index.rst
914 then the following stub files will be created in docs:
916 docs
918 ├── index.rst
919 └── modules
920 ├── foobar.bar.rst
921 ├── foobar.bar.baz.rst
922 └── foobar.foo.rst
923 and each of those files will contain a autodoc directive and some other
925 information.
926 See also
928 sphinx-build(1), sphinx-apidoc(1)
929
931 This section is a brief introduction to reStructuredText (reST) con‐
932 cepts and syntax, intended to provide authors with enough information
933 to author documents productively. Since reST was designed to be a sim‐
934 ple, unobtrusive markup language, this will not take too long.
935 SEE ALSO:
937 The authoritative reStructuredText User Documentation. The “ref”
938 links in this document link to the description of the individual
939 constructs in the reST reference.
940 Paragraphs
942 The paragraph (ref) is the most basic block in a reST document. Para‐
943 graphs are simply chunks of text separated by one or more blank lines.
944 As in Python, indentation is significant in reST, so all lines of the
945 same paragraph must be left-aligned to the same level of indentation.
946 Inline markup
948 The standard reST inline markup is quite simple: use
949 · one asterisk: *text* for emphasis (italics),
951 · two asterisks: **text** for strong emphasis (boldface), and
953 · backquotes: ``text`` for code samples.
955 If asterisks or backquotes appear in running text and could be confused
957 with inline markup delimiters, they have to be escaped with a back‐
958 slash.
959 Be aware of some restrictions of this markup:
961 · it may not be nested,
963 · content may not start or end with whitespace: * text* is wrong,
965 · it must be separated from surrounding text by non-word characters.
967 Use a backslash escaped space to work around that: thisis\ *one*\
968 word.
969 These restrictions may be lifted in future versions of the docutils.
971 reST also allows for custom “interpreted text roles”, which signify
973 that the enclosed text should be interpreted in a specific way. Sphinx
974 uses this to provide semantic markup and cross-referencing of identi‐
975 fiers, as described in the appropriate section. The general syntax is
976 :rolename:`content`.
977 Standard reST provides the following roles:
979 · emphasis – alternate spelling for *emphasis*
981 · strong – alternate spelling for **strong**
983 · literal – alternate spelling for ``literal``
985 · subscript – subscript text
987 · superscript – superscript text
989 · title-reference – for titles of books, periodicals, and other materi‐
991 als
992 See inline-markup for roles added by Sphinx.
994 Lists and Quote-like blocks
996 List markup (ref) is natural: just place an asterisk at the start of a
997 paragraph and indent properly. The same goes for numbered lists; they
998 can also be autonumbered using a # sign:
999 * This is a bulleted list.
1001 * It has two items, the second
1002 item uses two lines.
1003 1. This is a numbered list.
1005 2. It has two items too.
1006 #. This is a numbered list.
1008 #. It has two items too.
1009 Nested lists are possible, but be aware that they must be separated
1011 from the parent list items by blank lines:
1012 * this is
1014 * a list
1015 * with a nested list
1017 * and some subitems
1018 * and here the parent list continues
1020 Definition lists (ref) are created as follows:
1022 term (up to a line of text)
1024 Definition of the term, which must be indented
1025 and can even consist of multiple paragraphs
1027 next term
1029 Description.
1030 Note that the term cannot have more than one line of text.
1032 Quoted paragraphs (ref) are created by just indenting them more than
1034 the surrounding paragraphs.
1035 Line blocks (ref) are a way of preserving line breaks:
1037 | These lines are
1039 | broken exactly like in
1040 | the source file.
1041 There are also several more special blocks available:
1043 · field lists (ref)
1045 · option lists (ref)
1047 · quoted literal blocks (ref)
1049 · doctest blocks (ref)
1051 Source Code
1053 Literal code blocks (ref) are introduced by ending a paragraph with the
1054 special marker ::. The literal block must be indented (and, like all
1055 paragraphs, separated from the surrounding ones by blank lines):
1056 This is a normal text paragraph. The next paragraph is a code sample::
1058 It is not processed in any way, except
1060 that the indentation is removed.
1061 It can span multiple lines.
1063 This is a normal text paragraph again.
1065 The handling of the :: marker is smart:
1067 · If it occurs as a paragraph of its own, that paragraph is completely
1069 left out of the document.
1070 · If it is preceded by whitespace, the marker is removed.
1072 · If it is preceded by non-whitespace, the marker is replaced by a sin‐
1074 gle colon.
1075 That way, the second sentence in the above example’s first paragraph
1077 would be rendered as “The next paragraph is a code sample:”.
1078 Tables
1080 For grid tables (ref), you have to “paint” the cell grid yourself.
1081 They look like this:
1082 +------------------------+------------+----------+----------+
1084 | Header row, column 1 | Header 2 | Header 3 | Header 4 |
1085 | (header rows optional) | | | |
1086 +========================+============+==========+==========+
1087 | body row 1, column 1 | column 2 | column 3 | column 4 |
1088 +------------------------+------------+----------+----------+
1089 | body row 2 | ... | ... | |
1090 +------------------------+------------+----------+----------+
1091 Simple tables (ref) are easier to write, but limited: they must contain
1093 more than one row, and the first column cells cannot contain multiple
1094 lines. They look like this:
1095 ===== ===== =======
1097 A B A and B
1098 ===== ===== =======
1099 False False False
1100 True False False
1101 False True False
1102 True True True
1103 ===== ===== =======
1104 Two more syntaxes are supported: CSV tables and List tables. They use
1106 an explicit markup block, see Directives section.
1107 Hyperlinks
1109 External links
1110 Use `Link text <http://example.com/>`_ for inline web links. If the
1111 link text should be the web address, you don’t need special markup at
1112 all, the parser finds links and mail addresses in ordinary text.
1113 IMPORTANT:
1115 There must be a space between the link text and the opening < for
1116 the URL.
1117 You can also separate the link and the target definition (ref), like
1119 this:
1120 This is a paragraph that contains `a link`_.
1122 .. _a link: http://example.com/
1124 Internal links
1126 Internal linking is done via a special reST role provided by Sphinx,
1127 see the section on specific markup, ref-role.
1128 Sections
1130 Section headers (ref) are created by underlining (and optionally over‐
1131 lining) the section title with a punctuation character, at least as
1132 long as the text:
1133 =================
1135 This is a heading
1136 =================
1137 Normally, there are no heading levels assigned to certain characters as
1139 the structure is determined from the succession of headings. However,
1140 this convention is used in Python’s Style Guide for documenting which
1141 you may follow:
1142 · # with overline, for parts
1144 · * with overline, for chapters
1146 · =, for sections
1148 · -, for subsections
1150 · ^, for subsubsections
1152 · ", for paragraphs
1154 Of course, you are free to use your own marker characters (see the reST
1156 documentation), and use a deeper nesting level, but keep in mind that
1157 most target formats (HTML, LaTeX) have a limited supported nesting
1158 depth.
1159 Explicit Markup
1161 “Explicit markup” (ref) is used in reST for most constructs that need
1162 special handling, such as footnotes, specially-highlighted paragraphs,
1163 comments, and generic directives.
1164 An explicit markup block begins with a line starting with .. followed
1166 by whitespace and is terminated by the next paragraph at the same level
1167 of indentation. (There needs to be a blank line between explicit
1168 markup and normal paragraphs. This may all sound a bit complicated,
1169 but it is intuitive enough when you write it.)
1170 Directives
1172 A directive (ref) is a generic block of explicit markup. Besides
1173 roles, it is one of the extension mechanisms of reST, and Sphinx makes
1174 heavy use of it.
1175 Docutils supports the following directives:
1177 · Admonitions: attention, caution, danger, error, hint, important,
1179 note, tip, warning and the generic admonition. (Most themes style
1180 only “note” and “warning” specially.)
1181 · Images:
1183 · image (see also Images below)
1185 · figure (an image with caption and optional legend)
1187 · Additional body elements:
1189 · contents (a local, i.e. for the current file only, table of con‐
1191 tents)
1192 · container (a container with a custom class, useful to generate an
1194 outer <div> in HTML)
1195 · rubric (a heading without relation to the document sectioning)
1197 · topic, sidebar (special highlighted body elements)
1199 · parsed-literal (literal block that supports inline markup)
1201 · epigraph (a block quote with optional attribution line)
1203 · highlights, pull-quote (block quotes with their own class
1205 attribute)
1206 · compound (a compound paragraph)
1208 · Special tables:
1210 · table (a table with title)
1212 · csv-table (a table generated from comma-separated values)
1214 · list-table (a table generated from a list of lists)
1216 · Special directives:
1218 · raw (include raw target-format markup)
1220 · include (include reStructuredText from another file) – in Sphinx,
1222 when given an absolute include file path, this directive takes it
1223 as relative to the source directory
1224 · class (assign a class attribute to the next element) [1]
1226 · HTML specifics:
1228 · meta (generation of HTML <meta> tags)
1230 · title (override document title)
1232 · Influencing markup:
1234 · default-role (set a new default role)
1236 · role (create a new role)
1238 Since these are only per-file, better use Sphinx’s facilities for
1240 setting the default_role.
1241 Do not use the directives sectnum, header and footer.
1243 Directives added by Sphinx are described in sphinxmarkup.
1245 Basically, a directive consists of a name, arguments, options and con‐
1247 tent. (Keep this terminology in mind, it is used in the next chapter
1248 describing custom directives.) Looking at this example,
1249 .. function:: foo(x)
1251 foo(y, z)
1252 :module: some.module.name
1253 Return a line of text input from the user.
1255 function is the directive name. It is given two arguments here, the
1257 remainder of the first line and the second line, as well as one option
1258 module (as you can see, options are given in the lines immediately fol‐
1259 lowing the arguments and indicated by the colons). Options must be
1260 indented to the same level as the directive content.
1261 The directive content follows after a blank line and is indented rela‐
1263 tive to the directive start.
1264 Images
1266 reST supports an image directive (ref), used like so:
1267 .. image:: gnu.png
1269 (options)
1270 When used within Sphinx, the file name given (here gnu.png) must either
1272 be relative to the source file, or absolute which means that they are
1273 relative to the top source directory. For example, the file
1274 sketch/spam.rst could refer to the image images/spam.png as
1275 ../images/spam.png or /images/spam.png.
1276 Sphinx will automatically copy image files over to a subdirectory of
1278 the output directory on building (e.g. the _static directory for HTML
1279 output.)
1280 Interpretation of image size options (width and height) is as follows:
1282 if the size has no unit or the unit is pixels, the given size will only
1283 be respected for output channels that support pixels. Other units (like
1284 pt for points) will be used for HTML and LaTeX output (the latter
1285 replaces pt by bp as this is the TeX unit such that 72bp=1in).
1286 Sphinx extends the standard docutils behavior by allowing an asterisk
1288 for the extension:
1289 .. image:: gnu.*
1291 Sphinx then searches for all images matching the provided pattern and
1293 determines their type. Each builder then chooses the best image out of
1294 these candidates. For instance, if the file name gnu.* was given and
1295 two files gnu.pdf and gnu.png existed in the source tree, the LaTeX
1296 builder would choose the former, while the HTML builder would prefer
1297 the latter. Supported image types and choosing priority are defined at
1298 builders.
1299 Note that image file names should not contain spaces.
1301 Changed in version 0.4: Added the support for file names ending in an
1303 asterisk.
1304 Changed in version 0.6: Image paths can now be absolute.
1307 Changed in version 1.5: latex target supports pixels (default is
1310 96px=1in).
1311 Footnotes
1314 For footnotes (ref), use [#name]_ to mark the footnote location, and
1315 add the footnote body at the bottom of the document after a “Footnotes”
1316 rubric heading, like so:
1317 Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
1319 .. rubric:: Footnotes
1321 .. [#f1] Text of the first footnote.
1323 .. [#f2] Text of the second footnote.
1324 You can also explicitly number the footnotes ([1]_) or use auto-num‐
1326 bered footnotes without names ([#]_).
1327 Citations
1329 Standard reST citations (ref) are supported, with the additional fea‐
1330 ture that they are “global”, i.e. all citations can be referenced from
1331 all files. Use them like so:
1332 Lorem ipsum [Ref]_ dolor sit amet.
1334 .. [Ref] Book or article reference, URL or whatever.
1336 Citation usage is similar to footnote usage, but with a label that is
1338 not numeric or begins with #.
1339 Substitutions
1341 reST supports “substitutions” (ref), which are pieces of text and/or
1342 markup referred to in the text by |name|. They are defined like foot‐
1343 notes with explicit markup blocks, like this:
1344 .. |name| replace:: replacement *text*
1346 or this:
1348 .. |caution| image:: warning.png
1350 :alt: Warning!
1351 See the reST reference for substitutions for details.
1353 If you want to use some substitutions for all documents, put them into
1355 rst_prolog or put them into a separate file and include it into all
1356 documents you want to use them in, using the include directive. (Be
1357 sure to give the include file a file name extension differing from that
1358 of other source files, to avoid Sphinx finding it as a standalone docu‐
1359 ment.)
1360 Sphinx defines some default substitutions, see default-substitutions.
1362 Comments
1364 Every explicit markup block which isn’t a valid markup construct (like
1365 the footnotes above) is regarded as a comment (ref). For example:
1366 .. This is a comment.
1368 You can indent text after a comment start to form multiline comments:
1370 ..
1372 This whole indented block
1373 is a comment.
1374 Still in the comment.
1376 Source encoding
1378 Since the easiest way to include special characters like em dashes or
1379 copyright signs in reST is to directly write them as Unicode charac‐
1380 ters, one has to specify an encoding. Sphinx assumes source files to
1381 be encoded in UTF-8 by default; you can change this with the
1382 source_encoding config value.
1383 Gotchas
1385 There are some problems one commonly runs into while authoring reST
1386 documents:
1387 · Separation of inline markup: As said above, inline markup spans must
1389 be separated from the surrounding text by non-word characters, you
1390 have to use a backslash-escaped space to get around that. See the
1391 reference for the details.
1392 · No nested inline markup: Something like *see :func:`foo`* is not pos‐
1394 sible.
1395
1397 [1] When the default domain contains a class directive, this directive
1398 will be shadowed. Therefore, Sphinx re-exports it as rst-class.
1399
1401 Sphinx adds a lot of new directives and interpreted text roles to
1402 standard reST markup. This section contains the reference material for
1403 these facilities.
1404 The TOC tree
1406 Since reST does not have facilities to interconnect several documents,
1407 or split documents into multiple output files, Sphinx uses a custom
1408 directive to add relations between the single files the documentation
1409 is made of, as well as tables of contents. The toctree directive is
1410 the central element.
1411 NOTE:
1413 Simple “inclusion” of one file in another can be done with the
1414 include directive.
1415 .. toctree::
1417 This directive inserts a “TOC tree” at the current location,
1418 using the individual TOCs (including “sub-TOC trees”) of the
1419 documents given in the directive body. Relative document names
1420 (not beginning with a slash) are relative to the document the
1421 directive occurs in, absolute names are relative to the source
1422 directory. A numeric maxdepth option may be given to indicate
1423 the depth of the tree; by default, all levels are included. [1]
1424 Consider this example (taken from the Python docs’ library ref‐
1426 erence index):
1427 .. toctree::
1429 :maxdepth: 2
1430 intro
1432 strings
1433 datatypes
1434 numeric
1435 (many more documents listed here)
1436 This accomplishes two things:
1438 · Tables of contents from all those documents are inserted, with
1440 a maximum depth of two, that means one nested heading. toc‐
1441 tree directives in those documents are also taken into
1442 account.
1443 · Sphinx knows the relative order of the documents intro,
1445 strings and so forth, and it knows that they are children of
1446 the shown document, the library index. From this information
1447 it generates “next chapter”, “previous chapter” and “parent
1448 chapter” links.
1449 Entries
1451 Document titles in the toctree will be automatically read from
1453 the title of the referenced document. If that isn’t what you
1454 want, you can specify an explicit title and target using a simi‐
1455 lar syntax to reST hyperlinks (and Sphinx’s cross-referencing
1456 syntax). This looks like:
1457 .. toctree::
1459 intro
1461 All about strings <strings>
1462 datatypes
1463 The second line above will link to the strings document, but
1465 will use the title “All about strings” instead of the title of
1466 the strings document.
1467 You can also add external links, by giving an HTTP URL instead
1469 of a document name.
1470 Section numbering
1472 If you want to have section numbers even in HTML output, give
1474 the toplevel toctree a numbered option. For example:
1475 .. toctree::
1477 :numbered:
1478 foo
1480 bar
1481 Numbering then starts at the heading of foo. Sub-toctrees are
1483 automatically numbered (don’t give the numbered flag to those).
1484 Numbering up to a specific depth is also possible, by giving the
1486 depth as a numeric argument to numbered.
1487 Additional options
1489 You can use caption option to provide a toctree caption and you
1491 can use name option to provide implicit target name that can be
1492 referenced by using ref:
1493 .. toctree::
1495 :caption: Table of Contents
1496 :name: mastertoc
1497 foo
1499 If you want only the titles of documents in the tree to show up,
1501 not other headings of the same level, you can use the titlesonly
1502 option:
1503 .. toctree::
1505 :titlesonly:
1506 foo
1508 bar
1509 You can use “globbing” in toctree directives, by giving the glob
1511 flag option. All entries are then matched against the list of
1512 available documents, and matches are inserted into the list
1513 alphabetically. Example:
1514 .. toctree::
1516 :glob:
1517 intro*
1519 recipe/*
1520 *
1521 This includes first all documents whose names start with intro,
1523 then all documents in the recipe folder, then all remaining doc‐
1524 uments (except the one containing the directive, of course.) [2]
1525 The special entry name self stands for the document containing
1527 the toctree directive. This is useful if you want to generate a
1528 “sitemap” from the toctree.
1529 You can use the reversed flag option to reverse the order of the
1531 entries in the list. This can be useful when using the glob flag
1532 option to reverse the ordering of the files. Example:
1533 .. toctree::
1535 :glob:
1536 :reversed:
1537 recipe/*
1539 You can also give a “hidden” option to the directive, like this:
1541 .. toctree::
1543 :hidden:
1544 doc_1
1546 doc_2
1547 This will still notify Sphinx of the document hierarchy, but not
1549 insert links into the document at the location of the directive
1550 – this makes sense if you intend to insert these links yourself,
1551 in a different style, or in the HTML sidebar.
1552 In cases where you want to have only one top-level toctree and
1554 hide all other lower level toctrees you can add the “includehid‐
1555 den” option to the top-level toctree entry:
1556 .. toctree::
1558 :includehidden:
1559 doc_1
1561 doc_2
1562 All other toctree entries can then be eliminated by the “hidden”
1564 option.
1565 In the end, all documents in the source directory (or subdirec‐
1567 tories) must occur in some toctree directive; Sphinx will emit a
1568 warning if it finds a file that is not included, because that
1569 means that this file will not be reachable through standard nav‐
1570 igation.
1571 Use exclude_patterns to explicitly exclude documents or directo‐
1573 ries from building completely. Use the “orphan” metadata to let
1574 a document be built, but notify Sphinx that it is not reachable
1575 via a toctree.
1576 The “master document” (selected by master_doc) is the “root” of
1578 the TOC tree hierarchy. It can be used as the documentation’s
1579 main page, or as a “full table of contents” if you don’t give a
1580 maxdepth option.
1581 Changed in version 0.3: Added “globbing” option.
1583 Changed in version 0.6: Added “numbered” and “hidden” options as
1586 well as external links and support for “self” references.
1587 Changed in version 1.0: Added “titlesonly” option.
1590 Changed in version 1.1: Added numeric argument to “numbered”.
1593 Changed in version 1.2: Added “includehidden” option.
1596 Changed in version 1.3: Added “caption” and “name” option.
1599 Special names
1602 Sphinx reserves some document names for its own use; you should not try
1603 to create documents with these names – it will cause problems.
1604 The special document names (and pages generated for them) are:
1606 · genindex, modindex, search
1608 These are used for the general index, the Python module index, and
1610 the search page, respectively.
1611 The general index is populated with entries from modules, all
1613 index-generating object descriptions, and from index directives.
1614 The Python module index contains one entry per py:module directive.
1616 The search page contains a form that uses the generated JSON search
1618 index and JavaScript to full-text search the generated documents for
1619 search words; it should work on every major browser that supports
1620 modern JavaScript.
1621 · every name beginning with _
1623 Though only few such names are currently used by Sphinx, you should
1625 not create documents or document-containing directories with such
1626 names. (Using _ as a prefix for a custom template directory is
1627 fine.)
1628 WARNING:
1630 Be careful with unusual characters in filenames. Some formats may
1631 interpret these characters in unexpected ways:
1632 · Do not use the colon : for HTML based formats. Links to other
1634 parts may not work.
1635 · Do not use the plus + for the ePub format. Some resources may not
1637 be found.
1638
1640 [1] The LaTeX writer only refers the maxdepth option of first toctree
1641 directive in the document.
1642 [2] A note on available globbing syntax: you can use the standard
1644 shell constructs *, ?, [...] and [!...] with the feature that
1645 these all don’t match slashes. A double star ** can be used to
1646 match any sequence of characters including slashes.
1647 Paragraph-level markup
1649 These directives create short paragraphs and can be used inside infor‐
1650 mation units as well as normal text:
1651 .. note::
1653 An especially important bit of information about an API that a
1654 user should be aware of when using whatever bit of API the note
1655 pertains to. The content of the directive should be written in
1656 complete sentences and include all appropriate punctuation.
1657 Example:
1659 .. note::
1661 This function is not suitable for sending spam e-mails.
1663 .. warning::
1665 An important bit of information about an API that a user should
1666 be very aware of when using whatever bit of API the warning per‐
1667 tains to. The content of the directive should be written in
1668 complete sentences and include all appropriate punctuation. This
1669 differs from note in that it is recommended over note for infor‐
1670 mation regarding security.
1671 .. versionadded:: version
1673 This directive documents the version of the project which added
1674 the described feature to the library or C API. When this applies
1675 to an entire module, it should be placed at the top of the mod‐
1676 ule section before any prose.
1677 The first argument must be given and is the version in question;
1679 you can add a second argument consisting of a brief explanation
1680 of the change.
1681 Example:
1683 .. versionadded:: 2.5
1685 The *spam* parameter.
1686 Note that there must be no blank line between the directive head
1688 and the explanation; this is to make these blocks visually con‐
1689 tinuous in the markup.
1690 .. versionchanged:: version
1692 Similar to versionadded, but describes when and what changed in
1693 the named feature in some way (new parameters, changed side
1694 effects, etc.).
1695 .. deprecated:: version
1697 Similar to versionchanged, but describes when the feature was
1698 deprecated. An explanation can also be given, for example to
1699 inform the reader what should be used instead. Example:
1700 .. deprecated:: 3.1
1702 Use :func:`spam` instead.
1703 ----
1706 .. seealso::
1710 Many sections include a list of references to module documenta‐
1711 tion or external documents. These lists are created using the
1712 seealso directive.
1713 The seealso directive is typically placed in a section just
1715 before any subsections. For the HTML output, it is shown boxed
1716 off from the main flow of the text.
1717 The content of the seealso directive should be a reST definition
1719 list. Example:
1720 .. seealso::
1722 Module :py:mod:`zipfile`
1724 Documentation of the :py:mod:`zipfile` standard module.
1725 `GNU tar manual, Basic Tar Format <http://link>`_
1727 Documentation for tar archive files, including GNU tar extensions.
1728 There’s also a “short form” allowed that looks like this:
1730 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1732 New in version 0.5: The short form.
1734 .. rubric:: title
1737 This directive creates a paragraph heading that is not used to
1738 create a table of contents node.
1739 NOTE:
1741 If the title of the rubric is “Footnotes” (or the selected
1742 language’s equivalent), this rubric is ignored by the LaTeX
1743 writer, since it is assumed to only contain footnote defini‐
1744 tions and therefore would create an empty heading.
1745 .. centered::
1747 This directive creates a centered boldfaced line of text. Use
1748 it as follows:
1749 .. centered:: LICENSE AGREEMENT
1751 Deprecated since version 1.1: This presentation-only directive
1753 is a legacy from older versions. Use a rst-class directive
1754 instead and add an appropriate style.
1755 .. hlist::
1758 This directive must contain a bullet list. It will transform it
1759 into a more compact list by either distributing more than one
1760 item horizontally, or reducing spacing between items, depending
1761 on the builder.
1762 For builders that support the horizontal distribution, there is
1764 a columns option that specifies the number of columns; it
1765 defaults to 2. Example:
1766 .. hlist::
1768 :columns: 3
1769 * A list of
1771 * short items
1772 * that should be
1773 * displayed
1774 * horizontally
1775 New in version 0.6.
1777 Table-of-contents markup
1780 The toctree directive, which generates tables of contents of subdocu‐
1781 ments, is described in toctree-directive.
1782 For local tables of contents, use the standard reST contents directive.
1784 Glossary
1786 .. glossary::
1787 This directive must contain a reST definition-list-like markup
1788 with terms and definitions. The definitions will then be refer‐
1789 encable with the term role. Example:
1790 .. glossary::
1792 environment
1794 A structure where information about all documents under the root is
1795 saved, and used for cross-referencing. The environment is pickled
1796 after the parsing stage, so that successive runs only need to read
1797 and parse new and changed documents.
1798 source directory
1800 The directory which, including its subdirectories, contains all
1801 source files for one Sphinx project.
1802 In contrast to regular definition lists, multiple terms per
1804 entry are allowed, and inline markup is allowed in terms. You
1805 can link to all of the terms. For example:
1806 .. glossary::
1808 term 1
1810 term 2
1811 Definition of both terms.
1812 (When the glossary is sorted, the first term determines the sort
1814 order.)
1815 If you want to specify “grouping key” for general index entries,
1817 you can put a “key” as “term : key”. For example:
1818 .. glossary::
1820 term 1 : A
1822 term 2 : B
1823 Definition of both terms.
1824 Note that “key” is used for grouping key as is. The “key” isn’t
1826 normalized; key “A” and “a” become different groups. The whole
1827 characters in “key” is used instead of a first character; it is
1828 used for “Combining Character Sequence” and “Surrogate Pairs”
1829 grouping key.
1830 In i18n situation, you can specify “localized term : key” even
1832 if original text only have “term” part. In this case, translated
1833 “localized term” will be categorized in “key” group.
1834 New in version 0.6: You can now give the glossary directive a
1836 :sorted: flag that will automatically sort the entries alphabet‐
1837 ically.
1838 Changed in version 1.1: Now supports multiple terms and inline
1841 markup in terms.
1842 Changed in version 1.4: Index key for glossary term should be
1845 considered experimental.
1846 Grammar production displays
1849 Special markup is available for displaying the productions of a formal
1850 grammar. The markup is simple and does not attempt to model all
1851 aspects of BNF (or any derived forms), but provides enough to allow
1852 context-free grammars to be displayed in a way that causes uses of a
1853 symbol to be rendered as hyperlinks to the definition of the symbol.
1854 There is this directive:
1855 .. productionlist:: [name]
1857 This directive is used to enclose a group of productions. Each
1858 production is given on a single line and consists of a name,
1859 separated by a colon from the following definition. If the def‐
1860 inition spans multiple lines, each continuation line must begin
1861 with a colon placed at the same column as in the first line.
1862 The argument to productionlist serves to distinguish different
1864 sets of production lists that belong to different grammars.
1865 Blank lines are not allowed within productionlist directive
1867 arguments.
1868 The definition can contain token names which are marked as
1870 interpreted text (e.g. sum ::= `integer` "+" `integer`) – this
1871 generates cross-references to the productions of these tokens.
1872 Outside of the production list, you can reference to token pro‐
1873 ductions using token.
1874 Note that no further reST parsing is done in the production, so
1876 that you don’t have to escape * or | characters.
1877 The following is an example taken from the Python Reference Manual:
1879 .. productionlist::
1881 try_stmt: try1_stmt | try2_stmt
1882 try1_stmt: "try" ":" `suite`
1883 : ("except" [`expression` ["," `target`]] ":" `suite`)+
1884 : ["else" ":" `suite`]
1885 : ["finally" ":" `suite`]
1886 try2_stmt: "try" ":" `suite`
1887 : "finally" ":" `suite`
1888 Showing code examples
1890 Examples of Python source code or interactive sessions are represented
1891 using standard reST literal blocks. They are started by a :: at the
1892 end of the preceding paragraph and delimited by indentation.
1893 Representing an interactive session requires including the prompts and
1895 output along with the Python code. No special markup is required for
1896 interactive sessions. After the last line of input or output pre‐
1897 sented, there should not be an “unused” primary prompt; this is an
1898 example of what not to do:
1899 >>> 1 + 1
1901 2
1902 >>>
1903 Syntax highlighting is done with Pygments and handled in a smart way:
1905 · There is a “highlighting language” for each source file. Per
1907 default, this is 'python' as the majority of files will have to high‐
1908 light Python snippets, but the doc-wide default can be set with the
1909 highlight_language config value.
1910 · Within Python highlighting mode, interactive sessions are recognized
1912 automatically and highlighted appropriately. Normal Python code is
1913 only highlighted if it is parseable (so you can use Python as the
1914 default, but interspersed snippets of shell commands or other code
1915 blocks will not be highlighted as Python).
1916 · The highlighting language can be changed using the highlight direc‐
1918 tive, used as follows:
1919 .. highlight:: language
1921 Example:
1922 .. highlight:: c
1924 This language is used until the next highlight directive is
1926 encountered.
1927 · For documents that have to show snippets in different languages,
1929 there’s also a code-block directive that is given the highlighting
1930 language directly:
1931 .. code-block:: language
1933 Use it like this:
1934 .. code-block:: ruby
1936 Some Ruby code.
1938 The directive’s alias name sourcecode works as well.
1940 · The valid values for the highlighting language are:
1942 · none (no highlighting)
1944 · python (the default when highlight_language isn’t set)
1946 · guess (let Pygments guess the lexer based on contents, only works
1948 with certain well-recognizable languages)
1949 · rest
1951 · c
1953 · … and any other lexer alias that Pygments supports.
1955 · If highlighting with the selected language fails (i.e. Pygments emits
1957 an “Error” token), the block is not highlighted in any way.
1958 Line numbers
1960 Pygments can generate line numbers for code blocks. For automati‐
1961 cally-highlighted blocks (those started by ::), line numbers must be
1962 switched on in a highlight directive, with the linenothreshold option:
1963 .. highlight:: python
1965 :linenothreshold: 5
1966 This will produce line numbers for all code blocks longer than five
1968 lines.
1969 For code-block blocks, a linenos flag option can be given to switch on
1971 line numbers for the individual block:
1972 .. code-block:: ruby
1974 :linenos:
1975 Some more Ruby code.
1977 The first line number can be selected with the lineno-start option. If
1979 present, linenos flag is automatically activated:
1980 .. code-block:: ruby
1982 :lineno-start: 10
1983 Some more Ruby code, with line numbering starting at 10.
1985 Additionally, an emphasize-lines option can be given to have Pygments
1987 emphasize particular lines:
1988 .. code-block:: python
1990 :emphasize-lines: 3,5
1991 def some_function():
1993 interesting = False
1994 print 'This line is highlighted.'
1995 print 'This one is not...'
1996 print '...but this one is.'
1997 Changed in version 1.1: emphasize-lines has been added.
1999 Changed in version 1.3: lineno-start has been added.
2002 Changed in version 1.6.6: LaTeX supports the emphasize-lines option.
2005 Includes
2008 .. literalinclude:: filename
2009 Longer displays of verbatim text may be included by storing the
2010 example text in an external file containing only plain text.
2011 The file may be included using the literalinclude directive. [1]
2012 For example, to include the Python source file example.py, use:
2013 .. literalinclude:: example.py
2015 The file name is usually relative to the current file’s path.
2017 However, if it is absolute (starting with /), it is relative to
2018 the top source directory.
2019 Tabs in the input are expanded if you give a tab-width option
2021 with the desired tab width.
2022 Like code-block, the directive supports the linenos flag option
2024 to switch on line numbers, the lineno-start option to select the
2025 first line number, the emphasize-lines option to emphasize par‐
2026 ticular lines, and a language option to select a language dif‐
2027 ferent from the current file’s standard language. Example with
2028 options:
2029 .. literalinclude:: example.rb
2031 :language: ruby
2032 :emphasize-lines: 12,15-18
2033 :linenos:
2034 Include files are assumed to be encoded in the source_encoding.
2036 If the file has a different encoding, you can specify it with
2037 the encoding option:
2038 .. literalinclude:: example.py
2040 :encoding: latin-1
2041 The directive also supports including only parts of the file.
2043 If it is a Python module, you can select a class, function or
2044 method to include using the pyobject option:
2045 .. literalinclude:: example.py
2047 :pyobject: Timer.start
2048 This would only include the code lines belonging to the start()
2050 method in the Timer class within the file.
2051 Alternately, you can specify exactly which lines to include by
2053 giving a lines option:
2054 .. literalinclude:: example.py
2056 :lines: 1,3,5-10,20-
2057 This includes the lines 1, 3, 5 to 10 and lines 20 to the last
2059 line.
2060 Another way to control which part of the file is included is to
2062 use the start-after and end-before options (or only one of
2063 them). If start-after is given as a string option, only lines
2064 that follow the first line containing that string are included.
2065 If end-before is given as a string option, only lines that pre‐
2066 cede the first lines containing that string are included.
2067 With lines selected using start-after it is still possible to
2069 use lines, the first allowed line having by convention the line
2070 number 1.
2071 When lines have been selected in any of the ways described
2073 above, the line numbers in emphasize-lines refer to those
2074 selected lines, counted consecutively starting at 1.
2075 When specifying particular parts of a file to display, it can be
2077 useful to display the original line numbers. This can be done
2078 using the lineno-match option, which is however allowed only
2079 when the selection consists of contiguous lines.
2080 You can prepend and/or append a line to the included code, using
2082 the prepend and append option, respectively. This is useful
2083 e.g. for highlighting PHP code that doesn’t include the <?php/?>
2084 markers.
2085 If you want to show the diff of the code, you can specify the
2087 old file by giving a diff option:
2088 .. literalinclude:: example.py
2090 :diff: example.py.orig
2091 This shows the diff between example.py and example.py.orig with
2093 unified diff format.
2094 New in version 0.4.3: The encoding option.
2096 New in version 0.6: The pyobject, lines, start-after and
2099 end-before options, as well as support for absolute filenames.
2100 New in version 1.0: The prepend and append options, as well as
2103 tab-width.
2104 New in version 1.3: The diff option. The lineno-match option.
2107 Changed in version 1.6: With both start-after and lines in use,
2110 the first line as per start-after is considered to be with line
2111 number 1 for lines.
2112 Caption and name
2115 New in version 1.3.
2116 A caption option can be given to show that name before the code block.
2119 A name option can be provided implicit target name that can be refer‐
2120 enced by using ref. For example:
2121 .. code-block:: python
2123 :caption: this.py
2124 :name: this-py
2125 print 'Explicit is better than implicit.'
2127 literalinclude also supports the caption and name option. caption has
2129 an additional feature that if you leave the value empty, the shown
2130 filename will be exactly the one given as an argument.
2131 Dedent
2133 New in version 1.3.
2134 A dedent option can be given to strip indentation characters from the
2137 code block. For example:
2138 .. literalinclude:: example.rb
2140 :language: ruby
2141 :dedent: 4
2142 :lines: 10-15
2143 code-block also supports the dedent option.
2145
2147 [1] There is a standard .. include directive, but it raises errors if
2148 the file is not found. This one only emits a warning.
2149 Inline markup
2151 Sphinx uses interpreted text roles to insert semantic markup into docu‐
2152 ments. They are written as :rolename:`content`.
2153 NOTE:
2155 The default role (`content`) has no special meaning by default. You
2156 are free to use it for anything you like, e.g. variable names; use
2157 the default_role config value to set it to a known role – the any
2158 role to find anything or the py:obj role to find Python objects are
2159 very useful for this.
2160 See domains for roles added by domains.
2162 Cross-referencing syntax
2164 Cross-references are generated by many semantic interpreted text roles.
2165 Basically, you only need to write :role:`target`, and a link will be
2166 created to the item named target of the type indicated by role. The
2167 link’s text will be the same as target.
2168 There are some additional facilities, however, that make cross-refer‐
2170 encing roles more versatile:
2171 · You may supply an explicit title and reference target, like in reST
2173 direct hyperlinks: :role:`title <target>` will refer to target, but
2174 the link text will be title.
2175 · If you prefix the content with !, no reference/hyperlink will be cre‐
2177 ated.
2178 · If you prefix the content with ~, the link text will only be the last
2180 component of the target. For example, :py:meth:`~Queue.Queue.get`
2181 will refer to Queue.Queue.get but only display get as the link text.
2182 This does not work with all cross-reference roles, but is domain spe‐
2183 cific.
2184 In HTML output, the link’s title attribute (that is e.g. shown as a
2186 tool-tip on mouse-hover) will always be the full target name.
2187 Cross-referencing anything
2189 :any: New in version 1.3.
2190 This convenience role tries to do its best to find a valid tar‐
2193 get for its reference text.
2194 · First, it tries standard cross-reference targets that would be
2196 referenced by doc, ref or option.
2197 Custom objects added to the standard domain by extensions (see
2199 Sphinx.add_object_type()) are also searched.
2200 · Then, it looks for objects (targets) in all loaded domains.
2202 It is up to the domains how specific a match must be. For
2203 example, in the Python domain a reference of :any:`Builder`
2204 would match the sphinx.builders.Builder class.
2205 If none or multiple targets are found, a warning will be emit‐
2207 ted. In the case of multiple targets, you can change “any” to a
2208 specific role.
2209 This role is a good candidate for setting default_role. If you
2211 do, you can write cross-references without a lot of markup over‐
2212 head. For example, in this Python function documentation
2213 .. function:: install()
2215 This function installs a `handler` for every signal known by the
2217 `signal` module. See the section `about-signals` for more information.
2218 there could be references to a glossary term (usually
2220 :term:`handler`), a Python module (usually :py:mod:`signal` or
2221 :mod:`signal`) and a section (usually :ref:`about-signals`).
2222 The any role also works together with the intersphinx extension:
2224 when no local cross-reference is found, all object types of
2225 intersphinx inventories are also searched.
2226 Cross-referencing objects
2228 These roles are described with their respective domains:
2229 · Python
2231 · C
2233 · C++
2235 · JavaScript
2237 · ReST
2239 Cross-referencing arbitrary locations
2241 :ref: To support cross-referencing to arbitrary locations in any docu‐
2242 ment, the standard reST labels are used. For this to work label
2243 names must be unique throughout the entire documentation. There
2244 are two ways in which you can refer to labels:
2245 · If you place a label directly before a section title, you can
2247 reference to it with :ref:`label-name`. Example:
2248 .. _my-reference-label:
2250 Section to cross-reference
2252 --------------------------
2253 This is the text of the section.
2255 It refers to the section itself, see :ref:`my-reference-label`.
2257 The :ref: role would then generate a link to the section, with
2259 the link title being “Section to cross-reference”. This works
2260 just as well when section and reference are in different
2261 source files.
2262 Automatic labels also work with figures: given
2264 .. _my-figure:
2266 .. figure:: whatever
2268 Figure caption
2270 a reference :ref:`my-figure` would insert a reference to the
2272 figure with link text “Figure caption”.
2273 The same works for tables that are given an explicit caption
2275 using the table directive.
2276 · Labels that aren’t placed before a section title can still be
2278 referenced, but you must give the link an explicit title,
2279 using this syntax: :ref:`Link title <label-name>`.
2280 NOTE:
2282 Reference labels must start with an underscore. When refer‐
2283 encing a label, the underscore must be omitted (see examples
2284 above).
2285 Using ref is advised over standard reStructuredText links to
2287 sections (like `Section title`_) because it works across files,
2288 when section headings are changed, and for all builders that
2289 support cross-references.
2290 Cross-referencing documents
2292 New in version 0.6.
2293 There is also a way to directly link to documents:
2296 :doc: Link to the specified document; the document name can be speci‐
2298 fied in absolute or relative fashion. For example, if the ref‐
2299 erence :doc:`parrot` occurs in the document sketches/index, then
2300 the link refers to sketches/parrot. If the reference is
2301 :doc:`/people` or :doc:`../people`, the link refers to people.
2302 If no explicit link text is given (like usual: :doc:`Monty
2304 Python members </people>`), the link caption will be the title
2305 of the given document.
2306 Referencing downloadable files
2308 New in version 0.6.
2309 :download:
2312 This role lets you link to files within your source tree that
2313 are not reST documents that can be viewed, but files that can be
2314 downloaded.
2315 When you use this role, the referenced file is automatically
2317 marked for inclusion in the output when building (obviously, for
2318 HTML output only). All downloadable files are put into the
2319 _downloads subdirectory of the output directory; duplicate file‐
2320 names are handled.
2321 An example:
2323 See :download:`this example script <../example.py>`.
2325 The given filename is usually relative to the directory the cur‐
2327 rent source file is contained in, but if it absolute (starting
2328 with /), it is taken as relative to the top source directory.
2329 The example.py file will be copied to the output directory, and
2331 a suitable link generated to it.
2332 Not to show unavailable download links, you should wrap whole
2334 paragraphs that have this role:
2335 .. only:: builder_html
2337 See :download:`this example script <../example.py>`.
2339 Cross-referencing figures by figure number
2341 New in version 1.3.
2342 Changed in version 1.5: numref role can also refer sections. And num‐
2345 ref allows {name} for the link text.
2346 :numref:
2349 Link to the specified figures, tables, code-blocks and sections;
2350 the standard reST labels are used. When you use this role, it
2351 will insert a reference to the figure with link text by its fig‐
2352 ure number like “Fig. 1.1”.
2353 If an explicit link text is given (as usual: :numref:`Image of
2355 Sphinx (Fig. %s) <my-figure>`), the link caption will serve as
2356 title of the reference. As placeholders, %s and {number} get
2357 replaced by the figure number and {name} by the figure caption.
2358 If no explicit link text is given, the numfig_format setting is
2359 used as fall-back default.
2360 If numfig is False, figures are not numbered, so this role
2362 inserts not a reference but the label or the link text.
2363 Cross-referencing other items of interest
2365 The following roles do possibly create a cross-reference, but do not
2366 refer to objects:
2367 :envvar:
2369 An environment variable. Index entries are generated. Also
2370 generates a link to the matching envvar directive, if it exists.
2371 :token:
2373 The name of a grammar token (used to create links between pro‐
2374 ductionlist directives).
2375 :keyword:
2377 The name of a keyword in Python. This creates a link to a ref‐
2378 erence label with that name, if it exists.
2379 :option:
2381 A command-line option to an executable program. This generates
2382 a link to a option directive, if it exists.
2383 The following role creates a cross-reference to a term in a glossary:
2385 :term: Reference to a term in a glossary. A glossary is created using
2387 the glossary directive containing a definition list with terms
2388 and definitions. It does not have to be in the same file as the
2389 term markup, for example the Python docs have one global glos‐
2390 sary in the glossary.rst file.
2391 If you use a term that’s not explained in a glossary, you’ll get
2393 a warning during build.
2394 Other semantic markup
2396 The following roles don’t do anything special except formatting the
2397 text in a different style:
2398 :abbr: An abbreviation. If the role content contains a parenthesized
2400 explanation, it will be treated specially: it will be shown in a
2401 tool-tip in HTML, and output only once in LaTeX.
2402 Example: :abbr:`LIFO (last-in, first-out)`.
2404 New in version 0.6.
2406 :command:
2409 The name of an OS-level command, such as rm.
2410 :dfn: Mark the defining instance of a term in the text. (No index
2412 entries are generated.)
2413 :file: The name of a file or directory. Within the contents, you can
2415 use curly braces to indicate a “variable” part, for example:
2416 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
2418 In the built documentation, the x will be displayed differently
2420 to indicate that it is to be replaced by the Python minor ver‐
2421 sion.
2422 :guilabel:
2424 Labels presented as part of an interactive user interface should
2425 be marked using guilabel. This includes labels from text-based
2426 interfaces such as those created using curses or other
2427 text-based libraries. Any label used in the interface should be
2428 marked with this role, including button labels, window titles,
2429 field names, menu and menu selection names, and even values in
2430 selection lists.
2431 Changed in version 1.0: An accelerator key for the GUI label can
2433 be included using an ampersand; this will be stripped and dis‐
2434 played underlined in the output (example: :guilabel:`&Cancel`).
2435 To include a literal ampersand, double it.
2436 :kbd: Mark a sequence of keystrokes. What form the key sequence takes
2439 may depend on platform- or application-specific conventions.
2440 When there are no relevant conventions, the names of modifier
2441 keys should be spelled out, to improve accessibility for new
2442 users and non-native speakers. For example, an xemacs key
2443 sequence may be marked like :kbd:`C-x C-f`, but without refer‐
2444 ence to a specific application or platform, the same sequence
2445 should be marked as :kbd:`Control-x Control-f`.
2446 :mailheader:
2448 The name of an RFC 822-style mail header. This markup does not
2449 imply that the header is being used in an email message, but can
2450 be used to refer to any header of the same “style.” This is
2451 also used for headers defined by the various MIME specifica‐
2452 tions. The header name should be entered in the same way it
2453 would normally be found in practice, with the camel-casing con‐
2454 ventions being preferred where there is more than one common
2455 usage. For example: :mailheader:`Content-Type`.
2456 :makevar:
2458 The name of a make variable.
2459 :manpage:
2461 A reference to a Unix manual page including the section, e.g.
2462 :manpage:`ls(1)`. Creates a hyperlink to an external site ren‐
2463 dering the manpage if manpages_url is defined.
2464 :menuselection:
2466 Menu selections should be marked using the menuselection role.
2467 This is used to mark a complete sequence of menu selections,
2468 including selecting submenus and choosing a specific operation,
2469 or any subsequence of such a sequence. The names of individual
2470 selections should be separated by -->.
2471 For example, to mark the selection “Start > Programs”, use this
2473 markup:
2474 :menuselection:`Start --> Programs`
2476 When including a selection that includes some trailing indica‐
2478 tor, such as the ellipsis some operating systems use to indicate
2479 that the command opens a dialog, the indicator should be omitted
2480 from the selection name.
2481 menuselection also supports ampersand accelerators just like
2483 guilabel.
2484 :mimetype:
2486 The name of a MIME type, or a component of a MIME type (the
2487 major or minor portion, taken alone).
2488 :newsgroup:
2490 The name of a Usenet newsgroup.
2491 :program:
2493 The name of an executable program. This may differ from the
2494 file name for the executable for some platforms. In particular,
2495 the .exe (or other) extension should be omitted for Windows pro‐
2496 grams.
2497 :regexp:
2499 A regular expression. Quotes should not be included.
2500 :samp: A piece of literal text, such as code. Within the contents, you
2502 can use curly braces to indicate a “variable” part, as in file.
2503 For example, in :samp:`print 1+{variable}`, the part variable
2504 would be emphasized.
2505 If you don’t need the “variable part” indication, use the stan‐
2507 dard ``code`` instead.
2508 There is also an index role to generate index entries.
2510 The following roles generate external links:
2512 :pep: A reference to a Python Enhancement Proposal. This generates
2514 appropriate index entries. The text “PEP number” is generated;
2515 in the HTML output, this text is a hyperlink to an online copy
2516 of the specified PEP. You can link to a specific section by
2517 saying :pep:`number#anchor`.
2518 :rfc: A reference to an Internet Request for Comments. This generates
2520 appropriate index entries. The text “RFC number” is generated;
2521 in the HTML output, this text is a hyperlink to an online copy
2522 of the specified RFC. You can link to a specific section by
2523 saying :rfc:`number#anchor`.
2524 Note that there are no special roles for including hyperlinks as you
2526 can use the standard reST markup for that purpose.
2527 Substitutions
2529 The documentation system provides three substitutions that are defined
2530 by default. They are set in the build configuration file.
2531 |release|
2533 Replaced by the project release the documentation refers to.
2534 This is meant to be the full version string including
2535 alpha/beta/release candidate tags, e.g. 2.5.2b3. Set by
2536 release.
2537 |version|
2539 Replaced by the project version the documentation refers to.
2540 This is meant to consist only of the major and minor version
2541 parts, e.g. 2.5, even for version 2.5.1. Set by version.
2542 |today|
2544 Replaced by either today’s date (the date on which the document
2545 is read), or the date set in the build configuration file. Nor‐
2546 mally has the format April 14, 2007. Set by today_fmt and
2547 today.
2548 Miscellaneous markup
2550 File-wide metadata
2551 reST has the concept of “field lists”; these are a sequence of fields
2552 marked up like this:
2553 :fieldname: Field content
2555 A field list near the top of a file is parsed by docutils as the
2557 “docinfo” which is normally used to record the author, date of publica‐
2558 tion and other metadata. In Sphinx, a field list preceding any other
2559 markup is moved from the docinfo to the Sphinx environment as document
2560 metadata and is not displayed in the output; a field list appearing
2561 after the document title will be part of the docinfo as normal and will
2562 be displayed in the output.
2563 At the moment, these metadata fields are recognized:
2565 tocdepth
2567 The maximum depth for a table of contents of this file.
2568 New in version 0.4.
2570 nocomments
2573 If set, the web application won’t display a comment form for a
2574 page generated from this source file.
2575 orphan If set, warnings about this file not being included in any toc‐
2577 tree will be suppressed.
2578 New in version 1.0.
2580 Meta-information markup
2583 .. sectionauthor:: name <email>
2584 Identifies the author of the current section. The argument
2585 should include the author’s name such that it can be used for
2586 presentation and email address. The domain name portion of the
2587 address should be lower case. Example:
2588 .. sectionauthor:: Guido van Rossum <guido@python.org>
2590 By default, this markup isn’t reflected in the output in any way
2592 (it helps keep track of contributions), but you can set the con‐
2593 figuration value show_authors to True to make them produce a
2594 paragraph in the output.
2595 .. codeauthor:: name <email>
2597 The codeauthor directive, which can appear multiple times, names
2598 the authors of the described code, just like sectionauthor names
2599 the author(s) of a piece of documentation. It too only produces
2600 output if the show_authors configuration value is True.
2601 Index-generating markup
2603 Sphinx automatically creates index entries from all object descriptions
2604 (like functions, classes or attributes) like discussed in domains.
2605 However, there is also explicit markup available, to make the index
2607 more comprehensive and enable index entries in documents where informa‐
2608 tion is not mainly contained in information units, such as the language
2609 reference.
2610 .. index:: <entries>
2612 This directive contains one or more index entries. Each entry
2613 consists of a type and a value, separated by a colon.
2614 For example:
2616 .. index::
2618 single: execution; context
2619 module: __main__
2620 module: sys
2621 triple: module; search; path
2622 The execution context
2624 ---------------------
2625 ...
2627 This directive contains five entries, which will be converted to
2629 entries in the generated index which link to the exact location
2630 of the index statement (or, in case of offline media, the corre‐
2631 sponding page number).
2632 Since index directives generate cross-reference targets at their
2634 location in the source, it makes sense to put them before the
2635 thing they refer to – e.g. a heading, as in the example above.
2636 The possible entry types are:
2638 single Creates a single index entry. Can be made a subentry by
2640 separating the subentry text with a semicolon (this nota‐
2641 tion is also used below to describe what entries are cre‐
2642 ated).
2643 pair pair: loop; statement is a shortcut that creates two
2645 index entries, namely loop; statement and statement;
2646 loop.
2647 triple Likewise, triple: module; search; path is a shortcut that
2649 creates three index entries, which are module; search
2650 path, search; path, module and path; module search.
2651 see see: entry; other creates an index entry that refers from
2653 entry to other.
2654 seealso
2656 Like see, but inserts “see also” instead of “see”.
2657 module, keyword, operator, object, exception, statement, builtin
2659 These all create two index entries. For example, module:
2660 hashlib creates the entries module; hashlib and hashlib;
2661 module. (These are Python-specific and therefore depre‐
2662 cated.)
2663 You can mark up “main” index entries by prefixing them with an
2665 exclamation mark. The references to “main” entries are empha‐
2666 sized in the generated index. For example, if two pages contain
2667 .. index:: Python
2669 and one page contains
2671 .. index:: ! Python
2673 then the backlink to the latter page is emphasized among the
2675 three backlinks.
2676 For index directives containing only “single” entries, there is
2678 a shorthand notation:
2679 .. index:: BNF, grammar, syntax, notation
2681 This creates four index entries.
2683 Changed in version 1.1: Added see and seealso types, as well as
2685 marking main entries.
2686 :index:
2689 While the index directive is a block-level markup and links to
2690 the beginning of the next paragraph, there is also a correspond‐
2691 ing role that sets the link target directly where it is used.
2692 The content of the role can be a simple phrase, which is then
2694 kept in the text and used as an index entry. It can also be a
2695 combination of text and index entry, styled like with explicit
2696 targets of cross-references. In that case, the “target” part
2697 can be a full entry as described for the directive above. For
2698 example:
2699 This is a normal reST :index:`paragraph` that contains several
2701 :index:`index entries <pair: index; entry>`.
2702 New in version 1.1.
2704 Including content based on tags
2707 .. only:: <expression>
2708 Include the content of the directive only if the expression is
2709 true. The expression should consist of tags, like this:
2710 .. only:: html and draft
2712 Undefined tags are false, defined tags (via the -t command-line
2714 option or within conf.py, see here) are true. Boolean expres‐
2715 sions, also using parentheses (like html and (latex or draft))
2716 are supported.
2717 The format and the name of the current builder (html, latex or
2719 text) are always set as a tag [1]. To make the distinction
2720 between format and name explicit, they are also added with the
2721 prefix format_ and builder_, e.g. the epub builder defines the
2722 tags html, epub, format_html and builder_epub.
2723 These standard tags are set after the configuration file is
2725 read, so they are not available there.
2726 All tags must follow the standard Python identifier syntax as
2728 set out in the Identifiers and keywords documentation. That is,
2729 a tag expression may only consist of tags that conform to the
2730 syntax of Python variables. In ASCII, this consists of the
2731 uppercase and lowercase letters A through Z, the underscore _
2732 and, except for the first character, the digits 0 through 9.
2733 New in version 0.6.
2735 Changed in version 1.2: Added the name of the builder and the
2738 prefixes.
2739 WARNING:
2742 This directive is designed to control only content of docu‐
2743 ment. It could not control sections, labels and so on.
2744 Tables
2746 Use reStructuredText tables, i.e. either
2747 · grid table syntax (ref),
2749 · simple table syntax (ref),
2751 · csv-table syntax,
2753 · or list-table syntax.
2755 The table directive serves as optional wrapper of the grid and simple
2757 syntaxes.
2758 They work fine in HTML output, however there are some gotchas when
2760 using tables in LaTeX: the column width is hard to determine correctly
2761 automatically. For this reason, the following directive exists:
2762 .. tabularcolumns:: column spec
2764 This directive gives a “column spec” for the next table occur‐
2765 ring in the source file. The spec is the second argument to the
2766 LaTeX tabulary package’s environment (which Sphinx uses to
2767 translate tables). It can have values like
2768 |l|l|l|
2770 which means three left-adjusted, nonbreaking columns. For col‐
2772 umns with longer text that should automatically be broken, use
2773 either the standard p{width} construct, or tabulary’s automatic
2774 specifiers:
2775 ┌──┬────────────────────────────┐
2777 │L │ flush left column with │
2778 │ │ automatic width │
2779 ├──┼────────────────────────────┤
2780 │R │ flush right column with │
2781 │ │ automatic width │
2782 ├──┼────────────────────────────┤
2783 │C │ centered column with auto‐ │
2784 │ │ matic width │
2785 ├──┼────────────────────────────┤
2786 │J │ justified column with │
2787 │ │ automatic width │
2788 └──┴────────────────────────────┘
2789 The automatic widths of the LRCJ columns are attributed by tabu‐
2791 lary in proportion to the observed shares in a first pass where
2792 the table cells are rendered at their natural “horizontal”
2793 widths.
2794 By default, Sphinx uses a table layout with J for every column.
2796 New in version 0.3.
2798 Changed in version 1.6: Merged cells may now contain multiple
2801 paragraphs and are much better handled, thanks to custom Sphinx
2802 LaTeX macros. This novel situation motivated the switch to J
2803 specifier and not L by default.
2804 HINT:
2807 Sphinx actually uses T specifier having done \newcolumn‐
2808 type{T}{J}. To revert to previous default, insert \newcolum‐
2809 ntype{T}{L} in the LaTeX preamble (see latex_elements).
2810 A frequent issue with tabulary is that columns with little
2812 contents are “squeezed”. The minimal column width is a tabu‐
2813 lary parameter called \tymin. You may set it globally in the
2814 LaTeX preamble via \setlength{\tymin}{40pt} for example.
2815 Else, use the tabularcolumns directive with an explicit
2817 p{40pt} (for example) for that column. You may use also l
2818 specifier but this makes the task of setting column widths
2819 more difficult if some merged cell intersects that column.
2820 WARNING:
2822 Tables with more than 30 rows are rendered using longtable,
2823 not tabulary, in order to allow pagebreaks. The L, R, … spec‐
2824 ifiers do not work for these tables.
2825 Tables that contain list-like elements such as object
2827 descriptions, blockquotes or any kind of lists cannot be set
2828 out of the box with tabulary. They are therefore set with the
2829 standard LaTeX tabular (or longtable) environment if you
2830 don’t give a tabularcolumns directive. If you do, the table
2831 will be set with tabulary but you must use the p{width} con‐
2832 struct (or Sphinx’s \X and \Y specifiers described below) for
2833 the columns containing these elements.
2834 Literal blocks do not work with tabulary at all, so tables
2836 containing a literal block are always set with tabular. The
2837 verbatim environment used for literal blocks only works in
2838 p{width} (and \X or \Y) columns, hence Sphinx generates such
2839 column specs for tables containing literal blocks.
2840 Since Sphinx 1.5, the \X{a}{b} specifier is used (there is a
2842 backslash in the specifier letter). It is like p{width} with the
2843 width set to a fraction a/b of the current line width. You can
2844 use it in the tabularcolumns (it is not a problem if some LaTeX
2845 macro is also called \X.)
2846 It is not needed for b to be the total number of columns, nor
2848 for the sum of the fractions of the \X specifiers to add up to
2849 one. For example |\X{2}{5}|\X{1}{5}|\X{1}{5}| is legitimate and
2850 the table will occupy 80% of the line width, the first of its
2851 three columns having the same width as the sum of the next two.
2852 This is used by the :widths: option of the table directive.
2854 Since Sphinx 1.6, there is also the \Y{f} specifier which admits
2856 a decimal argument, such has \Y{0.15}: this would have the same
2857 effect as \X{3}{20}.
2858 Changed in version 1.6: Merged cells from complex grid tables
2860 (either multi-row, multi-column, or both) now allow blockquotes,
2861 lists, literal blocks, … as do regular cells.
2862 Sphinx’s merged cells interact well with p{width}, \X{a}{b},
2864 Y{f} and tabulary’s columns.
2865 NOTE:
2868 tabularcolumns conflicts with :widths: option of table direc‐
2869 tives. If both are specified, :widths: option will be
2870 ignored.
2871 Math
2873 See math-support.
2874
2876 [1] For most builders name and format are the same. At the moment only
2877 builders derived from the html builder distinguish between the
2878 builder format and the builder name.
2879 Note that the current builder tag is not available in conf.py, it
2881 is only available after the builder is initialized.
2882 More markup is added by domains.
2884
2886 New in version 1.0.
2887 What is a Domain?
2890 Originally, Sphinx was conceived for a single project, the documenta‐
2891 tion of the Python language. Shortly afterwards, it was made available
2892 for everyone as a documentation tool, but the documentation of Python
2893 modules remained deeply built in – the most fundamental directives,
2894 like function, were designed for Python objects. Since Sphinx has
2895 become somewhat popular, interest developed in using it for many dif‐
2896 ferent purposes: C/C++ projects, JavaScript, or even reStructuredText
2897 markup (like in this documentation).
2898 While this was always possible, it is now much easier to easily support
2900 documentation of projects using different programming languages or even
2901 ones not supported by the main Sphinx distribution, by providing a
2902 domain for every such purpose.
2903 A domain is a collection of markup (reStructuredText directives and
2905 roles) to describe and link to objects belonging together, e.g. ele‐
2906 ments of a programming language. Directive and role names in a domain
2907 have names like domain:name, e.g. py:function. Domains can also pro‐
2908 vide custom indices (like the Python Module Index).
2909 Having domains means that there are no naming problems when one set of
2911 documentation wants to refer to e.g. C++ and Python classes. It also
2912 means that extensions that support the documentation of whole new lan‐
2913 guages are much easier to write.
2914 This section describes what the domains that are included with Sphinx
2916 provide. The domain API is documented as well, in the section
2917 domain-api.
2918 Basic Markup
2920 Most domains provide a number of object description directives, used to
2921 describe specific objects provided by modules. Each directive requires
2922 one or more signatures to provide basic information about what is being
2923 described, and the content should be the description. The basic ver‐
2924 sion makes entries in the general index; if no index entry is desired,
2925 you can give the directive option flag :noindex:. An example using a
2926 Python domain directive:
2927 .. py:function:: spam(eggs)
2929 ham(eggs)
2930 Spam or ham the foo.
2932 This describes the two Python functions spam and ham. (Note that when
2934 signatures become too long, you can break them if you add a backslash
2935 to lines that are continued in the next line. Example:
2936 .. py:function:: filterwarnings(action, message='', category=Warning, \
2938 module='', lineno=0, append=False)
2939 :noindex:
2940 (This example also shows how to use the :noindex: flag.)
2942 The domains also provide roles that link back to these object descrip‐
2944 tions. For example, to link to one of the functions described in the
2945 example above, you could say
2946 The function :py:func:`spam` does a similar thing.
2948 As you can see, both directive and role names contain the domain name
2950 and the directive name. Default Domain
2951 For documentation describing objects from solely one domain, authors
2953 will not have to state again its name at each directive, role, etc…
2954 after having specified a default. This can be done either via the con‐
2955 fig value primary_domain or via this directive:
2956 .. default-domain:: name
2958 Select a new default domain. While the primary_domain selects a
2959 global default, this only has an effect within the same file.
2960 If no other default is selected, the Python domain (named py) is the
2962 default one, mostly for compatibility with documentation written for
2963 older versions of Sphinx.
2964 Directives and roles that belong to the default domain can be mentioned
2966 without giving the domain name, i.e.
2967 .. function:: pyfunc()
2969 Describes a Python function.
2971 Reference to :func:`pyfunc`.
2973 Cross-referencing syntax
2975 For cross-reference roles provided by domains, the same facilities
2976 exist as for general cross-references. See xref-syntax.
2977 In short:
2979 · You may supply an explicit title and reference target: :role:`title
2981 <target>` will refer to target, but the link text will be title.
2982 · If you prefix the content with !, no reference/hyperlink will be cre‐
2984 ated.
2985 · If you prefix the content with ~, the link text will only be the last
2987 component of the target. For example, :py:meth:`~Queue.Queue.get`
2988 will refer to Queue.Queue.get but only display get as the link text.
2989 The Python Domain
2991 The Python domain (name py) provides the following directives for mod‐
2992 ule declarations:
2993 .. py:module:: name
2995 This directive marks the beginning of the description of a mod‐
2996 ule (or package submodule, in which case the name should be
2997 fully qualified, including the package name). It does not cre‐
2998 ate content (like e.g. py:class does).
2999 This directive will also cause an entry in the global module
3001 index.
3002 The platform option, if present, is a comma-separated list of
3004 the platforms on which the module is available (if it is avail‐
3005 able on all platforms, the option should be omitted). The keys
3006 are short identifiers; examples that are in use include “IRIX”,
3007 “Mac”, “Windows”, and “Unix”. It is important to use a key
3008 which has already been used when applicable.
3009 The synopsis option should consist of one sentence describing
3011 the module’s purpose – it is currently only used in the Global
3012 Module Index.
3013 The deprecated option can be given (with no value) to mark a
3015 module as deprecated; it will be designated as such in various
3016 locations then.
3017 .. py:currentmodule:: name
3019 This directive tells Sphinx that the classes, functions etc.
3020 documented from here are in the given module (like py:module),
3021 but it will not create index entries, an entry in the Global
3022 Module Index, or a link target for py:mod. This is helpful in
3023 situations where documentation for things in a module is spread
3024 over multiple files or sections – one location has the py:module
3025 directive, the others only py:currentmodule.
3026 The following directives are provided for module and class contents:
3028 .. py:function:: name(parameters)
3030 Describes a module-level function. The signature should include
3031 the parameters as given in the Python function definition, see
3032 Python Signatures. For example:
3033 .. py:function:: Timer.repeat(repeat=3, number=1000000)
3035 For methods you should use py:method.
3037 The description normally includes information about the parame‐
3039 ters required and how they are used (especially whether mutable
3040 objects passed as parameters are modified), side effects, and
3041 possible exceptions.
3042 This information can (in any py directive) optionally be given
3044 in a structured form, see Info field lists.
3045 .. py:data:: name
3047 Describes global data in a module, including both variables and
3048 values used as “defined constants.” Class and object attributes
3049 are not documented using this environment.
3050 .. py:exception:: name
3052 Describes an exception class. The signature can, but need not
3053 include parentheses with constructor arguments.
3054 .. py:class:: name
3056 .. py:class:: name(parameters)
3058 Describes a class. The signature can optionally include paren‐
3059 theses with parameters which will be shown as the constructor
3060 arguments. See also Python Signatures.
3061 Methods and attributes belonging to the class should be placed
3063 in this directive’s body. If they are placed outside, the sup‐
3064 plied name should contain the class name so that cross-refer‐
3065 ences still work. Example:
3066 .. py:class:: Foo
3068 .. py:method:: quux()
3070 -- or --
3072 .. py:class:: Bar
3074 .. py:method:: Bar.quux()
3076 The first way is the preferred one.
3078 .. py:attribute:: name
3080 Describes an object data attribute. The description should
3081 include information about the type of the data to be expected
3082 and whether it may be changed directly.
3083 .. py:method:: name(parameters)
3085 Describes an object method. The parameters should not include
3086 the self parameter. The description should include similar
3087 information to that described for function. See also Python
3088 Signatures and Info field lists.
3089 .. py:staticmethod:: name(parameters)
3091 Like py:method, but indicates that the method is a static
3092 method.
3093 New in version 0.4.
3095 .. py:classmethod:: name(parameters)
3098 Like py:method, but indicates that the method is a class method.
3099 New in version 0.6.
3101 .. py:decorator:: name
3104 .. py:decorator:: name(parameters)
3106 Describes a decorator function. The signature should represent
3107 the usage as a decorator. For example, given the functions
3108 def removename(func):
3110 func.__name__ = ''
3111 return func
3112 def setnewname(name):
3114 def decorator(func):
3115 func.__name__ = name
3116 return func
3117 return decorator
3118 the descriptions should look like this:
3120 .. py:decorator:: removename
3122 Remove name of the decorated function.
3124 .. py:decorator:: setnewname(name)
3126 Set name of the decorated function to *name*.
3128 (as opposed to .. py:decorator:: removename(func).)
3130 There is no py:deco role to link to a decorator that is marked
3132 up with this directive; rather, use the py:func role.
3133 .. py:decoratormethod:: name
3135 .. py:decoratormethod:: name(signature)
3137 Same as py:decorator, but for decorators that are methods.
3138 Refer to a decorator method using the py:meth role.
3140 Python Signatures
3142 Signatures of functions, methods and class constructors can be given
3143 like they would be written in Python.
3144 Default values for optional arguments can be given (but if they contain
3146 commas, they will confuse the signature parser). Python 3-style argu‐
3147 ment annotations can also be given as well as return type annotations:
3148 .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3150 For functions with optional parameters that don’t have default values
3152 (typically functions implemented in C extension modules without keyword
3153 argument support), you can use brackets to specify the optional parts:
3154 compile(source[, filename[, symbol]])
3156 It is customary to put the opening bracket before the comma.
3158 Info field lists
3160 New in version 0.4.
3161 Inside Python object description directives, reST field lists with
3164 these fields are recognized and formatted nicely:
3165 · param, parameter, arg, argument, key, keyword: Description of a
3167 parameter.
3168 · type: Type of a parameter. Creates a link if possible.
3170 · raises, raise, except, exception: That (and when) a specific excep‐
3172 tion is raised.
3173 · var, ivar, cvar: Description of a variable.
3175 · vartype: Type of a variable. Creates a link if possible.
3177 · returns, return: Description of the return value.
3179 · rtype: Return type. Creates a link if possible.
3181 NOTE:
3183 In current release, all var, ivar and cvar are represented as “Vari‐
3184 able”. There is no difference at all.
3185 The field names must consist of one of these keywords and an argument
3187 (except for returns and rtype, which do not need an argument). This is
3188 best explained by an example:
3189 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3191 Send a message to a recipient
3193 :param str sender: The person sending the message
3195 :param str recipient: The recipient of the message
3196 :param str message_body: The body of the message
3197 :param priority: The priority of the message, can be a number 1-5
3198 :type priority: integer or None
3199 :return: the message id
3200 :rtype: int
3201 :raises ValueError: if the message_body exceeds 160 characters
3202 :raises TypeError: if the message_body is not a basestring
3203 This will render like this:
3205 send_message(sender, recipient, message_body[, priority=1])
3207 Send a message to a recipient
3208 Parameters
3210 · sender (str) – The person sending the message
3212 · recipient (str) – The recipient of the message
3214 · message_body (str) – The body of the message
3216 · priority (integer or None) – The priority of the
3218 message, can be a number 1-5
3219 Returns
3221 the message id
3222 Return type
3224 int
3225 Raises
3227 · ValueError – if the message_body exceeds 160 charac‐
3229 ters
3230 · TypeError – if the message_body is not a basestring
3232 It is also possible to combine parameter type and description, if the
3234 type is a single word, like this:
3235 :param int priority: The priority of the message, can be a number 1-5
3237 New in version 1.5.
3239 Container types such as lists and dictionaries can be linked automati‐
3242 cally using the following syntax:
3243 :type priorities: list(int)
3245 :type priorities: list[int]
3246 :type mapping: dict(str, int)
3247 :type mapping: dict[str, int]
3248 :type point: tuple(float, float)
3249 :type point: tuple[float, float]
3250 Multiple types in a type field will be linked automatically if sepa‐
3252 rated by the word “or”:
3253 :type an_arg: int or None
3255 :vartype a_var: str or int
3256 :rtype: float or str
3257 Cross-referencing Python objects
3259 The following roles refer to objects in modules and are possibly hyper‐
3260 linked if a matching identifier is found:
3261 :py:mod:
3263 Reference a module; a dotted name may be used. This should also
3264 be used for package names.
3265 :py:func:
3267 Reference a Python function; dotted names may be used. The role
3268 text needs not include trailing parentheses to enhance readabil‐
3269 ity; they will be added automatically by Sphinx if the add_func‐
3270 tion_parentheses config value is True (the default).
3271 :py:data:
3273 Reference a module-level variable.
3274 :py:const:
3276 Reference a “defined” constant. This may be a Python variable
3277 that is not intended to be changed.
3278 :py:class:
3280 Reference a class; a dotted name may be used.
3281 :py:meth:
3283 Reference a method of an object. The role text can include the
3284 type name and the method name; if it occurs within the descrip‐
3285 tion of a type, the type name can be omitted. A dotted name may
3286 be used.
3287 :py:attr:
3289 Reference a data attribute of an object.
3290 :py:exc:
3292 Reference an exception. A dotted name may be used.
3293 :py:obj:
3295 Reference an object of unspecified type. Useful e.g. as the
3296 default_role.
3297 New in version 0.4.
3299 The name enclosed in this markup can include a module name and/or a
3302 class name. For example, :py:func:`filter` could refer to a function
3303 named filter in the current module, or the built-in function of that
3304 name. In contrast, :py:func:`foo.filter` clearly refers to the filter
3305 function in the foo module.
3306 Normally, names in these roles are searched first without any further
3308 qualification, then with the current module name prepended, then with
3309 the current module and class name (if any) prepended. If you prefix
3310 the name with a dot, this order is reversed. For example, in the docu‐
3311 mentation of Python’s codecs module, :py:func:`open` always refers to
3312 the built-in function, while :py:func:`.open` refers to codecs.open().
3313 A similar heuristic is used to determine whether the name is an
3315 attribute of the currently documented class.
3316 Also, if the name is prefixed with a dot, and no exact match is found,
3318 the target is taken as a suffix and all object names with that suffix
3319 are searched. For example, :py:meth:`.TarFile.close` references the
3320 tarfile.TarFile.close() function, even if the current module is not
3321 tarfile. Since this can get ambiguous, if there is more than one pos‐
3322 sible match, you will get a warning from Sphinx.
3323 Note that you can combine the ~ and . prefixes:
3325 :py:meth:`~.TarFile.close` will reference the tarfile.TarFile.close()
3326 method, but the visible link caption will only be close().
3327 The C Domain
3329 The C domain (name c) is suited for documentation of C API.
3330 .. c:function:: function prototype
3332 Describes a C function. The signature should be given as in C,
3333 e.g.:
3334 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3336 This is also used to describe function-like preprocessor macros.
3338 The names of the arguments should be given so they may be used
3339 in the description.
3340 Note that you don’t have to backslash-escape asterisks in the
3342 signature, as it is not parsed by the reST inliner.
3343 .. c:member:: declaration
3345 Describes a C struct member. Example signature:
3346 .. c:member:: PyObject* PyTypeObject.tp_bases
3348 The text of the description should include the range of values
3350 allowed, how the value should be interpreted, and whether the
3351 value can be changed. References to structure members in text
3352 should use the member role.
3353 .. c:macro:: name
3355 Describes a “simple” C macro. Simple macros are macros which
3356 are used for code expansion, but which do not take arguments so
3357 cannot be described as functions. This is a simple C-language
3358 #define. Examples of its use in the Python documentation
3359 include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.
3360 .. c:type:: name
3362 Describes a C type (whether defined by a typedef or struct). The
3363 signature should just be the type name.
3364 .. c:var:: declaration
3366 Describes a global C variable. The signature should include the
3367 type, such as:
3368 .. c:var:: PyObject* PyClass_Type
3370 Cross-referencing C constructs
3372 The following roles create cross-references to C-language constructs if
3373 they are defined in the documentation:
3374 :c:func:
3376 Reference a C-language function. Should include trailing paren‐
3377 theses.
3378 :c:member:
3380 Reference a C-language member of a struct.
3381 :c:macro:
3383 Reference a “simple” C macro, as defined above.
3384 :c:type:
3386 Reference a C-language type.
3387 :c:data:
3389 Reference a C-language variable.
3390 The C++ Domain
3392 The C++ domain (name cpp) supports documenting C++ projects.
3393 Directives
3395 The following directives are available. All declarations can start with
3396 a visibility statement (public, private or protected).
3397 .. cpp:class:: class specifier
3399 Describe a class/struct, possibly with specification of inheri‐
3400 tance, e.g.,:
3401 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3403 The class can be directly declared inside a nested scope, e.g.,:
3405 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3407 A class template can be declared:
3409 .. cpp:class:: template<typename T, std::size_t N> std::array
3411 or with a line break:
3413 .. cpp:class:: template<typename T, std::size_t N> \
3415 std::array
3416 Full and partial template specialisations can be declared:
3418 .. cpp:class:: template<> \
3420 std::array<bool, 256>
3421 .. cpp:class:: template<typename T> \
3423 std::array<T, 42>
3424 .. cpp:function:: (member) function prototype
3426 Describe a function or member function, e.g.,:
3427 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3429 A function with parameters and types.
3431 .. cpp:function:: bool myMethod(int, double)
3433 A function with unnamed parameters.
3435 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3437 An overload for the indexing operator.
3439 .. cpp:function:: operator bool() const
3441 A casting operator.
3443 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3445 A constexpr function.
3447 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3449 A copy constructor with default implementation.
3451 Function templates can also be described:
3453 .. cpp:function:: template<typename U> \
3455 void print(U &&u)
3456 and function template specialisations:
3458 .. cpp:function:: template<> \
3460 void print(int i)
3461 .. cpp:member:: (member) variable declaration
3463 .. cpp:var:: (member) variable declaration
3465 Describe a variable or member variable, e.g.,:
3466 .. cpp:member:: std::string MyClass::myMember
3468 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3470 .. cpp:member:: int a = 42
3472 Variable templates can also be described:
3474 .. cpp:member:: template<class T> \
3476 constexpr T pi = T(3.1415926535897932385)
3477 .. cpp:type:: typedef declaration
3479 .. cpp:type:: name
3481 .. cpp:type:: type alias declaration
3483 Describe a type as in a typedef declaration, a type alias decla‐
3484 ration, or simply the name of a type with unspecified type,
3485 e.g.,:
3486 .. cpp:type:: std::vector<int> MyList
3488 A typedef-like declaration of a type.
3490 .. cpp:type:: MyContainer::const_iterator
3492 Declaration of a type alias with unspecified type.
3494 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3496 Declaration of a type alias.
3498 A type alias can also be templated:
3500 .. cpp:type:: template<typename T> \
3502 MyContainer = std::vector<T>
3503 The example are rendered as follows.
3505 typedef std::vector<int> MyList
3507 A typedef-like declaration of a type.
3508 type MyContainer::const_iterator
3510 Declaration of a type alias with unspecified type.
3511 using MyType = std::unordered_map<int, std::string>
3513 Declaration of a type alias.
3514 template<typename T> using MyContainer = std::vector<T>
3516 .. cpp:enum:: unscoped enum declaration
3518 .. cpp:enum-struct:: scoped enum declaration
3520 .. cpp:enum-class:: scoped enum declaration
3522 Describe a (scoped) enum, possibly with the underlying type
3523 specified. Any enumerators declared inside an unscoped enum
3524 will be declared both in the enum scope and in the parent scope.
3525 Examples:
3526 .. cpp:enum:: MyEnum
3528 An unscoped enum.
3530 .. cpp:enum:: MySpecificEnum : long
3532 An unscoped enum with specified underlying type.
3534 .. cpp:enum-class:: MyScopedEnum
3536 A scoped enum.
3538 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3540 A scoped enum with non-default visibility, and with a specified underlying type.
3542 .. cpp:enumerator:: name
3544 .. cpp:enumerator:: name = constant
3546 Describe an enumerator, optionally with its value defined,
3547 e.g.,:
3548 .. cpp:enumerator:: MyEnum::myEnumerator
3550 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3552 .. cpp:concept:: template-parameter-list name
3554 WARNING:
3556 The support for concepts is experimental. It is based on the
3557 current draft standard and the Concepts Technical Specifica‐
3558 tion. The features may change as they evolve.
3559 Describe a concept. It must have exactly 1 template parameter
3561 list. The name may be a nested name. Example:
3562 .. cpp:concept:: template<typename It> std::Iterator
3564 Proxy to an element of a notional sequence that can be compared,
3566 indirected, or incremented.
3567 **Notation**
3569 .. cpp:var:: It r
3571 An lvalue.
3573 **Valid Expressions**
3575 - :cpp:expr:`*r`, when :cpp:expr:`r` is dereferenceable.
3577 - :cpp:expr:`++r`, with return type :cpp:expr:`It&`, when :cpp:expr:`r` is incrementable.
3578 This will render as follows:
3580 template<typename It> concept std::Iterator
3582 Proxy to an element of a notional sequence that can be
3583 compared, indirected, or incremented.
3584 Notation
3586 It r An lvalue.
3588 Valid Expressions
3590 · *r, when r is dereferenceable.
3592 · ++r, with return type It&, when r is incrementable.
3594 Options
3596 Some directives support options:
3597 · :noindex:, see Basic Markup.
3599 · :tparam-line-spec:, for templated declarations. If specified, each
3601 template parameter will be rendered on a separate line.
3602 Constrained Templates
3604 WARNING:
3605 The support for concepts is experimental. It is based on the current
3606 draft standard and the Concepts Technical Specification. The fea‐
3607 tures may change as they evolve.
3608 NOTE:
3610 Sphinx does not currently support requires clauses.
3611 Placeholders
3613 Declarations may use the name of a concept to introduce constrained
3614 template parameters, or the keyword auto to introduce unconstrained
3615 template parameters:
3616 .. cpp:function:: void f(auto &&arg)
3618 A function template with a single unconstrained template parameter.
3620 .. cpp:function:: void f(std::Iterator it)
3622 A function template with a single template parameter, constrained by the
3624 Iterator concept.
3625 Template Introductions
3627 Simple constrained function or class templates can be declared with a
3628 template introduction instead of a template parameter list:
3629 .. cpp:function:: std::Iterator{It} void advance(It &it)
3631 A function template with a template parameter constrained to be an Iterator.
3633 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3635 A class template with a template parameter constrained to be LessThanComparable.
3637 They are rendered as follows.
3639 std::Iterator{It} void advance(It &it)
3641 A function template with a template parameter constrained to be
3642 an Iterator.
3643 std::LessThanComparable{T} class MySortedContainer
3645 A class template with a template parameter constrained to be
3646 LessThanComparable.
3647 Note however that no checking is performed with respect to parameter
3649 compatibility. E.g., Iterator{A, B, C} will be accepted as an introduc‐
3650 tion even though it would not be valid C++.
3651 Inline Expressions and Tpes
3653 :cpp:expr:
3654 A role for inserting a C++ expression or type as inline text.
3655 For example:
3656 .. cpp:var:: int a = 42
3658 .. cpp:function:: int f(int i)
3660 An expression: :cpp:expr:`a * f(a)`.
3662 A type: :cpp:expr:`const MySortedContainer<int>&`.
3663 will be rendered as follows:
3665 int a = 42
3667 int f(int i)
3669 An expression: a * f(a). A type: const MySortedContainer<int>&.
3671 Namespacing
3673 Declarations in the C++ domain are as default placed in global scope.
3674 The current scope can be changed using three namespace directives.
3675 They manage a stack declarations where cpp:namespace resets the stack
3676 and changes a given scope. The cpp:namespace-push directive changes
3677 the scope to a given inner scope of the current one. The cpp:names‐
3678 pace-pop directive undos the most recent cpp:namespace-push directive.
3679 .. cpp:namespace:: scope specification
3681 Changes the current scope for the subsequent objects to the
3682 given scope, and resets the namespace directive stack. Note
3683 that the namespace does not need to correspond to C++ names‐
3684 paces, but can end in names of classes, e.g.,:
3685 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3687 All subsequent objects will be defined as if their name were
3689 declared with the scope prepended. The subsequent cross-refer‐
3690 ences will be searched for starting in the current scope.
3691 Using NULL, 0, or nullptr as the scope will change to global
3693 scope.
3694 A namespace declaration can also be templated, e.g.,:
3696 .. cpp:class:: template<typename T> \
3698 std::vector
3699 .. cpp:namespace:: template<typename T> std::vector
3701 .. cpp:function:: std::size_t size() const
3703 declares size as a member function of the class template
3705 std::vector. Equivalently this could have been declared using:
3706 .. cpp:class:: template<typename T> \
3708 std::vector
3709 .. cpp:function:: std::size_t size() const
3711 or::
3713 .. cpp:class:: template<typename T> \
3715 std::vector
3716 .. cpp:namespace-push:: scope specification
3718 Change the scope relatively to the current scope. For example,
3719 after:
3720 .. cpp:namespace:: A::B
3722 .. cpp:namespace-push:: C::D
3724 the current scope will be A::B::C::D.
3726 .. cpp:namespace-pop::
3728 Undo the previous cpp:namespace-push directive (not just pop a
3729 scope). For example, after:
3730 .. cpp:namespace:: A::B
3732 .. cpp:namespace-push:: C::D
3734 .. cpp:namespace-pop::
3736 the current scope will be A::B (not A::B::C).
3738 If no previous cpp:namespace-push directive has been used, but
3740 only a cpp:namespace directive, then the current scope will be
3741 reset to global scope. That is, .. cpp:namespace:: A::B is
3742 equivalent to:
3743 .. cpp:namespace:: nullptr
3745 .. cpp:namespace-push:: A::B
3747 Info field lists
3749 The C++ directives support the following info fields (see also Info
3750 field lists):
3751 · param, parameter, arg, argument: Description of a parameter.
3753 · tparam: Description of a template parameter.
3755 · returns, return: Description of a return value.
3757 · throws, throw, exception: Description of a possibly thrown exception.
3759 Cross-referencing
3761 These roles link to the given declaration types:
3762 :cpp:any:
3764 :cpp:class:
3766 :cpp:func:
3768 :cpp:member:
3770 :cpp:var:
3772 :cpp:type:
3774 :cpp:concept:
3776 :cpp:enum:
3778 :cpp:enumerator:
3780 Reference a C++ declaration by name (see below for details).
3781 The name must be properly qualified relative to the position of
3782 the link.
3783 Note on References with Templates Parameters/Arguments
3785 Sphinx’s syntax to give references a custom title can inter‐
3787 fere with linking to class templates, if nothing follows the
3788 closing angle bracket, i.e. if the link looks like this:
3789 :cpp:class:`MyClass<int>`. This is interpreted as a link to
3790 int with a title of MyClass. In this case, please escape the
3791 opening angle bracket with a backslash, like this:
3792 :cpp:class:`MyClass\<int>`.
3793 Note on References to Overloaded Functions
3795 It is currently impossible to link to a specific version of
3797 an overloaded method. Currently the C++ domain is the first
3798 domain that has basic support for overloaded methods and
3799 until there is more data for comparison we don’t want to
3800 select a bad syntax to reference a specific overload. Cur‐
3801 rently Sphinx will link to the first overloaded version of
3802 the method / function.
3803 Declarations without template parameters and template arguments
3805 For linking to non-templated declarations the name must be a nested
3806 name, e.g., f or MyClass::f.
3807 Templated declarations
3809 Assume the following declarations.
3810 class Wrapper
3812 template<typename TOuter> class Outer
3814 template<typename TInner> class Inner
3816 In general the reference must include the template paraemter declara‐
3818 tions, e.g., template\<typename TOuter> Wrapper::Outer (‐
3819 template<typename TOuter> Wrapper::Outer). Currently the lookup only
3820 succeed if the template parameter identifiers are equal strings. That
3821 is, template\<typename UOuter> Wrapper::Outer will not work.
3822 The inner class template can not be directly referenced, unless the
3824 current namespace is changed or the following shorthand is used. If a
3825 template parameter list is omitted, then the lookup will assume either
3826 a template or a non-template, but not a partial template specialisa‐
3827 tion. This means the following references work.
3828 · Wrapper::Outer (Wrapper::Outer)
3830 · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
3832 · template\<typename TInner> Wrapper::Outer::Inner (template<typename
3834 TInner> Wrapper::Outer::Inner)
3835 (Full) Template Specialisations
3837 Assume the following declarations.
3838 template<typename TOuter> class Outer
3840 template<typename TInner> class Inner
3842 template<> class Outer<int>
3844 template<typename TInner> class Inner
3846 template<> class Inner<bool>
3848 In general the reference must include a template parameter list for
3850 each template argument list. The full specialisation above can there‐
3851 fore be referenced with template\<> Outer\<int> (template<> Outer<int>)
3852 and template\<> template\<> Outer\<int>::Inner\<bool> (template<> tem‐
3853 plate<> Outer<int>::Inner<bool>). As a shorthand the empty template
3854 parameter list can be omitted, e.g., Outer\<int> (Outer<int>) and
3855 Outer\<int>::Inner\<bool> (Outer<int>::Inner<bool>).
3856 Partial Template Specialisations
3858 Assume the following declaration.
3859 template<typename T> class Outer<T *>
3861 References to partial specialisations must always include the template
3863 parameter lists, e.g., template\<typename T> Outer\<T*> (‐
3864 template<typename T> Outer<T*>). Currently the lookup only succeed if
3865 the template parameter identifiers are equal strings.
3866 Configuration Variables
3868 See cpp-config.
3869 The Standard Domain
3871 The so-called “standard” domain collects all markup that doesn’t war‐
3872 rant a domain of its own. Its directives and roles are not prefixed
3873 with a domain name.
3874 The standard domain is also where custom object descriptions, added
3876 using the add_object_type() API, are placed.
3877 There is a set of directives allowing documenting command-line pro‐
3879 grams:
3880 .. option:: name args, name args, ...
3882 Describes a command line argument or switch. Option argument
3883 names should be enclosed in angle brackets. Examples:
3884 .. option:: dest_dir
3886 Destination directory.
3888 .. option:: -m <module>, --module <module>
3890 Run a module as a script.
3892 The directive will create cross-reference targets for the given
3894 options, referencable by option (in the example case, you’d use
3895 something like :option:`dest_dir`, :option:`-m`, or
3896 :option:`--module`).
3897 cmdoption directive is a deprecated alias for the option direc‐
3899 tive.
3900 .. envvar:: name
3902 Describes an environment variable that the documented code or
3903 program uses or defines. Referencable by envvar.
3904 .. program:: name
3906 Like py:currentmodule, this directive produces no output.
3907 Instead, it serves to notify Sphinx that all following option
3908 directives document options for the program called name.
3909 If you use program, you have to qualify the references in your
3911 option roles by the program name, so if you have the following
3912 situation
3913 .. program:: rm
3915 .. option:: -r
3917 Work recursively.
3919 .. program:: svn
3921 .. option:: -r revision
3923 Specify the revision to work upon.
3925 then :option:`rm -r` would refer to the first option, while
3927 :option:`svn -r` would refer to the second one.
3928 The program name may contain spaces (in case you want to docu‐
3930 ment subcommands like svn add and svn commit separately).
3931 New in version 0.5.
3933 There is also a very generic object description directive, which is not
3936 tied to any domain:
3937 .. describe:: text
3939 .. object:: text
3941 This directive produces the same formatting as the specific ones
3942 provided by domains, but does not create index entries or
3943 cross-referencing targets. Example:
3944 .. describe:: PAPER
3946 You can set this variable to select a paper size.
3948 The JavaScript Domain
3950 The JavaScript domain (name js) provides the following directives:
3951 .. js:module:: name
3953 This directive sets the module name for object declarations that
3954 follow after. The module name is used in the global module index
3955 and in cross references. This directive does not create an
3956 object heading like py:class would, for example.
3957 By default, this directive will create a linkable entity and
3959 will cause an entry in the global module index, unless the noin‐
3960 dex option is specified. If this option is specified, the
3961 directive will only update the current module name.
3962 To clear the current module, set the module name to null or None
3964 New in version 1.6.
3966 .. js:function:: name(signature)
3969 Describes a JavaScript function or method. If you want to
3970 describe arguments as optional use square brackets as documented
3971 for Python signatures.
3972 You can use fields to give more details about arguments and
3974 their expected types, errors which may be thrown by the func‐
3975 tion, and the value being returned:
3976 .. js:function:: $.getJSON(href, callback[, errback])
3978 :param string href: An URI to the location of the resource.
3980 :param callback: Gets called with the object.
3981 :param errback:
3982 Gets called in case the request fails. And a lot of other
3983 text so we need multiple lines.
3984 :throws SomeError: For whatever reason in that case.
3985 :returns: Something.
3986 This is rendered as:
3988 $.getJSON(href, callback[, errback])
3990 Arguments
3992 · href (string) – An URI to the location of the
3994 resource.
3995 · callback – Gets called with the object.
3997 · errback – Gets called in case the request
3999 fails. And a lot of other text so we need
4000 multiple lines.
4001 Throws SomeError – For whatever reason in that case.
4003 Returns
4005 Something.
4006 .. js:method:: name(signature)
4008 This directive is an alias for js:function, however it describes
4009 a function that is implemented as a method on a class object.
4010 New in version 1.6.
4012 .. js:class:: name
4015 Describes a constructor that creates an object. This is basi‐
4016 cally like a function but will show up with a class prefix:
4017 .. js:class:: MyAnimal(name[, age])
4019 :param string name: The name of the animal
4021 :param number age: an optional age for the animal
4022 This is rendered as:
4024 class MyAnimal(name[, age])
4026 Arguments
4028 · name (string) – The name of the animal
4030 · age (number) – an optional age for the animal
4032 .. js:data:: name
4034 Describes a global variable or constant.
4035 .. js:attribute:: object.name
4037 Describes the attribute name of object.
4038 These roles are provided to refer to the described objects:
4040 :js:mod:
4042 :js:func:
4044 :js:meth:
4046 :js:class:
4048 :js:data:
4050 :js:attr:
4052 The reStructuredText domain
4054 The reStructuredText domain (name rst) provides the following direc‐
4055 tives:
4056 .. rst:directive:: name
4058 Describes a reST directive. The name can be a single directive
4059 name or actual directive syntax (.. prefix and :: suffix) with
4060 arguments that will be rendered differently. For example:
4061 .. rst:directive:: foo
4063 Foo description.
4065 .. rst:directive:: .. bar:: baz
4067 Bar description.
4069 will be rendered as:
4071 .. foo::
4073 Foo description.
4074 .. bar:: baz
4076 Bar description.
4077 .. rst:role:: name
4079 Describes a reST role. For example:
4080 .. rst:role:: foo
4082 Foo description.
4084 will be rendered as:
4086 :foo: Foo description.
4088 These roles are provided to refer to the described objects:
4090 :rst:dir:
4092 :rst:role:
4094 More domains
4096 The sphinx-contrib repository contains more domains available as exten‐
4097 sions; currently Ada, CoffeeScript, Erlang, HTTP, Lasso, MATLAB, PHP,
4098 and Ruby domains. Also available are domains for Chapel, Common Lisp,
4099 dqn, Go, Jinja, Operation, and Scala.
4100
4102 These are the built-in Sphinx builders. More builders can be added by
4103 extensions.
4104 The builder’s “name” must be given to the -b command-line option of
4106 sphinx-build to select a builder.
4107 class sphinx.builders.html.StandaloneHTMLBuilder
4109 This is the standard HTML builder. Its output is a directory
4110 with HTML files, complete with style sheets and optionally the
4111 reST sources. There are quite a few configuration values that
4112 customize the output of this builder, see the chapter
4113 html-options for details.
4114 name = 'html'
4116 format = 'html'
4118 supported_image_types = ['image/svg+xml', 'image/png',
4120 'image/gif', 'image/jpeg']
4121 class sphinx.builders.html.DirectoryHTMLBuilder
4123 This is a subclass of the standard HTML builder. Its output is
4124 a directory with HTML files, where each file is called
4125 index.html and placed in a subdirectory named like its page
4126 name. For example, the document markup/rest.rst will not result
4127 in an output file markup/rest.html, but markup/rest/index.html.
4128 When generating links between pages, the index.html is omitted,
4129 so that the URL would look like markup/rest/.
4130 name = 'dirhtml'
4132 format = 'html'
4134 supported_image_types = ['image/svg+xml', 'image/png',
4136 'image/gif', 'image/jpeg']
4137 New in version 0.6.
4139 class sphinx.builders.html.SingleFileHTMLBuilder
4142 This is an HTML builder that combines the whole project in one
4143 output file. (Obviously this only works with smaller projects.)
4144 The file is named like the master document. No indices will be
4145 generated.
4146 name = 'singlehtml'
4148 format = 'html'
4150 supported_image_types = ['image/svg+xml', 'image/png',
4152 'image/gif', 'image/jpeg']
4153 New in version 1.0.
4155 class sphinx.builders.htmlhelp.HTMLHelpBuilder
4158 This builder produces the same output as the standalone HTML
4159 builder, but also generates HTML Help support files that allow
4160 the Microsoft HTML Help Workshop to compile them into a CHM
4161 file.
4162 name = 'htmlhelp'
4164 format = 'html'
4166 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
4168 class sphinx.builders.qthelp.QtHelpBuilder
4170 This builder produces the same output as the standalone HTML
4171 builder, but also generates Qt help collection support files
4172 that allow the Qt collection generator to compile them.
4173 name = 'qthelp'
4175 format = 'html'
4177 supported_image_types = ['image/svg+xml', 'image/png',
4179 'image/gif', 'image/jpeg']
4180 class sphinx.builders.applehelp.AppleHelpBuilder
4182 This builder produces an Apple Help Book based on the same out‐
4183 put as the standalone HTML builder.
4184 If the source directory contains any .lproj folders, the one
4186 corresponding to the selected language will have its contents
4187 merged with the generated output. These folders will be ignored
4188 by all other documentation types.
4189 In order to generate a valid help book, this builder requires
4191 the command line tool hiutil, which is only available on Mac OS
4192 X 10.6 and above. You can disable the indexing step by setting
4193 applehelp_disable_external_tools to True, in which case the out‐
4194 put will not be valid until hiutil has been run on all of the
4195 .lproj folders within the bundle.
4196 name = 'applehelp'
4198 format = 'html'
4200 supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
4202 'image/tiff', 'image/jp2', 'image/svg+xml']
4203 New in version 1.3.
4205 class sphinx.builders.devhelp.DevhelpBuilder
4208 This builder produces the same output as the standalone HTML
4209 builder, but also generates GNOME Devhelp support file that
4210 allows the GNOME Devhelp reader to view them.
4211 name = 'devhelp'
4213 format = 'html'
4215 supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
4217 class sphinx.builders.epub3.Epub3Builder
4219 This builder produces the same output as the standalone HTML
4220 builder, but also generates an epub file for ebook readers. See
4221 epub-faq for details about it. For definition of the epub for‐
4222 mat, have a look at http://idpf.org/epub or
4223 https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3
4224 files.
4225 name = 'epub'
4227 format = 'html'
4229 supported_image_types = ['image/svg+xml', 'image/png',
4231 'image/gif', 'image/jpeg']
4232 New in version 1.4.
4234 Changed in version 1.5: Since Sphinx-1.5, the epub3 builder is
4237 used for the default builder of epub.
4238 class sphinx.builders.latex.LaTeXBuilder
4241 This builder produces a bunch of LaTeX files in the output
4242 directory. You have to specify which documents are to be
4243 included in which LaTeX files via the latex_documents configura‐
4244 tion value. There are a few configuration values that customize
4245 the output of this builder, see the chapter latex-options for
4246 details.
4247 The produced LaTeX file uses several LaTeX packages that may not
4249 be present in a “minimal” TeX distribution installation. For
4250 example, on Ubuntu, the following packages need to be installed
4251 for successful PDF builds:
4252 · texlive-latex-recommended
4254 · texlive-fonts-recommended
4256 · texlive-latex-extra
4258 · latexmk (for make latexpdf on GNU/Linux and MacOS X)
4260 · latex-xcolor (old Ubuntu)
4262 · texlive-luatex, texlive-xetex (see latex_engine)
4264 The testing of Sphinx LaTeX is done on Ubuntu trusty with the
4266 above mentioned packages, which are from a TeXLive 2013 snapshot
4267 dated February 2014.
4268 Changed in version 1.6: Formerly, testing had been done on
4270 Ubuntu precise (TeXLive 2009).
4271 NOTE:
4274 Since 1.6, make latexpdf uses latexmk (not on Windows). This
4275 makes sure the needed number of runs is automatically exe‐
4276 cuted to get the cross-references, bookmarks, indices, and
4277 tables of contents right.
4278 One can pass to latexmk options via the LATEXMKOPTS Makefile
4280 variable. For example:
4281 make latexpdf LATEXMKOPTS="-silent"
4283 reduces console output to a minimum.
4285 Also, if latexmk version is 4.52b or higher (Jan 17)
4287 LATEXMKOPTS="-xelatex" will speed up PDF builds via XeLateX
4288 in case of numerous graphics inclusions.
4289 make latexpdf LATEXMKOPTS="-xelatex"
4291 To pass options directly to the (pdf|xe|lua)latex executable,
4293 use variable LATEXOPTS.
4294 make latexpdf LATEXOPTS="--interaction=nonstopmode"
4296 name = 'latex'
4298 format = 'latex'
4300 supported_image_types = ['application/pdf', 'image/png',
4302 'image/jpeg']
4303 Note that a direct PDF builder is being provided by rinohtype. The
4305 builder’s name is rinoh. Refer to the rinohtype manual for details.
4306 There is also PDF builder using ReportLab in rst2pdf version 0.12 or
4307 greater. However, rst2pdf is no longer being actively maintained and
4308 suffers from some problems when used with recent Sphinx versions. See
4309 the rst2pdf manual for usage instructions.
4310 class sphinx.builders.text.TextBuilder
4312 This builder produces a text file for each reST file – this is
4313 almost the same as the reST source, but with much of the markup
4314 stripped for better readability.
4315 name = 'text'
4317 format = 'text'
4319 supported_image_types = []
4321 New in version 0.4.
4323 class sphinx.builders.manpage.ManualPageBuilder
4326 This builder produces manual pages in the groff format. You
4327 have to specify which documents are to be included in which man‐
4328 ual pages via the man_pages configuration value.
4329 name = 'man'
4331 format = 'man'
4333 supported_image_types = []
4335 New in version 1.0.
4337 class sphinx.builders.texinfo.TexinfoBuilder
4340 This builder produces Texinfo files that can be processed into
4341 Info files by the makeinfo program. You have to specify which
4342 documents are to be included in which Texinfo files via the tex‐
4343 info_documents configuration value.
4344 The Info format is the basis of the on-line help system used by
4346 GNU Emacs and the terminal-based program info. See texinfo-faq
4347 for more details. The Texinfo format is the official documenta‐
4348 tion system used by the GNU project. More information on Tex‐
4349 info can be found at https://www.gnu.org/software/texinfo/.
4350 name = 'texinfo'
4352 format = 'texinfo'
4354 supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
4356 New in version 1.1.
4358 class sphinx.builders.html.SerializingHTMLBuilder
4361 This builder uses a module that implements the Python serializa‐
4362 tion API (pickle, simplejson, phpserialize, and others) to dump
4363 the generated HTML documentation. The pickle builder is a sub‐
4364 class of it.
4365 A concrete subclass of this builder serializing to the PHP seri‐
4367 alization format could look like this:
4368 import phpserialize
4370 class PHPSerializedBuilder(SerializingHTMLBuilder):
4372 name = 'phpserialized'
4373 implementation = phpserialize
4374 out_suffix = '.file.phpdump'
4375 globalcontext_filename = 'globalcontext.phpdump'
4376 searchindex_filename = 'searchindex.phpdump'
4377 implementation
4379 A module that implements dump(), load(), dumps() and
4380 loads() functions that conform to the functions with the
4381 same names from the pickle module. Known modules imple‐
4382 menting this interface are simplejson, phpserialize,
4383 plistlib, and others.
4384 out_suffix
4386 The suffix for all regular files.
4387 globalcontext_filename
4389 The filename for the file that contains the “global con‐
4390 text”. This is a dict with some general configuration
4391 values such as the name of the project.
4392 searchindex_filename
4394 The filename for the search index Sphinx generates.
4395 See Serialization builder details for details about the output
4397 format.
4398 New in version 0.5.
4400 class sphinx.builders.html.PickleHTMLBuilder
4403 This builder produces a directory with pickle files containing
4404 mostly HTML fragments and TOC information, for use of a web
4405 application (or custom postprocessing tool) that doesn’t use the
4406 standard HTML templates.
4407 See Serialization builder details for details about the output
4409 format.
4410 name = 'pickle'
4412 The old name web still works as well.
4413 format = 'html'
4415 supported_image_types = ['image/svg+xml', 'image/png',
4417 'image/gif', 'image/jpeg']
4418 The file suffix is .fpickle. The global context is called glob‐
4420 alcontext.pickle, the search index searchindex.pickle.
4421 class sphinx.builders.html.JSONHTMLBuilder
4423 This builder produces a directory with JSON files containing
4424 mostly HTML fragments and TOC information, for use of a web
4425 application (or custom postprocessing tool) that doesn’t use the
4426 standard HTML templates.
4427 See Serialization builder details for details about the output
4429 format.
4430 name = 'json'
4432 format = 'html'
4434 supported_image_types = ['image/svg+xml', 'image/png',
4436 'image/gif', 'image/jpeg']
4437 The file suffix is .fjson. The global context is called global‐
4439 context.json, the search index searchindex.json.
4440 New in version 0.5.
4442 class sphinx.builders.gettext.MessageCatalogBuilder
4445 This builder produces gettext-style message catalogs. Each
4446 top-level file or subdirectory grows a single .pot catalog tem‐
4447 plate.
4448 See the documentation on intl for further reference.
4450 name = 'gettext'
4452 format = ''
4454 supported_image_types = []
4456 New in version 1.1.
4458 class sphinx.builders.changes.ChangesBuilder
4461 This builder produces an HTML overview of all versionadded, ver‐
4462 sionchanged and deprecated directives for the current version.
4463 This is useful to generate a ChangeLog file, for example.
4464 name = 'changes'
4466 format = ''
4468 supported_image_types = []
4470 class sphinx.builders.dummy.DummyBuilder
4472 This builder produces no output. The input is only parsed and
4473 checked for consistency. This is useful for linting purposes.
4474 name = 'dummy'
4476 supported_image_types = []
4478 New in version 1.4.
4480 class sphinx.builders.linkcheck.CheckExternalLinksBuilder
4483 This builder scans all documents for external links, tries to
4484 open them with requests, and writes an overview which ones are
4485 broken and redirected to standard output and to output.txt in
4486 the output directory.
4487 name = 'linkcheck'
4489 format = ''
4491 supported_image_types = []
4493 Changed in version 1.5: Since Sphinx-1.5, the linkcheck builder
4495 comes to use requests module.
4496 class sphinx.builders.xml.XMLBuilder
4499 This builder produces Docutils-native XML files. The output can
4500 be transformed with standard XML tools such as XSLT processors
4501 into arbitrary final forms.
4502 name = 'xml'
4504 format = 'xml'
4506 supported_image_types = []
4508 New in version 1.2.
4510 class sphinx.builders.xml.PseudoXMLBuilder
4513 This builder is used for debugging the Sphinx/Docutils “Reader
4514 to Transform to Writer” pipeline. It produces compact
4515 pretty-printed “pseudo-XML”, files where nesting is indicated by
4516 indentation (no end-tags). External attributes for all elements
4517 are output, and internal attributes for any leftover “pending”
4518 elements are also given.
4519 name = 'pseudoxml'
4521 format = 'pseudoxml'
4523 supported_image_types = []
4525 New in version 1.2.
4527 Built-in Sphinx extensions that offer more builders are:
4530 · doctest
4532 · coverage
4534 Serialization builder details
4536 All serialization builders outputs one file per source file and a few
4537 special files. They also copy the reST source files in the directory
4538 _sources under the output directory.
4539 The PickleHTMLBuilder is a builtin subclass that implements the pickle
4541 serialization interface.
4542 The files per source file have the extensions of out_suffix, and are
4544 arranged in directories just as the source files are. They unserialize
4545 to a dictionary (or dictionary like structure) with these keys:
4546 body The HTML “body” (that is, the HTML rendering of the source
4548 file), as rendered by the HTML translator.
4549 title The title of the document, as HTML (may contain markup).
4551 toc The table of contents for the file, rendered as an HTML <ul>.
4553 display_toc
4555 A boolean that is True if the toc contains more than one entry.
4556 current_page_name
4558 The document name of the current file.
4559 parents, prev and next
4561 Information about related chapters in the TOC tree. Each rela‐
4562 tion is a dictionary with the keys link (HREF for the relation)
4563 and title (title of the related document, as HTML). parents is
4564 a list of relations, while prev and next are a single relation.
4565 sourcename
4567 The name of the source file under _sources.
4568 The special files are located in the root output directory. They are:
4570 SerializingHTMLBuilder.globalcontext_filename
4572 A pickled dict with these keys:
4573 project, copyright, release, version
4575 The same values as given in the configuration file.
4576 style html_style.
4578 last_updated
4580 Date of last build.
4581 builder
4583 Name of the used builder, in the case of pickles this is
4584 always 'pickle'.
4585 titles A dictionary of all documents’ titles, as HTML strings.
4587 SerializingHTMLBuilder.searchindex_filename
4589 An index that can be used for searching the documentation. It
4590 is a pickled list with these entries:
4591 · A list of indexed docnames.
4593 · A list of document titles, as HTML strings, in the same order
4595 as the first list.
4596 · A dict mapping word roots (processed by an English-language
4598 stemmer) to a list of integers, which are indices into the
4599 first list.
4600 environment.pickle
4602 The build environment. This is always a pickle file, indepen‐
4603 dent of the builder and a copy of the environment that was used
4604 when the builder was started.
4605 Todo
4607 Document common members.
4608 Unlike the other pickle files this pickle file requires that the
4610 sphinx package is available on unpickling.
4611
4613 The configuration directory must contain a file named conf.py. This
4614 file (containing Python code) is called the “build configuration file”
4615 and contains (almost) all configuration needed to customize Sphinx
4616 input and output behavior.
4617 An optional file docutils.conf can be added to the configuration
4618 directory to adjust Docutils configuration if not otherwise overri‐
4619 den or set by Sphinx.
4620 The configuration file is executed as Python code at build time (using
4622 execfile(), and with the current directory set to its containing direc‐
4623 tory), and therefore can execute arbitrarily complex code. Sphinx then
4624 reads simple names from the file’s namespace as its configuration.
4625 Important points to note:
4627 · If not otherwise documented, values must be strings, and their
4629 default is the empty string.
4630 · The term “fully-qualified name” refers to a string that names an
4632 importable Python object inside a module; for example, the FQN
4633 "sphinx.builders.Builder" means the Builder class in the
4634 sphinx.builders module.
4635 · Remember that document names use / as the path separator and don’t
4637 contain the file name extension.
4638 · Since conf.py is read as a Python file, the usual rules apply for
4640 encodings and Unicode support: declare the encoding using an encoding
4641 cookie (a comment like # -*- coding: utf-8 -*-) and use Unicode
4642 string literals when you include non-ASCII characters in configura‐
4643 tion values.
4644 · The contents of the config namespace are pickled (so that Sphinx can
4646 find out when configuration changes), so it may not contain unpick‐
4647 leable values – delete them from the namespace with del if appropri‐
4648 ate. Modules are removed automatically, so you don’t need to del
4649 your imports after use.
4650 · There is a special object named tags available in the config file.
4652 It can be used to query and change the tags (see tags). Use
4653 tags.has('tag') to query, tags.add('tag') and tags.remove('tag') to
4654 change. Only tags set via the -t command-line option or via
4655 tags.add('tag') can be queried using tags.has('tag'). Note that the
4656 current builder tag is not available in conf.py, as it is created
4657 after the builder is initialized.
4658 SEE ALSO:
4660 Additional configurations, such as adding stylesheets, javascripts,
4661 builders, etc. can be made through the /extdev/appapi.
4662 General configuration
4664 extensions
4665 A list of strings that are module names of extensions. These can
4666 be extensions coming with Sphinx (named sphinx.ext.*) or custom
4667 ones.
4668 Note that you can extend sys.path within the conf file if your
4670 extensions live in another directory – but make sure you use
4671 absolute paths. If your extension path is relative to the con‐
4672 figuration directory, use os.path.abspath() like so:
4673 import sys, os
4675 sys.path.append(os.path.abspath('sphinxext'))
4677 extensions = ['extname']
4679 That way, you can load an extension called extname from the sub‐
4681 directory sphinxext.
4682 The configuration file itself can be an extension; for that, you
4684 only need to provide a setup() function in it.
4685 source_suffix
4687 The file name extension, or list of extensions, of source files.
4688 Only files with this suffix will be read as sources. Default is
4689 '.rst'.
4690 Changed in version 1.3: Can now be a list of extensions.
4692 source_encoding
4695 The encoding of all reST source files. The recommended encod‐
4696 ing, and the default value, is 'utf-8-sig'.
4697 New in version 0.5: Previously, Sphinx accepted only UTF-8
4699 encoded sources.
4700 source_parsers
4703 If given, a dictionary of parser classes for different source
4704 suffices. The keys are the suffix, the values can be either a
4705 class or a string giving a fully-qualified name of a parser
4706 class. The parser class can be either docutils.parsers.Parser
4707 or sphinx.parsers.Parser. Files with a suffix that is not in
4708 the dictionary will be parsed with the default reStructuredText
4709 parser.
4710 For example:
4712 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4714 NOTE:
4716 Read more about how to use Markdown with Sphinx at markdown.
4717 New in version 1.3.
4719 master_doc
4722 The document name of the “master” document, that is, the docu‐
4723 ment that contains the root toctree directive. Default is 'con‐
4724 tents'.
4725 exclude_patterns
4727 A list of glob-style patterns that should be excluded when look‐
4728 ing for source files. [1] They are matched against the source
4729 file names relative to the source directory, using slashes as
4730 directory separators on all platforms.
4731 Example patterns:
4733 · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4735 entry in unused_docs)
4736 · 'library/xml' – ignores the library/xml directory
4738 · 'library/xml*' – ignores all files and directories starting
4740 with library/xml
4741 · '**/.svn' – ignores all .svn directories
4743 exclude_patterns is also consulted when looking for static files
4745 in html_static_path and html_extra_path.
4746 New in version 1.0.
4748 templates_path
4751 A list of paths that contain extra templates (or templates that
4752 overwrite builtin/theme-specific templates). Relative paths are
4753 taken as relative to the configuration directory.
4754 Changed in version 1.3: As these files are not meant to be
4756 built, they are automatically added to exclude_patterns.
4757 template_bridge
4760 A string with the fully-qualified name of a callable (or simply
4761 a class) that returns an instance of TemplateBridge. This
4762 instance is then used to render HTML documents, and possibly the
4763 output of other builders (currently the changes builder). (Note
4764 that the template bridge must be made theme-aware if HTML themes
4765 are to be used.)
4766 rst_epilog
4768 A string of reStructuredText that will be included at the end of
4769 every source file that is read. This is the right place to add
4770 substitutions that should be available in every file. An exam‐
4771 ple:
4772 rst_epilog = """
4774 .. |psf| replace:: Python Software Foundation
4775 """
4776 New in version 0.6.
4778 rst_prolog
4781 A string of reStructuredText that will be included at the begin‐
4782 ning of every source file that is read.
4783 New in version 1.0.
4785 primary_domain
4788 The name of the default domain. Can also be None to disable a
4789 default domain. The default is 'py'. Those objects in other
4790 domains (whether the domain name is given explicitly, or
4791 selected by a default-domain directive) will have the domain
4792 name explicitly prepended when named (e.g., when the default
4793 domain is C, Python functions will be named “Python function”,
4794 not just “function”).
4795 New in version 1.0.
4797 default_role
4800 The name of a reST role (builtin or Sphinx extension) to use as
4801 the default role, that is, for text marked up `like this`. This
4802 can be set to 'py:obj' to make `filter` a cross-reference to the
4803 Python function “filter”. The default is None, which doesn’t
4804 reassign the default role.
4805 The default role can always be set within individual documents
4807 using the standard reST default-role directive.
4808 New in version 0.4.
4810 keep_warnings
4813 If true, keep warnings as “system message” paragraphs in the
4814 built documents. Regardless of this setting, warnings are
4815 always written to the standard error stream when sphinx-build is
4816 run.
4817 The default is False, the pre-0.5 behavior was to always keep
4819 them.
4820 New in version 0.5.
4822 suppress_warnings
4825 A list of warning types to suppress arbitrary warning messages.
4826 Sphinx supports following warning types:
4828 · app.add_node
4830 · app.add_directive
4832 · app.add_role
4834 · app.add_generic_role
4836 · app.add_source_parser
4838 · download.not_readable
4840 · image.not_readable
4842 · ref.term
4844 · ref.ref
4846 · ref.numref
4848 · ref.keyword
4850 · ref.option
4852 · ref.citation
4854 · ref.footnote
4856 · ref.doc
4858 · ref.python
4860 · misc.highlighting_failure
4862 · toc.secnum
4864 · epub.unknown_project_files
4866 You can choose from these types.
4868 Now, this option should be considered experimental.
4870 New in version 1.4.
4872 Changed in version 1.5: Added misc.highlighting_failure
4875 Changed in version 1.5.1: Added epub.unknown_project_files
4878 Changed in version 1.6: Added ref.footnote
4881 needs_sphinx
4884 If set to a major.minor version string like '1.1', Sphinx will
4885 compare it with its version and refuse to build if it is too
4886 old. Default is no requirement.
4887 New in version 1.0.
4889 Changed in version 1.4: also accepts micro version string
4892 needs_extensions
4895 This value can be a dictionary specifying version requirements
4896 for extensions in extensions, e.g. needs_extensions = {'sphinx‐
4897 contrib.something': '1.5'}. The version strings should be in
4898 the form major.minor. Requirements do not have to be specified
4899 for all extensions, only for those you want to check.
4900 This requires that the extension specifies its version to Sphinx
4902 (see dev-extensions for how to do that).
4903 New in version 1.3.
4905 manpages_url
4908 A URL to cross-reference manpage directives. If this is defined
4909 to https://manpages.debian.org/{path}, the :manpage:`man(1)`
4910 role will like to <https://manpages.debian.org/man(1)>. The pat‐
4911 terns available are:
4912 · page - the manual page (man)
4914 · section - the manual section (1)
4916 · path - the original manual page and section specified
4918 (man(1))
4919 This also supports manpages specified as man.1.
4921 NOTE:
4923 This currently affects only HTML writers but could be
4924 expanded in the future.
4925 New in version 1.7.
4927 nitpicky
4930 If true, Sphinx will warn about all references where the target
4931 cannot be found. Default is False. You can activate this mode
4932 temporarily using the -n command-line switch.
4933 New in version 1.0.
4935 nitpick_ignore
4938 A list of (type, target) tuples (by default empty) that should
4939 be ignored when generating warnings in “nitpicky mode”. Note
4940 that type should include the domain name if present. Example
4941 entries would be ('py:func', 'int') or ('envvar',
4942 'LD_LIBRARY_PATH').
4943 New in version 1.1.
4945 numfig If true, figures, tables and code-blocks are automatically num‐
4948 bered if they have a caption. The numref role is enabled.
4949 Obeyed so far only by HTML and LaTeX builders. Default is False.
4950 NOTE:
4952 The LaTeX builder always assigns numbers whether this option
4953 is enabled or not.
4954 New in version 1.3.
4956 numfig_format
4959 A dictionary mapping 'figure', 'table', 'code-block' and 'sec‐
4960 tion' to strings that are used for format of figure numbers. As
4961 a special character, %s will be replaced to figure number.
4962 Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4964 ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4965 New in version 1.3.
4967 numfig_secnum_depth
4970 · if set to 0, figures, tables and code-blocks are continuously
4972 numbered starting at 1.
4973 · if 1 (default) numbers will be x.1, x.2, … with x the section
4975 number (top level sectioning; no x. if no section). This nat‐
4976 urally applies only if section numbering has been activated
4977 via the :numbered: option of the toctree directive.
4978 · 2 means that numbers will be x.y.1, x.y.2, … if located in a
4980 sub-section (but still x.1, x.2, … if located directly under a
4981 section and 1, 2, … if not in any top level section.)
4982 · etc…
4984 New in version 1.3.
4986 Changed in version 1.7: The LaTeX builder obeys this setting (if
4989 numfig is set to True).
4990 smartquotes
4993 If true, the Docutils Smart Quotes transform, originally based
4994 on SmartyPants (limited to English) and currently applying to
4995 many languages, will be used to convert quotes and dashes to
4996 typographically correct entities. Default: True.
4997 New in version 1.6.6: It replaces deprecated
4999 html_use_smartypants. It applies by default to all builders
5000 except man and text (see smartquotes_excludes.)
5001 A docutils.conf file located in the configuration directory (or
5004 a global ~/.docutils file) is obeyed unconditionally if it deac‐
5005 tivates smart quotes via the corresponding Docutils option. But
5006 if it activates them, then smartquotes does prevail.
5007 smartquotes_action
5009 This string, for use with Docutils 0.14 or later, customizes the
5010 Smart Quotes transform. See the file smartquotes.py at the
5011 Docutils repository for details. The default 'qDe' educates
5012 normal quote characters ", ', em- and en-Dashes ---, --, and
5013 ellipses ....
5014 New in version 1.6.6.
5016 smartquotes_excludes
5019 This is a dict whose default is:
5020 {'languages': ['ja'], 'builders': ['man', 'text']}
5022 Each entry gives a sufficient condition to ignore the
5024 smartquotes setting and deactivate the Smart Quotes transform.
5025 Accepted keys are as above 'builders' or 'languages'. The val‐
5026 ues are lists.
5027 NOTE:
5029 Currently, in case of invocation of make with multiple tar‐
5030 gets, the first target name is the only one which is tested
5031 against the 'builders' entry and it decides for all. Also, a
5032 make text following make html needs to be issued in the form
5033 make text O="-E" to force re-parsing of source files, as the
5034 cached ones are already transformed. On the other hand the
5035 issue does not arise with direct usage of sphinx-build as it
5036 caches (in its default usage) the parsed source files in per
5037 builder locations.
5038 New in version 1.6.6.
5040 tls_verify
5043 If true, Sphinx verifies server certifications. Default is
5044 True.
5045 New in version 1.5.
5047 tls_cacerts
5050 A path to a certification file of CA or a path to directory
5051 which contains the certificates. This also allows a dictionary
5052 mapping hostname to the path to certificate file. The certifi‐
5053 cates are used to verify server certifications.
5054 New in version 1.5.
5056 Project information
5059 project
5060 The documented project’s name.
5061 copyright
5063 A copyright statement in the style '2008, Author Name'.
5064 version
5066 The major project version, used as the replacement for |ver‐
5067 sion|. For example, for the Python documentation, this may be
5068 something like 2.6.
5069 release
5071 The full project version, used as the replacement for |release|
5072 and e.g. in the HTML templates. For example, for the Python
5073 documentation, this may be something like 2.6.0rc1.
5074 If you don’t need the separation provided between version and
5076 release, just set them both to the same value.
5077 today
5079 today_fmt
5081 These values determine how to format the current date, used as
5082 the replacement for |today|.
5083 · If you set today to a non-empty value, it is used.
5085 · Otherwise, the current time is formatted using time.strftime()
5087 and the format given in today_fmt.
5088 The default is no today and a today_fmt of '%B %d, %Y' (or, if
5090 translation is enabled with language, an equivalent format for
5091 the selected locale).
5092 highlight_language
5094 The default language to highlight source code in. The default
5095 is 'python3'. The value should be a valid Pygments lexer name,
5096 see code-examples for more details.
5097 New in version 0.5.
5099 Changed in version 1.4: The default is now 'default'. It is sim‐
5102 ilar to 'python3'; it is mostly a superset of 'python'. but it
5103 fallbacks to 'none' without warning if failed. 'python3' and
5104 other languages will emit warning if failed. If you prefer
5105 Python 2 only highlighting, you can set it back to 'python'.
5106 highlight_options
5109 A dictionary of options that modify how the lexer specified by
5110 highlight_language generates highlighted source code. These are
5111 lexer-specific; for the options understood by each, see the
5112 Pygments documentation.
5113 New in version 1.3.
5115 pygments_style
5118 The style name to use for Pygments highlighting of source code.
5119 If not set, either the theme’s default style or 'sphinx' is
5120 selected for HTML output.
5121 Changed in version 0.3: If the value is a fully-qualified name
5123 of a custom Pygments style class, this is then used as custom
5124 style.
5125 add_function_parentheses
5128 A boolean that decides whether parentheses are appended to func‐
5129 tion and method role text (e.g. the content of :func:`input`) to
5130 signify that the name is callable. Default is True.
5131 add_module_names
5133 A boolean that decides whether module names are prepended to all
5134 object names (for object types where a “module” of some kind is
5135 defined), e.g. for py:function directives. Default is True.
5136 show_authors
5138 A boolean that decides whether codeauthor and sectionauthor
5139 directives produce any output in the built files.
5140 modindex_common_prefix
5142 A list of prefixes that are ignored for sorting the Python mod‐
5143 ule index (e.g., if this is set to ['foo.'], then foo.bar is
5144 shown under B, not F). This can be handy if you document a
5145 project that consists of a single package. Works only for the
5146 HTML builder currently. Default is [].
5147 New in version 0.6.
5149 trim_footnote_reference_space
5152 Trim spaces before footnote references that are necessary for
5153 the reST parser to recognize the footnote, but do not look too
5154 nice in the output.
5155 New in version 0.6.
5157 trim_doctest_flags
5160 If true, doctest flags (comments looking like # doctest: FLAG,
5161 ...) at the ends of lines and <BLANKLINE> markers are removed
5162 for all code blocks showing interactive Python sessions (i.e.
5163 doctests). Default is True. See the extension doctest for more
5164 possibilities of including doctests.
5165 New in version 1.0.
5167 Changed in version 1.1: Now also removes <BLANKLINE>.
5170 Options for internationalization
5173 These options influence Sphinx’s Native Language Support. See the doc‐
5174 umentation on intl for details.
5175 language
5177 The code for the language the docs are written in. Any text
5178 automatically generated by Sphinx will be in that language.
5179 Also, Sphinx will try to substitute individual paragraphs from
5180 your documents with the translation sets obtained from
5181 locale_dirs. Sphinx will search language-specific figures named
5182 by figure_language_filename and substitute them for original
5183 figures. In the LaTeX builder, a suitable language will be
5184 selected as an option for the Babel package. Default is None,
5185 which means that no translation will be done.
5186 New in version 0.5.
5188 Changed in version 1.4: Support figure substitution
5191 Currently supported languages by Sphinx are:
5194 · bn – Bengali
5196 · ca – Catalan
5198 · cs – Czech
5200 · da – Danish
5202 · de – German
5204 · en – English
5206 · es – Spanish
5208 · et – Estonian
5210 · eu – Basque
5212 · fa – Iranian
5214 · fi – Finnish
5216 · fr – French
5218 · he – Hebrew
5220 · hr – Croatian
5222 · hu – Hungarian
5224 · id – Indonesian
5226 · it – Italian
5228 · ja – Japanese
5230 · ko – Korean
5232 · lt – Lithuanian
5234 · lv – Latvian
5236 · mk – Macedonian
5238 · nb_NO – Norwegian Bokmal
5240 · ne – Nepali
5242 · nl – Dutch
5244 · pl – Polish
5246 · pt_BR – Brazilian Portuguese
5248 · pt_PT – European Portuguese
5250 · ru – Russian
5252 · si – Sinhala
5254 · sk – Slovak
5256 · sl – Slovenian
5258 · sv – Swedish
5260 · tr – Turkish
5262 · uk_UA – Ukrainian
5264 · vi – Vietnamese
5266 · zh_CN – Simplified Chinese
5268 · zh_TW – Traditional Chinese
5270 locale_dirs
5272 New in version 0.5.
5273 Directories in which to search for additional message catalogs
5276 (see language), relative to the source directory. The directo‐
5277 ries on this path are searched by the standard gettext module.
5278 Internal messages are fetched from a text domain of sphinx; so
5280 if you add the directory ./locale to this setting, the message
5281 catalogs (compiled from .po format using msgfmt) must be in
5282 ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of
5283 individual documents depends on gettext_compact.
5284 The default is ['locales'].
5286 Changed in version 1.5: Use locales directory as a default value
5288 gettext_compact
5291 New in version 1.1.
5292 If true, a document’s text domain is its docname if it is a
5295 top-level project file and its very base directory otherwise.
5296 By default, the document markup/code.rst ends up in the markup
5298 text domain. With this option set to False, it is markup/code.
5299 gettext_uuid
5301 If true, Sphinx generates uuid information for version tracking
5302 in message catalogs. It is used for:
5303 · Add uid line for each msgids in .pot files.
5305 · Calculate similarity between new msgids and previously saved
5307 old msgids. This calculation takes a long time.
5308 If you want to accelerate the calculation, you can use
5310 python-levenshtein 3rd-party package written in C by using pip
5311 install python-levenshtein.
5312 The default is False.
5314 New in version 1.3.
5316 gettext_location
5319 If true, Sphinx generates location information for messages in
5320 message catalogs.
5321 The default is True.
5323 New in version 1.3.
5325 gettext_auto_build
5328 If true, Sphinx builds mo file for each translation catalog
5329 files.
5330 The default is True.
5332 New in version 1.3.
5334 gettext_additional_targets
5337 To specify names to enable gettext extracting and translation
5338 applying for i18n additionally. You can specify below names:
5339 Index index terms
5341 Literal-block
5343 literal blocks: :: and code-block.
5344 Doctest-block
5346 doctest block
5347 Raw raw content
5349 Image image/figure uri and alt
5351 For example: gettext_additional_targets = ['literal-block',
5353 'image'].
5354 The default is [].
5356 New in version 1.3.
5358 figure_language_filename
5361 The filename format for language-specific figures. The default
5362 value is {root}.{language}{ext}. It will be expanded to
5363 dirname/filename.en.png from .. image:: dirname/filename.png.
5364 The available format tokens are:
5365 · {root} - the filename, including any path component, without
5367 the file extension, e.g. dirname/filename
5368 · {path} - the directory path component of the filename, with a
5370 trailing slash if non-empty, e.g. dirname/
5371 · {basename} - the filename without the directory path or file
5373 extension components, e.g. filename
5374 · {ext} - the file extension, e.g. .png
5376 · {language} - the translation language, e.g. en
5378 For example, setting this to {path}{language}/{basename}{ext}
5380 will expand to dirname/en/filename.png instead.
5381 New in version 1.4.
5383 Changed in version 1.5: Added {path} and {basename} tokens.
5386 Options for HTML output
5389 These options influence HTML as well as HTML Help output, and other
5390 builders that use Sphinx’s HTMLWriter class.
5391 html_theme
5393 The “theme” that the HTML output should use. See the section
5394 about theming. The default is 'alabaster'.
5395 New in version 0.6.
5397 html_theme_options
5400 A dictionary of options that influence the look and feel of the
5401 selected theme. These are theme-specific. For the options
5402 understood by the builtin themes, see this section.
5403 New in version 0.6.
5405 html_theme_path
5408 A list of paths that contain custom themes, either as subdirec‐
5409 tories or as zip files. Relative paths are taken as relative to
5410 the configuration directory.
5411 New in version 0.6.
5413 html_style
5416 The style sheet to use for HTML pages. A file of that name must
5417 exist either in Sphinx’s static/ path, or in one of the custom
5418 paths given in html_static_path. Default is the stylesheet
5419 given by the selected theme. If you only want to add or over‐
5420 ride a few things compared to the theme’s stylesheet, use CSS
5421 @import to import the theme’s stylesheet.
5422 html_title
5424 The “title” for HTML documentation generated with Sphinx’s own
5425 templates. This is appended to the <title> tag of individual
5426 pages, and used in the navigation bar as the “topmost” element.
5427 It defaults to '<project> v<revision> documentation'.
5428 html_short_title
5430 A shorter “title” for the HTML docs. This is used in for links
5431 in the header and in the HTML Help docs. If not given, it
5432 defaults to the value of html_title.
5433 New in version 0.4.
5435 html_context
5438 A dictionary of values to pass into the template engine’s con‐
5439 text for all pages. Single values can also be put in this dic‐
5440 tionary using the -A command-line option of sphinx-build.
5441 New in version 0.5.
5443 html_logo
5446 If given, this must be the name of an image file (path relative
5447 to the configuration directory) that is the logo of the docs.
5448 It is placed at the top of the sidebar; its width should there‐
5449 fore not exceed 200 pixels. Default: None.
5450 New in version 0.4.1: The image file will be copied to the
5452 _static directory of the output HTML, but only if the file does
5453 not already exist there.
5454 html_favicon
5457 If given, this must be the name of an image file (path relative
5458 to the configuration directory) that is the favicon of the docs.
5459 Modern browsers use this as the icon for tabs, windows and book‐
5460 marks. It should be a Windows-style icon file (.ico), which is
5461 16x16 or 32x32 pixels large. Default: None.
5462 New in version 0.4: The image file will be copied to the _static
5464 directory of the output HTML, but only if the file does not
5465 already exist there.
5466 html_static_path
5469 A list of paths that contain custom static files (such as style
5470 sheets or script files). Relative paths are taken as relative
5471 to the configuration directory. They are copied to the output’s
5472 _static directory after the theme’s static files, so a file
5473 named default.css will overwrite the theme’s default.css.
5474 Changed in version 0.4: The paths in html_static_path can now
5476 contain subdirectories.
5477 Changed in version 1.0: The entries in html_static_path can now
5480 be single files.
5481 html_extra_path
5484 A list of paths that contain extra files not directly related to
5485 the documentation, such as robots.txt or .htaccess. Relative
5486 paths are taken as relative to the configuration directory.
5487 They are copied to the output directory. They will overwrite
5488 any existing file of the same name.
5489 As these files are not meant to be built, they are automatically
5491 added to exclude_patterns.
5492 New in version 1.2.
5494 Changed in version 1.4: The dotfiles in the extra directory will
5497 be copied to the output directory. And it refers
5498 exclude_patterns on copying extra files and directories, and
5499 ignores if path matches to patterns.
5500 html_last_updated_fmt
5503 If this is not None, a ‘Last updated on:’ timestamp is inserted
5504 at every page bottom, using the given strftime() format. The
5505 empty string is equivalent to '%b %d, %Y' (or a locale-dependent
5506 equivalent).
5507 html_use_smartypants
5509 If true, quotes and dashes are converted to typographically cor‐
5510 rect entities. Default: True.
5511 Deprecated since version 1.6: To disable smart quotes, use
5513 rather smartquotes.
5514 html_add_permalinks
5517 Sphinx will add “permalinks” for each heading and description
5518 environment as paragraph signs that become visible when the
5519 mouse hovers over them.
5520 This value determines the text for the permalink; it defaults to
5522 "¶". Set it to None or the empty string to disable permalinks.
5523 New in version 0.6: Previously, this was always activated.
5525 Changed in version 1.1: This can now be a string to select the
5528 actual text of the link. Previously, only boolean values were
5529 accepted.
5530 html_sidebars
5533 Custom sidebar templates, must be a dictionary that maps docu‐
5534 ment names to template names.
5535 The keys can contain glob-style patterns [1], in which case all
5537 matching documents will get the specified sidebars. (A warning
5538 is emitted when a more than one glob-style pattern matches for
5539 any document.)
5540 The values can be either lists or single strings.
5542 · If a value is a list, it specifies the complete list of side‐
5544 bar templates to include. If all or some of the default side‐
5545 bars are to be included, they must be put into this list as
5546 well.
5547 The default sidebars (for documents that don’t match any pat‐
5549 tern) are defined by theme itself. Builtin themes are using
5550 these templates by default: ['localtoc.html', 'rela‐
5551 tions.html', 'sourcelink.html', 'searchbox.html'].
5552 · If a value is a single string, it specifies a custom sidebar
5554 to be added between the 'sourcelink.html' and 'searchbox.html'
5555 entries. This is for compatibility with Sphinx versions
5556 before 1.0.
5557 Deprecated since version 1.7: a single string value for
5559 html_sidebars will be removed in 2.0
5560 Builtin sidebar templates that can be rendered are:
5563 · localtoc.html – a fine-grained table of contents of the cur‐
5565 rent document
5566 · globaltoc.html – a coarse-grained table of contents for the
5568 whole documentation set, collapsed
5569 · relations.html – two links to the previous and next documents
5571 · sourcelink.html – a link to the source of the current docu‐
5573 ment, if enabled in html_show_sourcelink
5574 · searchbox.html – the “quick search” box
5576 Example:
5578 html_sidebars = {
5580 '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5581 'using/windows': ['windowssidebar.html', 'searchbox.html'],
5582 }
5583 This will render the custom template windowssidebar.html and the
5585 quick search box within the sidebar of the given document, and
5586 render the default sidebars for all other pages (except that the
5587 local TOC is replaced by the global TOC).
5588 New in version 1.0: The ability to use globbing keys and to
5590 specify multiple sidebars.
5591 Note that this value only has no effect if the chosen theme does
5594 not possess a sidebar, like the builtin scrolls and haiku
5595 themes.
5596 html_additional_pages
5598 Additional templates that should be rendered to HTML pages, must
5599 be a dictionary that maps document names to template names.
5600 Example:
5602 html_additional_pages = {
5604 'download': 'customdownload.html',
5605 }
5606 This will render the template customdownload.html as the page
5608 download.html.
5609 html_domain_indices
5611 If true, generate domain-specific indices in addition to the
5612 general index. For e.g. the Python domain, this is the global
5613 module index. Default is True.
5614 This value can be a bool or a list of index names that should be
5616 generated. To find out the index name for a specific index,
5617 look at the HTML file name. For example, the Python module
5618 index has the name 'py-modindex'.
5619 New in version 1.0.
5621 html_use_index
5624 If true, add an index to the HTML documents. Default is True.
5625 New in version 0.4.
5627 html_split_index
5630 If true, the index is generated twice: once as a single page
5631 with all the entries, and once as one page per starting letter.
5632 Default is False.
5633 New in version 0.4.
5635 html_copy_source
5638 If true, the reST sources are included in the HTML build as
5639 _sources/name. The default is True.
5640 WARNING:
5642 If this config value is set to False, the JavaScript search
5643 function will only display the titles of matching documents,
5644 and no excerpt from the matching contents.
5645 html_show_sourcelink
5647 If true (and html_copy_source is true as well), links to the
5648 reST sources will be added to the sidebar. The default is True.
5649 New in version 0.6.
5651 html_sourcelink_suffix
5654 Suffix to be appended to source links (see
5655 html_show_sourcelink), unless they have this suffix already.
5656 Default is '.txt'.
5657 New in version 1.5.
5659 html_use_opensearch
5662 If nonempty, an OpenSearch description file will be output, and
5663 all pages will contain a <link> tag referring to it. Since
5664 OpenSearch doesn’t support relative URLs for its search page
5665 location, the value of this option must be the base URL from
5666 which these documents are served (without trailing slash), e.g.
5667 "https://docs.python.org". The default is ''.
5668 html_file_suffix
5670 This is the file name suffix for generated HTML files. The
5671 default is ".html".
5672 New in version 0.4.
5674 html_link_suffix
5677 Suffix for generated links to HTML files. The default is what‐
5678 ever html_file_suffix is set to; it can be set differently (e.g.
5679 to support different web server setups).
5680 New in version 0.6.
5682 html_show_copyright
5685 If true, “(C) Copyright …” is shown in the HTML footer. Default
5686 is True.
5687 New in version 1.0.
5689 html_show_sphinx
5692 If true, “Created using Sphinx” is shown in the HTML footer.
5693 Default is True.
5694 New in version 0.4.
5696 html_output_encoding
5699 Encoding of HTML output files. Default is 'utf-8'. Note that
5700 this encoding name must both be a valid Python encoding name and
5701 a valid HTML charset value.
5702 New in version 1.0.
5704 html_compact_lists
5707 If true, a list all whose items consist of a single paragraph
5708 and/or a sub-list all whose items etc… (recursive definition)
5709 will not use the <p> element for any of its items. This is stan‐
5710 dard docutils behavior. Default: True.
5711 New in version 1.0.
5713 html_secnumber_suffix
5716 Suffix for section numbers. Default: ". ". Set to " " to sup‐
5717 press the final dot on section numbers.
5718 New in version 1.0.
5720 html_search_language
5723 Language to be used for generating the HTML full-text search
5724 index. This defaults to the global language selected with
5725 language. If there is no support for this language, "en" is
5726 used which selects the English language.
5727 Support is present for these languages:
5729 · da – Danish
5731 · nl – Dutch
5733 · en – English
5735 · fi – Finnish
5737 · fr – French
5739 · de – German
5741 · hu – Hungarian
5743 · it – Italian
5745 · ja – Japanese
5747 · no – Norwegian
5749 · pt – Portuguese
5751 · ro – Romanian
5753 · ru – Russian
5755 · es – Spanish
5757 · sv – Swedish
5759 · tr – Turkish
5761 · zh – Chinese
5763 Accelerating build speed
5765 Each language (except Japanese) provides its own stem‐
5767 ming algorithm. Sphinx uses a Python implementation
5768 by default. You can use a C implementation to accel‐
5769 erate building the index file.
5770 · PorterStemmer (en)
5772 · PyStemmer (all languages)
5774 New in version 1.1: With support for en and ja.
5776 Changed in version 1.3: Added additional languages.
5779 html_search_options
5782 A dictionary with options for the search language support, empty
5783 by default. The meaning of these options depends on the lan‐
5784 guage selected.
5785 The English support has no options.
5787 The Japanese support has these options:
5789 Type
5791 is dotted module path string to specify Splitter imple‐
5792 mentation which should be derived from
5793 sphinx.search.ja.BaseSplitter. If not specified or None
5794 is specified, 'sphinx.search.ja.DefaultSplitter' will be
5795 used.
5796 You can choose from these modules:
5798 ‘sphinx.search.ja.DefaultSplitter’
5800 TinySegmenter algorithm. This is default splitter.
5801 ‘sphinx.search.ja.MeCabSplitter’
5803 MeCab binding. To use this splitter, ‘mecab’
5804 python binding or dynamic link library (‘libme‐
5805 cab.so’ for linux, ‘libmecab.dll’ for windows) is
5806 required.
5807 ‘sphinx.search.ja.JanomeSplitter’
5809 Janome binding. To use this splitter, Janome is
5810 required.
5811 To keep compatibility, 'mecab', 'janome' and 'default'
5813 are also acceptable. However it will be deprecated in
5814 Sphinx-1.6.
5815 Other option values depend on splitter value which you choose.
5817 Options for 'mecab':
5819 dic_enc
5821 is the encoding for the MeCab algorithm.
5822 dict
5824 is the dictionary to use for the MeCab algorithm.
5825 lib
5827 is the library name for finding the MeCab library
5828 via ctypes if the Python binding is not installed.
5829 For example:
5831 html_search_options = {
5833 'type': 'mecab',
5834 'dic_enc': 'utf-8',
5835 'dict': '/path/to/mecab.dic',
5836 'lib': '/path/to/libmecab.so',
5837 }
5838 Options for 'janome':
5840 user_dic
5842 is the user dictionary file path for Janome.
5843 user_dic_enc
5845 is the encoding for the user dictionary file
5846 specified by user_dic option. Default is ‘utf8’.
5847 New in version 1.1.
5849 Changed in version 1.4: html_search_options for Japanese is
5852 re-organized and any custom splitter can be used by type set‐
5853 tings.
5854 The Chinese support has these options:
5857 · dict – the jieba dictionary path if want to use custom dic‐
5859 tionary.
5860 html_search_scorer
5862 The name of a JavaScript file (relative to the configuration
5863 directory) that implements a search results scorer. If empty,
5864 the default will be used.
5865 New in version 1.2.
5867 html_scaled_image_link
5870 If true, images itself links to the original image if it doesn’t
5871 have ‘target’ option or scale related options: ‘scale’, ‘width’,
5872 ‘height’. The default is True.
5873 New in version 1.3.
5875 htmlhelp_basename
5878 Output file base name for HTML help builder. Default is
5879 'pydoc'.
5880 html_experimental_html5_writer
5882 Output is processed with HTML5 writer. This feature needs docu‐
5883 tils 0.13 or newer. Default is False.
5884 New in version 1.6.
5886 Options for Apple Help output
5889 New in version 1.3.
5890 These options influence the Apple Help output. This builder derives
5893 from the HTML builder, so the HTML options also apply where appropri‐
5894 ate.
5895 NOTE:
5897 Apple Help output will only work on Mac OS X 10.6 and higher, as it
5898 requires the hiutil and codesign command line tools, neither of
5899 which are Open Source.
5900 You can disable the use of these tools using
5902 applehelp_disable_external_tools, but the result will not be a valid
5903 help book until the indexer is run over the .lproj folders within
5904 the bundle.
5905 applehelp_bundle_name
5907 The basename for the Apple Help Book. Defaults to the project
5908 name.
5909 applehelp_bundle_id
5911 The bundle ID for the help book bundle.
5912 WARNING:
5914 You must set this value in order to generate Apple Help.
5915 applehelp_dev_region
5917 The development region. Defaults to 'en-us', which is Apple’s
5918 recommended setting.
5919 applehelp_bundle_version
5921 The bundle version (as a string). Defaults to '1'.
5922 applehelp_icon
5924 The help bundle icon file, or None for no icon. According to
5925 Apple’s documentation, this should be a 16-by-16 pixel version
5926 of the application’s icon with a transparent background, saved
5927 as a PNG file.
5928 applehelp_kb_product
5930 The product tag for use with applehelp_kb_url. Defaults to
5931 '<project>-<release>'.
5932 applehelp_kb_url
5934 The URL for your knowledgebase server, e.g. https://exam‐
5935 ple.com/kbsearch.py?p='product'&q='query'&l='lang'. Help Viewer
5936 will replace the values 'product', 'query' and 'lang' at runtime
5937 with the contents of applehelp_kb_product, the text entered by
5938 the user in the search box and the user’s system language
5939 respectively.
5940 Defaults to None for no remote search.
5942 applehelp_remote_url
5944 The URL for remote content. You can place a copy of your Help
5945 Book’s Resources folder at this location and Help Viewer will
5946 attempt to use it to fetch updated content.
5947 e.g. if you set it to https://example.com/help/Foo/ and Help
5949 Viewer wants a copy of index.html for an English speaking cus‐
5950 tomer, it will look at https://exam‐
5951 ple.com/help/Foo/en.lproj/index.html.
5952 Defaults to None for no remote content.
5954 applehelp_index_anchors
5956 If True, tell the help indexer to index anchors in the generated
5957 HTML. This can be useful for jumping to a particular topic
5958 using the AHLookupAnchor function or the openHelpAnchor:inBook:
5959 method in your code. It also allows you to use help:anchor
5960 URLs; see the Apple documentation for more information on this
5961 topic.
5962 applehelp_min_term_length
5964 Controls the minimum term length for the help indexer. Defaults
5965 to None, which means the default will be used.
5966 applehelp_stopwords
5968 Either a language specification (to use the built-in stopwords),
5969 or the path to a stopwords plist, or None if you do not want to
5970 use stopwords. The default stopwords plist can be found at
5971 /usr/share/hiutil/Stopwords.plist and contains, at time of writ‐
5972 ing, stopwords for the following languages:
5973 ┌──────────┬──────┐
5975 │Language │ Code │
5976 ├──────────┼──────┤
5977 │English │ en │
5978 ├──────────┼──────┤
5979 │German │ de │
5980 ├──────────┼──────┤
5981 │Spanish │ es │
5982 ├──────────┼──────┤
5983 │French │ fr │
5984 ├──────────┼──────┤
5985 │Swedish │ sv │
5986 ├──────────┼──────┤
5987 │Hungarian │ hu │
5988 ├──────────┼──────┤
5989 │Italian │ it │
5990 └──────────┴──────┘
5991 Defaults to language, or if that is not set, to en.
5993 applehelp_locale
5995 Specifies the locale to generate help for. This is used to
5996 determine the name of the .lproj folder inside the Help Book’s
5997 Resources, and is passed to the help indexer.
5998 Defaults to language, or if that is not set, to en.
6000 applehelp_title
6002 Specifies the help book title. Defaults to '<project> Help'.
6003 applehelp_codesign_identity
6005 Specifies the identity to use for code signing, or None if code
6006 signing is not to be performed.
6007 Defaults to the value of the environment variable
6009 CODE_SIGN_IDENTITY, which is set by Xcode for script build
6010 phases, or None if that variable is not set.
6011 applehelp_codesign_flags
6013 A list of additional arguments to pass to codesign when signing
6014 the help book.
6015 Defaults to a list based on the value of the environment vari‐
6017 able OTHER_CODE_SIGN_FLAGS, which is set by Xcode for script
6018 build phases, or the empty list if that variable is not set.
6019 applehelp_indexer_path
6021 The path to the hiutil program. Defaults to '/usr/bin/hiutil'.
6022 applehelp_codesign_path
6024 The path to the codesign program. Defaults to '/usr/bin/code‐
6025 sign'.
6026 applehelp_disable_external_tools
6028 If True, the builder will not run the indexer or the code sign‐
6029 ing tool, no matter what other settings are specified.
6030 This is mainly useful for testing, or where you want to run the
6032 Sphinx build on a non-Mac OS X platform and then complete the
6033 final steps on OS X for some reason.
6034 Defaults to False.
6036 Options for epub output
6038 These options influence the epub output. As this builder derives from
6039 the HTML builder, the HTML options also apply where appropriate. The
6040 actual values for some of the options is not really important, they
6041 just have to be entered into the Dublin Core metadata.
6042 epub_basename
6044 The basename for the epub file. It defaults to the project
6045 name.
6046 epub_theme
6048 The HTML theme for the epub output. Since the default themes
6049 are not optimized for small screen space, using the same theme
6050 for HTML and epub output is usually not wise. This defaults to
6051 'epub', a theme designed to save visual space.
6052 epub_theme_options
6054 A dictionary of options that influence the look and feel of the
6055 selected theme. These are theme-specific. For the options
6056 understood by the builtin themes, see this section.
6057 New in version 1.2.
6059 epub_title
6062 The title of the document. It defaults to the html_title option
6063 but can be set independently for epub creation.
6064 epub_description
6066 The description of the document. The default value is 'unknown'.
6067 New in version 1.4.
6069 Changed in version 1.5: Renamed from epub3_description
6072 epub_author
6075 The author of the document. This is put in the Dublin Core
6076 metadata. The default value is 'unknown'.
6077 epub_contributor
6079 The name of a person, organization, etc. that played a secondary
6080 role in the creation of the content of an EPUB Publication. The
6081 default value is 'unknown'.
6082 New in version 1.4.
6084 Changed in version 1.5: Renamed from epub3_contributor
6087 epub_language
6090 The language of the document. This is put in the Dublin Core
6091 metadata. The default is the language option or 'en' if unset.
6092 epub_publisher
6094 The publisher of the document. This is put in the Dublin Core
6095 metadata. You may use any sensible string, e.g. the project
6096 homepage. The default value is 'unknown'.
6097 epub_copyright
6099 The copyright of the document. It defaults to the copyright
6100 option but can be set independently for epub creation.
6101 epub_identifier
6103 An identifier for the document. This is put in the Dublin Core
6104 metadata. For published documents this is the ISBN number, but
6105 you can also use an alternative scheme, e.g. the project home‐
6106 page. The default value is 'unknown'.
6107 epub_scheme
6109 The publication scheme for the epub_identifier. This is put in
6110 the Dublin Core metadata. For published books the scheme is
6111 'ISBN'. If you use the project homepage, 'URL' seems reason‐
6112 able. The default value is 'unknown'.
6113 epub_uid
6115 A unique identifier for the document. This is put in the Dublin
6116 Core metadata. You may use a XML’s Name format string. You
6117 can’t use hyphen, period, numbers as a first character. The
6118 default value is 'unknown'.
6119 epub_cover
6121 The cover page information. This is a tuple containing the
6122 filenames of the cover image and the html template. The ren‐
6123 dered html cover page is inserted as the first item in the spine
6124 in content.opf. If the template filename is empty, no html
6125 cover page is created. No cover at all is created if the tuple
6126 is empty. Examples:
6127 epub_cover = ('_static/cover.png', 'epub-cover.html')
6129 epub_cover = ('_static/cover.png', '')
6130 epub_cover = ()
6131 The default value is ().
6133 New in version 1.1.
6135 epub_guide
6138 Meta data for the guide element of content.opf. This is a
6139 sequence of tuples containing the type, the uri and the title of
6140 the optional guide information. See the OPF documentation at
6141 http://idpf.org/epub for details. If possible, default entries
6142 for the cover and toc types are automatically inserted. However,
6143 the types can be explicitly overwritten if the default entries
6144 are not appropriate. Example:
6145 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6147 The default value is ().
6149 epub_pre_files
6151 Additional files that should be inserted before the text gener‐
6152 ated by Sphinx. It is a list of tuples containing the file name
6153 and the title. If the title is empty, no entry is added to
6154 toc.ncx. Example:
6155 epub_pre_files = [
6157 ('index.html', 'Welcome'),
6158 ]
6159 The default value is [].
6161 epub_post_files
6163 Additional files that should be inserted after the text gener‐
6164 ated by Sphinx. It is a list of tuples containing the file name
6165 and the title. This option can be used to add an appendix. If
6166 the title is empty, no entry is added to toc.ncx. The default
6167 value is [].
6168 epub_exclude_files
6170 A list of files that are generated/copied in the build directory
6171 but should not be included in the epub file. The default value
6172 is [].
6173 epub_tocdepth
6175 The depth of the table of contents in the file toc.ncx. It
6176 should be an integer greater than zero. The default value is 3.
6177 Note: A deeply nested table of contents may be difficult to nav‐
6178 igate.
6179 epub_tocdup
6181 This flag determines if a toc entry is inserted again at the
6182 beginning of its nested toc listing. This allows easier naviga‐
6183 tion to the top of a chapter, but can be confusing because it
6184 mixes entries of different depth in one list. The default value
6185 is True.
6186 epub_tocscope
6188 This setting control the scope of the epub table of contents.
6189 The setting can have the following values:
6190 · 'default' – include all toc entries that are not hidden
6192 (default)
6193 · 'includehidden' – include all toc entries
6195 New in version 1.2.
6197 epub_fix_images
6200 This flag determines if sphinx should try to fix image formats
6201 that are not supported by some epub readers. At the moment pal‐
6202 ette images with a small color table are upgraded. You need the
6203 Python Image Library (Pillow the successor of the PIL) installed
6204 to use this option. The default value is False because the
6205 automatic conversion may lose information.
6206 New in version 1.2.
6208 epub_max_image_width
6211 This option specifies the maximum width of images. If it is set
6212 to a value greater than zero, images with a width larger than
6213 the given value are scaled accordingly. If it is zero, no scal‐
6214 ing is performed. The default value is 0. You need the Python
6215 Image Library (Pillow) installed to use this option.
6216 New in version 1.2.
6218 epub_show_urls
6221 Control whether to display URL addresses. This is very useful
6222 for readers that have no other means to display the linked URL.
6223 The settings can have the following values:
6224 · 'inline' – display URLs inline in parentheses (default)
6226 · 'footnote' – display URLs in footnotes
6228 · 'no' – do not display URLs
6230 The display of inline URLs can be customized by adding CSS rules
6232 for the class link-target.
6233 New in version 1.2.
6235 epub_use_index
6238 If true, add an index to the epub document. It defaults to the
6239 html_use_index option but can be set independently for epub cre‐
6240 ation.
6241 New in version 1.2.
6243 epub_writing_mode
6246 It specifies writing direction. It can accept 'horizontal'
6247 (default) and 'vertical'
6248 ┌────────────────────┬─────────────────────┬─────────────────────┐
6250 │epub_writing_mode │ 'horizontal' │ 'vertical' │
6251 ├────────────────────┼─────────────────────┼─────────────────────┤
6252 │writing-mode [2] │ horizontal-tb │ vertical-rl │
6253 ├────────────────────┼─────────────────────┼─────────────────────┤
6254 │page progression │ left to right │ right to left │
6255 ├────────────────────┼─────────────────────┼─────────────────────┤
6256 │iBook’s Scroll │ scroll-axis is ver‐ │ scroll-axis is hor‐ │
6257 │Theme support │ tical. │ izontal. │
6258 └────────────────────┴─────────────────────┴─────────────────────┘
6259 [2] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6261 Options for LaTeX output
6263 These options influence LaTeX output. See further latex.
6264 latex_engine
6266 The LaTeX engine to build the docs. The setting can have the
6267 following values:
6268 · 'pdflatex' – PDFLaTeX (default)
6270 · 'xelatex' – XeLaTeX
6272 · 'lualatex' – LuaLaTeX
6274 · 'platex' – pLaTeX (default if language is 'ja')
6276 PDFLaTeX’s support for Unicode characters covers those from the
6278 document language (the LaTeX babel and inputenc packages map
6279 them to glyph slots in the document font, at various encodings
6280 allowing each only 256 characters; Sphinx uses by default
6281 (except for Cyrillic languages) the times package), but stray
6282 characters from other scripts or special symbols may require
6283 adding extra LaTeX packages or macros to the LaTeX preamble.
6284 If your project uses such extra Unicode characters, switching
6286 the engine to XeLaTeX or LuaLaTeX often provides a quick fix.
6287 They only work with UTF-8 encoded sources and can (in fact,
6288 should) use OpenType fonts, either from the system or the TeX
6289 install tree. Recent LaTeX releases will default with these
6290 engines to the Latin Modern OpenType font, which has good cover‐
6291 age of Latin and Cyrillic scripts (it is provided by standard
6292 LaTeX installation), and Sphinx does not modify this default.
6293 Refer to the documentation of the LaTeX polyglossia package to
6294 see how to instruct LaTeX to use some other OpenType font if
6295 Unicode coverage proves insufficient (or use directly \setmain‐
6296 font et. al. as in this example.)
6297 latex_documents
6299 This value determines how to group the document tree into LaTeX
6300 source files. It must be a list of tuples (startdocname, tar‐
6301 getname, title, author, documentclass, toctree_only), where the
6302 items are:
6303 · startdocname: document name that is the “root” of the LaTeX
6305 file. All documents referenced by it in TOC trees will be
6306 included in the LaTeX file too. (If you want only one LaTeX
6307 file, use your master_doc here.)
6308 · targetname: file name of the LaTeX file in the output direc‐
6310 tory.
6311 · title: LaTeX document title. Can be empty to use the title of
6313 the startdoc. This is inserted as LaTeX markup, so special
6314 characters like a backslash or ampersand must be represented
6315 by the proper LaTeX commands if they are to be inserted liter‐
6316 ally.
6317 · author: Author for the LaTeX document. The same LaTeX markup
6319 caveat as for title applies. Use \\and to separate multiple
6320 authors, as in: 'John \\and Sarah' (backslashes must be
6321 Python-escaped to reach LaTeX).
6322 · documentclass: Normally, one of 'manual' or 'howto' (provided
6324 by Sphinx and based on 'report', resp. 'article'; Japanese
6325 documents use 'jsbook', resp. 'jreport'.) “howto” (non-Japa‐
6326 nese) documents will not get appendices. Also they have a sim‐
6327 pler title page. Other document classes can be given. Inde‐
6328 pendently of the document class, the “sphinx” package is
6329 always loaded in order to define Sphinx’s custom LaTeX com‐
6330 mands.
6331 · toctree_only: Must be True or False. If true, the startdoc
6333 document itself is not included in the output, only the docu‐
6334 ments referenced by it via TOC trees. With this option, you
6335 can put extra stuff in the master document that shows up in
6336 the HTML, but not the LaTeX output.
6337 New in version 1.2: In the past including your own document
6339 class required you to prepend the document class name with the
6340 string “sphinx”. This is not necessary anymore.
6341 New in version 0.3: The 6th item toctree_only. Tuples with 5
6344 items are still accepted.
6345 latex_logo
6348 If given, this must be the name of an image file (relative to
6349 the configuration directory) that is the logo of the docs. It
6350 is placed at the top of the title page. Default: None.
6351 latex_toplevel_sectioning
6353 This value determines the topmost sectioning unit. It should be
6354 chosen from 'part', 'chapter' or 'section'. The default is None;
6355 the topmost sectioning unit is switched by documentclass: sec‐
6356 tion is used if documentclass will be howto, otherwise chapter
6357 will be used.
6358 Note that if LaTeX uses \part command, then the numbering of
6360 sectioning units one level deep gets off-sync with HTML number‐
6361 ing, because LaTeX numbers continuously \chapter (or \section
6362 for howto.)
6363 New in version 1.4.
6365 latex_appendices
6368 A list of document names to append as an appendix to all manu‐
6369 als.
6370 latex_domain_indices
6372 If true, generate domain-specific indices in addition to the
6373 general index. For e.g. the Python domain, this is the global
6374 module index. Default is True.
6375 This value can be a bool or a list of index names that should be
6377 generated, like for html_domain_indices.
6378 New in version 1.0.
6380 latex_show_pagerefs
6383 If true, add page references after internal references. This is
6384 very useful for printed copies of the manual. Default is False.
6385 New in version 1.0.
6387 latex_show_urls
6390 Control whether to display URL addresses. This is very useful
6391 for printed copies of the manual. The setting can have the fol‐
6392 lowing values:
6393 · 'no' – do not display URLs (default)
6395 · 'footnote' – display URLs in footnotes
6397 · 'inline' – display URLs inline in parentheses
6399 New in version 1.0.
6401 Changed in version 1.1: This value is now a string; previously
6404 it was a boolean value, and a true value selected the 'inline'
6405 display. For backwards compatibility, True is still accepted.
6406 latex_use_latex_multicolumn
6409 The default is False: it means that Sphinx’s own macros are used
6410 for merged cells from grid tables. They allow general contents
6411 (literal blocks, lists, blockquotes, …) but may have problems if
6412 the tabularcolumns directive was used to inject LaTeX mark-up of
6413 the type >{..}, <{..}, @{..} as column specification.
6414 Setting to True means to use LaTeX’s standard \multicolumn; this
6416 is incompatible with literal blocks in the horizontally merged
6417 cell, and also with multiple paragraphs in such cell if the ta‐
6418 ble is rendered using tabulary.
6419 New in version 1.6.
6421 latex_elements
6424 New in version 0.5.
6425 A dictionary that contains LaTeX snippets that override those
6428 Sphinx usually puts into the generated .tex files.
6429 Keep in mind that backslashes must be doubled in Python string
6431 literals to avoid interpretation as escape sequences.
6432 · Keys that you may want to override include:
6434 'papersize'
6436 Paper size option of the document class ('a4paper' or
6437 'letterpaper'), default 'letterpaper'.
6438 'pointsize'
6440 Point size option of the document class ('10pt', '11pt'
6441 or '12pt'), default '10pt'.
6442 'pxunit'
6444 the value of the px when used in image attributes width
6445 and height. The default value is '0.75bp' which
6446 achieves 96px=1in (in TeX 1in = 72bp = 72.27pt.) To
6447 obtain for example 100px=1in use '0.01in' or '0.7227pt'
6448 (the latter leads to TeX computing a more precise
6449 value, due to the smaller unit used in the specifica‐
6450 tion); for 72px=1in, simply use '1bp'; for 90px=1in,
6451 use '0.8bp' or '0.803pt'.
6452 New in version 1.5.
6454 'sphinxsetup'
6457 A comma separated list of key=value package options for
6458 the Sphinx LaTeX style, default empty. See latex.
6459 New in version 1.5.
6461 'passoptionstopackages'
6464 A string which will be positioned early in the pream‐
6465 ble, designed to contain \\PassOptionsToPack‐
6466 age{options}{foo} commands. Default empty.
6467 New in version 1.4.
6469 'babel'
6472 “babel” package inclusion, default '\\usepack‐
6473 age{babel}' (the suitable document language string is
6474 passed as class option, and english is used if no lan‐
6475 guage.) For Japanese documents, the default is the
6476 empty string.
6477 Changed in version 1.5: For latex_engine set to 'xela‐
6479 tex', the default is '\\usepackage{polyglossia}\n\\set‐
6480 mainlanguage{<language>}'.
6481 Changed in version 1.6: 'lualatex' uses same default
6484 setting as 'xelatex'
6485 'fontpkg'
6488 Font package inclusion, default '\\usepackage{times}'
6489 (which uses Times for text, Helvetica for sans serif
6490 and Courier for code-blocks).
6491 HINT:
6493 Courier is much wider than Times, and Sphinx emits
6494 LaTeX command \small in code-blocks to compensate.
6495 Since 1.5 this is not hard-coded anymore, and can be
6496 modified via inclusion in 'preamble' key of
6497 \\fvset{fontsize=auto}. This is recommended if the
6498 fonts match better than Times and Courier. At 1.8 a
6499 separate 'fvset' key will permit such customization
6500 without usage of 'preamble' key.
6501 Changed in version 1.2: Defaults to '' when the
6503 language uses the Cyrillic script.
6504 Changed in version 1.5: Defaults to '' when
6507 latex_engine is 'xelatex'.
6508 Changed in version 1.6: Defaults to '' also with
6511 'lualatex'.
6512 'fncychap'
6515 Inclusion of the “fncychap” package (which makes fancy
6516 chapter titles), default '\\usepackage[Bjarne]{fncy‐
6517 chap}' for English documentation (this option is
6518 slightly customized by Sphinx), '\\usepack‐
6519 age[Sonny]{fncychap}' for internationalized docs
6520 (because the “Bjarne” style uses numbers spelled out in
6521 English). Other “fncychap” styles you can try are
6522 “Lenny”, “Glenn”, “Conny”, “Rejne” and “Bjornstrup”.
6523 You can also set this to '' to disable fncychap.
6524 'preamble'
6526 Additional preamble content, default empty. See latex.
6527 'atendofbody'
6529 Additional document content (right before the indices),
6530 default empty.
6531 New in version 1.5.
6533 'figure_align'
6536 Latex figure float alignment, default ‘htbp’ (here,
6537 top, bottom, page). Whenever an image doesn’t fit into
6538 the current page, it will be ‘floated’ into the next
6539 page but may be preceded by any other text. If you
6540 don’t like this behavior, use ‘H’ which will disable
6541 floating and position figures strictly in the order
6542 they appear in the source.
6543 New in version 1.3.
6545 'footer'
6548 Additional footer content (before the indices), default
6549 empty.
6550 Deprecated since version 1.5: Use 'atendofbody' key
6552 instead.
6553 · Keys that don’t need to be overridden unless in special cases
6556 are:
6557 'extraclassoptions'
6559 The default is the empty string. Example: 'extraclas‐
6560 soptions': 'openany' will allow chapters (for documents
6561 of the 'manual' type) to start on any page.
6562 New in version 1.2.
6564 Changed in version 1.6: Added this documentation.
6567 'maxlistdepth'
6570 LaTeX allows by default at most 6 levels for nesting
6571 list and quote-like environments, with at most 4 enu‐
6572 merated lists, and 4 bullet lists. Setting this key for
6573 example to '10' (as a string) will allow up to 10
6574 nested levels (of all sorts). Leaving it to the empty
6575 string means to obey the LaTeX default.
6576 WARNING:
6578 · Using this key may prove incompatible with some
6580 LaTeX packages or special document classes which
6581 do their own list customization.
6582 · The key setting is silently ignored if \usepack‐
6584 age{enumitem} is executed inside the document pre‐
6585 amble. Use then rather the dedicated commands of
6586 this LaTeX package.
6587 New in version 1.5.
6589 'inputenc'
6592 “inputenc” package inclusion, defaults to '\\usepack‐
6593 age[utf8]{inputenc}' when using pdflatex. Otherwise
6594 empty.
6595 Changed in version 1.4.3: Previously '\\usepack‐
6597 age[utf8]{inputenc}' was used for all compilers.
6598 'cmappkg'
6601 “cmap” package inclusion, default '\\usepackage{cmap}'.
6602 New in version 1.2.
6604 'fontenc'
6607 “fontenc” package inclusion, default '\\usepack‐
6608 age[T1]{fontenc}'.
6609 Changed in version 1.5: Defaults to '\\usepack‐
6611 age{fontspec}' when latex_engine is 'xelatex'.
6612 Changed in version 1.6: 'lualatex' also uses fontspec
6615 per default.
6616 'geometry'
6619 “geometry” package inclusion, the default definition
6620 is:
6621 '\\usepackage{geometry}'
6622 with an additional [dvipdfm] for Japanese documents.
6624 The Sphinx LaTeX style file executes:
6625 \PassOptionsToPackage{hmargin=1in,vmar‐
6626 gin=1in,marginpar=0.5in}{geometry}
6627 which can be customized via corresponding ‘sphinxsetup’
6629 options.
6630 New in version 1.5.
6632 Changed in version 1.5.2: dvipdfm option if
6635 latex_engine is 'platex'.
6636 New in version 1.5.3: The ‘sphinxsetup’ keys for the
6639 margins.
6640 Changed in version 1.5.3: The location in the LaTeX
6643 file has been moved to after \usepackage{sphinx} and
6644 \sphinxsetup{..}, hence also after insertion of
6645 'fontpkg' key. This is in order to handle the paper
6646 layout options in a special way for Japanese documents:
6647 the text width will be set to an integer multiple of
6648 the zenkaku width, and the text height to an integer
6649 multiple of the baseline. See the hmargin documentation
6650 for more.
6651 'hyperref'
6654 “hyperref” package inclusion; also loads package “hyp‐
6655 cap” and issues \urlstyle{same}. This is done after
6656 sphinx.sty file is loaded and before executing the con‐
6657 tents of 'preamble' key.
6658 ATTENTION:
6660 Loading of packages “hyperref” and “hypcap” is
6661 mandatory.
6662 New in version 1.5: Previously this was done from
6664 inside sphinx.sty.
6665 'maketitle'
6668 “maketitle” call, default '\\maketitle' (but it has
6669 been redefined by the Sphinx manual and howto classes.)
6670 Override if you want to generate a differently-styled
6671 title page.
6672 'releasename'
6674 value that prefixes 'release' element on title page,
6675 default 'Release'. As for title and author used in the
6676 tuples of latex_documents, it is inserted as LaTeX
6677 markup.
6678 'tableofcontents'
6680 “tableofcontents” call, default '\\sphinxtableofcon‐
6681 tents' (it is a wrapper of unmodified \tableofcontents,
6682 which may itself be customized by user loaded pack‐
6683 ages.) Override if you want to generate a different
6684 table of contents or put content between the title page
6685 and the TOC.
6686 Changed in version 1.5: Previously the meaning of
6688 \tableofcontents itself was modified by Sphinx. This
6689 created an incompatibility with dedicated packages mod‐
6690 ifying it also such as “tocloft” or “etoc”.
6691 'transition'
6694 Commands used to display transitions, default
6695 '\n\n\\bigskip\\hrule\\bigskip\n\n'. Override if you
6696 want to display transitions differently.
6697 New in version 1.2.
6699 Changed in version 1.6: Remove unneeded {} after
6702 \\hrule.
6703 'printindex'
6706 “printindex” call, the last thing in the file, default
6707 '\\printindex'. Override if you want to generate the
6708 index differently or append some content after the
6709 index. For example '\\footnote‐
6710 size\\raggedright\\printindex' is advisable when the
6711 index is full of long entries.
6712 · Keys that are set by other options and therefore should not be
6714 overridden are:
6715 'docclass' 'classoptions' 'title' 'date' 'release' 'author'
6717 'logo' 'makeindex' 'shorthandoff'
6718 latex_docclass
6720 A dictionary mapping 'howto' and 'manual' to names of real docu‐
6721 ment classes that will be used as the base for the two Sphinx
6722 classes. Default is to use 'article' for 'howto' and 'report'
6723 for 'manual'.
6724 New in version 1.0.
6726 Changed in version 1.5: In Japanese docs (language is 'ja'), by
6729 default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6730 latex_additional_files
6733 A list of file names, relative to the configuration directory,
6734 to copy to the build directory when building LaTeX output. This
6735 is useful to copy files that Sphinx doesn’t copy automatically,
6736 e.g. if they are referenced in custom LaTeX added in latex_ele‐
6737 ments. Image files that are referenced in source files (e.g.
6738 via .. image::) are copied automatically.
6739 You have to make sure yourself that the filenames don’t collide
6741 with those of any automatically copied files.
6742 New in version 0.6.
6744 Changed in version 1.2: This overrides the files which is pro‐
6747 vided from Sphinx such as sphinx.sty.
6748 Options for text output
6751 These options influence text output.
6752 text_newlines
6754 Determines which end-of-line character(s) are used in text out‐
6755 put.
6756 · 'unix': use Unix-style line endings (\n)
6758 · 'windows': use Windows-style line endings (\r\n)
6760 · 'native': use the line ending style of the platform the docu‐
6762 mentation is built on
6763 Default: 'unix'.
6765 New in version 1.1.
6767 text_sectionchars
6770 A string of 7 characters that should be used for underlining
6771 sections. The first character is used for first-level headings,
6772 the second for second-level headings and so on.
6773 The default is '*=-~"+`'.
6775 New in version 1.1.
6777 text_add_secnumbers
6780 A boolean that decides whether section numbers are included in
6781 text output. Default is True.
6782 New in version 1.7.
6784 text_secnumber_suffix
6787 Suffix for section numbers in text output. Default: ". ". Set
6788 to " " to suppress the final dot on section numbers.
6789 New in version 1.7.
6791 Options for manual page output
6794 These options influence manual page output.
6795 man_pages
6797 This value determines how to group the document tree into manual
6798 pages. It must be a list of tuples (startdocname, name,
6799 description, authors, section), where the items are:
6800 · startdocname: document name that is the “root” of the manual
6802 page. All documents referenced by it in TOC trees will be
6803 included in the manual file too. (If you want one master man‐
6804 ual page, use your master_doc here.)
6805 · name: name of the manual page. This should be a short string
6807 without spaces or special characters. It is used to determine
6808 the file name as well as the name of the manual page (in the
6809 NAME section).
6810 · description: description of the manual page. This is used in
6812 the NAME section.
6813 · authors: A list of strings with authors, or a single string.
6815 Can be an empty string or list if you do not want to automati‐
6816 cally generate an AUTHORS section in the manual page.
6817 · section: The manual page section. Used for the output file
6819 name as well as in the manual page header.
6820 New in version 1.0.
6822 man_show_urls
6825 If true, add URL addresses after links. Default is False.
6826 New in version 1.1.
6828 Options for Texinfo output
6831 These options influence Texinfo output.
6832 texinfo_documents
6834 This value determines how to group the document tree into Tex‐
6835 info source files. It must be a list of tuples (startdocname,
6836 targetname, title, author, dir_entry, description, category,
6837 toctree_only), where the items are:
6838 · startdocname: document name that is the “root” of the Texinfo
6840 file. All documents referenced by it in TOC trees will be
6841 included in the Texinfo file too. (If you want only one Tex‐
6842 info file, use your master_doc here.)
6843 · targetname: file name (no extension) of the Texinfo file in
6845 the output directory.
6846 · title: Texinfo document title. Can be empty to use the title
6848 of the startdoc. Inserted as Texinfo markup, so special char‐
6849 acters like @ and {} will need to be escaped to be inserted
6850 literally.
6851 · author: Author for the Texinfo document. Inserted as Texinfo
6853 markup. Use @* to separate multiple authors, as in:
6854 'John@*Sarah'.
6855 · dir_entry: The name that will appear in the top-level DIR menu
6857 file.
6858 · description: Descriptive text to appear in the top-level DIR
6860 menu file.
6861 · category: Specifies the section which this entry will appear
6863 in the top-level DIR menu file.
6864 · toctree_only: Must be True or False. If true, the startdoc
6866 document itself is not included in the output, only the docu‐
6867 ments referenced by it via TOC trees. With this option, you
6868 can put extra stuff in the master document that shows up in
6869 the HTML, but not the Texinfo output.
6870 New in version 1.1.
6872 texinfo_appendices
6875 A list of document names to append as an appendix to all manu‐
6876 als.
6877 New in version 1.1.
6879 texinfo_domain_indices
6882 If true, generate domain-specific indices in addition to the
6883 general index. For e.g. the Python domain, this is the global
6884 module index. Default is True.
6885 This value can be a bool or a list of index names that should be
6887 generated, like for html_domain_indices.
6888 New in version 1.1.
6890 texinfo_show_urls
6893 Control how to display URL addresses.
6894 · 'footnote' – display URLs in footnotes (default)
6896 · 'no' – do not display URLs
6898 · 'inline' – display URLs inline in parentheses
6900 New in version 1.1.
6902 texinfo_no_detailmenu
6905 If true, do not generate a @detailmenu in the “Top” node’s menu
6906 containing entries for each sub-node in the document. Default
6907 is False.
6908 New in version 1.2.
6910 texinfo_elements
6913 A dictionary that contains Texinfo snippets that override those
6914 Sphinx usually puts into the generated .texi files.
6915 · Keys that you may want to override include:
6917 'paragraphindent'
6919 Number of spaces to indent the first line of each para‐
6920 graph, default 2. Specify 0 for no indentation.
6921 'exampleindent'
6923 Number of spaces to indent the lines for examples or
6924 literal blocks, default 4. Specify 0 for no indenta‐
6925 tion.
6926 'preamble'
6928 Texinfo markup inserted near the beginning of the file.
6929 'copying'
6931 Texinfo markup inserted within the @copying block and
6932 displayed after the title. The default value consists
6933 of a simple title page identifying the project.
6934 · Keys that are set by other options and therefore should not be
6936 overridden are:
6937 'author' 'body' 'date' 'direntry' 'filename' 'project'
6939 'release' 'title'
6940 New in version 1.1.
6942 Options for QtHelp output
6945 These options influence qthelp output. As this builder derives from
6946 the HTML builder, the HTML options also apply where appropriate.
6947 qthelp_basename
6949 The basename for the qthelp file. It defaults to the project
6950 name.
6951 qthelp_namespace
6953 The namespace for the qthelp file. It defaults to
6954 org.sphinx.<project_name>.<project_version>.
6955 qthelp_theme
6957 The HTML theme for the qthelp output. This defaults to 'nonav'.
6958 qthelp_theme_options
6960 A dictionary of options that influence the look and feel of the
6961 selected theme. These are theme-specific. For the options
6962 understood by the builtin themes, see this section.
6963 Options for the linkcheck builder
6965 linkcheck_ignore
6966 A list of regular expressions that match URIs that should not be
6967 checked when doing a linkcheck build. Example:
6968 linkcheck_ignore = [r'http://localhost:\d+/']
6970 New in version 1.1.
6972 linkcheck_retries
6975 The number of times the linkcheck builder will attempt to check
6976 a URL before declaring it broken. Defaults to 1 attempt.
6977 New in version 1.4.
6979 linkcheck_timeout
6982 A timeout value, in seconds, for the linkcheck builder. The
6983 default is to use Python’s global socket timeout.
6984 New in version 1.1.
6986 linkcheck_workers
6989 The number of worker threads to use when checking links.
6990 Default is 5 threads.
6991 New in version 1.1.
6993 linkcheck_anchors
6996 If true, check the validity of #anchors in links. Since this
6997 requires downloading the whole document, it’s considerably
6998 slower when enabled. Default is True.
6999 New in version 1.2.
7001 linkcheck_anchors_ignore
7004 A list of regular expressions that match URIs that should skip
7005 checking the validity of anchors in links. This allows skipping
7006 entire sites, where anchors are used to control dynamic pages,
7007 or just specific anchors within a page, where javascript is used
7008 to add anchors dynamically, or use the fragment as part of to
7009 trigger an internal REST request. Default is ["/#!"].
7010 New in version 1.5.
7012 Options for the XML builder
7015 xml_pretty
7016 If true, pretty-print the XML. Default is True.
7017 New in version 1.2.
7019
7022 [1] A note on available globbing syntax: you can use the standard
7023 shell constructs *, ?, [...] and [!...] with the feature that
7024 these all don’t match slashes. A double star ** can be used to
7025 match any sequence of characters including slashes.
7026 Options for the C++ domain
7028 cpp_index_common_prefix
7029 A list of prefixes that will be ignored when sorting C++ objects
7030 in the global index. For example ['awesome_lib::'].
7031 New in version 1.5.
7033 cpp_id_attributes
7036 A list of strings that the parser additionally should accept as
7037 attributes. This can for example be used when attributes have
7038 been #define d for portability.
7039 New in version 1.5.
7041 cpp_paren_attributes
7044 A list of strings that the parser additionally should accept as
7045 attributes with one argument. That is, if my_align_as is in the
7046 list, then my_align_as(X) is parsed as an attribute for all
7047 strings X that have balanced brances ((), [], and {}). This can
7048 for example be used when attributes have been #define d for
7049 portability.
7050 New in version 1.5.
7052
7055 # -*- coding: utf-8 -*-
7056 #
7057 # test documentation build configuration file, created by
7058 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
7059 #
7060 # This file is execfile()d with the current directory set to its
7061 # containing dir.
7062 #
7063 # Note that not all possible configuration values are present in this
7064 # autogenerated file.
7065 #
7066 # All configuration values have a default; values that are commented out
7067 # serve to show the default.
7068 # If extensions (or modules to document with autodoc) are in another directory,
7070 # add these directories to sys.path here. If the directory is relative to the
7071 # documentation root, use os.path.abspath to make it absolute, like shown here.
7072 #
7073 # import os
7074 # import sys
7075 # sys.path.insert(0, os.path.abspath('.'))
7076 # -- General configuration ------------------------------------------------
7078 # If your documentation needs a minimal Sphinx version, state it here.
7080 #
7081 # needs_sphinx = '1.0'
7082 # Add any Sphinx extension module names here, as strings. They can be
7084 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
7085 # ones.
7086 extensions = []
7087 # Add any paths that contain templates here, relative to this directory.
7089 templates_path = ['_templates']
7090 # The suffix(es) of source filenames.
7092 # You can specify multiple suffix as a list of string:
7093 #
7094 # source_suffix = ['.rst', '.md']
7095 source_suffix = '.rst'
7096 # The encoding of source files.
7098 #
7099 # source_encoding = 'utf-8-sig'
7100 # The master toctree document.
7102 master_doc = 'index'
7103 # General information about the project.
7105 project = u'test'
7106 copyright = u'2016, test'
7107 author = u'test'
7108 # The version info for the project you're documenting, acts as replacement for
7110 # |version| and |release|, also used in various other places throughout the
7111 # built documents.
7112 #
7113 # The short X.Y version.
7114 version = u'test'
7115 # The full version, including alpha/beta/rc tags.
7116 release = u'test'
7117 # The language for content autogenerated by Sphinx. Refer to documentation
7119 # for a list of supported languages.
7120 #
7121 # This is also used if you do content translation via gettext catalogs.
7122 # Usually you set "language" from the command line for these cases.
7123 language = None
7124 # There are two options for replacing |today|: either, you set today to some
7126 # non-false value, then it is used:
7127 #
7128 # today = ''
7129 #
7130 # Else, today_fmt is used as the format for a strftime call.
7131 #
7132 # today_fmt = '%B %d, %Y'
7133 # List of patterns, relative to source directory, that match files and
7135 # directories to ignore when looking for source files.
7136 # These patterns also affect html_static_path and html_extra_path
7137 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
7138 # The reST default role (used for this markup: `text`) to use for all
7140 # documents.
7141 #
7142 # default_role = None
7143 # If true, '()' will be appended to :func: etc. cross-reference text.
7145 #
7146 # add_function_parentheses = True
7147 # If true, the current module name will be prepended to all description
7149 # unit titles (such as .. function::).
7150 #
7151 # add_module_names = True
7152 # If true, sectionauthor and moduleauthor directives will be shown in the
7154 # output. They are ignored by default.
7155 #
7156 # show_authors = False
7157 # The name of the Pygments (syntax highlighting) style to use.
7159 pygments_style = 'sphinx'
7160 # A list of ignored prefixes for module index sorting.
7162 # modindex_common_prefix = []
7163 # If true, keep warnings as "system message" paragraphs in the built documents.
7165 # keep_warnings = False
7166 # If true, `todo` and `todoList` produce output, else they produce nothing.
7168 todo_include_todos = False
7169 # -- Options for HTML output ----------------------------------------------
7172 # The theme to use for HTML and HTML Help pages. See the documentation for
7174 # a list of builtin themes.
7175 #
7176 html_theme = 'alabaster'
7177 # Theme options are theme-specific and customize the look and feel of a theme
7179 # further. For a list of options available for each theme, see the
7180 # documentation.
7181 #
7182 # html_theme_options = {}
7183 # Add any paths that contain custom themes here, relative to this directory.
7185 # html_theme_path = []
7186 # The name for this set of Sphinx documents.
7188 # "<project> v<release> documentation" by default.
7189 #
7190 # html_title = u'test vtest'
7191 # A shorter title for the navigation bar. Default is the same as html_title.
7193 #
7194 # html_short_title = None
7195 # The name of an image file (relative to this directory) to place at the top
7197 # of the sidebar.
7198 #
7199 # html_logo = None
7200 # The name of an image file (relative to this directory) to use as a favicon of
7202 # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
7203 # pixels large.
7204 #
7205 # html_favicon = None
7206 # Add any paths that contain custom static files (such as style sheets) here,
7208 # relative to this directory. They are copied after the builtin static files,
7209 # so a file named "default.css" will overwrite the builtin "default.css".
7210 html_static_path = ['_static']
7211 # Add any extra paths that contain custom files (such as robots.txt or
7213 # .htaccess) here, relative to this directory. These files are copied
7214 # directly to the root of the documentation.
7215 #
7216 # html_extra_path = []
7217 # If not None, a 'Last updated on:' timestamp is inserted at every page
7219 # bottom, using the given strftime format.
7220 # The empty string is equivalent to '%b %d, %Y'.
7221 #
7222 # html_last_updated_fmt = None
7223 # Custom sidebar templates, maps document names to template names.
7225 #
7226 # html_sidebars = {}
7227 # Additional templates that should be rendered to pages, maps page names to
7229 # template names.
7230 #
7231 # html_additional_pages = {}
7232 # If false, no module index is generated.
7234 #
7235 # html_domain_indices = True
7236 # If false, no index is generated.
7238 #
7239 # html_use_index = True
7240 # If true, the index is split into individual pages for each letter.
7242 #
7243 # html_split_index = False
7244 # If true, links to the reST sources are added to the pages.
7246 #
7247 # html_show_sourcelink = True
7248 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7250 #
7251 # html_show_sphinx = True
7252 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7254 #
7255 # html_show_copyright = True
7256 # If true, an OpenSearch description file will be output, and all pages will
7258 # contain a <link> tag referring to it. The value of this option must be the
7259 # base URL from which the finished HTML is served.
7260 #
7261 # html_use_opensearch = ''
7262 # This is the file name suffix for HTML files (e.g. ".xhtml").
7264 # html_file_suffix = None
7265 # Language to be used for generating the HTML full-text search index.
7267 # Sphinx supports the following languages:
7268 # 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
7269 # 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
7270 #
7271 # html_search_language = 'en'
7272 # A dictionary with options for the search language support, empty by default.
7274 # 'ja' uses this config value.
7275 # 'zh' user can custom change `jieba` dictionary path.
7276 #
7277 # html_search_options = {'type': 'default'}
7278 # The name of a javascript file (relative to the configuration directory) that
7280 # implements a search results scorer. If empty, the default will be used.
7281 #
7282 # html_search_scorer = 'scorer.js'
7283 # Output file base name for HTML help builder.
7285 htmlhelp_basename = 'testdoc'
7286 # -- Options for LaTeX output ---------------------------------------------
7288 latex_elements = {
7290 # The paper size ('letterpaper' or 'a4paper').
7291 #
7292 # 'papersize': 'letterpaper',
7293 # The font size ('10pt', '11pt' or '12pt').
7295 #
7296 # 'pointsize': '10pt',
7297 # Additional stuff for the LaTeX preamble.
7299 #
7300 # 'preamble': '',
7301 # Latex figure (float) alignment
7303 #
7304 # 'figure_align': 'htbp',
7305 }
7306 # Grouping the document tree into LaTeX files. List of tuples
7308 # (source start file, target name, title,
7309 # author, documentclass [howto, manual, or own class]).
7310 latex_documents = [
7311 (master_doc, 'test.tex', u'test Documentation',
7312 u'test', 'manual'),
7313 ]
7314 # The name of an image file (relative to this directory) to place at the top of
7316 # the title page.
7317 #
7318 # latex_logo = None
7319 # If true, show page references after internal links.
7321 #
7322 # latex_show_pagerefs = False
7323 # If true, show URL addresses after external links.
7325 #
7326 # latex_show_urls = False
7327 # Documents to append as an appendix to all manuals.
7329 #
7330 # latex_appendices = []
7331 # If false, no module index is generated.
7333 #
7334 # latex_domain_indices = True
7335 # -- Options for manual page output ---------------------------------------
7338 # One entry per manual page. List of tuples
7340 # (source start file, name, description, authors, manual section).
7341 man_pages = [
7342 (master_doc, 'test', u'test Documentation',
7343 [author], 1)
7344 ]
7345 # If true, show URL addresses after external links.
7347 #
7348 # man_show_urls = False
7349 # -- Options for Texinfo output -------------------------------------------
7352 # Grouping the document tree into Texinfo files. List of tuples
7354 # (source start file, target name, title, author,
7355 # dir menu entry, description, category)
7356 texinfo_documents = [
7357 (master_doc, 'test', u'test Documentation',
7358 author, 'test', 'One line description of project.',
7359 'Miscellaneous'),
7360 ]
7361 # Documents to append as an appendix to all manuals.
7363 #
7364 # texinfo_appendices = []
7365 # If false, no module index is generated.
7367 #
7368 # texinfo_domain_indices = True
7369 # How to display URL addresses: 'footnote', 'no', or 'inline'.
7371 #
7372 # texinfo_show_urls = 'footnote'
7373 # If true, do not generate a @detailmenu in the "Top" node's menu.
7375 #
7376 # texinfo_no_detailmenu = False
7377 # -- A random example -----------------------------------------------------
7379 import sys, os
7381 sys.path.insert(0, os.path.abspath('.'))
7382 exclude_patterns = ['zzz']
7383 numfig = True
7385 #language = 'ja'
7386 extensions.append('sphinx.ext.todo')
7388 extensions.append('sphinx.ext.autodoc')
7389 #extensions.append('sphinx.ext.autosummary')
7390 extensions.append('sphinx.ext.intersphinx')
7391 extensions.append('sphinx.ext.mathjax')
7392 extensions.append('sphinx.ext.viewcode')
7393 extensions.append('sphinx.ext.graphviz')
7394 autosummary_generate = True
7397 html_theme = 'default'
7398 #source_suffix = ['.rst', '.txt']
7399
7402 New in version 1.1.
7403 Complementary to translations provided for Sphinx-generated messages
7406 such as navigation bars, Sphinx provides mechanisms facilitating docu‐
7407 ment translations in itself. See the intl-options for details on con‐
7408 figuration.
7409 [image] Workflow visualization of translations in Sphinx. (The
7410 stick-figure is taken from an XKCD comic.).UNINDENT
7411 · Sphinx internationalization details
7413 · Translating with sphinx-intl
7415 · Quick guide
7417 · Translating
7419 · Update your po files by new pot files
7421 · Using Transifex service for team translation
7423 · Contributing to Sphinx reference translation
7425 Sphinx internationalization details
7427 gettext [1] is an established standard for internationalization and
7428 localization. It naively maps messages in a program to a translated
7429 string. Sphinx uses these facilities to translate whole documents.
7430 Initially project maintainers have to collect all translatable strings
7432 (also referred to as messages) to make them known to translators.
7433 Sphinx extracts these through invocation of sphinx-build -b gettext.
7434 Every single element in the doctree will end up in a single message
7436 which results in lists being equally split into different chunks while
7437 large paragraphs will remain as coarsely-grained as they were in the
7438 original document. This grants seamless document updates while still
7439 providing a little bit of context for translators in free-text pas‐
7440 sages. It is the maintainer’s task to split up paragraphs which are
7441 too large as there is no sane automated way to do that.
7442 After Sphinx successfully ran the MessageCatalogBuilder you will find a
7444 collection of .pot files in your output directory. These are catalog
7445 templates and contain messages in your original language only.
7446 They can be delivered to translators which will transform them to .po
7448 files — so called message catalogs — containing a mapping from the
7449 original messages to foreign-language strings.
7450 Gettext compiles them into a binary format known as binary catalogs
7452 through msgfmt for efficiency reasons. If you make these files discov‐
7453 erable with locale_dirs for your language, Sphinx will pick them up
7454 automatically.
7455 An example: you have a document usage.rst in your Sphinx project. The
7457 gettext builder will put its messages into usage.pot. Imagine you have
7458 Spanish translations [2] on your hands in usage.po — for your builds to
7459 be translated you need to follow these instructions:
7460 · Compile your message catalog to a locale directory, say locale, so it
7462 ends up in ./locale/es/LC_MESSAGES/usage.mo in your source directory
7463 (where es is the language code for Spanish.)
7464 msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
7466 · Set locale_dirs to ["locale/"].
7468 · Set language to es (also possible via -D).
7470 · Run your desired build.
7472 Translating with sphinx-intl
7474 Quick guide
7475 sphinx-intl is a useful tool to work with Sphinx translation flow.
7476 This section describe an easy way to translate with sphinx-intl.
7477 1. Install sphinx-intl by pip install sphinx-intl or easy_install
7479 sphinx-intl.
7480 2. Add configurations to your conf.py:
7482 locale_dirs = ['locale/'] # path is example but recommended.
7484 gettext_compact = False # optional.
7485 This case-study assumes that locale_dirs is set to ‘locale/’ and
7487 gettext_compact is set to False (the Sphinx document is already con‐
7488 figured as such).
7489 3. Extract document’s translatable messages into pot files:
7491 $ make gettext
7493 As a result, many pot files are generated under _build/gettext
7495 directory.
7496 4. Setup/Update your locale_dir:
7498 $ sphinx-intl update -p _build/gettext -l de -l ja
7500 Done. You got these directories that contain po files:
7502 · ./locale/de/LC_MESSAGES/
7504 · ./locale/ja/LC_MESSAGES/
7506 5. Translate your po files under ./locale/<lang>/LC_MESSAGES/.
7508 6. make translated document.
7510 You need a language parameter in conf.py or you may also specify the
7512 parameter on the command line (for BSD/GNU make):
7513 $ make -e SPHINXOPTS="-D language='de'" html
7515 command line (for Windows cmd.exe):
7517 > set SPHINXOPTS=-D language='de'
7519 > .\make.bat html
7520 command line (for PowerShell):
7522 > Set-Item env:SPHINXOPTS "-D language='de'"
7524 > .\make.bat html
7525 Congratulations! You got the translated documentation in the
7527 _build/html directory.
7528 New in version 1.3: sphinx-build that is invoked by make command will
7530 build po files into mo files.
7531 If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
7533 mand before make command.
7534 Translating
7537 Translate po file under ./locale/de/LC_MESSAGES directory. The case of
7538 builders.po file for sphinx document:
7539 # a5600c3d2e3d48fc8c261ea0284db79b
7541 #: ../../builders.rst:4
7542 msgid "Available builders"
7543 msgstr "<FILL HERE BY TARGET LANGUAGE>"
7544 Another case, msgid is multi-line text and contains reStructuredText
7546 syntax:
7547 # 302558364e1d41c69b3277277e34b184
7549 #: ../../builders.rst:9
7550 msgid ""
7551 "These are the built-in Sphinx builders. More builders can be added by "
7552 ":ref:`extensions <extensions>`."
7553 msgstr ""
7554 "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
7555 "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
7556 Please be careful not to break reST notation. Most po-editors will
7558 help you with that.
7559 Update your po files by new pot files
7561 If a document is updated, it is necessary to generate updated pot files
7562 and to apply differences to translated po files. In order to apply the
7563 updating difference of a pot file to po file, use the sphinx-intl
7564 update command.
7565 $ sphinx-intl update -p _build/locale
7567 Using Transifex service for team translation
7569 Transifex is one of several services that allow collaborative transla‐
7570 tion via a web interface. It has a nifty Python-based command line
7571 client that makes it easy to fetch and push translations.
7572 1. Install transifex-client
7574 You need tx command to upload resources (pot files).
7576 $ pip install transifex-client
7578 SEE ALSO:
7580 Transifex Client documentation
7581 2. Create your transifex account and create new project for your docu‐
7583 ment
7584 Currently, transifex does not allow for a translation project to
7586 have more than one version of the document, so you’d better include
7587 a version number in your project name.
7588 For example:
7590 Project ID
7592 sphinx-document-test_1_0
7593 Project URL
7595 https://www.transifex.com/projects/p/sphinx-docu‐
7596 ment-test_1_0/
7597 3. Create config files for tx command
7599 This process will create .tx/config in the current directory, as
7601 well as a ~/.transifexrc file that includes auth information.
7602 $ tx init
7604 Creating .tx folder...
7605 Transifex instance [https://www.transifex.com]:
7606 ...
7607 Please enter your transifex username: <transifex-username>
7608 Password: <transifex-password>
7609 ...
7610 Done.
7611 4. Upload pot files to transifex service
7613 Register pot files to .tx/config file:
7615 $ cd /your/document/root
7617 $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
7618 --transifex-project-name sphinx-document-test_1_0
7619 and upload pot files:
7621 $ tx push -s
7623 Pushing translations for resource sphinx-document-test_1_0.builders:
7624 Pushing source file (locale/pot/builders.pot)
7625 Resource does not exist. Creating...
7626 ...
7627 Done.
7628 5. Forward the translation on transifex
7630 6. Pull translated po files and make translated html
7632 Get translated catalogs and build mo files (ex. for ‘de’):
7634 $ cd /your/document/root
7636 $ tx pull -l de
7637 Pulling translations for resource sphinx-document-test_1_0.builders (...)
7638 -> de: locale/de/LC_MESSAGES/builders.po
7639 ...
7640 Done.
7641 Invoke make html (for BSD/GNU make):
7643 $ make -e SPHINXOPTS="-D language='de'" html
7645 That’s all!
7647 TIP:
7649 Translating locally and on Transifex
7650 If you want to push all language’s po files, you can be done by
7652 using tx push -t command. Watch out! This operation overwrites
7653 translations in transifex.
7654 In other words, if you have updated each in the service and local po
7656 files, it would take much time and effort to integrate them.
7657 Contributing to Sphinx reference translation
7659 The recommended way for new contributors to translate Sphinx reference
7660 is to join the translation team on Transifex.
7661 There is sphinx translation page for Sphinx (master) documentation.
7663 1. Login to transifex service.
7665 2. Go to sphinx translation page.
7667 3. Click Request language and fill form.
7669 4. Wait acceptance by transifex sphinx translation maintainers.
7671 5. (after acceptance) translate on transifex.
7673
7675 [1] See the GNU gettext utilities for details on that software suite.
7676 [2] Because nobody expects the Spanish Inquisition!
7678
7680 New in version 0.6.
7681 Sphinx supports changing the appearance of its HTML output via themes.
7684 A theme is a collection of HTML templates, stylesheet(s) and other
7685 static files. Additionally, it has a configuration file which speci‐
7686 fies from which theme to inherit, which highlighting style to use, and
7687 what options exist for customizing the theme’s look and feel.
7688 Themes are meant to be project-unaware, so they can be used for differ‐
7690 ent projects without change.
7691 Using a theme
7693 Using an existing theme is easy. If the theme is builtin to Sphinx,
7694 you only need to set the html_theme config value. With the
7695 html_theme_options config value you can set theme-specific options that
7696 change the look and feel. For example, you could have the following in
7697 your conf.py:
7698 html_theme = "classic"
7700 html_theme_options = {
7701 "rightsidebar": "true",
7702 "relbarbgcolor": "black"
7703 }
7704 That would give you the classic theme, but with a sidebar on the right
7706 side and a black background for the relation bar (the bar with the nav‐
7707 igation links at the page’s top and bottom).
7708 If the theme does not come with Sphinx, it can be in two static forms:
7710 either a directory (containing theme.conf and other needed files), or a
7711 zip file with the same contents. Either of them must be put where
7712 Sphinx can find it; for this there is the config value html_theme_path.
7713 It gives a list of directories, relative to the directory containing
7714 conf.py, that can contain theme directories or zip files. For example,
7715 if you have a theme in the file blue.zip, you can put it right in the
7716 directory containing conf.py and use this configuration:
7717 html_theme = "blue"
7719 html_theme_path = ["."]
7720 The third form is a python package. If a theme you want to use is dis‐
7722 tributed as a python package, you can use it after installing
7723 # installing theme package
7725 $ pip install sphinxjp.themes.dotted
7726 # use it in your conf.py
7728 html_theme = "dotted"
7729 Builtin themes
7731 ──────────────────────────────────────────────────────────
7732 Theme overview
7733 ──────────────────────────────────────────────────────────
7734 [image: alabaster] [image] [image: classic] [image]
7735 alabaster classic
7738 ──────────────────────────────────────────────────────────
7739 [image: sphinxdoc] [image] [image: scrolls] [image]
7740 sphinxdoc scrolls
7743 ──────────────────────────────────────────────────────────
7744 [image: agogo] [image] [image: traditional]
7745 [image]
7746 agogo
7748 traditional
7749 ──────────────────────────────────────────────────────────
7750 [image: nature] [image] [image: haiku] [image]
7751 nature haiku
7754 ──────────────────────────────────────────────────────────
7755 [image: pyramid] [image] [image: bizstyle] [image]
7756 pyramid bizstyle
7759 ┌───────────────────────────┬────────────────────────────┐
7760 │ │ │
7761 Sphinx │comes with a selection of th│emes to choose from. │
7762 │ │ │
7763 These t│hemes are: │ │
7764 │ │ │
7765 · basic│ – This is a basically unst│yled layout used as the base │for the
7766 other│themes, and usable as the b│ase for custom themes as well│. The
7767 HTML │contains all important ele│ments like sidebar and relati│on bar.
7768 There│are these options (which ar│e inherited by the other them│es):
7769 │ │ │
7770 · nos│idebar (true or false): Don’│t include the sidebar. Defau│lts to
7771 Fal│se. │ │
7772 │ │ │
7773 · sid│ebarwidth (int or str): W│idth of the sidebar in pixels│. This
7774 can│be an int, which is interpr│eted as pixels or a valid CSS│dimen‐
7775 sio│n string such as ‘70em’ or ‘│50%’. Defaults to 230 pixels│.
7776 │ │ │
7777 · bod│y_min_width (int or str):│Minimal width of the documen│t body.
7778 Thi│s can be an int, which is in│terpreted as pixels or a val│id CSS
7779 dim│ension string such as ‘70em’│or ‘50%’. Use 0 if you don’t│want a
7780 wid│th limit. Defaults may depen│d on the theme (often 450px).│
7781 │ │ │
7782 · bod│y_max_width (int or str): Ma│ximal width of the document│ body.
7783 Thi│s can be an int, which is │interpreted as pixels or a va│lid CSS
7784 dim│ension string such as ‘70em’│or ‘50%’. Use ‘none’ if you│ don’t
7785 wan│t a width limit. Defaults ma│y depend on the theme (often │800px).
7786 │ │ │
7787 · alaba│ster – Alabaster theme i│s a modified “Kr” Sphinx the│me from
7788 @kenn│ethreitz (especially as used│in his Requests project), wh│ich was
7789 itsel│f originally based on @m│itsuhiko’s theme used for │Flask &
7790 relat│ed projects. Check out at i│ts installation page how to │set up
7791 prope│rly html_sidebars for its us│e. │
7792 │ │ │
7793 · class│ic – This is the classic │theme, which looks like the P│ython 2
7794 docum│entation. It can be customi│zed via these options: │
7795 │ │ │
7796 · rig│htsidebar (true or false): P│ut the sidebar on the right│ side.
7797 Def│aults to False. │ │
7798 │ │ │
7799 · sti│ckysidebar (true or false):│Make the sidebar “fixed” so │that it
7800 doe│sn’t scroll out of view for │long body content. This m│ay not
7801 wor│k well with all browsers. D│efaults to False. │
7802 │ │ │
7803 · col│lapsiblesidebar (true or fa│lse): Add an experimental Jav│aScript
7804 sni│ppet that makes the sidebar │collapsible via a button │on its
7805 sid│e. Doesn’t work with “stick│ysidebar”. Defaults to False.│
7806 │ │ │
7807 · ext│ernalrefs (true or false)│: Display external links diff│erently
7808 fro│m internal links. Defaults │to False. │
7809 │ │ │
7810 There│are also various color and │font options that can chan│ge the
7811 color│scheme without having to wr│ite a custom stylesheet: │
7812 │ │ │
7813 · foo│terbgcolor (CSS color): Back│ground color for the footer l│ine.
7814 │ │ │
7815 · foo│tertextcolor (CSS color): Te│xt color for the footer line.│
7816 │ │ │
7817 · sid│ebarbgcolor (CSS color): Bac│kground color for the sidebar│.
7818 │ │ │
7819 · sid│ebarbtncolor (CSS color): B│ackground color for the sideb│ar col‐
7820 lap│se button (used when collaps│iblesidebar is True). │
7821 │ │ │
7822 · sid│ebartextcolor (CSS color): T│ext color for the sidebar. │
7823 │ │ │
7824 · sid│ebarlinkcolor (CSS color): L│ink color for the sidebar. │
7825 │ │ │
7826 · rel│barbgcolor (CSS color): Back│ground color for the relation│bar.
7827 │ │ │
7828 · rel│bartextcolor (CSS color): Te│xt color for the relation bar│.
7829 │ │ │
7830 · relbarlinkcolor (CSS color): Link color for the relation bar.
7831 · bgcolor (CSS color): Body background color.
7833 · textcolor (CSS color): Body text color.
7835 · linkcolor (CSS color): Body link color.
7837 · visitedlinkcolor (CSS color): Body color for visited links.
7839 · headbgcolor (CSS color): Background color for headings.
7841 · headtextcolor (CSS color): Text color for headings.
7843 · headlinkcolor (CSS color): Link color for headings.
7845 · codebgcolor (CSS color): Background color for code blocks.
7847 · codetextcolor (CSS color): Default text color for code blocks, if
7849 not set differently by the highlighting style.
7850 · bodyfont (CSS font-family): Font for normal text.
7852 · headfont (CSS font-family): Font for headings.
7854 · sphinxdoc – The theme originally used by this documentation. It fea‐
7856 tures a sidebar on the right side. There are currently no options
7857 beyond nosidebar and sidebarwidth.
7858 NOTE:
7860 The Sphinx documentation now uses an adjusted version of the
7861 sphinxdoc theme.
7862 · scrolls – A more lightweight theme, based on the Jinja documentation.
7864 The following color options are available:
7865 · headerbordercolor
7867 · subheadlinecolor
7869 · linkcolor
7871 · visitedlinkcolor
7873 · admonitioncolor
7875 · agogo – A theme created by Andi Albrecht. The following options are
7877 supported:
7878 · bodyfont (CSS font family): Font for normal text.
7880 · headerfont (CSS font family): Font for headings.
7882 · pagewidth (CSS length): Width of the page content, default 70em.
7884 · documentwidth (CSS length): Width of the document (without side‐
7886 bar), default 50em.
7887 · sidebarwidth (CSS length): Width of the sidebar, default 20em.
7889 · bgcolor (CSS color): Background color.
7891 · headerbg (CSS value for “background”): background for the header
7893 area, default a grayish gradient.
7894 · footerbg (CSS value for “background”): background for the footer
7896 area, default a light gray gradient.
7897 · linkcolor (CSS color): Body link color.
7899 · headercolor1, headercolor2 (CSS color): colors for <h1> and <h2>
7901 headings.
7902 · headerlinkcolor (CSS color): Color for the backreference link in
7904 headings.
7905 · textalign (CSS text-align value): Text alignment for the body,
7907 default is justify.
7908 · nature – A greenish theme. There are currently no options beyond
7910 nosidebar and sidebarwidth.
7911 · pyramid – A theme from the Pyramid web framework project, designed by
7913 Blaise Laflamme. There are currently no options beyond nosidebar and
7914 sidebarwidth.
7915 · haiku – A theme without sidebar inspired by the Haiku OS user guide.
7917 The following options are supported:
7918 · full_logo (true or false, default False): If this is true, the
7920 header will only show the html_logo. Use this for large logos. If
7921 this is false, the logo (if present) will be shown floating right,
7922 and the documentation title will be put in the header.
7923 · textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlink‐
7925 color (CSS colors): Colors for various body elements.
7926 · traditional – A theme resembling the old Python documentation. There
7928 are currently no options beyond nosidebar and sidebarwidth.
7929 · epub – A theme for the epub builder. This theme tries to save visual
7931 space which is a sparse resource on ebook readers. The following
7932 options are supported:
7933 · relbar1 (true or false, default True): If this is true, the relbar1
7935 block is inserted in the epub output, otherwise it is omitted.
7936 · footer (true or false, default True): If this is true, the footer
7938 block is inserted in the epub output, otherwise it is omitted.
7939 · bizstyle – A simple bluish theme. The following options are supported
7941 beyond nosidebar and sidebarwidth:
7942 · rightsidebar (true or false): Put the sidebar on the right side.
7944 Defaults to False.
7945 New in version 1.3: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’
7947 theme.
7948 Changed in version 1.3: The ‘default’ theme has been renamed to ‘clas‐
7951 sic’. ‘default’ is still available, however it will emit a notice that
7952 it is an alias for the new ‘alabaster’ theme.
7953 Creating themes
7956 As said, themes are either a directory or a zipfile (whose name is the
7957 theme name), containing the following:
7958 · A theme.conf file, see below.
7960 · HTML templates, if needed.
7962 · A static/ directory containing any static files that will be copied
7964 to the output static directory on build. These can be images,
7965 styles, script files.
7966 The theme.conf file is in INI format [1] (readable by the standard
7968 Python ConfigParser module) and has the following structure:
7969 [theme]
7971 inherit = base theme
7972 stylesheet = main CSS name
7973 pygments_style = stylename
7974 sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
7975 [options]
7977 variable = default value
7978 · The inherit setting gives the name of a “base theme”, or none. The
7980 base theme will be used to locate missing templates (most themes will
7981 not have to supply most templates if they use basic as the base
7982 theme), its options will be inherited, and all of its static files
7983 will be used as well.
7984 · The stylesheet setting gives the name of a CSS file which will be
7986 referenced in the HTML header. If you need more than one CSS file,
7987 either include one from the other via CSS’ @import, or use a custom
7988 HTML template that adds <link rel="stylesheet"> tags as necessary.
7989 Setting the html_style config value will override this setting.
7990 · The pygments_style setting gives the name of a Pygments style to use
7992 for highlighting. This can be overridden by the user in the pyg‐
7993 ments_style config value.
7994 · The sidebars setting gives the comma separated list of sidebar tem‐
7996 plates for constructing sidebars. This can be overridden by the user
7997 in the html_sidebars config value.
7998 · The options section contains pairs of variable names and default val‐
8000 ues. These options can be overridden by the user in
8001 html_theme_options and are accessible from all templates as
8002 theme_<name>.
8003 New in version 1.7: sidebar settings
8005 Distribute your theme as a python package
8008 As a way to distribute your theme, you can use python package. Python
8009 package brings to users easy setting up ways.
8010 To distribute your theme as a python package, please define an entry
8012 point called sphinx.html_themes in your setup.py file, and write a set‐
8013 up() function to register your themes using add_html_theme() API in it:
8014 # 'setup.py'
8016 setup(
8017 ...
8018 entry_points = {
8019 'sphinx.html_themes': [
8020 'name_of_theme = your_package',
8021 ]
8022 },
8023 ...
8024 )
8025 # 'your_package.py'
8027 from os import path
8028 def setup(app):
8030 app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
8031 If your theme package contains two or more themes, please call
8033 add_html_theme() twice or more.
8034 New in version 1.2: ‘sphinx_themes’ entry_points feature.
8036 Deprecated since version 1.6: sphinx_themes entry_points has been dep‐
8039 recated.
8040 New in version 1.6: sphinx.html_themes entry_points feature.
8043 Templating
8046 The guide to templating is helpful if you want to write your own tem‐
8047 plates. What is important to keep in mind is the order in which Sphinx
8048 searches for templates:
8049 · First, in the user’s templates_path directories.
8051 · Then, in the selected theme.
8053 · Then, in its base theme, its base’s base theme, etc.
8055 When extending a template in the base theme with the same name, use the
8057 theme name as an explicit directory: {% extends "basic/layout.html" %}.
8058 From a user templates_path template, you can still use the “exclamation
8059 mark” syntax as described in the templating document.
8060 Static templates
8062 Since theme options are meant for the user to configure a theme more
8063 easily, without having to write a custom stylesheet, it is necessary to
8064 be able to template static files as well as HTML files. Therefore,
8065 Sphinx supports so-called “static templates”, like this:
8066 If the name of a file in the static/ directory of a theme (or in the
8068 user’s static path, for that matter) ends with _t, it will be processed
8069 by the template engine. The _t will be left from the final file name.
8070 For example, the classic theme has a file static/classic.css_t which
8071 uses templating to put the color options into the stylesheet. When a
8072 documentation is built with the classic theme, the output directory
8073 will contain a _static/classic.css file where all template tags have
8074 been processed.
8075 [1] It is not an executable Python file, as opposed to conf.py,
8077 because that would pose an unnecessary security risk if themes are
8078 shared.
8079 Third Party Themes
8081 ┌───────────────────────────┬───┐
8082 │Theme overview │ │
8083 ├───────────────────────────┼───┤
8084 │[image: sphinx_rtd_theme] │ │
8085 │[image] │ │
8086 │ │ │
8087 │ │ │
8088 │sphinx_rtd_theme │ │
8089 └───────────────────────────┴───┘
8090 · sphinx_rtd_theme – Read the Docs Sphinx Theme. This is a
8092 mobile-friendly sphinx theme that was made for readthedocs.org. View
8093 a working demo over on readthedocs.org. You can get install and
8094 options information at Read the Docs Sphinx Theme page.
8095 Changed in version 1.4: sphinx_rtd_theme has become optional.
8097
8100 Sphinx supports integration with setuptools and distutils through a
8101 custom command - BuildDoc.
8102 Using setuptools integration
8104 The Sphinx build can then be triggered from distutils, and some Sphinx
8105 options can be set in setup.py or setup.cfg instead of Sphinx’s own
8106 configuration file.
8107 For instance, from setup.py:
8109 # this is only necessary when not using setuptools/distribute
8111 from sphinx.setup_command import BuildDoc
8112 cmdclass = {'build_sphinx': BuildDoc}
8113 name = 'My project'
8115 version = '1.2'
8116 release = '1.2.0'
8117 setup(
8118 name=name,
8119 author='Bernard Montgomery',
8120 version=release,
8121 cmdclass=cmdclass,
8122 # these are optional and override conf.py settings
8123 command_options={
8124 'build_sphinx': {
8125 'project': ('setup.py', name),
8126 'version': ('setup.py', version),
8127 'release': ('setup.py', release),
8128 'source_dir': ('setup.py', 'doc')}},
8129 )
8130 NOTE:
8132 If you set Sphinx options directly in the setup() command, replace
8133 hyphens in variable names with underscores. In the example above,
8134 source-dir becomes source_dir.
8135 Or add this section in setup.cfg:
8137 [build_sphinx]
8139 project = 'My project'
8140 version = 1.2
8141 release = 1.2.0
8142 source-dir = 'doc'
8143 Once configured, call this by calling the relevant command on setup.py:
8145 $ python setup.py build_sphinx
8147 Options for setuptools integration
8149 fresh-env
8150 A boolean that determines whether the saved environment should
8151 be discarded on build. Default is false.
8152 This can also be set by passing the -E flag to setup.py.
8154 $ python setup.py build_sphinx -E
8156 all-files
8158 A boolean that determines whether all files should be built from
8159 scratch. Default is false.
8160 This can also be set by passing the -a flag to setup.py:
8162 $ python setup.py build_sphinx -a
8164 source-dir
8166 The target source directory. This can be relative to the set‐
8167 up.py or setup.cfg file, or it can be absolute. It defaults to
8168 ./doc or ./docs if either contains a file named conf.py (check‐
8169 ing ./doc first); otherwise it defaults to the current direc‐
8170 tory.
8171 This can also be set by passing the -s flag to setup.py:
8173 $ python setup.py build_sphinx -s $SOURCE_DIR
8175 build-dir
8177 The target build directory. This can be relative to the setup.py
8178 or setup.cfg file, or it can be absolute. Default is
8179 ./build/sphinx.
8180 config-dir
8182 Location of the configuration directory. This can be relative to
8183 the setup.py or setup.cfg file, or it can be absolute. Default
8184 is to use source-dir.
8185 This can also be set by passing the -c flag to setup.py:
8187 $ python setup.py build_sphinx -c $CONFIG_DIR
8189 New in version 1.0.
8191 builder
8194 The builder or list of builders to use. Default is html.
8195 This can also be set by passing the -b flag to setup.py:
8197 $ python setup.py build_sphinx -b $BUILDER
8199 Changed in version 1.6: This can now be a comma- or space-sepa‐
8201 rated list of builders
8202 warning-is-error
8205 A boolean that ensures Sphinx warnings will result in a failed
8206 build. Default is false.
8207 This can also be set by passing the -W flag to setup.py:
8209 $ python setup.py build_sphinx -W
8211 New in version 1.5.
8213 project
8216 The documented project’s name. Default is ''.
8217 New in version 1.0.
8219 version
8222 The short X.Y version. Default is ''.
8223 New in version 1.0.
8225 release
8228 The full version, including alpha/beta/rc tags. Default is ''.
8229 New in version 1.0.
8231 today How to format the current date, used as the replacement for
8234 |today|. Default is ''.
8235 New in version 1.0.
8237 link-index
8240 A boolean that ensures index.html will be linked to the master
8241 doc. Default is false.
8242 This can also be set by passing the -i flag to setup.py:
8244 $ python setup.py build_sphinx -i
8246 New in version 1.0.
8248 copyright
8251 The copyright string. Default is ''.
8252 New in version 1.3.
8254 pdb A boolean to configure pdb on exception. Default is false.
8257 New in version 1.5.
8259
8262 Sphinx uses the Jinja templating engine for its HTML templates. Jinja
8263 is a text-based engine, and inspired by Django templates, so anyone
8264 having used Django will already be familiar with it. It also has
8265 excellent documentation for those who need to make themselves familiar
8266 with it.
8267 Do I need to use Sphinx’s templates to produce HTML?
8269 No. You have several other options:
8270 · You can write a TemplateBridge subclass that calls your template
8272 engine of choice, and set the template_bridge configuration value
8273 accordingly.
8274 · You can write a custom builder that derives from StandaloneHTML‐
8276 Builder and calls your template engine of choice.
8277 · You can use the PickleHTMLBuilder that produces pickle files with the
8279 page contents, and postprocess them using a custom tool, or use them
8280 in your Web application.
8281 Jinja/Sphinx Templating Primer
8283 The default templating language in Sphinx is Jinja. It’s Django/Smarty
8284 inspired and easy to understand. The most important concept in Jinja
8285 is template inheritance, which means that you can overwrite only spe‐
8286 cific blocks within a template, customizing it while also keeping the
8287 changes at a minimum.
8288 To customize the output of your documentation you can override all the
8290 templates (both the layout templates and the child templates) by adding
8291 files with the same name as the original filename into the template
8292 directory of the structure the Sphinx quickstart generated for you.
8293 Sphinx will look for templates in the folders of templates_path first,
8295 and if it can’t find the template it’s looking for there, it falls back
8296 to the selected theme’s templates.
8297 A template contains variables, which are replaced with values when the
8299 template is evaluated, tags, which control the logic of the template
8300 and blocks which are used for template inheritance.
8301 Sphinx’s basic theme provides base templates with a couple of blocks it
8303 will fill with data. These are located in the themes/basic subdirec‐
8304 tory of the Sphinx installation directory, and used by all builtin
8305 Sphinx themes. Templates with the same name in the templates_path
8306 override templates supplied by the selected theme.
8307 For example, to add a new link to the template area containing related
8309 links all you have to do is to add a new template called layout.html
8310 with the following contents:
8311 {% extends "!layout.html" %}
8313 {% block rootrellink %}
8314 <li><a href="http://project.invalid/">Project Homepage</a> »</li>
8315 {{ super() }}
8316 {% endblock %}
8317 By prefixing the name of the overridden template with an exclamation
8319 mark, Sphinx will load the layout template from the underlying HTML
8320 theme.
8321 Important: If you override a block, call {{ super() }} somewhere to
8323 render the block’s content in the extended template – unless you don’t
8324 want that content to show up.
8325 Working with the builtin templates
8327 The builtin basic theme supplies the templates that all builtin Sphinx
8328 themes are based on. It has the following elements you can override or
8329 use:
8330 Blocks
8332 The following blocks exist in the layout.html template:
8333 doctype
8335 The doctype of the output format. By default this is XHTML 1.0
8336 Transitional as this is the closest to what Sphinx and Docutils
8337 generate and it’s a good idea not to change it unless you want
8338 to switch to HTML 5 or a different but compatible XHTML doctype.
8339 linktags
8341 This block adds a couple of <link> tags to the head section of
8342 the template.
8343 extrahead
8345 This block is empty by default and can be used to add extra con‐
8346 tents into the <head> tag of the generated HTML file. This is
8347 the right place to add references to JavaScript or extra CSS
8348 files.
8349 relbar1 / relbar2
8351 This block contains the relation bar, the list of related links
8352 (the parent documents on the left, and the links to index, mod‐
8353 ules etc. on the right). relbar1 appears before the document,
8354 relbar2 after the document. By default, both blocks are filled;
8355 to show the relbar only before the document, you would override
8356 relbar2 like this:
8357 {% block relbar2 %}{% endblock %}
8359 rootrellink / relbaritems
8361 Inside the relbar there are three sections: The rootrellink, the
8362 links from the documentation and the custom relbaritems. The
8363 rootrellink is a block that by default contains a list item
8364 pointing to the master document by default, the relbaritems is
8365 an empty block. If you override them to add extra links into
8366 the bar make sure that they are list items and end with the
8367 reldelim1.
8368 document
8370 The contents of the document itself. It contains the block
8371 “body” where the individual content is put by subtemplates like
8372 page.html.
8373 sidebar1 / sidebar2
8375 A possible location for a sidebar. sidebar1 appears before the
8376 document and is empty by default, sidebar2 after the document
8377 and contains the default sidebar. If you want to swap the side‐
8378 bar location override this and call the sidebar helper:
8379 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
8381 {% block sidebar2 %}{% endblock %}
8382 (The sidebar2 location for the sidebar is needed by the sphinx‐
8384 doc.css stylesheet, for example.)
8385 sidebarlogo
8387 The logo location within the sidebar. Override this if you want
8388 to place some content at the top of the sidebar.
8389 footer The block for the footer div. If you want a custom footer or
8391 markup before or after it, override this one.
8392 The following four blocks are only used for pages that do not have
8394 assigned a list of custom sidebars in the html_sidebars config value.
8395 Their use is deprecated in favor of separate sidebar templates, which
8396 can be included via html_sidebars.
8397 sidebartoc
8399 The table of contents within the sidebar.
8400 Deprecated since version 1.0.
8402 sidebarrel
8405 The relation links (previous, next document) within the sidebar.
8406 Deprecated since version 1.0.
8408 sidebarsourcelink
8411 The “Show source” link within the sidebar (normally only shown
8412 if this is enabled by html_show_sourcelink).
8413 Deprecated since version 1.0.
8415 sidebarsearch
8418 The search box within the sidebar. Override this if you want to
8419 place some content at the bottom of the sidebar.
8420 Deprecated since version 1.0.
8422 Configuration Variables
8425 Inside templates you can set a couple of variables used by the layout
8426 template using the {% set %} tag:
8427 reldelim1
8429 The delimiter for the items on the left side of the related bar.
8430 This defaults to ' »' Each item in the related bar ends
8431 with the value of this variable.
8432 reldelim2
8434 The delimiter for the items on the right side of the related
8435 bar. This defaults to ' |'. Each item except of the last one
8436 in the related bar ends with the value of this variable.
8437 Overriding works like this:
8439 {% extends "!layout.html" %}
8441 {% set reldelim1 = ' >' %}
8442 script_files
8444 Add additional script files here, like this:
8445 {% set script_files = script_files + ["_static/myscript.js"] %}
8447 Helper Functions
8449 Sphinx provides various Jinja functions as helpers in the template.
8450 You can use them to generate links or output multiply used elements.
8451 pathto(document)
8453 Return the path to a Sphinx document as a URL. Use this to
8454 refer to built documents.
8455 pathto(file, 1)
8457 Return the path to a file which is a filename relative to the
8458 root of the generated output. Use this to refer to static
8459 files.
8460 hasdoc(document)
8462 Check if a document with the name document exists.
8463 sidebar()
8465 Return the rendered sidebar.
8466 relbar()
8468 Return the rendered relation bar.
8469 Global Variables
8471 These global variables are available in every template and are safe to
8472 use. There are more, but most of them are an implementation detail and
8473 might change in the future.
8474 builder
8476 The name of the builder (e.g. html or htmlhelp).
8477 copyright
8479 The value of copyright.
8480 docstitle
8482 The title of the documentation (the value of html_title), except
8483 when the “single-file” builder is used, when it is set to None.
8484 embedded
8486 True if the built HTML is meant to be embedded in some viewing
8487 application that handles navigation, not the web browser, such
8488 as for HTML help or Qt help formats. In this case, the sidebar
8489 is not included.
8490 favicon
8492 The path to the HTML favicon in the static path, or ''.
8493 file_suffix
8495 The value of the builder’s out_suffix attribute, i.e. the file
8496 name extension that the output files will get. For a standard
8497 HTML builder, this is usually .html.
8498 has_source
8500 True if the reST document sources are copied (if
8501 html_copy_source is True).
8502 language
8504 The value of language.
8505 last_updated
8507 The build date.
8508 logo The path to the HTML logo image in the static path, or ''.
8510 master_doc
8512 The value of master_doc, for usage with pathto().
8513 pagename
8515 The “page name” of the current file, i.e. either the document
8516 name if the file is generated from a reST source, or the equiva‐
8517 lent hierarchical name relative to the output directory ([direc‐
8518 tory/]filename_without_extension).
8519 project
8521 The value of project.
8522 release
8524 The value of release.
8525 rellinks
8527 A list of links to put at the left side of the relbar, next to
8528 “next” and “prev”. This usually contains links to the general
8529 index and other indices, such as the Python module index. If
8530 you add something yourself, it must be a tuple (pagename, link
8531 title, accesskey, link text).
8532 shorttitle
8534 The value of html_short_title.
8535 show_source
8537 True if html_show_sourcelink is True.
8538 sphinx_version
8540 The version of Sphinx used to build.
8541 style The name of the main stylesheet, as given by the theme or
8543 html_style.
8544 title The title of the current document, as used in the <title> tag.
8546 use_opensearch
8548 The value of html_use_opensearch.
8549 version
8551 The value of version.
8552 In addition to these values, there are also all theme options available
8554 (prefixed by theme_), as well as the values given by the user in
8555 html_context.
8556 In documents that are created from source files (as opposed to automat‐
8558 ically-generated files like the module index, or documents that already
8559 are in HTML form), these variables are also available:
8560 body A string containing the content of the page in HTML form as pro‐
8562 duced by the HTML builder, before the theme is applied.
8563 display_toc
8565 A boolean that is True if the toc contains more than one entry.
8566 meta Document metadata (a dictionary), see metadata.
8568 metatags
8570 A string containing the page’s HTML meta tags.
8571 next The next document for the navigation. This variable is either
8573 false or has two attributes link and title. The title contains
8574 HTML markup. For example, to generate a link to the next page,
8575 you can use this snippet:
8576 {% if next %}
8578 <a href="{{ next.link|e }}">{{ next.title }}</a>
8579 {% endif %}
8580 page_source_suffix
8582 The suffix of the file that was rendered. Since we support a
8583 list of source_suffix, this will allow you to properly link to
8584 the original source file.
8585 parents
8587 A list of parent documents for navigation, structured like the
8588 next item.
8589 prev Like next, but for the previous page.
8591 sourcename
8593 The name of the copied source file for the current document.
8594 This is only nonempty if the html_copy_source value is True.
8595 This has empty value on creating automatically-generated files.
8596 title The page title.
8598 toc The local table of contents for the current page, rendered as
8600 HTML bullet lists.
8601 toctree
8603 A callable yielding the global TOC tree containing the current
8604 page, rendered as HTML bullet lists. Optional keyword argu‐
8605 ments:
8606 · collapse (True by default): if true, all TOC entries that are
8608 not ancestors of the current page are collapsed
8609 · maxdepth (defaults to the max depth selected in the toctree
8611 directive): the maximum depth of the tree; set it to -1 to
8612 allow unlimited depth
8613 · titles_only (False by default): if true, put only toplevel
8615 document titles in the tree
8616 · includehidden (False by default): if true, the TOC tree will
8618 also contain hidden entries.
8619
8621 For details of the LaTeX/PDF builder command line invocation, refer to
8622 LaTeXBuilder.
8623 Basic customization
8625 The latex target does not benefit from prepared themes.
8626 Basic customization is obtained via usage of the latex-options. For
8628 example:
8629 # inside conf.py
8631 latex_engine = 'xelatex'
8632 latex_elements = {
8633 'fontpkg': r'''
8634 \setmainfont{DejaVu Serif}
8635 \setsansfont{DejaVu Sans}
8636 \setmonofont{DejaVu Sans Mono}
8637 ''',
8638 'preamble': r'''
8639 \usepackage[titles]{tocloft}
8640 \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
8641 \setlength{\cftchapnumwidth}{0.75cm}
8642 \setlength{\cftsecindent}{\cftchapnumwidth}
8643 \setlength{\cftsecnumwidth}{1.25cm}
8644 ''',
8645 'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
8646 'printindex': r'\footnotesize\raggedright\printindex',
8647 }
8648 latex_show_urls = 'footnote'
8649 If the size of the 'preamble' contents becomes inconvenient, one may
8651 move all needed macros into some file mystyle.tex.txt of the project
8652 source repertory, and get LaTeX to import it at run time:
8653 'preamble': r'\input{mystyle.tex.txt}',
8655 # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
8656 'preamble': r'\usepackage{mystyle}',
8657 It is then needed to set appropriately latex_additional_files, for
8659 example:
8660 latex_additional_files = ["mystyle.sty"]
8662 The LaTeX style file options
8664 Additional customization is possible via LaTeX options of the Sphinx
8665 style file.
8666 The sphinxsetup interface
8668 The 'sphinxsetup' key of latex_elements provides a convenient inter‐
8669 face:
8670 latex_elements = {
8672 'sphinxsetup': 'key1=value1, key2=value2, ...',
8673 }
8674 · some values may be LaTeX macros, then the backslashes must be
8676 Python-escaped, or the whole must be a Python raw string,
8677 · LaTeX boolean keys require lowercase true or false values,
8679 · spaces around the commas and equal signs are ignored, spaces inside
8681 LaTeX macros may be significant.
8682 If non-empty, it will be passed as argument to the \sphinxsetup macro
8684 inside the document preamble, like this:
8685 \usepackage{sphinx}
8687 \sphinxsetup{key1=value1, key2=value2,...}
8688 New in version 1.5.
8690 HINT:
8693 It is possible to insert further uses of the \sphinxsetup LaTeX
8694 macro directly into the body of the document, via the help of the
8695 raw directive. Here is how this present chapter in PDF is styled:
8696 .. raw:: latex
8698 \begingroup
8700 \sphinxsetup{%
8701 verbatimwithframe=false,
8702 VerbatimColor={named}{OldLace},
8703 TitleColor={named}{DarkGoldenrod},
8704 hintBorderColor={named}{LightCoral},
8705 attentionborder=3pt,
8706 attentionBorderColor={named}{Crimson},
8707 attentionBgColor={named}{FloralWhite},
8708 noteborder=2pt,
8709 noteBorderColor={named}{Olive},
8710 cautionborder=3pt,
8711 cautionBorderColor={named}{Cyan},
8712 cautionBgColor={named}{LightCyan}}
8713 at the start of the chapter and:
8715 .. raw:: latex
8717 \endgroup
8719 at its end.
8721 The colors used in the above are provided by the svgnames option of
8723 the “xcolor” package:
8724 latex_elements = {
8726 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
8727 }
8728 The available styling options
8730 hmargin, vmargin
8731 The dimensions of the horizontal (resp. vertical) margins,
8732 passed as hmargin (resp. vmargin) option to the geometry pack‐
8733 age. The default is 1in, which is equivalent to {1in,1in}. Exam‐
8734 ple:
8735 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
8737 Japanese documents currently accept only the one-dimension for‐
8739 mat for these parameters. The geometry package is then passed
8740 suitable options to get the text width set to an exact multiple
8741 of the zenkaku width, and the text height set to an integer mul‐
8742 tiple of the baselineskip, with the closest fit for the margins.
8743 HINT:
8745 For Japanese 'manual' docclass with pointsize 11pt or 12pt,
8746 use the nomag extra document class option (cf. 'extraclas‐
8747 soptions' key of latex_elements) or so-called TeX “true”
8748 units:
8749 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
8751 New in version 1.5.3.
8753 marginpar
8756 The \marginparwidth LaTeX dimension, defaults to 0.5in. For Ja‐
8757 panese documents, the value is modified to be the closest inte‐
8758 ger multiple of the zenkaku width.
8759 New in version 1.5.3.
8761 verbatimwithframe
8764 default true. Boolean to specify if code-blocks and literal
8765 includes are framed. Setting it to false does not deactivate use
8766 of package “framed”, because it is still in use for the optional
8767 background colour.
8768 verbatimwrapslines
8770 default true. Tells whether long lines in code-block’s contents
8771 should wrap.
8772 literalblockcappos
8774 default t for “top”. Decides the caption position. Alternative
8775 is b (“bottom”).
8776 New in version 1.7.
8778 verbatimhintsturnover
8781 default true. If true, code-blocks display “continued on next
8782 page”, “continued from previous page” hints in case of page‐
8783 breaks.
8784 New in version 1.6.3.
8786 Changed in version 1.7: the default changed from false to true.
8789 verbatimcontinuedalign, verbatimcontinuesalign
8792 default c. Horizontal position relative to the framed contents:
8793 either l (left aligned), r (right aligned) or c (centered).
8794 New in version 1.7.
8796 parsedliteralwraps
8799 default true. Tells whether long lines in parsed-literal’s con‐
8800 tents should wrap.
8801 New in version 1.5.2: set this option value to false to recover
8803 former behaviour.
8804 inlineliteralwraps
8807 default true. Allows linebreaks inside inline literals: but
8808 extra potential break-points (additionally to those allowed by
8809 LaTeX at spaces or for hyphenation) are currently inserted only
8810 after the characters . , ; ? ! /. Due to TeX internals, white
8811 space in the line will be stretched (or shrunk) in order to
8812 accomodate the linebreak.
8813 New in version 1.5: set this option value to false to recover
8815 former behaviour.
8816 verbatimvisiblespace
8819 default \textcolor{red}{\textvisiblespace}. When a long code
8820 line is split, the last space character from the source code
8821 line right before the linebreak location is typeset using this.
8822 verbatimcontinued
8824 A LaTeX macro inserted at start of continuation code lines. Its
8825 (complicated…) default typesets a small red hook pointing to the
8826 right:
8827 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
8829 Changed in version 1.5: The breaking of long code lines was
8831 added at 1.4.2. The default definition of the continuation sym‐
8832 bol was changed at 1.5 to accomodate various font sizes (e.g.
8833 code-blocks can be in footnotes).
8834 TitleColor
8837 default {rgb}{0.126,0.263,0.361}. The colour for titles (as con‐
8838 figured via use of package “titlesec”.)
8839 WARNING:
8841 Colours set via 'sphinxsetup' must obey the syntax of the argument
8842 of the color/xcolor packages \definecolor command.
8843 InnerLinkColor
8845 default {rgb}{0.208,0.374,0.486}. A colour passed to hyperref as
8846 value of linkcolor and citecolor.
8847 OuterLinkColor
8849 default {rgb}{0.216,0.439,0.388}. A colour passed to hyperref as
8850 value of filecolor, menucolor, and urlcolor.
8851 VerbatimColor
8853 default {rgb}{1,1,1}. The background colour for code-blocks. The
8854 default is white.
8855 VerbatimBorderColor
8857 default {rgb}{0,0,0}. The frame color, defaults to black.
8858 VerbatimHighlightColor
8860 default {rgb}{0.878,1,1}. The color for highlighted lines.
8861 New in version 1.6.6.
8863 NOTE:
8866 Starting with this colour key, and for all others coming next, the
8867 actual names declared to “color” or “xcolor” are prefixed with
8868 “sphinx”.
8869 verbatimsep
8871 default \fboxsep. The separation between code lines and the
8872 frame.
8873 verbatimborder
8875 default \fboxrule. The width of the frame around code-blocks.
8876 shadowsep
8878 default 5pt. The separation between contents and frame for
8879 contents and topic boxes.
8880 shadowsize
8882 default 4pt. The width of the lateral “shadow” to the right.
8883 shadowrule
8885 default \fboxrule. The width of the frame around topic boxes.
8886 noteBorderColor, hintBorderColor,
8888 importantBorderColor, tipBorderColor default {rgb}{0,0,0}
8889 (black). The colour for the two horizontal rules used by Sphinx
8890 in LaTeX for styling a note type admonition.
8891 noteborder, hintborder, importantborder, tipborder
8893 default 0.5pt. The width of the two horizontal rules.
8894 warningBorderColor, cautionBorderColor,
8896 attentionBorderColor, dangerBorderColor, errorBorderColor
8897 default {rgb}{0,0,0} (black). The colour for the admonition
8898 frame.
8899 warningBgColor, cautionBgColor,
8901 attentionBgColor, dangerBgColor, errorBgColor default
8902 {rgb}{1,1,1} (white). The background colours for the respective
8903 admonitions.
8904 warningBorder, cautionBorder,
8906 attentionBorder, dangerBorder, errorBorder default 1pt. The
8907 width of the frame.
8908 AtStartFootnote
8910 default \mbox{ }. LaTeX macros inserted at the start of the
8911 footnote text at bottom of page, after the footnote number.
8912 BeforeFootnote
8914 default \leavevmode\unskip. LaTeX macros inserted before the
8915 footnote mark. The default removes possible space before it
8916 (else, TeX could insert a linebreak there).
8917 New in version 1.5.
8919 HeaderFamily
8922 default \sffamily\bfseries. Sets the font used by headings.
8923 LaTeX macros and environments
8925 Here are some macros from the package file sphinx.sty and class files
8926 sphinxhowto.cls, sphinxmanual.cls, which have public names thus allow‐
8927 ing redefinitions. Check the respective files for the defaults.
8928 Macros
8930 · text styling commands \sphinx<foo> with <foo> being one of strong,
8931 bfcode, email, tablecontinued, titleref, menuselection, accelerator,
8932 crossref, termref, optional.
8933 New in version 1.4.5: Use of \sphinx prefixed macro names to limit
8935 possibilities of conflict with LaTeX packages.
8936 · more text styling: \sphinxstyle<bar> with <bar> one of indexentry,
8939 indexextra, indexpageref, topictitle, sidebartitle, othertitle, side‐
8940 barsubtitle, theadfamily, emphasis, literalemphasis, strong, literal‐
8941 strong, abbreviation, literalintitle, codecontinued, codecontinues
8942 New in version 1.5: these macros were formerly hard-coded as non cus‐
8944 tomizable \texttt, \emph, etc…
8945 New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
8948 ily and allows multiple paragraphs in header cells of tables.
8949 New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
8952 continues.
8953 · by default the Sphinx style file sphinx.sty executes the command
8956 \fvset{fontsize=\small} as part of its configuration of fancyvrb.sty.
8957 This may be overriden for example via \fvset{fontsize=auto} which
8958 will let code listings use the ambient font size. Refer to fan‐
8959 cyvrb.sty’s documentation for further keys.
8960 New in version 1.5.
8962 · the table of contents is typeset via \sphinxtableofcontents which is
8965 a wrapper (whose definition can be found in sphinxhowto.cls or in
8966 sphinxmanual.cls) of standard \tableofcontents.
8967 Changed in version 1.5: formerly, the meaning of \tableofcontents was
8969 modified by Sphinx.
8970 · the \maketitle command is redefined by the class files sphinxman‐
8973 ual.cls and sphinxhowto.cls.
8974 Environments
8976 · a figure may have an optional legend with arbitrary body elements:
8977 they are rendered in a sphinxlegend environment. The default defini‐
8978 tion issues \small, and ends with \par.
8979 New in version 1.5.6: formerly, the \small was hardcoded in LaTeX
8981 writer and the ending \par was lacking.
8982 · for each admonition type <foo>, the used environment is named
8985 sphinx<foo>. They may be \renewenvironment ‘d individually, and must
8986 then be defined with one argument (it is the heading of the notice,
8987 for example Warning: for warning directive, if English is the docu‐
8988 ment language). Their default definitions use either the sphinxheavy‐
8989 box (for the first listed directives) or the sphinxlightbox environ‐
8990 ments, configured to use the parameters (colours, border thickness)
8991 specific to each type, which can be set via 'sphinxsetup' string.
8992 Changed in version 1.5: use of public environment names, separate
8994 customizability of the parameters, such as noteBorderColor, notebor‐
8995 der, warningBgColor, warningBorderColor, warningborder, …
8996 · the contents directive (with :local: option) and the topic directive
8999 are implemented by environment sphinxShadowBox.
9000 New in version 1.4.2: former code refactored into an environment
9002 allowing page breaks.
9003 Changed in version 1.5: options shadowsep, shadowsize, shadowrule.
9006 · the literal blocks (via :: or code-block), are implemented using
9009 sphinxVerbatim environment which is a wrapper of Verbatim environment
9010 from package fancyvrb.sty. It adds the handling of the top caption
9011 and the wrapping of long lines, and a frame which allows pagebreaks.
9012 Inside tables the used environment is sphinxVerbatimintable (it does
9013 not draw a frame, but allows a caption).
9014 Changed in version 1.5: Verbatim keeps exact same meaning as in fan‐
9016 cyvrb.sty (also under the name OriginalVerbatim); sphinxVerbatim‐
9017 intable is used inside tables.
9018 New in version 1.5: options verbatimwithframe, verbatimwrapslines,
9021 verbatimsep, verbatimborder.
9022 New in version 1.6.6: support for :emphasize-lines: option
9025 New in version 1.6.6: easier customizability of the formatting via
9028 exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
9029 · the bibliography uses sphinxthebibliography and the Python Module
9032 index as well as the general index both use sphinxtheindex; these
9033 environments are wrappers of the thebibliography and respectively
9034 theindex environments as provided by the document class (or pack‐
9035 ages).
9036 Changed in version 1.5: formerly, the original environments were mod‐
9038 ified by Sphinx.
9039 Miscellany
9042 · the section, subsection, … headings are set using titlesec’s
9043 \titleformat command.
9044 · for the 'manual' docclass, the chapter headings can be customized
9046 using fncychap’s commands \ChNameVar, \ChNumVar, \ChTitleVar. File
9047 sphinx.sty has custom re-definitions in case of fncychap option
9048 Bjarne.
9049 Changed in version 1.5: formerly, use of fncychap with other styles
9051 than Bjarne was dysfunctional.
9052 HINT:
9055 As an experimental feature, Sphinx can use user-defined template
9056 file for LaTeX source if you have a file named _tem‐
9057 plates/latex.tex_t in your project.
9058 New in version 1.5: currently all template variables are unstable
9060 and undocumented.
9061 Additional files longtable.tex_t, tabulary.tex_t and tabular.tex_t
9064 can be added to _templates/ to configure some aspects of table ren‐
9065 dering (such as the caption position).
9066 New in version 1.6: currently all template variables are unstable
9068 and undocumented.
9069
9072 Markdown is a lightweight markup language with a simplistic plain text
9073 formatting syntax. It exists in many syntactically different flavors.
9074 To support Markdown-based documentation, Sphinx can use recommonmark.
9075 recommonmark is a Docutils bridge to CommonMark-py, a Python package
9076 for parsing the CommonMark Markdown flavor.
9077 Configuration
9079 To configure your Sphinx project for Markdown support, proceed as fol‐
9080 lows:
9081 1. Install recommonmark:
9083 pip install recommonmark
9085 2. Add the Markdown parser to the source_parsers configuration variable
9087 in your Sphinx configuration file:
9088 source_parsers = {
9090 '.md': 'recommonmark.parser.CommonMarkParser',
9091 }
9092 You can replace .md with a filename extension of your choice.
9094 3. Add the Markdown filename extension to the source_suffix configura‐
9096 tion variable:
9097 source_suffix = ['.rst', '.md']
9099 4. You can further configure recommonmark to allow custom syntax that
9101 standard CommonMark doesn’t support. Read more in the recommonmark
9102 documentation.
9103
9105 Since many projects will need special features in their documentation,
9106 Sphinx allows adding “extensions” to the build process, each of which
9107 can modify almost any aspect of document processing.
9108 This chapter describes the extensions bundled with Sphinx. For the API
9110 documentation on writing your own extension, see dev-extensions.
9111 Builtin Sphinx extensions
9113 These extensions are built in and can be activated by respective
9114 entries in the extensions configuration value:
9115 sphinx.ext.autodoc – Include documentation from docstrings
9117 This extension can import the modules you are documenting, and pull in
9118 documentation from docstrings in a semi-automatic way.
9119 NOTE:
9121 For Sphinx (actually, the Python interpreter that executes Sphinx)
9122 to find your module, it must be importable. That means that the
9123 module or the package must be in one of the directories on sys.path
9124 – adapt your sys.path in the configuration file accordingly.
9125 WARNING:
9127 autodoc imports the modules to be documented. If any modules have
9128 side effects on import, these will be executed by autodoc when
9129 sphinx-build is run.
9130 If you document scripts (as opposed to library modules), make sure
9132 their main routine is protected by a if __name__ == '__main__' con‐
9133 dition.
9134 For this to work, the docstrings must of course be written in correct
9136 reStructuredText. You can then use all of the usual Sphinx markup in
9137 the docstrings, and it will end up correctly in the documentation.
9138 Together with hand-written documentation, this technique eases the pain
9139 of having to maintain two locations for documentation, while at the
9140 same time avoiding auto-generated-looking pure API documentation.
9141 If you prefer NumPy or Google style docstrings over reStructuredText,
9143 you can also enable the napoleon extension. napoleon is a preprocessor
9144 that converts your docstrings to correct reStructuredText before
9145 autodoc processes them.
9146 autodoc provides several directives that are versions of the usual
9148 py:module, py:class and so forth. On parsing time, they import the
9149 corresponding module and extract the docstring of the given objects,
9150 inserting them into the page source under a suitable py:module,
9151 py:class etc. directive.
9152 NOTE:
9154 Just as py:class respects the current py:module, autoclass will also
9155 do so. Likewise, automethod will respect the current py:class.
9156 .. automodule::
9158 .. autoclass::
9160 .. autoexception::
9162 Document a module, class or exception. All three directives
9163 will by default only insert the docstring of the object itself:
9164 .. autoclass:: Noodle
9166 will produce source like this:
9168 .. class:: Noodle
9170 Noodle's docstring.
9172 The “auto” directives can also contain content of their own, it
9174 will be inserted into the resulting non-auto directive source
9175 after the docstring (but before any automatic member documenta‐
9176 tion).
9177 Therefore, you can also mix automatic and non-automatic member
9179 documentation, like so:
9180 .. autoclass:: Noodle
9182 :members: eat, slurp
9183 .. method:: boil(time=10)
9185 Boil the noodle *time* minutes.
9187 Options and advanced usage
9189 · If you want to automatically document members, there’s a mem‐
9191 bers option:
9192 .. automodule:: noodle
9194 :members:
9195 will document all module members (recursively), and
9197 .. autoclass:: Noodle
9199 :members:
9200 will document all non-private member functions and properties
9202 (that is, those whose name doesn’t start with _).
9203 For modules, __all__ will be respected when looking for mem‐
9205 bers unless you give the ignore-module-all flag option. With‐
9206 out ignore-module-all, the order of the members will also be
9207 the order in __all__.
9208 You can also give an explicit list of members; only these will
9210 then be documented:
9211 .. autoclass:: Noodle
9213 :members: eat, slurp
9214 · If you want to make the members option (or other flag options
9216 described below) the default, see autodoc_default_flags.
9217 · Members without docstrings will be left out, unless you give
9219 the undoc-members flag option:
9220 .. automodule:: noodle
9222 :members:
9223 :undoc-members:
9224 · “Private” members (that is, those named like _private or
9226 __private) will be included if the private-members flag option
9227 is given.
9228 New in version 1.1.
9230 · Python “special” members (that is, those named like __spe‐
9233 cial__) will be included if the special-members flag option is
9234 given:
9235 .. autoclass:: my.Class
9237 :members:
9238 :private-members:
9239 :special-members:
9240 would document both “private” and “special” members of the
9242 class.
9243 New in version 1.1.
9245 Changed in version 1.2: The option can now take arguments,
9248 i.e. the special members to document.
9249 · For classes and exceptions, members inherited from base
9252 classes will be left out when documenting all members, unless
9253 you give the inherited-members flag option, in addition to
9254 members:
9255 .. autoclass:: Noodle
9257 :members:
9258 :inherited-members:
9259 This can be combined with undoc-members to document all avail‐
9261 able members of the class or module.
9262 Note: this will lead to markup errors if the inherited members
9264 come from a module whose docstrings are not reST formatted.
9265 New in version 0.3.
9267 · It’s possible to override the signature for explicitly docu‐
9270 mented callable objects (functions, methods, classes) with the
9271 regular syntax that will override the signature gained from
9272 introspection:
9273 .. autoclass:: Noodle(type)
9275 .. automethod:: eat(persona)
9277 This is useful if the signature from the method is hidden by a
9279 decorator.
9280 New in version 0.4.
9282 · The automodule, autoclass and autoexception directives also
9285 support a flag option called show-inheritance. When given, a
9286 list of base classes will be inserted just below the class
9287 signature (when used with automodule, this will be inserted
9288 for every class that is documented in the module).
9289 New in version 0.4.
9291 · All autodoc directives support the noindex flag option that
9294 has the same effect as for standard py:function etc. direc‐
9295 tives: no index entries are generated for the documented
9296 object (and all autodocumented members).
9297 New in version 0.4.
9299 · automodule also recognizes the synopsis, platform and depre‐
9302 cated options that the standard py:module directive supports.
9303 New in version 0.5.
9305 · automodule and autoclass also has an member-order option that
9308 can be used to override the global value of
9309 autodoc_member_order for one directive.
9310 New in version 0.6.
9312 · The directives supporting member documentation also have a
9315 exclude-members option that can be used to exclude single mem‐
9316 ber names from documentation, if all members are to be docu‐
9317 mented.
9318 New in version 0.6.
9320 · In an automodule directive with the members option set, only
9323 module members whose __module__ attribute is equal to the mod‐
9324 ule name as given to automodule will be documented. This is
9325 to prevent documentation of imported classes or functions.
9326 Set the imported-members option if you want to prevent this
9327 behavior and document all available members. Note that
9328 attributes from imported modules will not be documented,
9329 because attribute documentation is discovered by parsing the
9330 source file of the current module.
9331 New in version 1.2.
9333 · Add a list of modules in the autodoc_mock_imports to prevent
9336 import errors to halt the building process when some external
9337 dependencies are not importable at build time.
9338 New in version 1.3.
9340 .. autofunction::
9343 .. autodata::
9345 .. automethod::
9347 .. autoattribute::
9349 These work exactly like autoclass etc., but do not offer the
9350 options used for automatic member documentation.
9351 autodata and autoattribute support the annotation option. With‐
9353 out this option, the representation of the object will be shown
9354 in the documentation. When the option is given without argu‐
9355 ments, only the name of the object will be printed:
9356 .. autodata:: CD_DRIVE
9358 :annotation:
9359 You can tell sphinx what should be printed after the name:
9361 .. autodata:: CD_DRIVE
9363 :annotation: = your CD device name
9364 For module data members and class attributes, documentation can
9366 either be put into a comment with special formatting (using a #:
9367 to start the comment instead of just #), or in a docstring after
9368 the definition. Comments need to be either on a line of their
9369 own before the definition, or immediately after the assignment
9370 on the same line. The latter form is restricted to one line
9371 only.
9372 This means that in the following class definition, all
9374 attributes can be autodocumented:
9375 class Foo:
9377 """Docstring for class Foo."""
9378 #: Doc comment for class attribute Foo.bar.
9380 #: It can have multiple lines.
9381 bar = 1
9382 flox = 1.5 #: Doc comment for Foo.flox. One line only.
9384 baz = 2
9386 """Docstring for class attribute Foo.baz."""
9387 def __init__(self):
9389 #: Doc comment for instance attribute qux.
9390 self.qux = 3
9391 self.spam = 4
9393 """Docstring for instance attribute spam."""
9394 Changed in version 0.6: autodata and autoattribute can now
9396 extract docstrings.
9397 Changed in version 1.1: Comment docs are now allowed on the same
9400 line after an assignment.
9401 Changed in version 1.2: autodata and autoattribute have an anno‐
9404 tation option.
9405 NOTE:
9408 If you document decorated functions or methods, keep in mind
9409 that autodoc retrieves its docstrings by importing the module
9410 and inspecting the __doc__ attribute of the given function or
9411 method. That means that if a decorator replaces the deco‐
9412 rated function with another, it must copy the original
9413 __doc__ to the new function.
9414 From Python 2.5, functools.wraps() can be used to create
9416 well-behaved decorating functions.
9417 There are also new config values that you can set:
9419 autoclass_content
9421 This value selects what content will be inserted into the main
9422 body of an autoclass directive. The possible values are:
9423 "class"
9425 Only the class’ docstring is inserted. This is the
9426 default. You can still document __init__ as a separate
9427 method using automethod or the members option to
9428 autoclass.
9429 "both" Both the class’ and the __init__ method’s docstring are
9431 concatenated and inserted.
9432 "init" Only the __init__ method’s docstring is inserted.
9434 New in version 0.3.
9436 If the class has no __init__ method or if the __init__ method’s
9439 docstring is empty, but the class has a __new__ method’s doc‐
9440 string, it is used instead.
9441 New in version 1.4.
9443 autodoc_member_order
9446 This value selects if automatically documented members are
9447 sorted alphabetical (value 'alphabetical'), by member type
9448 (value 'groupwise') or by source order (value 'bysource'). The
9449 default is alphabetical.
9450 Note that for source order, the module must be a Python module
9452 with the source code available.
9453 New in version 0.6.
9455 Changed in version 1.0: Support for 'bysource'.
9458 autodoc_default_flags
9461 This value is a list of autodoc directive flags that should be
9462 automatically applied to all autodoc directives. The supported
9463 flags are 'members', 'undoc-members', 'private-members', 'spe‐
9464 cial-members', 'inherited-members', 'show-inheritance' and
9465 'ignore-module-all'.
9466 If you set one of these flags in this config value, you can use
9468 a negated form, 'no-flag', in an autodoc directive, to disable
9469 it once. For example, if autodoc_default_flags is set to ['mem‐
9470 bers', 'undoc-members'], and you write a directive like this:
9471 .. automodule:: foo
9473 :no-undoc-members:
9474 the directive will be interpreted as if only :members: was
9476 given.
9477 New in version 1.0.
9479 autodoc_docstring_signature
9482 Functions imported from C modules cannot be introspected, and
9483 therefore the signature for such functions cannot be automati‐
9484 cally determined. However, it is an often-used convention to
9485 put the signature into the first line of the function’s doc‐
9486 string.
9487 If this boolean value is set to True (which is the default),
9489 autodoc will look at the first line of the docstring for func‐
9490 tions and methods, and if it looks like a signature, use the
9491 line as the signature and remove it from the docstring content.
9492 New in version 1.1.
9494 autodoc_mock_imports
9497 This value contains a list of modules to be mocked up. This is
9498 useful when some external dependencies are not met at build time
9499 and break the building process. You may only specify the root
9500 package of the dependencies themselves and omit the sub-modules:
9501 autodoc_mock_imports = ["django"]
9503 Will mock all imports under the django package.
9505 New in version 1.3.
9507 Changed in version 1.6: This config value only requires to
9510 declare the top-level modules that should be mocked.
9511 autodoc_warningiserror
9514 This value controls the behavior of sphinx-build -W during
9515 importing modules. If False is given, autodoc forcely sup‐
9516 presses the error if the imported module emits warnings. By
9517 default, True.
9518 autodoc_inherit_docstrings
9520 This value controls the docstrings inheritance. If set to True
9521 the cocstring for classes or methods, if not explicitly set, is
9522 inherited form parents.
9523 The default is True.
9525 New in version 1.7.
9527 Docstring preprocessing
9530 autodoc provides the following additional events:
9531 autodoc-process-docstring(app, what, name, obj, options, lines)
9533 New in version 0.4.
9534 Emitted when autodoc has read and processed a docstring. lines
9537 is a list of strings – the lines of the processed docstring –
9538 that the event handler can modify in place to change what Sphinx
9539 puts into the output.
9540 Parameters
9542 · app – the Sphinx application object
9544 · what – the type of the object which the docstring
9546 belongs to (one of "module", "class", "exception",
9547 "function", "method", "attribute")
9548 · name – the fully qualified name of the object
9550 · obj – the object itself
9552 · options – the options given to the directive: an object
9554 with attributes inherited_members, undoc_members,
9555 show_inheritance and noindex that are true if the flag
9556 option of same name was given to the auto directive
9557 · lines – the lines of the docstring, see above
9559 autodoc-process-signature(app, what, name, obj, options, signature,
9561 return_annotation)
9562 New in version 0.5.
9563 Emitted when autodoc has formatted a signature for an object.
9566 The event handler can return a new tuple (signature,
9567 return_annotation) to change what Sphinx puts into the output.
9568 Parameters
9570 · app – the Sphinx application object
9572 · what – the type of the object which the docstring
9574 belongs to (one of "module", "class", "exception",
9575 "function", "method", "attribute")
9576 · name – the fully qualified name of the object
9578 · obj – the object itself
9580 · options – the options given to the directive: an object
9582 with attributes inherited_members, undoc_members,
9583 show_inheritance and noindex that are true if the flag
9584 option of same name was given to the auto directive
9585 · signature – function signature, as a string of the form
9587 "(parameter_1, parameter_2)", or None if introspection
9588 didn’t succeed and signature wasn’t specified in the
9589 directive.
9590 · return_annotation – function return annotation as a
9592 string of the form " -> annotation", or None if there
9593 is no return annotation
9594 The sphinx.ext.autodoc module provides factory functions for commonly
9596 needed docstring processing in event autodoc-process-docstring:
9597 sphinx.ext.autodoc.cut_lines(pre, post=0, what=None)
9599 Return a listener that removes the first pre and last post lines
9600 of every docstring. If what is a sequence of strings, only doc‐
9601 strings of a type in what will be processed.
9602 Use like this (e.g. in the setup() function of conf.py):
9604 from sphinx.ext.autodoc import cut_lines
9606 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
9607 This can (and should) be used in place of automodule_skip_lines.
9609 sphinx.ext.autodoc.between(marker, what=None, keepempty=False,
9611 exclude=False)
9612 Return a listener that either keeps, or if exclude is True
9613 excludes, lines between lines that match the marker regular
9614 expression. If no line matches, the resulting docstring would
9615 be empty, so no change will be made unless keepempty is true.
9616 If what is a sequence of strings, only docstrings of a type in
9618 what will be processed.
9619 Skipping members
9621 autodoc allows the user to define a custom method for determining
9622 whether a member should be included in the documentation by using the
9623 following event:
9624 autodoc-skip-member(app, what, name, obj, skip, options)
9626 New in version 0.5.
9627 Emitted when autodoc has to decide whether a member should be
9630 included in the documentation. The member is excluded if a han‐
9631 dler returns True. It is included if the handler returns False.
9632 If more than one enabled extension handles the autodoc-skip-mem‐
9634 ber event, autodoc will use the first non-None value returned by
9635 a handler. Handlers should return None to fall back to the
9636 skipping behavior of autodoc and other enabled extensions.
9637 Parameters
9639 · app – the Sphinx application object
9641 · what – the type of the object which the docstring
9643 belongs to (one of "module", "class", "exception",
9644 "function", "method", "attribute")
9645 · name – the fully qualified name of the object
9647 · obj – the object itself
9649 · skip – a boolean indicating if autodoc will skip this
9651 member if the user handler does not override the deci‐
9652 sion
9653 · options – the options given to the directive: an object
9655 with attributes inherited_members, undoc_members,
9656 show_inheritance and noindex that are true if the flag
9657 option of same name was given to the auto directive
9658 sphinx.ext.autosectionlabel – Allow reference sections using its title
9660 New in version 1.4.
9661 This extension allows you to refer sections its title. This affects to
9664 the reference role (ref).
9665 For example:
9667 A Plain Title
9669 -------------
9670 This is the text of the section.
9672 It refers to the section title, see :ref:`A Plain Title`.
9674 Internally, this extension generates the labels for each section. If
9676 same section names are used in whole of document, any one is used for a
9677 target by default. The autosectionlabel_prefix_document configuration
9678 variable can be used to make headings which appear multiple times but
9679 in different documents unique.
9680 Configuration
9682 autosectionlabel_prefix_document
9683 True to prefix each section label with the name of the document
9684 it is in, followed by a colon. For example, index:Introduction
9685 for a section called Introduction that appears in document
9686 index.rst. Useful for avoiding ambiguity when the same section
9687 heading appears in different documents.
9688 sphinx.ext.autosummary – Generate autodoc summaries
9690 New in version 0.6.
9691 This extension generates function/method/attribute summary lists, simi‐
9694 lar to those output e.g. by Epydoc and other API doc generation tools.
9695 This is especially useful when your docstrings are long and detailed,
9696 and putting each one of them on a separate page makes them easier to
9697 read.
9698 The sphinx.ext.autosummary extension does this in two parts:
9700 1. There is an autosummary directive for generating summary listings
9702 that contain links to the documented items, and short summary blurbs
9703 extracted from their docstrings.
9704 2. Optionally, the convenience script sphinx-autogen or the new
9706 autosummary_generate config value can be used to generate short
9707 “stub” files for the entries listed in the autosummary directives.
9708 These files by default contain only the corresponding
9709 sphinx.ext.autodoc directive, but can be customized with templates.
9710 .. autosummary::
9712 Insert a table that contains links to documented items, and a
9713 short summary blurb (the first sentence of the docstring) for
9714 each of them.
9715 The autosummary directive can also optionally serve as a toctree
9717 entry for the included items. Optionally, stub .rst files for
9718 these items can also be automatically generated.
9719 For example,
9721 .. currentmodule:: sphinx
9723 .. autosummary::
9725 environment.BuildEnvironment
9727 util.relative_uri
9728 produces a table like this:
9730 ┌──────────────────────────┬────────────────────────────┐
9732 │environment.BuildEnviron‐ │ The environment in which │
9733 │ment(app) │ the ReST files are trans‐ │
9734 │ │ lated. │
9735 ├──────────────────────────┼────────────────────────────┤
9736 │util.relative_uri(base, │ Return a relative URL from │
9737 │to) │ base to to. │
9738 └──────────────────────────┴────────────────────────────┘
9739 Autosummary preprocesses the docstrings and signatures with the
9741 same autodoc-process-docstring and autodoc-process-signature
9742 hooks as autodoc.
9743 Options
9745 · If you want the autosummary table to also serve as a toctree
9747 entry, use the toctree option, for example:
9748 .. autosummary::
9750 :toctree: DIRNAME
9751 sphinx.environment.BuildEnvironment
9753 sphinx.util.relative_uri
9754 The toctree option also signals to the sphinx-autogen script
9756 that stub pages should be generated for the entries listed in
9757 this directive. The option accepts a directory name as an
9758 argument; sphinx-autogen will by default place its output in
9759 this directory. If no argument is given, output is placed in
9760 the same directory as the file that contains the directive.
9761 · If you don’t want the autosummary to show function signatures
9763 in the listing, include the nosignatures option:
9764 .. autosummary::
9766 :nosignatures:
9767 sphinx.environment.BuildEnvironment
9769 sphinx.util.relative_uri
9770 · You can specify a custom template with the template option.
9772 For example,
9773 .. autosummary::
9775 :template: mytemplate.rst
9776 sphinx.environment.BuildEnvironment
9778 would use the template mytemplate.rst in your templates_path
9780 to generate the pages for all entries listed. See Customizing
9781 templates below.
9782 New in version 1.0.
9784 sphinx-autogen – generate autodoc stub pages
9787 The sphinx-autogen script can be used to conveniently generate stub
9788 documentation pages for items included in autosummary listings.
9789 For example, the command
9791 $ sphinx-autogen -o generated *.rst
9793 will read all autosummary tables in the *.rst files that have the :toc‐
9795 tree: option set, and output corresponding stub pages in directory gen‐
9796 erated for all documented items. The generated pages by default con‐
9797 tain text of the form:
9798 sphinx.util.relative_uri
9800 ========================
9801 .. autofunction:: sphinx.util.relative_uri
9803 If the -o option is not given, the script will place the output files
9805 in the directories specified in the :toctree: options.
9806 For more information, refer to the sphinx-autogen documentation
9808 Generating stub pages automatically
9810 If you do not want to create stub pages with sphinx-autogen, you can
9811 also use this new config value:
9812 autosummary_generate
9814 Boolean indicating whether to scan all found documents for auto‐
9815 summary directives, and to generate stub pages for each.
9816 Can also be a list of documents for which stub pages should be
9818 generated.
9819 The new files will be placed in the directories specified in the
9821 :toctree: options of the directives.
9822 Customizing templates
9824 New in version 1.0.
9825 You can customize the stub page templates, in a similar way as the HTML
9828 Jinja templates, see templating. (TemplateBridge is not supported.)
9829 NOTE:
9831 If you find yourself spending much time tailoring the stub tem‐
9832 plates, this may indicate that it’s a better idea to write custom
9833 narrative documentation instead.
9834 Autosummary uses the following Jinja template files:
9836 · autosummary/base.rst – fallback template
9838 · autosummary/module.rst – template for modules
9840 · autosummary/class.rst – template for classes
9842 · autosummary/function.rst – template for functions
9844 · autosummary/attribute.rst – template for class attributes
9846 · autosummary/method.rst – template for class methods
9848 The following variables available in the templates:
9850 name Name of the documented object, excluding the module and class
9852 parts.
9853 objname
9855 Name of the documented object, excluding the module parts.
9856 fullname
9858 Full name of the documented object, including module and class
9859 parts.
9860 module Name of the module the documented object belongs to.
9862 class Name of the class the documented object belongs to. Only avail‐
9864 able for methods and attributes.
9865 underline
9867 A string containing len(full_name) * '='. Use the underline fil‐
9868 ter instead.
9869 members
9871 List containing names of all members of the module or class.
9872 Only available for modules and classes.
9873 functions
9875 List containing names of “public” functions in the module.
9876 Here, “public” here means that the name does not start with an
9877 underscore. Only available for modules.
9878 classes
9880 List containing names of “public” classes in the module. Only
9881 available for modules.
9882 exceptions
9884 List containing names of “public” exceptions in the module.
9885 Only available for modules.
9886 methods
9888 List containing names of “public” methods in the class. Only
9889 available for classes.
9890 attributes
9892 List containing names of “public” attributes in the class. Only
9893 available for classes.
9894 Additionally, the following filters are available
9896 escape(s)
9898 Escape any special characters in the text to be used in format‐
9899 ting RST contexts. For instance, this prevents asterisks making
9900 things bold. This replaces the builtin Jinja escape filter that
9901 does html-escaping.
9902 underline(s, line='=')
9904 Add a title underline to a piece of text.
9905 For instance, {{ fullname | escape | underline }} should be used to
9907 produce the title of a page.
9908 NOTE:
9910 You can use the autosummary directive in the stub pages. Stub pages
9911 are generated also based on these directives.
9912 sphinx.ext.coverage – Collect doc coverage stats
9914 This extension features one additional builder, the CoverageBuilder.
9915 class sphinx.ext.coverage.CoverageBuilder
9917 To use this builder, activate the coverage extension in your
9918 configuration file and give -b coverage on the command line.
9919 Todo
9921 Write this section.
9922 Several new configuration values can be used to specify what the
9924 builder should check:
9925 coverage_ignore_modules
9927 coverage_ignore_functions
9929 coverage_ignore_classes
9931 coverage_c_path
9933 coverage_c_regexes
9935 coverage_ignore_c_items
9937 coverage_write_headline
9939 Set to False to not write headlines.
9940 New in version 1.1.
9942 coverage_skip_undoc_in_source
9945 Skip objects that are not documented in the source with a doc‐
9946 string. False by default.
9947 New in version 1.1.
9949 sphinx.ext.doctest – Test snippets in the documentation
9952 This extension allows you to test snippets in the documentation in a
9953 natural way. It works by collecting specially-marked up code blocks
9954 and running them as doctest tests.
9955 Within one document, test code is partitioned in groups, where each
9957 group consists of:
9958 · zero or more setup code blocks (e.g. importing the module to test)
9960 · one or more test blocks
9962 When building the docs with the doctest builder, groups are collected
9964 for each document and run one after the other, first executing setup
9965 code blocks, then the test blocks in the order they appear in the file.
9966 There are two kinds of test blocks:
9968 · doctest-style blocks mimic interactive sessions by interleaving
9970 Python code (including the interpreter prompt) and output.
9971 · code-output-style blocks consist of an ordinary piece of Python code,
9973 and optionally, a piece of output for that code.
9974 Directives
9976 The group argument below is interpreted as follows: if it is empty, the
9977 block is assigned to the group named default. If it is *, the block is
9978 assigned to all groups (including the default group). Otherwise, it
9979 must be a comma-separated list of group names.
9980 .. testsetup:: [group]
9982 A setup code block. This code is not shown in the output for
9983 other builders, but executed before the doctests of the group(s)
9984 it belongs to.
9985 .. testcleanup:: [group]
9987 A cleanup code block. This code is not shown in the output for
9988 other builders, but executed after the doctests of the group(s)
9989 it belongs to.
9990 New in version 1.1.
9992 .. doctest:: [group]
9995 A doctest-style code block. You can use standard doctest flags
9996 for controlling how actual output is compared with what you give
9997 as output. The default set of flags is specified by the
9998 doctest_default_flags configuration variable.
9999 This directive supports three options:
10001 · hide, a flag option, hides the doctest block in other
10003 builders. By default it is shown as a highlighted doctest
10004 block.
10005 · options, a string option, can be used to give a comma-sepa‐
10007 rated list of doctest flags that apply to each example in the
10008 tests. (You still can give explicit flags per example, with
10009 doctest comments, but they will show up in other builders
10010 too.)
10011 · pyversion, a string option, can be used to specify the
10013 required Python version for the example to be tested. For
10014 instance, in the following case the example will be tested
10015 only for Python versions greather than 3.3:
10016 .. doctest::
10018 :pyversion: > 3.3
10019 The following operands are supported:
10021 · ~=: Compatible release clause
10023 · ==: Version matching clause
10025 · !=: Version exclusion clause
10027 · <=, >=: Inclusive ordered comparison clause
10029 · <, >: Exclusive ordered comparison clause
10031 · ===: Arbitrary equality clause.
10033 pyversion option is followed PEP-440: Version Specifiers.
10035 New in version 1.6.
10037 Changed in version 1.7: Supported PEP-440 operands and nota‐
10040 tions
10041 Note that like with standard doctests, you have to use
10044 <BLANKLINE> to signal a blank line in the expected output. The
10045 <BLANKLINE> is removed when building presentation output (HTML,
10046 LaTeX etc.).
10047 Also, you can give inline doctest options, like in doctest:
10049 >>> datetime.date.now() # doctest: +SKIP
10051 datetime.date(2008, 1, 1)
10052 They will be respected when the test is run, but stripped from
10054 presentation output.
10055 .. testcode:: [group]
10057 A code block for a code-output-style test.
10058 This directive supports one option:
10060 · hide, a flag option, hides the code block in other builders.
10062 By default it is shown as a highlighted code block.
10063 NOTE:
10065 Code in a testcode block is always executed all at once, no
10066 matter how many statements it contains. Therefore, output
10067 will not be generated for bare expressions – use print.
10068 Example:
10069 .. testcode::
10071 1+1 # this will give no output!
10073 print 2+2 # this will give output
10074 .. testoutput::
10076 4
10078 Also, please be aware that since the doctest module does not
10080 support mixing regular output and an exception message in the
10081 same snippet, this applies to testcode/testoutput as well.
10082 .. testoutput:: [group]
10084 The corresponding output, or the exception message, for the last
10085 testcode block.
10086 This directive supports two options:
10088 · hide, a flag option, hides the output block in other builders.
10090 By default it is shown as a literal block without highlight‐
10091 ing.
10092 · options, a string option, can be used to give doctest flags
10094 (comma-separated) just like in normal doctest blocks.
10095 Example:
10097 .. testcode::
10099 print 'Output text.'
10101 .. testoutput::
10103 :hide:
10104 :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
10105 Output text.
10107 The following is an example for the usage of the directives. The test
10109 via doctest and the test via testcode and testoutput are equivalent.
10110 The parrot module
10112 =================
10113 .. testsetup:: *
10115 import parrot
10117 The parrot module is a module about parrots.
10119 Doctest example:
10121 .. doctest::
10123 >>> parrot.voom(3000)
10125 This parrot wouldn't voom if you put 3000 volts through it!
10126 Test-Output example:
10128 .. testcode::
10130 parrot.voom(3000)
10132 This would output:
10134 .. testoutput::
10136 This parrot wouldn't voom if you put 3000 volts through it!
10138 Configuration
10140 The doctest extension uses the following configuration values:
10141 doctest_default_flags
10143 By default, these options are enabled:
10144 · ELLIPSIS, allowing you to put ellipses in the expected output
10146 that match anything in the actual output;
10147 · IGNORE_EXCEPTION_DETAIL, causing everything following the
10149 leftmost colon and any module information in the exception
10150 name to be ignored;
10151 · DONT_ACCEPT_TRUE_FOR_1, rejecting “True” in the output where
10153 “1” is given – the default behavior of accepting this substi‐
10154 tution is a relic of pre-Python 2.2 times.
10155 New in version 1.5.
10157 doctest_path
10160 A list of directories that will be added to sys.path when the
10161 doctest builder is used. (Make sure it contains absolute
10162 paths.)
10163 doctest_global_setup
10165 Python code that is treated like it were put in a testsetup
10166 directive for every file that is tested, and for every group.
10167 You can use this to e.g. import modules you will always need in
10168 your doctests.
10169 New in version 0.6.
10171 doctest_global_cleanup
10174 Python code that is treated like it were put in a testcleanup
10175 directive for every file that is tested, and for every group.
10176 You can use this to e.g. remove any temporary files that the
10177 tests leave behind.
10178 New in version 1.1.
10180 doctest_test_doctest_blocks
10183 If this is a nonempty string (the default is 'default'), stan‐
10184 dard reST doctest blocks will be tested too. They will be
10185 assigned to the group name given.
10186 reST doctest blocks are simply doctests put into a paragraph of
10188 their own, like so:
10189 Some documentation text.
10191 >>> print 1
10193 1
10194 Some more documentation text.
10196 (Note that no special :: is used to introduce a doctest block;
10198 docutils recognizes them from the leading >>>. Also, no addi‐
10199 tional indentation is used, though it doesn’t hurt.)
10200 If this value is left at its default value, the above snippet is
10202 interpreted by the doctest builder exactly like the following:
10203 Some documentation text.
10205 .. doctest::
10207 >>> print 1
10209 1
10210 Some more documentation text.
10212 This feature makes it easy for you to test doctests in doc‐
10214 strings included with the autodoc extension without marking them
10215 up with a special directive.
10216 Note though that you can’t have blank lines in reST doctest
10218 blocks. They will be interpreted as one block ending and
10219 another one starting. Also, removal of <BLANKLINE> and #
10220 doctest: options only works in doctest blocks, though you may
10221 set trim_doctest_flags to achieve that in all code blocks with
10222 Python console content.
10223 sphinx.ext.extlinks – Markup to shorten external links
10225 Module author: Georg Brandl
10226 New in version 1.0.
10228 This extension is meant to help with the common pattern of having many
10231 external links that point to URLs on one and the same site, e.g. links
10232 to bug trackers, version control web interfaces, or simply subpages in
10233 other websites. It does so by providing aliases to base URLs, so that
10234 you only need to give the subpage name when creating a link.
10235 Let’s assume that you want to include many links to issues at the
10237 Sphinx tracker, at https://github.com/sphinx-doc/sphinx/issues/num.
10238 Typing this URL again and again is tedious, so you can use extlinks to
10239 avoid repeating yourself.
10240 The extension adds one new config value:
10242 extlinks
10244 This config value must be a dictionary of external sites, map‐
10245 ping unique short alias names to a base URL and a prefix. For
10246 example, to create an alias for the above mentioned issues, you
10247 would add
10248 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
10250 'issue ')}
10251 Now, you can use the alias name as a new role, e.g.
10253 :issue:`123`. This then inserts a link to
10254 https://github.com/sphinx-doc/sphinx/issues/123. As you can
10255 see, the target given in the role is substituted in the base URL
10256 in the place of %s.
10257 The link caption depends on the second item in the tuple, the
10259 prefix:
10260 · If the prefix is None, the link caption is the full URL.
10262 · If the prefix is the empty string, the link caption is the
10264 partial URL given in the role content (123 in this case.)
10265 · If the prefix is a non-empty string, the link caption is the
10267 partial URL, prepended by the prefix – in the above example,
10268 the link caption would be issue 123.
10269 You can also use the usual “explicit title” syntax supported by
10271 other roles that generate links, i.e. :issue:`this issue <123>`.
10272 In this case, the prefix is not relevant.
10273 NOTE:
10275 Since links are generated from the role in the reading stage, they
10276 appear as ordinary links to e.g. the linkcheck builder.
10277 sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
10279 New in version 1.4.
10280 This extension creates .nojekyll file on generated HTML directory to
10283 publish the document on GitHub Pages.
10284 sphinx.ext.graphviz – Add Graphviz graphs
10286 New in version 0.6.
10287 This extension allows you to embed Graphviz graphs in your documents.
10290 It adds these directives:
10292 .. graphviz::
10294 Directive to embed graphviz code. The input code for dot is
10295 given as the content. For example:
10296 .. graphviz::
10298 digraph foo {
10300 "bar" -> "baz";
10301 }
10302 In HTML output, the code will be rendered to a PNG or SVG image
10304 (see graphviz_output_format). In LaTeX output, the code will be
10305 rendered to an embeddable PDF file.
10306 You can also embed external dot files, by giving the file name
10308 as an argument to graphviz and no additional content:
10309 .. graphviz:: external.dot
10311 As for all file references in Sphinx, if the filename is abso‐
10313 lute, it is taken as relative to the source directory.
10314 Changed in version 1.1: Added support for external files.
10316 .. graph::
10319 Directive for embedding a single undirected graph. The name is
10320 given as a directive argument, the contents of the graph are the
10321 directive content. This is a convenience directive to generate
10322 graph <name> { <content> }.
10323 For example:
10325 .. graph:: foo
10327 "bar" -- "baz";
10329 NOTE:
10331 The graph name is passed unchanged to Graphviz. If it con‐
10332 tains non-alphanumeric characters (e.g. a dash), you will
10333 have to double-quote it.
10334 .. digraph::
10336 Directive for embedding a single directed graph. The name is
10337 given as a directive argument, the contents of the graph are the
10338 directive content. This is a convenience directive to generate
10339 digraph <name> { <content> }.
10340 For example:
10342 .. digraph:: foo
10344 "bar" -> "baz" -> "quux";
10346 New in version 1.0: All three directives support an alt option that
10348 determines the image’s alternate text for HTML output. If not given,
10349 the alternate text defaults to the graphviz code.
10350 New in version 1.1: All three directives support a caption option that
10353 can be used to give a caption to the diagram.
10354 Changed in version 1.4: All three directives support a graphviz_dot
10357 option that can be switch the dot command within the directive.
10358 New in version 1.5: All three directives support a align option to
10361 align the graph horizontal. The values “left”, “center”, “right” are
10362 allowed.
10363 New in version 1.6: All three directives support a name option to set
10366 the label to graph.
10367 There are also these new config values:
10370 graphviz_dot
10372 The command name with which to invoke dot. The default is
10373 'dot'; you may need to set this to a full path if dot is not in
10374 the executable search path.
10375 Since this setting is not portable from system to system, it is
10377 normally not useful to set it in conf.py; rather, giving it on
10378 the sphinx-build command line via the -D option should be
10379 preferable, like this:
10380 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
10382 graphviz_dot_args
10384 Additional command-line arguments to give to dot, as a list.
10385 The default is an empty list. This is the right place to set
10386 global graph, node or edge attributes via dot’s -G, -N and -E
10387 options.
10388 graphviz_output_format
10390 The output format for Graphviz when building HTML files. This
10391 must be either 'png' or 'svg'; the default is 'png'. If 'svg' is
10392 used, in order to make the URL links work properly, an appropri‐
10393 ate target attribute must be set, such as "_top" and "_blank".
10394 For example, the link in the following graph should work in the
10395 svg output:
10396 .. graphviz::
10398 digraph example {
10400 a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
10401 b [label="other"];
10402 a -> b;
10403 }
10404 New in version 1.0: Previously, output always was PNG.
10406 sphinx.ext.ifconfig – Include content based on configuration
10409 This extension is quite simple, and features only one directive:
10410 .. ifconfig::
10412 Include content of the directive only if the Python expression
10413 given as an argument is True, evaluated in the namespace of the
10414 project’s configuration (that is, all registered variables from
10415 conf.py are available).
10416 For example, one could write
10418 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
10420 This stuff is only included in the built docs for unstable versions.
10422 To make a custom config value known to Sphinx, use add_con‐
10424 fig_value() in the setup function in conf.py, e.g.:
10425 def setup(app):
10427 app.add_config_value('releaselevel', '', 'env')
10428 The second argument is the default value, the third should
10430 always be 'env' for such values (it selects if Sphinx re-reads
10431 the documents if the value changes).
10432 sphinx.ext.imgconverter – Convert images to appropriate format for builders
10434 New in version 1.6.
10435 This extension converts images in your document to appropriate format
10438 for builders. For example, it allows you to use SVG images with LaTeX
10439 builder. As a result, you don’t mind what image format the builder
10440 supports.
10441 Internally, this extension uses Imagemagick to convert images.
10443 Configuration
10445 image_converter
10446 A path to convert command. By default, the imgconverter uses
10447 the command from search paths.
10448 image_converter_args
10450 Additional command-line arguments to give to convert, as a list.
10451 The default is an empty list [].
10452 sphinx.ext.inheritance_diagram – Include inheritance diagrams
10454 New in version 0.6.
10455 This extension allows you to include inheritance diagrams, rendered via
10458 the Graphviz extension.
10459 It adds this directive:
10461 .. inheritance-diagram::
10463 This directive has one or more arguments, each giving a module
10464 or class name. Class names can be unqualified; in that case
10465 they are taken to exist in the currently described module (see
10466 py:module).
10467 For each given class, and each class in each given module, the
10469 base classes are determined. Then, from all classes and their
10470 base classes, a graph is generated which is then rendered via
10471 the graphviz extension to a directed graph.
10472 This directive supports an option called parts that, if given,
10474 must be an integer, advising the directive to remove that many
10475 parts of module names from the displayed names. (For example,
10476 if all your class names start with lib., you can give :parts: 1
10477 to remove that prefix from the displayed node names.)
10478 It also supports a private-bases flag option; if given, private
10480 base classes (those whose name starts with _) will be included.
10481 You can use caption option to give a caption to the diagram.
10483 Changed in version 1.1: Added private-bases option; previously,
10485 all bases were always included.
10486 Changed in version 1.5: Added caption option
10489 It also supports a top-classes option which requires one or more
10492 class names separated by comma. If specified inheritance traver‐
10493 sal will stop at the specified class names. Given the following
10494 Python module:
10495 """
10497 A
10498 / \
10499 B C
10500 / \ / \
10501 E D F
10502 """
10503 class A(object):
10505 pass
10506 class B(A):
10508 pass
10509 class C(A):
10511 pass
10512 class D(B, C):
10514 pass
10515 class E(B):
10517 pass
10518 class F(C):
10520 pass
10521 If you have specified a module in the inheritance diagram like
10523 this:
10524 .. inheritance-diagram:: dummy.test
10526 :top-classes: dummy.test.B, dummy.test.C
10527 any base classes which are ancestors to top-classes and are also
10529 defined in the same module will be rendered as stand alone
10530 nodes. In this example class A will be rendered as stand alone
10531 node in the graph. This is a known issue due to how this exten‐
10532 sion works internally.
10533 If you don’t want class A (or any other ancestors) to be visible
10535 then specify only the classes you would like to generate the
10536 diagram for like this:
10537 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
10539 :top-classes: dummy.test.B, dummy.test.C
10540 Changed in version 1.7: Added top-classes option to limit the
10542 scope of inheritance graphs.
10543 New config values are:
10546 inheritance_graph_attrs
10548 A dictionary of graphviz graph attributes for inheritance dia‐
10549 grams.
10550 For example:
10552 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10554 fontsize=14, ratio='compress')
10555 inheritance_node_attrs
10557 A dictionary of graphviz node attributes for inheritance dia‐
10558 grams.
10559 For example:
10561 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10563 color='dodgerblue1', style='filled')
10564 inheritance_edge_attrs
10566 A dictionary of graphviz edge attributes for inheritance dia‐
10567 grams.
10568 inheritance_alias
10570 Allows mapping the full qualified name of the class to custom
10571 values (useful when exposing the underlying path of a class is
10572 not desirable, e.g. it’s a private class and should not be
10573 instantiated by the user).
10574 For example:
10576 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10578 sphinx.ext.intersphinx – Link to other projects’ documentation
10580 New in version 0.5.
10581 This extension can generate automatic links to the documentation of
10584 objects in other projects.
10585 Usage is simple: whenever Sphinx encounters a cross-reference that has
10587 no matching target in the current documentation set, it looks for tar‐
10588 gets in the documentation sets configured in intersphinx_mapping. A
10589 reference like :py:class:`zipfile.ZipFile` can then link to the Python
10590 documentation for the ZipFile class, without you having to specify
10591 where it is located exactly.
10592 When using the “new” format (see below), you can even force lookup in a
10594 foreign set by prefixing the link target appropriately. A link like
10595 :ref:`comparison manual <python:comparisons>` will then link to the
10596 label “comparisons” in the doc set “python”, if it exists.
10597 Behind the scenes, this works as follows:
10599 · Each Sphinx HTML build creates a file named objects.inv that contains
10601 a mapping from object names to URIs relative to the HTML set’s root.
10602 · Projects using the Intersphinx extension can specify the location of
10604 such mapping files in the intersphinx_mapping config value. The map‐
10605 ping will then be used to resolve otherwise missing references to
10606 objects into links to the other documentation.
10607 · By default, the mapping file is assumed to be at the same location as
10609 the rest of the documentation; however, the location of the mapping
10610 file can also be specified individually, e.g. if the docs should be
10611 buildable without Internet access.
10612 To use intersphinx linking, add 'sphinx.ext.intersphinx' to your exten‐
10614 sions config value, and use these new config values to activate link‐
10615 ing:
10616 intersphinx_mapping
10618 This config value contains the locations and names of other
10619 projects that should be linked to in this documentation.
10620 Relative local paths for target locations are taken as relative
10622 to the base of the built documentation, while relative local
10623 paths for inventory locations are taken as relative to the
10624 source directory.
10625 When fetching remote inventory files, proxy settings will be
10627 read from the $HTTP_PROXY environment variable.
10628 Old format for this config value
10630 This is the format used before Sphinx 1.0. It is still recog‐
10632 nized.
10633 A dictionary mapping URIs to either None or an URI. The keys
10635 are the base URI of the foreign Sphinx documentation sets and
10636 can be local paths or HTTP URIs. The values indicate where the
10637 inventory file can be found: they can be None (at the same loca‐
10638 tion as the base URI) or another local or HTTP URI.
10639 New format for this config value
10641 New in version 1.0.
10643 A dictionary mapping unique identifiers to a tuple (target,
10646 inventory). Each target is the base URI of a foreign Sphinx
10647 documentation set and can be a local path or an HTTP URI. The
10648 inventory indicates where the inventory file can be found: it
10649 can be None (at the same location as the base URI) or another
10650 local or HTTP URI.
10651 The unique identifier can be used to prefix cross-reference tar‐
10653 gets, so that it is clear which intersphinx set the target
10654 belongs to. A link like :ref:`comparison manual <python:compar‐
10655 isons>` will link to the label “comparisons” in the doc set
10656 “python”, if it exists.
10657 Example
10659 To add links to modules and objects in the Python standard
10661 library documentation, use:
10662 intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None)}
10664 This will download the corresponding objects.inv file from the
10666 Internet and generate links to the pages under the given URI.
10667 The downloaded inventory is cached in the Sphinx environment, so
10668 it must be re-downloaded whenever you do a full rebuild.
10669 A second example, showing the meaning of a non-None value of the
10671 second tuple item:
10672 intersphinx_mapping = {'python': ('https://docs.python.org/3.4',
10674 'python-inv.txt')}
10675 This will read the inventory from python-inv.txt in the source
10677 directory, but still generate links to the pages under
10678 https://docs.python.org/3.4. It is up to you to update the
10679 inventory file as new objects are added to the Python documenta‐
10680 tion.
10681 Multiple target for the inventory
10683 New in version 1.3.
10685 Alternative files can be specified for each inventory. One can
10688 give a tuple for the second inventory tuple item as shown in the
10689 following example. This will read the inventory iterating
10690 through the (second) tuple items until the first successful
10691 fetch. The primary use case for this to specify mirror sites for
10692 server downtime of the primary inventory:
10693 intersphinx_mapping = {'python': ('https://docs.python.org/3.4',
10695 (None, 'python-inv.txt'))}
10696 intersphinx_cache_limit
10698 The maximum number of days to cache remote inventories. The
10699 default is 5, meaning five days. Set this to a negative value
10700 to cache inventories for unlimited time.
10701 intersphinx_timeout
10703 The number of seconds for timeout. The default is None, meaning
10704 do not timeout.
10705 NOTE:
10707 timeout is not a time limit on the entire response download;
10708 rather, an exception is raised if the server has not issued a
10709 response for timeout seconds.
10710 sphinx.ext.linkcode – Add external links to source code
10712 Module author: Pauli Virtanen
10713 New in version 1.2.
10715 This extension looks at your object descriptions (.. class::, .. func‐
10718 tion:: etc.) and adds external links to code hosted somewhere on the
10719 web. The intent is similar to the sphinx.ext.viewcode extension, but
10720 assumes the source code can be found somewhere on the Internet.
10721 In your configuration, you need to specify a linkcode_resolve function
10723 that returns an URL based on the object.
10724 linkcode_resolve
10726 This is a function linkcode_resolve(domain, info), which should
10727 return the URL to source code corresponding to the object in
10728 given domain with given information.
10729 The function should return None if no link is to be added.
10731 The argument domain specifies the language domain the object is
10733 in. info is a dictionary with the following keys guaranteed to
10734 be present (dependent on the domain):
10735 · py: module (name of the module), fullname (name of the object)
10737 · c: names (list of names for the object)
10739 · cpp: names (list of names for the object)
10741 · javascript: object (name of the object), fullname (name of the
10743 item)
10744 Example:
10746 def linkcode_resolve(domain, info):
10748 if domain != 'py':
10749 return None
10750 if not info['module']:
10751 return None
10752 filename = info['module'].replace('.', '/')
10753 return "http://somesite/sourcerepo/%s.py" % filename
10754 Math support in Sphinx
10756 New in version 0.5.
10757 Since mathematical notation isn’t natively supported by HTML in any
10760 way, Sphinx supports math in documentation with several extensions.
10761 The basic math support is contained in sphinx.ext.mathbase. Other math
10763 support extensions should, if possible, reuse that support too.
10764 NOTE:
10766 mathbase is not meant to be added to the extensions config value,
10767 instead, use either sphinx.ext.imgmath or sphinx.ext.mathjax as
10768 described below.
10769 The input language for mathematics is LaTeX markup. This is the
10771 de-facto standard for plain-text math notation and has the added advan‐
10772 tage that no further translation is necessary when building LaTeX out‐
10773 put.
10774 Keep in mind that when you put math markup in Python docstrings read by
10776 autodoc, you either have to double all backslashes, or use Python raw
10777 strings (r"raw").
10778 mathbase provides the following config values:
10780 math_number_all
10782 Set this option to True if you want all displayed math to be
10783 numbered. The default is False.
10784 math_eqref_format
10786 A string that are used for format of label of references to
10787 equations. As a special character, {number} will be replaced to
10788 equaition number.
10789 Example: 'Eq.{number}' is rendered as Eq.10
10791 math_numfig
10793 If True, displayed math equations are numbered across pages when
10794 numfig is enabled. The numfig_secnum_depth setting is
10795 respected. The eq, not numref, role must be used to reference
10796 equation numbers. Default is True.
10797 New in version 1.7.
10799 mathbase defines these new markup elements:
10802 :math: Role for inline math. Use like this:
10804 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
10806 .. math::
10808 Directive for displayed math (math that takes the whole line for
10809 itself).
10810 The directive supports multiple equations, which should be sepa‐
10812 rated by a blank line:
10813 .. math::
10815 (a + b)^2 = a^2 + 2ab + b^2
10817 (a - b)^2 = a^2 - 2ab + b^2
10819 In addition, each single equation is set within a split environ‐
10821 ment, which means that you can have multiple aligned lines in an
10822 equation, aligned at & and separated by \\:
10823 .. math::
10825 (a + b)^2 &= (a + b)(a + b) \\
10827 &= a^2 + 2ab + b^2
10828 For more details, look into the documentation of the AmSMath
10830 LaTeX package.
10831 When the math is only one line of text, it can also be given as
10833 a directive argument:
10834 .. math:: (a + b)^2 = a^2 + 2ab + b^2
10836 Normally, equations are not numbered. If you want your equation
10838 to get a number, use the label option. When given, it selects
10839 an internal label for the equation, by which it can be
10840 cross-referenced, and causes an equation number to be issued.
10841 See eq for an example. The numbering style depends on the out‐
10842 put format.
10843 There is also an option nowrap that prevents any wrapping of the
10845 given math in a math environment. When you give this option,
10846 you must make sure yourself that the math is properly set up.
10847 For example:
10848 .. math::
10850 :nowrap:
10851 \begin{eqnarray}
10853 y & = & ax^2 + bx + c \\
10854 f(x) & = & x^2 + 2xy + y^2
10855 \end{eqnarray}
10856 :eq: Role for cross-referencing equations via their label. Example:
10858 .. math:: e^{i\pi} + 1 = 0
10860 :label: euler
10861 Euler's identity, equation :eq:`euler`, was elected one of the most
10863 beautiful mathematical formulas.
10864 sphinx.ext.imgmath – Render math as images
10866 New in version 1.4.
10867 This extension renders math via LaTeX and dvipng or dvisvgm into PNG or
10870 SVG images. This of course means that the computer where the docs are
10871 built must have both programs available.
10872 There are various config values you can set to influence how the images
10874 are built:
10875 imgmath_image_format
10877 The output image format. The default is 'png'. It should be
10878 either 'png' or 'svg'.
10879 imgmath_latex
10881 The command name with which to invoke LaTeX. The default is
10882 'latex'; you may need to set this to a full path if latex is not
10883 in the executable search path.
10884 Since this setting is not portable from system to system, it is
10886 normally not useful to set it in conf.py; rather, giving it on
10887 the sphinx-build command line via the -D option should be
10888 preferable, like this:
10889 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
10891 This value should only contain the path to the latex executable,
10893 not further arguments; use imgmath_latex_args for that purpose.
10894 imgmath_dvipng
10896 The command name with which to invoke dvipng. The default is
10897 'dvipng'; you may need to set this to a full path if dvipng is
10898 not in the executable search path. This option is only used when
10899 imgmath_image_format is set to 'png'.
10900 imgmath_dvisvgm
10902 The command name with which to invoke dvisvgm. The default is
10903 'dvisvgm'; you may need to set this to a full path if dvisvgm is
10904 not in the executable search path. This option is only used
10905 when imgmath_image_format is 'svg'.
10906 imgmath_latex_args
10908 Additional arguments to give to latex, as a list. The default
10909 is an empty list.
10910 imgmath_latex_preamble
10912 Additional LaTeX code to put into the preamble of the short
10913 LaTeX files that are used to translate the math snippets. This
10914 is empty by default. Use it e.g. to add more packages whose
10915 commands you want to use in the math.
10916 imgmath_dvipng_args
10918 Additional arguments to give to dvipng, as a list. The default
10919 value is ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']
10920 which makes the image a bit darker and larger then it is by
10921 default, and produces PNGs with a transparent background. This
10922 option is used only when imgmath_image_format is 'png'.
10923 imgmath_dvisvgm_args
10925 Additional arguments to give to dvisvgm, as a list. The default
10926 value is ['--no-fonts']. This option is used only when img‐
10927 math_image_format is 'svg'.
10928 imgmath_use_preview
10930 dvipng has the ability to determine the “depth” of the rendered
10931 text: for example, when typesetting a fraction inline, the base‐
10932 line of surrounding text should not be flush with the bottom of
10933 the image, rather the image should extend a bit below the base‐
10934 line. This is what TeX calls “depth”. When this is enabled,
10935 the images put into the HTML document will get a vertical-align
10936 style that correctly aligns the baselines.
10937 Unfortunately, this only works when the preview-latex package is
10939 installed. Therefore, the default for this option is False.
10940 Currently this option is only used when imgmath_image_format is
10942 'png'.
10943 imgmath_add_tooltips
10945 Default: True. If false, do not add the LaTeX code as an “alt”
10946 attribute for math images.
10947 imgmath_font_size
10949 The font size (in pt) of the displayed math. The default value
10950 is 12. It must be a positive integer.
10951 sphinx.ext.mathjax – Render math via JavaScript
10953 New in version 1.1.
10954 This extension puts math as-is into the HTML files. The JavaScript
10957 package MathJax is then loaded and transforms the LaTeX markup to read‐
10958 able math live in the browser.
10959 Because MathJax (and the necessary fonts) is very large, it is not
10961 included in Sphinx.
10962 mathjax_path
10964 The path to the JavaScript file to include in the HTML files in
10965 order to load MathJax.
10966 The default is the https:// URL that loads the JS files from the
10968 cdnjs Content Delivery Network. See the MathJax Getting Started
10969 page for details. If you want MathJax to be available offline,
10970 you have to download it and set this value to a different path.
10971 The path can be absolute or relative; if it is relative, it is
10973 relative to the _static directory of the built docs.
10974 For example, if you put MathJax into the static path of the
10976 Sphinx docs, this value would be MathJax/MathJax.js. If you
10977 host more than one Sphinx documentation set on one server, it is
10978 advisable to install MathJax in a shared location.
10979 You can also give a full http:// URL different from the CDN URL.
10981 sphinx.ext.jsmath – Render math via JavaScript
10983 This extension works just as the MathJax extension does, but uses the
10984 older package jsMath. It provides this config value:
10985 jsmath_path
10987 The path to the JavaScript file to include in the HTML files in
10988 order to load JSMath. There is no default.
10989 The path can be absolute or relative; if it is relative, it is
10991 relative to the _static directory of the built docs.
10992 For example, if you put JSMath into the static path of the
10994 Sphinx docs, this value would be jsMath/easy/load.js. If you
10995 host more than one Sphinx documentation set on one server, it is
10996 advisable to install jsMath in a shared location.
10997 sphinx.ext.napoleon – Support for NumPy and Google style docstrings
10999 Module author: Rob Ruana
11000 New in version 1.3.
11002 Napoleon - Marching toward legible docstrings
11005 Are you tired of writing docstrings that look like this:
11006 :param path: The path of the file to wrap
11008 :type path: str
11009 :param field_storage: The :class:`FileStorage` instance to wrap
11010 :type field_storage: FileStorage
11011 :param temporary: Whether or not to delete the file when the File
11012 instance is destructed
11013 :type temporary: bool
11014 :returns: A buffered writable file descriptor
11015 :rtype: BufferedFileStorage
11016 ReStructuredText is great, but it creates visually dense, hard to read
11018 docstrings. Compare the jumble above to the same thing rewritten
11019 according to the Google Python Style Guide:
11020 Args:
11022 path (str): The path of the file to wrap
11023 field_storage (FileStorage): The :class:`FileStorage` instance to wrap
11024 temporary (bool): Whether or not to delete the file when the File
11025 instance is destructed
11026 Returns:
11028 BufferedFileStorage: A buffered writable file descriptor
11029 Much more legible, no?
11031 Napoleon is a ../extensions that enables Sphinx to parse both NumPy and
11033 Google style docstrings - the style recommended by Khan Academy.
11034 Napoleon is a pre-processor that parses NumPy and Google style doc‐
11036 strings and converts them to reStructuredText before Sphinx attempts to
11037 parse them. This happens in an intermediate step while Sphinx is pro‐
11038 cessing the documentation, so it doesn’t modify any of the docstrings
11039 in your actual source code files.
11040 Getting Started
11042 1. After setting up Sphinx to build your docs, enable napoleon in the
11043 Sphinx conf.py file:
11044 # conf.py
11046 # Add napoleon to the extensions list
11048 extensions = ['sphinx.ext.napoleon']
11049 2. Use sphinx-apidoc to build your API documentation:
11051 $ sphinx-apidoc -f -o docs/source projectdir
11053 Docstrings
11055 Napoleon interprets every docstring that autodoc can find, including
11056 docstrings on: modules, classes, attributes, methods, functions, and
11057 variables. Inside each docstring, specially formatted Sections are
11058 parsed and converted to reStructuredText.
11059 All standard reStructuredText formatting still works as expected.
11061 Docstring Sections
11063 All of the following section headers are supported:
11064 · Args (alias of Parameters)
11066 · Arguments (alias of Parameters)
11068 · Attributes
11070 · Example
11072 · Examples
11074 · Keyword Args (alias of Keyword Arguments)
11076 · Keyword Arguments
11078 · Methods
11080 · Note
11082 · Notes
11084 · Other Parameters
11086 · Parameters
11088 · Return (alias of Returns)
11090 · Returns
11092 · Raises
11094 · References
11096 · See Also
11098 · Todo
11100 · Warning
11102 · Warnings (alias of Warning)
11104 · Warns
11106 · Yield (alias of Yields)
11108 · Yields
11110 Google vs NumPy
11112 Napoleon supports two styles of docstrings: Google and NumPy. The main
11113 difference between the two styles is that Google uses indention to sep‐
11114 arate sections, whereas NumPy uses underlines.
11115 Google style:
11117 def func(arg1, arg2):
11119 """Summary line.
11120 Extended description of function.
11122 Args:
11124 arg1 (int): Description of arg1
11125 arg2 (str): Description of arg2
11126 Returns:
11128 bool: Description of return value
11129 """
11131 return True
11132 NumPy style:
11134 def func(arg1, arg2):
11136 """Summary line.
11137 Extended description of function.
11139 Parameters
11141 ----------
11142 arg1 : int
11143 Description of arg1
11144 arg2 : str
11145 Description of arg2
11146 Returns
11148 -------
11149 bool
11150 Description of return value
11151 """
11153 return True
11154 NumPy style tends to require more vertical space, whereas Google style
11156 tends to use more horizontal space. Google style tends to be easier to
11157 read for short and simple docstrings, whereas NumPy style tends be eas‐
11158 ier to read for long and in-depth docstrings.
11159 The Khan Academy recommends using Google style.
11161 The choice between styles is largely aesthetic, but the two styles
11163 should not be mixed. Choose one style for your project and be consis‐
11164 tent with it.
11165 SEE ALSO:
11167 For complete examples:
11168 · example_google
11170 · example_numpy
11172 Type Annotations
11174 PEP 484 introduced a standard way to express types in Python code.
11175 This is an alternative to expressing types directly in docstrings. One
11176 benefit of expressing types according to PEP 484 is that type checkers
11177 and IDEs can take advantage of them for static code analysis.
11178 Google style with Python 3 type annotations:
11180 def func(arg1: int, arg2: str) -> bool:
11182 """Summary line.
11183 Extended description of function.
11185 Args:
11187 arg1: Description of arg1
11188 arg2: Description of arg2
11189 Returns:
11191 Description of return value
11192 """
11194 return True
11195 Google style with types in docstrings:
11197 def func(arg1, arg2):
11199 """Summary line.
11200 Extended description of function.
11202 Args:
11204 arg1 (int): Description of arg1
11205 arg2 (str): Description of arg2
11206 Returns:
11208 bool: Description of return value
11209 """
11211 return True
11212 NOTE:
11214 Python 2/3 compatible annotations aren’t currently supported by
11215 Sphinx and won’t show up in the docs.
11216 Configuration
11218 Listed below are all the settings used by napoleon and their default
11219 values. These settings can be changed in the Sphinx conf.py file. Make
11220 sure that “sphinx.ext.napoleon” is enabled in conf.py:
11221 # conf.py
11223 # Add any Sphinx extension module names here, as strings
11225 extensions = ['sphinx.ext.napoleon']
11226 # Napoleon settings
11228 napoleon_google_docstring = True
11229 napoleon_numpy_docstring = True
11230 napoleon_include_init_with_doc = False
11231 napoleon_include_private_with_doc = False
11232 napoleon_include_special_with_doc = True
11233 napoleon_use_admonition_for_examples = False
11234 napoleon_use_admonition_for_notes = False
11235 napoleon_use_admonition_for_references = False
11236 napoleon_use_ivar = False
11237 napoleon_use_param = True
11238 napoleon_use_rtype = True
11239 napoleon_google_docstring
11241 True to parse Google style docstrings. False to disable support
11242 for Google style docstrings. Defaults to True.
11243 napoleon_numpy_docstring
11245 True to parse NumPy style docstrings. False to disable support
11246 for NumPy style docstrings. Defaults to True.
11247 napoleon_include_init_with_doc
11249 True to list __init___ docstrings separately from the class doc‐
11250 string. False to fall back to Sphinx’s default behavior, which
11251 considers the __init___ docstring as part of the class documen‐
11252 tation. Defaults to False.
11253 If True:
11255 def __init__(self):
11257 \"\"\"
11258 This will be included in the docs because it has a docstring
11259 \"\"\"
11260 def __init__(self):
11262 # This will NOT be included in the docs
11263 napoleon_include_private_with_doc
11265 True to include private members (like _membername) with doc‐
11266 strings in the documentation. False to fall back to Sphinx’s
11267 default behavior. Defaults to False.
11268 If True:
11270 def _included(self):
11272 """
11273 This will be included in the docs because it has a docstring
11274 """
11275 pass
11276 def _skipped(self):
11278 # This will NOT be included in the docs
11279 pass
11280 napoleon_include_special_with_doc
11282 True to include special members (like __membername__) with doc‐
11283 strings in the documentation. False to fall back to Sphinx’s
11284 default behavior. Defaults to True.
11285 If True:
11287 def __str__(self):
11289 """
11290 This will be included in the docs because it has a docstring
11291 """
11292 return unicode(self).encode('utf-8')
11293 def __unicode__(self):
11295 # This will NOT be included in the docs
11296 return unicode(self.__class__.__name__)
11297 napoleon_use_admonition_for_examples
11299 True to use the .. admonition:: directive for the Example and
11300 Examples sections. False to use the .. rubric:: directive
11301 instead. One may look better than the other depending on what
11302 HTML theme is used. Defaults to False.
11303 This NumPy style snippet will be converted as follows:
11305 Example
11307 -------
11308 This is just a quick example
11309 If True:
11311 .. admonition:: Example
11313 This is just a quick example
11315 If False:
11317 .. rubric:: Example
11319 This is just a quick example
11321 napoleon_use_admonition_for_notes
11323 True to use the .. admonition:: directive for Notes sections.
11324 False to use the .. rubric:: directive instead. Defaults to
11325 False.
11326 NOTE:
11328 The singular Note section will always be converted to a ..
11329 note:: directive.
11330 SEE ALSO:
11332 napoleon_use_admonition_for_examples
11333 napoleon_use_admonition_for_references
11335 True to use the .. admonition:: directive for References sec‐
11336 tions. False to use the .. rubric:: directive instead. Defaults
11337 to False.
11338 SEE ALSO:
11340 napoleon_use_admonition_for_examples
11341 napoleon_use_ivar
11343 True to use the :ivar: role for instance variables. False to use
11344 the .. attribute:: directive instead. Defaults to False.
11345 This NumPy style snippet will be converted as follows:
11347 Attributes
11349 ----------
11350 attr1 : int
11351 Description of `attr1`
11352 If True:
11354 :ivar attr1: Description of `attr1`
11356 :vartype attr1: int
11357 If False:
11359 .. attribute:: attr1
11361 *int*
11363 Description of `attr1`
11365 napoleon_use_param
11367 True to use a :param: role for each function parameter. False to
11368 use a single :parameters: role for all the parameters. Defaults
11369 to True.
11370 This NumPy style snippet will be converted as follows:
11372 Parameters
11374 ----------
11375 arg1 : str
11376 Description of `arg1`
11377 arg2 : int, optional
11378 Description of `arg2`, defaults to 0
11379 If True:
11381 :param arg1: Description of `arg1`
11383 :type arg1: str
11384 :param arg2: Description of `arg2`, defaults to 0
11385 :type arg2: int, optional
11386 If False:
11388 :parameters: * **arg1** (*str*) --
11390 Description of `arg1`
11391 * **arg2** (*int, optional*) --
11392 Description of `arg2`, defaults to 0
11393 napoleon_use_keyword
11395 True to use a :keyword: role for each function keyword argument.
11396 False to use a single :keyword arguments: role for all the key‐
11397 words. Defaults to True.
11398 This behaves similarly to napoleon_use_param. Note unlike docu‐
11400 tils, :keyword: and :param: will not be treated the same way -
11401 there will be a separate “Keyword Arguments” section, rendered
11402 in the same fashion as “Parameters” section (type links created
11403 if possible)
11404 SEE ALSO:
11406 napoleon_use_param
11407 napoleon_use_rtype
11409 True to use the :rtype: role for the return type. False to out‐
11410 put the return type inline with the description. Defaults to
11411 True.
11412 This NumPy style snippet will be converted as follows:
11414 Returns
11416 -------
11417 bool
11418 True if successful, False otherwise
11419 If True:
11421 :returns: True if successful, False otherwise
11423 :rtype: bool
11424 If False:
11426 :returns: *bool* -- True if successful, False otherwise
11428 sphinx.ext.todo – Support for todo items
11430 Module author: Daniel Bültmann
11431 New in version 0.5.
11433 There are two additional directives when using this extension:
11436 .. todo::
11438 Use this directive like, for example, note.
11439 It will only show up in the output if todo_include_todos is
11441 True.
11442 New in version 1.3.2: This directive supports an class option
11444 that determines the class attribute for HTML output. If not
11445 given, the class defaults to admonition-todo.
11446 .. todolist::
11449 This directive is replaced by a list of all todo directives in
11450 the whole documentation, if todo_include_todos is True.
11451 There is also an additional config value:
11453 todo_include_todos
11455 If this is True, todo and todolist produce output, else they
11456 produce nothing. The default is False.
11457 todo_emit_warnings
11459 If this is True, todo emits a warning for each TODO entries.
11460 The default is False.
11461 New in version 1.5.
11463 todo_link_only
11466 If this is True, todolist produce output without file path and
11467 line, The default is False.
11468 New in version 1.4.
11470 autodoc provides the following an additional event:
11473 todo-defined(app, node)
11475 New in version 1.5.
11476 Emitted when a todo is defined. node is the defined
11479 sphinx.ext.todo.todo_node node.
11480 sphinx.ext.viewcode – Add links to highlighted source code
11482 Module author: Georg Brandl
11483 New in version 1.0.
11485 This extension looks at your Python object descriptions (.. class::, ..
11488 function:: etc.) and tries to find the source files where the objects
11489 are contained. When found, a separate HTML page will be output for
11490 each module with a highlighted version of the source code, and a link
11491 will be added to all object descriptions that leads to the source code
11492 of the described object. A link back from the source to the descrip‐
11493 tion will also be inserted.
11494 This extension works only on HTML related builders like html, apple‐
11496 help, devhelp, htmlhelp, qthelp and so on except singlehtml. By default
11497 epub builder doesn’t support this extension (see viewcode_enable_epub).
11498 There is an additional config value:
11500 viewcode_import
11502 If this is True, viewcode extension will follow alias objects
11503 that imported from another module such as functions, classes and
11504 attributes. As side effects, this option else they produce
11505 nothing. The default is True.
11506 WARNING:
11508 viewcode_import imports the modules to be followed real loca‐
11509 tion. If any modules have side effects on import, these will
11510 be executed by viewcode when sphinx-build is run.
11511 If you document scripts (as opposed to library modules), make
11513 sure their main routine is protected by a if __name__ ==
11514 '__main__' condition.
11515 New in version 1.3.
11517 viewcode_enable_epub
11520 If this is True, viewcode extension is also enabled even if you
11521 use epub builders. This extension generates pages outside toc‐
11522 tree, but this is not preferred as epub format.
11523 Until 1.4.x, this extension is always enabled. If you want to
11525 generate epub as same as 1.4.x, you should set True, but epub
11526 format checker’s score becomes worse.
11527 The default is False.
11529 New in version 1.5.
11531 WARNING:
11534 Not all epub readers support pages generated by viewcode
11535 extension. These readers ignore links to pages are not under
11536 toctree.
11537 Some reader’s rendering result are corrupted and epubcheck’s
11539 score becomes worse even if the reader supports.
11540 Third-party extensions
11542 You can find several extensions contributed by users in the Sphinx Con‐
11543 trib repository. It is open for anyone who wants to maintain an exten‐
11544 sion publicly; just send a short message asking for write permissions.
11545 There are also several extensions hosted elsewhere. The Sphinx exten‐
11547 sion survey contains a comprehensive list.
11548 If you write an extension that you think others will find useful or you
11550 think should be included as a part of Sphinx, please write to the
11551 project mailing list (join here).
11552 Where to put your own extensions?
11554 Extensions local to a project should be put within the project’s direc‐
11555 tory structure. Set Python’s module search path, sys.path, accordingly
11556 so that Sphinx can find them. E.g., if your extension foo.py lies in
11557 the exts subdirectory of the project root, put into conf.py:
11558 import sys, os
11560 sys.path.append(os.path.abspath('exts'))
11562 extensions = ['foo']
11564 You can also install extensions anywhere else on sys.path, e.g. in the
11566 site-packages directory.
11567
11569 Since many projects will need special features in their documentation,
11570 Sphinx is designed to be extensible on several levels.
11571 This is what you can do in an extension: First, you can add new
11573 builders to support new output formats or actions on the parsed docu‐
11574 ments. Then, it is possible to register custom reStructuredText roles
11575 and directives, extending the markup. And finally, there are so-called
11576 “hook points” at strategic places throughout the build process, where
11577 an extension can register a hook and run specialized code.
11578 An extension is simply a Python module. When an extension is loaded,
11580 Sphinx imports this module and executes its setup() function, which in
11581 turn notifies Sphinx of everything the extension offers – see the
11582 extension tutorial for examples.
11583 The configuration file itself can be treated as an extension if it con‐
11585 tains a setup() function. All other extensions to load must be listed
11586 in the extensions configuration value.
11587 Discovery of builders by entry point
11589 New in version 1.6.
11590 Builder extensions can be discovered by means of entry points so that
11593 they do not have to be listed in the extensions configuration value.
11594 Builder extensions should define an entry point in the sphinx.builders
11596 group. The name of the entry point needs to match your builder’s name
11597 attribute, which is the name passed to the sphinx-build -b option. The
11598 entry point value should equal the dotted name of the extension module.
11599 Here is an example of how an entry point for ‘mybuilder’ can be defined
11600 in the extension’s setup.py:
11601 setup(
11603 # ...
11604 entry_points={
11605 'sphinx.builders': [
11606 'mybuilder = my.extension.module',
11607 ],
11608 }
11609 )
11610 Note that it is still necessary to register the builder using
11612 add_builder() in the extension’s setup() function.
11613 Extension metadata
11615 New in version 1.3.
11616 The setup() function can return a dictionary. This is treated by
11619 Sphinx as metadata of the extension. Metadata keys currently recog‐
11620 nized are:
11621 · 'version': a string that identifies the extension version. It is
11623 used for extension version requirement checking (see needs_exten‐
11624 sions) and informational purposes. If not given, "unknown version"
11625 is substituted.
11626 · 'parallel_read_safe': a boolean that specifies if parallel reading of
11628 source files can be used when the extension is loaded. It defaults
11629 to False, i.e. you have to explicitly specify your extension to be
11630 parallel-read-safe after checking that it is.
11631 · 'parallel_write_safe': a boolean that specifies if parallel writing
11633 of output files can be used when the extension is loaded. Since
11634 extensions usually don’t negatively influence the process, this
11635 defaults to True.
11636 APIs used for writing extensions
11638 Tutorial: Writing a simple extension
11639 This section is intended as a walkthrough for the creation of custom
11640 extensions. It covers the basics of writing and activating an exten‐
11641 sion, as well as commonly used features of extensions.
11642 As an example, we will cover a “todo” extension that adds capabilities
11644 to include todo entries in the documentation, and to collect these in a
11645 central place. (A similar “todo” extension is distributed with
11646 Sphinx.)
11647 Important objects
11649 There are several key objects whose API you will use while writing an
11650 extension. These are:
11651 Application
11653 The application object (usually called app) is an instance of
11654 Sphinx. It controls most high-level functionality, such as the
11655 setup of extensions, event dispatching and producing output
11656 (logging).
11657 If you have the environment object, the application is available
11659 as env.app.
11660 Environment
11662 The build environment object (usually called env) is an instance
11663 of BuildEnvironment. It is responsible for parsing the source
11664 documents, stores all metadata about the document collection and
11665 is serialized to disk after each build.
11666 Its API provides methods to do with access to metadata, resolv‐
11668 ing references, etc. It can also be used by extensions to cache
11669 information that should persist for incremental rebuilds.
11670 If you have the application or builder object, the environment
11672 is available as app.env or builder.env.
11673 Builder
11675 The builder object (usually called builder) is an instance of a
11676 specific subclass of Builder. Each builder class knows how to
11677 convert the parsed documents into an output format, or otherwise
11678 process them (e.g. check external links).
11679 If you have the application object, the builder is available as
11681 app.builder.
11682 Config The config object (usually called config) provides the values of
11684 configuration values set in conf.py as attributes. It is an
11685 instance of Config.
11686 The config is available as app.config or env.config.
11688 Build Phases
11690 One thing that is vital in order to understand extension mechanisms is
11691 the way in which a Sphinx project is built: this works in several
11692 phases.
11693 Phase 0: Initialization
11695 In this phase, almost nothing of interest to us happens. The source
11696 directory is searched for source files, and extensions are initial‐
11697 ized. Should a stored build environment exist, it is loaded, other‐
11698 wise a new one is created.
11699 Phase 1: Reading
11701 In Phase 1, all source files (and on subsequent builds, those that
11702 are new or changed) are read and parsed. This is the phase where
11703 directives and roles are encountered by docutils, and the corre‐
11704 sponding code is executed. The output of this phase is a doctree
11705 for each source file; that is a tree of docutils nodes. For docu‐
11706 ment elements that aren’t fully known until all existing files are
11707 read, temporary nodes are created.
11708 There are nodes provided by docutils, which are documented in the
11710 docutils documentation. Additional nodes are provided by Sphinx and
11711 documented here.
11712 During reading, the build environment is updated with all meta- and
11714 cross reference data of the read documents, such as labels, the
11715 names of headings, described Python objects and index entries. This
11716 will later be used to replace the temporary nodes.
11717 The parsed doctrees are stored on the disk, because it is not possi‐
11719 ble to hold all of them in memory.
11720 Phase 2: Consistency checks
11722 Some checking is done to ensure no surprises in the built documents.
11723 Phase 3: Resolving
11725 Now that the metadata and cross-reference data of all existing docu‐
11726 ments is known, all temporary nodes are replaced by nodes that can
11727 be converted into output using components called tranform. For
11728 example, links are created for object references that exist, and
11729 simple literal nodes are created for those that don’t.
11730 Phase 4: Writing
11732 This phase converts the resolved doctrees to the desired output for‐
11733 mat, such as HTML or LaTeX. This happens via a so-called docutils
11734 writer that visits the individual nodes of each doctree and produces
11735 some output in the process.
11736 NOTE:
11738 Some builders deviate from this general build plan, for example, the
11739 builder that checks external links does not need anything more than
11740 the parsed doctrees and therefore does not have phases 2–4.
11741 Extension Design
11743 We want the extension to add the following to Sphinx:
11744 · A “todo” directive, containing some content that is marked with
11746 “TODO”, and only shown in the output if a new config value is set.
11747 (Todo entries should not be in the output by default.)
11748 · A “todolist” directive that creates a list of all todo entries
11750 throughout the documentation.
11751 For that, we will need to add the following elements to Sphinx:
11753 · New directives, called todo and todolist.
11755 · New document tree nodes to represent these directives, conventionally
11757 also called todo and todolist. We wouldn’t need new nodes if the new
11758 directives only produced some content representable by existing
11759 nodes.
11760 · A new config value todo_include_todos (config value names should
11762 start with the extension name, in order to stay unique) that controls
11763 whether todo entries make it into the output.
11764 · New event handlers: one for the doctree-resolved event, to replace
11766 the todo and todolist nodes, and one for env-purge-doc (the reason
11767 for that will be covered later).
11768 The Setup Function
11770 The new elements are added in the extension’s setup function. Let us
11771 create a new Python module called todo.py and add the setup function:
11772 def setup(app):
11774 app.add_config_value('todo_include_todos', False, 'html')
11775 app.add_node(todolist)
11777 app.add_node(todo,
11778 html=(visit_todo_node, depart_todo_node),
11779 latex=(visit_todo_node, depart_todo_node),
11780 text=(visit_todo_node, depart_todo_node))
11781 app.add_directive('todo', TodoDirective)
11783 app.add_directive('todolist', TodolistDirective)
11784 app.connect('doctree-resolved', process_todo_nodes)
11785 app.connect('env-purge-doc', purge_todos)
11786 return {'version': '0.1'} # identifies the version of our extension
11788 The calls in this function refer to classes and functions not yet writ‐
11790 ten. What the individual calls do is the following:
11791 · add_config_value() lets Sphinx know that it should recognize the new
11793 config value todo_include_todos, whose default value should be False
11794 (this also tells Sphinx that it is a boolean value).
11795 If the third argument was 'html', HTML documents would be full
11797 rebuild if the config value changed its value. This is needed for
11798 config values that influence reading (build phase 1).
11799 · add_node() adds a new node class to the build system. It also can
11801 specify visitor functions for each supported output format. These
11802 visitor functions are needed when the new nodes stay until phase 4 –
11803 since the todolist node is always replaced in phase 3, it doesn’t
11804 need any.
11805 We need to create the two node classes todo and todolist later.
11807 · add_directive() adds a new directive, given by name and class.
11809 The handler functions are created later.
11811 · Finally, connect() adds an event handler to the event whose name is
11813 given by the first argument. The event handler function is called
11814 with several arguments which are documented with the event.
11815 The Node Classes
11817 Let’s start with the node classes:
11818 from docutils import nodes
11820 class todo(nodes.Admonition, nodes.Element):
11822 pass
11823 class todolist(nodes.General, nodes.Element):
11825 pass
11826 def visit_todo_node(self, node):
11828 self.visit_admonition(node)
11829 def depart_todo_node(self, node):
11831 self.depart_admonition(node)
11832 Node classes usually don’t have to do anything except inherit from the
11834 standard docutils classes defined in docutils.nodes. todo inherits
11835 from Admonition because it should be handled like a note or warning,
11836 todolist is just a “general” node.
11837 NOTE:
11839 Many extensions will not have to create their own node classes and
11840 work fine with the nodes already provided by docutils and Sphinx.
11841 The Directive Classes
11843 A directive class is a class deriving usually from docu‐
11844 tils.parsers.rst.Directive. The directive interface is also covered in
11845 detail in the docutils documentation; the important thing is that the
11846 class should have attributes that configure the allowed markup, and a
11847 run method that returns a list of nodes.
11848 The todolist directive is quite simple:
11850 from docutils.parsers.rst import Directive
11852 class TodolistDirective(Directive):
11854 def run(self):
11856 return [todolist('')]
11857 An instance of our todolist node class is created and returned. The
11859 todolist directive has neither content nor arguments that need to be
11860 handled.
11861 The todo directive function looks like this:
11863 from sphinx.locale import _
11865 class TodoDirective(Directive):
11867 # this enables content in the directive
11869 has_content = True
11870 def run(self):
11872 env = self.state.document.settings.env
11873 targetid = "todo-%d" % env.new_serialno('todo')
11875 targetnode = nodes.target('', '', ids=[targetid])
11876 todo_node = todo('\n'.join(self.content))
11878 todo_node += nodes.title(_('Todo'), _('Todo'))
11879 self.state.nested_parse(self.content, self.content_offset, todo_node)
11880 if not hasattr(env, 'todo_all_todos'):
11882 env.todo_all_todos = []
11883 env.todo_all_todos.append({
11884 'docname': env.docname,
11885 'lineno': self.lineno,
11886 'todo': todo_node.deepcopy(),
11887 'target': targetnode,
11888 })
11889 return [targetnode, todo_node]
11891 Several important things are covered here. First, as you can see, you
11893 can refer to the build environment instance using self.state.docu‐
11894 ment.settings.env.
11895 Then, to act as a link target (from the todolist), the todo directive
11897 needs to return a target node in addition to the todo node. The target
11898 ID (in HTML, this will be the anchor name) is generated by using
11899 env.new_serialno which returns a new unique integer on each call and
11900 therefore leads to unique target names. The target node is instanti‐
11901 ated without any text (the first two arguments).
11902 On creating admonition node, the content body of the directive are
11904 parsed using self.state.nested_parse. The first argument gives the
11905 content body, and the second one gives content offset. The third argu‐
11906 ment gives the parent node of parsed result, in our case the todo node.
11907 Then, the todo node is added to the environment. This is needed to be
11909 able to create a list of all todo entries throughout the documentation,
11910 in the place where the author puts a todolist directive. For this
11911 case, the environment attribute todo_all_todos is used (again, the name
11912 should be unique, so it is prefixed by the extension name). It does
11913 not exist when a new environment is created, so the directive must
11914 check and create it if necessary. Various information about the todo
11915 entry’s location are stored along with a copy of the node.
11916 In the last line, the nodes that should be put into the doctree are
11918 returned: the target node and the admonition node.
11919 The node structure that the directive returns looks like this:
11921 +--------------------+
11923 | target node |
11924 +--------------------+
11925 +--------------------+
11926 | todo node |
11927 +--------------------+
11928 \__+--------------------+
11929 | admonition title |
11930 +--------------------+
11931 | paragraph |
11932 +--------------------+
11933 | ... |
11934 +--------------------+
11935 The Event Handlers
11937 Finally, let’s look at the event handlers. First, the one for the
11938 env-purge-doc event:
11939 def purge_todos(app, env, docname):
11941 if not hasattr(env, 'todo_all_todos'):
11942 return
11943 env.todo_all_todos = [todo for todo in env.todo_all_todos
11944 if todo['docname'] != docname]
11945 Since we store information from source files in the environment, which
11947 is persistent, it may become out of date when the source file changes.
11948 Therefore, before each source file is read, the environment’s records
11949 of it are cleared, and the env-purge-doc event gives extensions a
11950 chance to do the same. Here we clear out all todos whose docname
11951 matches the given one from the todo_all_todos list. If there are todos
11952 left in the document, they will be added again during parsing.
11953 The other handler belongs to the doctree-resolved event. This event is
11955 emitted at the end of phase 3 and allows custom resolving to be done:
11956 def process_todo_nodes(app, doctree, fromdocname):
11958 if not app.config.todo_include_todos:
11959 for node in doctree.traverse(todo):
11960 node.parent.remove(node)
11961 # Replace all todolist nodes with a list of the collected todos.
11963 # Augment each todo with a backlink to the original location.
11964 env = app.builder.env
11965 for node in doctree.traverse(todolist):
11967 if not app.config.todo_include_todos:
11968 node.replace_self([])
11969 continue
11970 content = []
11972 for todo_info in env.todo_all_todos:
11974 para = nodes.paragraph()
11975 filename = env.doc2path(todo_info['docname'], base=None)
11976 description = (
11977 _('(The original entry is located in %s, line %d and can be found ') %
11978 (filename, todo_info['lineno']))
11979 para += nodes.Text(description, description)
11980 # Create a reference
11982 newnode = nodes.reference('', '')
11983 innernode = nodes.emphasis(_('here'), _('here'))
11984 newnode['refdocname'] = todo_info['docname']
11985 newnode['refuri'] = app.builder.get_relative_uri(
11986 fromdocname, todo_info['docname'])
11987 newnode['refuri'] += '#' + todo_info['target']['refid']
11988 newnode.append(innernode)
11989 para += newnode
11990 para += nodes.Text('.)', '.)')
11991 # Insert into the todolist
11993 content.append(todo_info['todo'])
11994 content.append(para)
11995 node.replace_self(content)
11997 It is a bit more involved. If our new “todo_include_todos” config
11999 value is false, all todo and todolist nodes are removed from the docu‐
12000 ments.
12001 If not, todo nodes just stay where and how they are. Todolist nodes
12003 are replaced by a list of todo entries, complete with backlinks to the
12004 location where they come from. The list items are composed of the
12005 nodes from the todo entry and docutils nodes created on the fly: a
12006 paragraph for each entry, containing text that gives the location, and
12007 a link (reference node containing an italic node) with the backrefer‐
12008 ence. The reference URI is built by app.builder.get_relative_uri which
12009 creates a suitable URI depending on the used builder, and appending the
12010 todo node’s (the target’s) ID as the anchor name.
12011 Application API
12013 Each Sphinx extension is a Python module with at least a setup() func‐
12014 tion. This function is called at initialization time with one argu‐
12015 ment, the application object representing the Sphinx process.
12016 class sphinx.application.Sphinx
12018 This application object has the public API described in the fol‐
12019 lowing.
12020 Extension setup
12022 These methods are usually called in an extension’s setup() function.
12023 Examples of using the Sphinx extension API can be seen in the
12025 sphinx.ext package.
12026 Sphinx.setup_extension(name)
12028 Load the extension given by the module name. Use this if your
12029 extension needs the features provided by another extension.
12030 Sphinx.add_builder(builder)
12032 Register a new builder. builder must be a class that inherits
12033 from Builder.
12034 Sphinx.add_config_value(name, default, rebuild)
12036 Register a configuration value. This is necessary for Sphinx to
12037 recognize new values and set default values accordingly. The
12038 name should be prefixed with the extension name, to avoid
12039 clashes. The default value can be any Python object. The
12040 string value rebuild must be one of those values:
12041 · 'env' if a change in the setting only takes effect when a doc‐
12043 ument is parsed – this means that the whole environment must
12044 be rebuilt.
12045 · 'html' if a change in the setting needs a full rebuild of HTML
12047 documents.
12048 · '' if a change in the setting will not need any special
12050 rebuild.
12051 Changed in version 0.4: If the default value is a callable, it
12053 will be called with the config object as its argument in order
12054 to get the default value. This can be used to implement config
12055 values whose default depends on other values.
12056 Changed in version 0.6: Changed rebuild from a simple boolean
12059 (equivalent to '' or 'env') to a string. However, booleans are
12060 still accepted and converted internally.
12061 Sphinx.add_domain(domain)
12064 Make the given domain (which must be a class; more precisely, a
12065 subclass of Domain) known to Sphinx.
12066 New in version 1.0.
12068 Sphinx.override_domain(domain)
12071 Make the given domain class known to Sphinx, assuming that there
12072 is already a domain with its .name. The new domain must be a
12073 subclass of the existing one.
12074 New in version 1.0.
12076 Sphinx.add_index_to_domain(domain, index)
12079 Add a custom index class to the domain named domain. index must
12080 be a subclass of Index.
12081 New in version 1.0.
12083 Sphinx.add_event(name)
12086 Register an event called name. This is needed to be able to
12087 emit it.
12088 Sphinx.set_translator(name, translator_class)
12090 Register or override a Docutils translator class. This is used
12091 to register a custom output translator or to replace a builtin
12092 translator. This allows extensions to use custom translator and
12093 define custom nodes for the translator (see add_node()).
12094 New in version 1.3.
12096 Sphinx.add_node(node, **kwds)
12099 Register a Docutils node class. This is necessary for Docutils
12100 internals. It may also be used in the future to validate nodes
12101 in the parsed documents.
12102 Node visitor functions for the Sphinx HTML, LaTeX, text and man‐
12104 page writers can be given as keyword arguments: the keyword
12105 should be one or more of 'html', 'latex', 'text', 'man', 'tex‐
12106 info' or any other supported translators, the value a 2-tuple of
12107 (visit, depart) methods. depart can be None if the visit func‐
12108 tion raises docutils.nodes.SkipNode. Example:
12109 class math(docutils.nodes.Element): pass
12111 def visit_math_html(self, node):
12113 self.body.append(self.starttag(node, 'math'))
12114 def depart_math_html(self, node):
12115 self.body.append('</math>')
12116 app.add_node(math, html=(visit_math_html, depart_math_html))
12118 Obviously, translators for which you don’t specify visitor meth‐
12120 ods will choke on the node when encountered in a document to
12121 translate.
12122 Changed in version 0.5: Added the support for keyword arguments
12124 giving visit functions.
12125 Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
12128 Register a Docutils node class as a numfig target. Sphinx num‐
12129 bers the node automatically. And then the users can refer it
12130 using numref.
12131 figtype is a type of enumerable nodes. Each figtypes have indi‐
12133 vidual numbering sequences. As a system figtypes, figure, table
12134 and code-block are defined. It is able to add custom nodes to
12135 these default figtypes. It is also able to define new custom
12136 figtype if new figtype is given.
12137 title_getter is a getter function to obtain the title of node.
12139 It takes an instance of the enumerable node, and it must return
12140 its title as string. The title is used to the default title of
12141 references for ref. By default, Sphinx searches docu‐
12142 tils.nodes.caption or docutils.nodes.title from the node as a
12143 title.
12144 Other keyword arguments are used for node visitor functions. See
12146 the Sphinx.add_node() for details.
12147 New in version 1.4.
12149 Sphinx.add_directive(name, func, content, arguments, **options)
12152 Sphinx.add_directive(name, directiveclass)
12154 Register a Docutils directive. name must be the prospective
12155 directive name. There are two possible ways to write a direc‐
12156 tive:
12157 · In the docutils 0.4 style, obj is the directive function.
12159 content, arguments and options are set as attributes on the
12160 function and determine whether the directive has content,
12161 arguments and options, respectively. This style is depre‐
12162 cated.
12163 · In the docutils 0.5 style, directiveclass is the directive
12165 class. It must already have attributes named has_content,
12166 required_arguments, optional_arguments, final_argument_white‐
12167 space and option_spec that correspond to the options for the
12168 function way. See the Docutils docs for details.
12169 The directive class must inherit from the class docu‐
12171 tils.parsers.rst.Directive.
12172 For example, the (already existing) literalinclude directive
12174 would be added like this:
12175 from docutils.parsers.rst import directives
12177 add_directive('literalinclude', literalinclude_directive,
12178 content = 0, arguments = (1, 0, 0),
12179 linenos = directives.flag,
12180 language = directives.unchanged,
12181 encoding = directives.encoding)
12182 Changed in version 0.6: Docutils 0.5-style directive classes are
12184 now supported.
12185 Sphinx.add_directive_to_domain(domain, name, func, content, arguments,
12188 **options)
12189 Sphinx.add_directive_to_domain(domain, name, directiveclass)
12191 Like add_directive(), but the directive is added to the domain
12192 named domain.
12193 New in version 1.0.
12195 Sphinx.add_role(name, role)
12198 Register a Docutils role. name must be the role name that
12199 occurs in the source, role the role function (see the Docutils
12200 documentation on details).
12201 Sphinx.add_role_to_domain(domain, name, role)
12203 Like add_role(), but the role is added to the domain named
12204 domain.
12205 New in version 1.0.
12207 Sphinx.add_generic_role(name, nodeclass)
12210 Register a Docutils role that does nothing but wrap its contents
12211 in the node given by nodeclass.
12212 New in version 0.6.
12214 Sphinx.add_object_type(directivename, rolename, indextemplate='',
12217 parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
12218 This method is a very convenient way to add a new object type
12219 that can be cross-referenced. It will do this:
12220 · Create a new directive (called directivename) for documenting
12222 an object. It will automatically add index entries if index‐
12223 template is nonempty; if given, it must contain exactly one
12224 instance of %s. See the example below for how the template
12225 will be interpreted.
12226 · Create a new role (called rolename) to cross-reference to
12228 these object descriptions.
12229 · If you provide parse_node, it must be a function that takes a
12231 string and a docutils node, and it must populate the node with
12232 children parsed from the string. It must then return the name
12233 of the item to be used in cross-referencing and index entries.
12234 See the conf.py file in the source for this documentation for
12235 an example.
12236 · The objname (if not given, will default to directivename)
12238 names the type of object. It is used when listing objects,
12239 e.g. in search results.
12240 For example, if you have this call in a custom Sphinx extension:
12242 app.add_object_type('directive', 'dir', 'pair: %s; directive')
12244 you can use this markup in your documents:
12246 .. rst:directive:: function
12248 Document a function.
12250 <...>
12252 See also the :rst:dir:`function` directive.
12254 For the directive, an index entry will be generated as if you
12256 had prepended
12257 .. index:: pair: function; directive
12259 The reference node will be of class literal (so it will be ren‐
12261 dered in a proportional font, as appropriate for code) unless
12262 you give the ref_nodeclass argument, which must be a docutils
12263 node class. Most useful are docutils.nodes.emphasis or docu‐
12264 tils.nodes.strong – you can also use docutils.nodes.generated if
12265 you want no further text decoration. If the text should be
12266 treated as literal (e.g. no smart quote replacement), but not
12267 have typewriter styling, use sphinx.addnodes.literal_emphasis or
12268 sphinx.addnodes.literal_strong.
12269 For the role content, you have the same syntactical possibili‐
12271 ties as for standard Sphinx roles (see xref-syntax).
12272 This method is also available under the deprecated alias
12274 add_description_unit.
12275 Sphinx.add_crossref_type(directivename, rolename, indextemplate='',
12277 ref_nodeclass=None, objname='')
12278 This method is very similar to add_object_type() except that the
12279 directive it generates must be empty, and will produce no out‐
12280 put.
12281 That means that you can add semantic targets to your sources,
12283 and refer to them using custom roles instead of generic ones
12284 (like ref). Example call:
12285 app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
12287 Example usage:
12289 .. topic:: application API
12291 The application API
12293 -------------------
12294 <...>
12296 See also :topic:`this section <application API>`.
12298 (Of course, the element following the topic directive needn’t be
12300 a section.)
12301 Sphinx.add_transform(transform)
12303 Add the standard docutils Transform subclass transform to the
12304 list of transforms that are applied after Sphinx parses a reST
12305 document.
12306 Sphinx.add_post_transform(transform)
12308 Add the standard docutils Transform subclass transform to the
12309 list of transforms that are applied before Sphinx writes a docu‐
12310 ment.
12311 Sphinx.add_javascript(filename)
12313 Add filename to the list of JavaScript files that the default
12314 HTML template will include. The filename must be relative to
12315 the HTML static path, see the docs for the config value. A full
12316 URI with scheme, like http://example.org/foo.js, is also sup‐
12317 ported.
12318 New in version 0.5.
12320 Sphinx.add_stylesheet(filename, alternate=None, title=None)
12323 Add filename to the list of CSS files that the default HTML tem‐
12324 plate will include. Like for add_javascript(), the filename
12325 must be relative to the HTML static path, or a full URI with
12326 scheme.
12327 New in version 1.0.
12329 Changed in version 1.6: Optional alternate and/or title
12332 attributes can be supplied with the alternate (of boolean type)
12333 and title (a string) arguments. The default is no title and
12334 alternate = False (see this explanation).
12335 Sphinx.add_latex_package(packagename, options=None)
12338 Add packagename to the list of packages that LaTeX source code
12339 will include. If you provide options, it will be taken to usep‐
12340 ackage declaration.
12341 app.add_latex_package('mypackage') # => \usepackage{mypackage}
12343 app.add_latex_package('mypackage', 'foo,bar') # => \usepackage[foo,bar]{mypackage}
12344 New in version 1.3.
12346 Sphinx.add_lexer(alias, lexer)
12349 Use lexer, which must be an instance of a Pygments lexer class,
12350 to highlight code blocks with the given language alias.
12351 New in version 0.6.
12353 Sphinx.add_autodocumenter(cls)
12356 Add cls as a new documenter class for the sphinx.ext.autodoc
12357 extension. It must be a subclass of sphinx.ext.autodoc.Docu‐
12358 menter. This allows to auto-document new types of objects. See
12359 the source of the autodoc module for examples on how to subclass
12360 Documenter.
12361 New in version 0.6.
12363 Sphinx.add_autodoc_attrgetter(type, getter)
12366 Add getter, which must be a function with an interface compati‐
12367 ble to the getattr() builtin, as the autodoc attribute getter
12368 for objects that are instances of type. All cases where autodoc
12369 needs to get an attribute of a type are then handled by this
12370 function instead of getattr().
12371 New in version 0.6.
12373 Sphinx.add_search_language(cls)
12376 Add cls, which must be a subclass of sphinx.search.Search‐
12377 Language, as a support language for building the HTML full-text
12378 search index. The class must have a lang attribute that indi‐
12379 cates the language it should be used for. See html_search_lan‐
12380 guage.
12381 New in version 1.1.
12383 Sphinx.add_source_parser(suffix, parser)
12386 Register a parser class for specified suffix.
12387 New in version 1.4.
12389 Sphinx.add_html_theme(name, theme_path)
12392 Register a HTML Theme. The name is a name of theme, and path is
12393 a full path to the theme (refs: distribute-your-theme).
12394 New in version 1.6.
12396 Sphinx.add_env_collector(collector)
12399 Register an environment collector class (refs: collector-api)
12400 New in version 1.6.
12402 Sphinx.require_sphinx(version)
12405 Compare version (which must be a major.minor version string,
12406 e.g. '1.1') with the version of the running Sphinx, and abort
12407 the build when it is too old.
12408 New in version 1.0.
12410 Sphinx.connect(event, callback)
12413 Register callback to be called when event is emitted. For
12414 details on available core events and the arguments of callback
12415 functions, please see Sphinx core events.
12416 The method returns a “listener ID” that can be used as an argu‐
12418 ment to disconnect().
12419 Sphinx.disconnect(listener_id)
12421 Unregister callback listener_id.
12422 exception sphinx.application.ExtensionError
12424 All these methods raise this exception if something went wrong
12425 with the extension API.
12426 Emitting events
12428 Sphinx.emit(event, *arguments)
12429 Emit event and pass arguments to the callback functions. Return
12430 the return values of all callbacks as a list. Do not emit core
12431 Sphinx events in extensions!
12432 Sphinx.emit_firstresult(event, *arguments)
12434 Emit event and pass arguments to the callback functions. Return
12435 the result of the first callback that doesn’t return None.
12436 New in version 0.5.
12438 Producing messages / logging
12441 The application object also provides support for emitting leveled mes‐
12442 sages.
12443 NOTE:
12445 There is no “error” call: in Sphinx, errors are defined as things
12446 that stop the build; just raise an exception (‐
12447 sphinx.errors.SphinxError or a custom subclass) to do that.
12448 Deprecated since version 1.6: Please use logging-api instead.
12450 Sphinx.warn(message, location=None, type=None, subtype=None)
12453 Emit a warning.
12454 If location is given, it should either be a tuple of (docname,
12456 lineno) or a string describing the location of the warning as
12457 well as possible.
12458 type and subtype are used to suppress warnings with sup‐
12460 press_warnings.
12461 Sphinx.info(message='', nonl=False)
12463 Emit an informational message.
12464 If nonl is true, don’t emit a newline at the end (which implies
12466 that more info output will follow soon.)
12467 Sphinx.verbose(message, *args, **kwargs)
12469 Emit a verbose informational message.
12470 Sphinx.debug(message, *args, **kwargs)
12472 Emit a debug-level informational message.
12473 Sphinx.debug2(message, *args, **kwargs)
12475 Emit a lowlevel debug-level informational message.
12476 Sphinx runtime information
12478 The application object also provides runtime information as attributes.
12479 sphinx.application.srcdir
12481 Source directory.
12482 sphinx.application.confdir
12484 Directory containing conf.py.
12485 sphinx.application.doctreedir
12487 Directory for storing pickled doctrees.
12488 sphinx.application.outdir
12490 Directory for storing built document.
12491 Sphinx core events
12493 These events are known to the core. The arguments shown are given to
12494 the registered event handlers. Use connect() in an extension’s setup
12495 function (note that conf.py can also have a setup function) to connect
12496 handlers to the events. Example:
12497 def source_read_handler(app, docname, source):
12499 print('do something here...')
12500 def setup(app):
12502 app.connect('source-read', source_read_handler)
12503 builder-inited(app)
12505 Emitted when the builder object has been created. It is avail‐
12506 able as app.builder.
12507 env-get-outdated(app, env, added, changed, removed)
12509 Emitted when the environment determines which source files have
12510 changed and should be re-read. added, changed and removed are
12511 sets of docnames that the environment has determined. You can
12512 return a list of docnames to re-read in addition to these.
12513 New in version 1.1.
12515 env-purge-doc(app, env, docname)
12518 Emitted when all traces of a source file should be cleaned from
12519 the environment, that is, if the source file is removed or
12520 before it is freshly read. This is for extensions that keep
12521 their own caches in attributes of the environment.
12522 For example, there is a cache of all modules on the environment.
12524 When a source file has been changed, the cache’s entries for the
12525 file are cleared, since the module declarations could have been
12526 removed from the file.
12527 New in version 0.5.
12529 env-before-read-docs(app, env, docnames)
12532 Emitted after the environment has determined the list of all
12533 added and changed files and just before it reads them. It
12534 allows extension authors to reorder the list of docnames
12535 (inplace) before processing, or add more docnames that Sphinx
12536 did not consider changed (but never add any docnames that are
12537 not in env.found_docs).
12538 You can also remove document names; do this with caution since
12540 it will make Sphinx treat changed files as unchanged.
12541 New in version 1.3.
12543 source-read(app, docname, source)
12546 Emitted when a source file has been read. The source argument
12547 is a list whose single element is the contents of the source
12548 file. You can process the contents and replace this item to
12549 implement source-level transformations.
12550 For example, if you want to use $ signs to delimit inline math,
12552 like in LaTeX, you can use a regular expression to replace $...$
12553 by :math:`...`.
12554 New in version 0.5.
12556 doctree-read(app, doctree)
12559 Emitted when a doctree has been parsed and read by the environ‐
12560 ment, and is about to be pickled. The doctree can be modified
12561 in-place.
12562 missing-reference(app, env, node, contnode)
12564 Emitted when a cross-reference to a Python module or object can‐
12565 not be resolved. If the event handler can resolve the refer‐
12566 ence, it should return a new docutils node to be inserted in the
12567 document tree in place of the node node. Usually this node is a
12568 reference node containing contnode as a child.
12569 Parameters
12571 · env – The build environment (app.builder.env).
12573 · node – The pending_xref node to be resolved. Its
12575 attributes reftype, reftarget, modname and classname
12576 attributes determine the type and target of the refer‐
12577 ence.
12578 · contnode – The node that carries the text and format‐
12580 ting inside the future reference and should be a child
12581 of the returned reference node.
12582 New in version 0.5.
12584 doctree-resolved(app, doctree, docname)
12587 Emitted when a doctree has been “resolved” by the environment,
12588 that is, all references have been resolved and TOCs have been
12589 inserted. The doctree can be modified in place.
12590 Here is the place to replace custom nodes that don’t have visi‐
12592 tor methods in the writers, so that they don’t cause errors when
12593 the writers encounter them.
12594 env-merge-info(env, docnames, other)
12596 This event is only emitted when parallel reading of documents is
12597 enabled. It is emitted once for every subprocess that has read
12598 some documents.
12599 You must handle this event in an extension that stores data in
12601 the environment in a custom location. Otherwise the environment
12602 in the main process will not be aware of the information stored
12603 in the subprocess.
12604 other is the environment object from the subprocess, env is the
12606 environment from the main process. docnames is a set of docu‐
12607 ment names that have been read in the subprocess.
12608 For a sample of how to deal with this event, look at the stan‐
12610 dard sphinx.ext.todo extension. The implementation is often
12611 similar to that of env-purge-doc, only that information is not
12612 removed, but added to the main environment from the other envi‐
12613 ronment.
12614 New in version 1.3.
12616 env-updated(app, env)
12619 Emitted when the update() method of the build environment has
12620 completed, that is, the environment and all doctrees are now
12621 up-to-date.
12622 You can return an iterable of docnames from the handler. These
12624 documents will then be considered updated, and will be
12625 (re-)written during the writing phase.
12626 New in version 0.5.
12628 Changed in version 1.3: The handlers’ return value is now used.
12631 env-check-consistency(env)
12634 Emmited when Consistency checks phase. You can check consis‐
12635 tency of metadata for whole of documents.
12636 New in version 1.6: As a experimental event
12638 html-collect-pages(app)
12641 Emitted when the HTML builder is starting to write non-document
12642 pages. You can add pages to write by returning an iterable from
12643 this event consisting of (pagename, context, templatename).
12644 New in version 1.0.
12646 html-page-context(app, pagename, templatename, context, doctree)
12649 Emitted when the HTML builder has created a context dictionary
12650 to render a template with – this can be used to add custom ele‐
12651 ments to the context.
12652 The pagename argument is the canonical name of the page being
12654 rendered, that is, without .html suffix and using slashes as
12655 path separators. The templatename is the name of the template
12656 to render, this will be 'page.html' for all pages from reST doc‐
12657 uments.
12658 The context argument is a dictionary of values that are given to
12660 the template engine to render the page and can be modified to
12661 include custom values. Keys must be strings.
12662 The doctree argument will be a doctree when the page is created
12664 from a reST documents; it will be None when the page is created
12665 from an HTML template alone.
12666 You can return a string from the handler, it will then replace
12668 'page.html' as the HTML template for this page.
12669 New in version 0.4.
12671 Changed in version 1.3: The return value can now specify a tem‐
12674 plate name.
12675 build-finished(app, exception)
12678 Emitted when a build has finished, before Sphinx exits, usually
12679 used for cleanup. This event is emitted even when the build
12680 process raised an exception, given as the exception argument.
12681 The exception is reraised in the application after the event
12682 handlers have run. If the build process raised no exception,
12683 exception will be None. This allows to customize cleanup
12684 actions depending on the exception status.
12685 New in version 0.5.
12687 Checking the Sphinx version
12690 Use this to adapt your extension to API changes in Sphinx.
12691 sphinx.version_info
12693 A tuple of five elements; for Sphinx version 1.2.1 beta 3 this
12694 would be (1, 2, 1, 'beta', 3).
12695 New in version 1.2: Before version 1.2, check the string
12697 sphinx.__version__.
12698 The Config object
12701 class sphinx.config.Config
12702 The config object makes the values of all config values avail‐
12703 able as attributes.
12704 It is available as the config attribute on the application and
12706 environment objects. For example, to get the value of language,
12707 use either app.config.language or env.config.language.
12708 The template bridge
12710 class sphinx.application.TemplateBridge
12711 This class defines the interface for a “template bridge”, that
12712 is, a class that renders templates given a template name and a
12713 context.
12714 init(builder, theme=None, dirs=None)
12716 Called by the builder to initialize the template system.
12717 builder is the builder object; you’ll probably want to
12719 look at the value of builder.config.templates_path.
12720 theme is a sphinx.theming.Theme object or None; in the
12722 latter case, dirs can be list of fixed directories to
12723 look for templates.
12724 newest_template_mtime()
12726 Called by the builder to determine if output files are
12727 outdated because of template changes. Return the mtime
12728 of the newest template file that was changed. The
12729 default implementation returns 0.
12730 render(template, context)
12732 Called by the builder to render a template given as a
12733 filename with a specified context (a Python dictionary).
12734 render_string(template, context)
12736 Called by the builder to render a template given as a
12737 string with a specified context (a Python dictionary).
12738 Exceptions
12740 exception sphinx.errors.SphinxError
12741 This is the base class for “nice” exceptions. When such an
12742 exception is raised, Sphinx will abort the build and present the
12743 exception category and message to the user.
12744 Extensions are encouraged to derive from this exception for
12746 their custom errors.
12747 Exceptions not derived from SphinxError are treated as unex‐
12749 pected and shown to the user with a part of the traceback (and
12750 the full traceback saved in a temporary file).
12751 category
12753 Description of the exception “category”, used in convert‐
12754 ing the exception to a string (“category: message”).
12755 Should be set accordingly in subclasses.
12756 exception sphinx.errors.ConfigError
12758 Used for erroneous values or nonsensical combinations of config‐
12759 uration values.
12760 exception sphinx.errors.ExtensionError
12762 Used for errors in setting up extensions.
12763 exception sphinx.errors.ThemeError
12765 Used for errors to do with themes.
12766 exception sphinx.errors.VersionRequirementError
12768 Raised when the docs require a higher Sphinx version than the
12769 current one.
12770 Build environment API
12772 class sphinx.environment.BuildEnvironment
12773 Attributes
12774 app Reference to the Sphinx (application) object.
12776 config Reference to the Config object.
12778 srcdir Source directory.
12780 doctreedir
12782 Directory for storing pickled doctrees.
12783 found_docs
12785 A set of all existing docnames.
12786 metadata
12788 Dictionary mapping docnames to “metadata” (see metadata).
12789 titles Dictionary mapping docnames to the docutils node for
12791 their main title.
12792 docname
12794 Returns the docname of the document currently being
12795 parsed.
12796 Utility methods
12798 warn(docname, msg, lineno=None, **kwargs)
12800 Emit a warning.
12801 This differs from using app.warn() in that the warning
12803 may not be emitted instantly, but collected for emitting
12804 all warnings after the update of the environment.
12805 warn_node(msg, node, **kwargs)
12807 Like warn(), but with source information taken from node.
12808 doc2path(docname, base=True, suffix=None)
12810 Return the filename for the document name.
12811 If base is True, return absolute path under self.srcdir.
12813 If base is None, return relative path to self.srcdir. If
12814 base is a path string, return absolute path under that.
12815 If suffix is not None, add it instead of con‐
12816 fig.source_suffix.
12817 relfn2path(filename, docname=None)
12819 Return paths to a file referenced from a document, rela‐
12820 tive to documentation root and absolute.
12821 In the input “filename”, absolute filenames are taken as
12823 relative to the source dir, while relative filenames are
12824 relative to the dir of the containing document.
12825 note_dependency(filename)
12827 Add filename as a dependency of the current document.
12828 This means that the document will be rebuilt if this file
12830 changes.
12831 filename should be absolute or relative to the source
12833 directory.
12834 new_serialno(category='')
12836 Return a serial number, e.g. for index entry targets.
12837 The number is guaranteed to be unique in the current doc‐
12839 ument.
12840 note_reread()
12842 Add the current document to the list of documents that
12843 will automatically be re-read at the next build.
12844 Builder API
12846 Todo
12847 Expand this.
12848 class sphinx.builders.Builder
12850 This is the base class for all builders.
12851 These attributes should be set on builder classes:
12853 name = ''
12855 The builder’s name, for the -b command line option.
12856 format = ''
12858 The builder’s output format, or ‘’ if no document output
12859 is produced.
12860 epilog = ''
12862 The message emitted upon successful build completion.
12863 This can be a printf-style template string with the fol‐
12864 lowing keys: outdir, project
12865 supported_image_types = []
12867 The list of MIME types of image formats supported by the
12868 builder. Image files are searched in the order in which
12869 they appear here.
12870 These methods are predefined and will be called from the appli‐
12872 cation:
12873 get_relative_uri(from_, to, typ=None)
12875 Return a relative URI between two source filenames.
12876 May raise environment.NoUri if there’s no way to return a
12878 sensible URI.
12879 build_all()
12881 Build all source files.
12882 build_specific(filenames)
12884 Only rebuild as much as needed for changes in the file‐
12885 names.
12886 build_update()
12888 Only rebuild what was changed or added since last build.
12889 build(docnames, summary=None, method='update')
12891 Main build method.
12892 First updates the environment, and then calls write().
12894 These methods can be overridden in concrete builder classes:
12896 init() Load necessary templates and perform initialization. The
12898 default implementation does nothing.
12899 get_outdated_docs()
12901 Return an iterable of output files that are outdated, or
12902 a string describing what an update build will build.
12903 If the builder does not output individual files corre‐
12905 sponding to source files, return a string here. If it
12906 does, return an iterable of those files that need to be
12907 written.
12908 get_target_uri(docname, typ=None)
12910 Return the target URI for a document name.
12911 typ can be used to qualify the link characteristic for
12913 individual builders.
12914 prepare_writing(docnames)
12916 A place where you can add logic before write_doc() is run
12917 write_doc(docname, doctree)
12919 Where you actually write something to the filesystem.
12920 finish()
12922 Finish the building process.
12923 The default implementation does nothing.
12925 Environment Collector API
12927 class sphinx.environment.collectors.EnvironmentCollector
12928 An EnvironmentCollector is a specific data collector from each
12929 document.
12930 It gathers data and stores BuildEnvironment as a database.
12932 Examples of specific data would be images, download files, sec‐
12933 tion titles, metadatas, index entries and toctrees, etc.
12934 clear_doc(app, env, docname)
12936 Remove specified data of a document.
12937 This method is called on the removal of the document.
12939 get_outdated_docs(app, env, added, changed, removed)
12941 Return a list of docnames to re-read.
12942 This methods is called before reading the documents.
12944 get_updated_docs(app, env)
12946 Return a list of docnames to re-read.
12947 This methods is called after reading the whole of docu‐
12949 ments (experimental).
12950 merge_other(app, env, docnames, other)
12952 Merge in specified data regarding docnames from a differ‐
12953 ent BuildEnvironment object which coming from a subpro‐
12954 cess in parallel builds.
12955 process_doc(app, doctree)
12957 Process a document and gather specific data from it.
12958 This method is called after the document is read.
12960 Docutils markup API
12962 This section describes the API for adding ReST markup elements (roles
12963 and directives).
12964 Roles
12966 Directives
12967 Directives are handled by classes derived from docu‐
12968 tils.parsers.rst.Directive. They have to be registered by an extension
12969 using Sphinx.add_directive() or Sphinx.add_directive_to_domain().
12970 class docutils.parsers.rst.Directive
12972 The markup syntax of the new directive is determined by the fol‐
12973 low five class attributes:
12974 required_arguments = 0
12976 Number of required directive arguments.
12977 optional_arguments = 0
12979 Number of optional arguments after the required argu‐
12980 ments.
12981 final_argument_whitespace = False
12983 May the final argument contain whitespace?
12984 option_spec = None
12986 Mapping of option names to validator functions.
12987 Option validator functions take a single parameter, the
12989 option argument (or None if not given), and should vali‐
12990 date it or convert it to the proper form. They raise
12991 ValueError or TypeError to indicate failure.
12992 There are several predefined and possibly useful valida‐
12994 tors in the docutils.parsers.rst.directives module.
12995 has_content = False
12997 May the directive have content?
12998 New directives must implement the run() method:
13000 run() This method must process the directive arguments, options
13002 and content, and return a list of Docutils/Sphinx nodes
13003 that will be inserted into the document tree at the point
13004 where the directive was encountered.
13005 Instance attributes that are always set on the directive are:
13007 name The directive name (useful when registering the same
13009 directive class under multiple names).
13010 arguments
13012 The arguments given to the directive, as a list.
13013 options
13015 The options given to the directive, as a dictionary map‐
13016 ping option names to validated/converted values.
13017 content
13019 The directive content, if given, as a ViewList.
13020 lineno The absolute line number on which the directive appeared.
13022 This is not always a useful value; use srcline instead.
13023 content_offset
13025 Internal offset of the directive content. Used when
13026 calling nested_parse (see below).
13027 block_text
13029 The string containing the entire directive.
13030 state
13032 state_machine
13034 The state and state machine which controls the parsing.
13035 Used for nested_parse.
13036 ViewLists
13038 Docutils represents document source lines in a class docutils.statema‐
13039 chine.ViewList. This is a list with extended functionality – for one,
13040 slicing creates views of the original list, and also the list contains
13041 information about the source line numbers.
13042 The Directive.content attribute is a ViewList. If you generate content
13044 to be parsed as ReST, you have to create a ViewList yourself. Impor‐
13045 tant for content generation are the following points:
13046 · The constructor takes a list of strings (lines) and a source (docu‐
13048 ment) name.
13049 · The .append() method takes a line and a source name as well.
13051 Parsing directive content as ReST
13053 Many directives will contain more markup that must be parsed. To do
13054 this, use one of the following APIs from the Directive.run() method:
13055 · self.state.nested_parse
13057 · sphinx.util.nodes.nested_parse_with_titles() – this allows titles in
13059 the parsed content.
13060 Both APIs parse the content into a given node. They are used like this:
13062 node = docutils.nodes.paragraph()
13064 # either
13065 nested_parse_with_titles(self.state, self.result, node)
13066 # or
13067 self.state.nested_parse(self.result, 0, node)
13068 NOTE:
13070 sphinx.util.docutils.switch_source_input() allows to change a target
13071 file during nested_parse. It is useful to mixed contents. For
13072 example, sphinx. ext.autodoc uses it to parse docstrings:
13073 from sphinx.util.docutils import switch_source_input
13075 # Switch source_input between parsing content.
13077 # Inside this context, all parsing errors and warnings are reported as
13078 # happened in new source_input (in this case, ``self.result``).
13079 with switch_source_input(self.state, self.result):
13080 node = docutils.nodes.paragraph()
13081 self.state.nested_parse(self.result, 0, node)
13082 Deprecated since version 1.7: Until Sphinx-1.6,
13084 sphinx.ext.autodoc.AutodocReporter is used for this purpose. For
13085 now, it is replaced by switch_source_input().
13086 If you don’t need the wrapping node, you can use any concrete node type
13089 and return node.children from the Directive.
13090 SEE ALSO:
13092 Creating directives
13094 HOWTO of the Docutils documentation
13095 Domain API
13097 class sphinx.domains.Domain(env)
13098 A Domain is meant to be a group of “object” description direc‐
13099 tives for objects of a similar nature, and corresponding roles
13100 to create references to them. Examples would be Python modules,
13101 classes, functions etc., elements of a templating language,
13102 Sphinx roles and directives, etc.
13103 Each domain has a separate storage for information about exist‐
13105 ing objects and how to reference them in self.data, which must
13106 be a dictionary. It also must implement several functions that
13107 expose the object information in a uniform way to parts of
13108 Sphinx that allow the user to reference or search for objects in
13109 a domain-agnostic way.
13110 About self.data: since all object and cross-referencing informa‐
13112 tion is stored on a BuildEnvironment instance, the domain.data
13113 object is also stored in the env.domaindata dict under the key
13114 domain.name. Before the build process starts, every active
13115 domain is instantiated and given the environment object; the
13116 domaindata dict must then either be nonexistent or a dictionary
13117 whose ‘version’ key is equal to the domain class’ data_version
13118 attribute. Otherwise, IOError is raised and the pickled envi‐
13119 ronment is discarded.
13120 add_object_type(name, objtype)
13122 Add an object type.
13123 check_consistency()
13125 Do consistency checks (experimental).
13126 clear_doc(docname)
13128 Remove traces of a document in the domain-specific inven‐
13129 tories.
13130 directive(name)
13132 Return a directive adapter class that always gives the
13133 registered directive its full name (‘domain:name’) as
13134 self.name.
13135 get_full_qualified_name(node)
13137 Return full qualified name for given node.
13138 get_objects()
13140 Return an iterable of “object descriptions”, which are
13141 tuples with five items:
13142 · name – fully qualified name
13144 · dispname – name to display when searching/linking
13146 · type – object type, a key in self.object_types
13148 · docname – the document where it is to be found
13150 · anchor – the anchor name for the object
13152 · priority – how “important” the object is (determines
13154 placement in search results)
13155 · 1: default priority (placed before full-text matches)
13157 · 0: object is important (placed before default-prior‐
13159 ity objects)
13160 · 2: object is unimportant (placed after full-text
13162 matches)
13163 · -1: object should not show up in search at all
13165 get_type_name(type, primary=False)
13167 Return full name for given ObjType.
13168 merge_domaindata(docnames, otherdata)
13170 Merge in data regarding docnames from a different domain‐
13171 data inventory (coming from a subprocess in parallel
13172 builds).
13173 process_doc(env, docname, document)
13175 Process a document after it is read by the environment.
13176 process_field_xref(pnode)
13178 Process a pending xref created in a doc field. For exam‐
13179 ple, attach information about the current scope.
13180 resolve_any_xref(env, fromdocname, builder, target, node, contn‐
13182 ode)
13183 Resolve the pending_xref node with the given target.
13184 The reference comes from an “any” or similar role, which
13186 means that we don’t know the type. Otherwise, the argu‐
13187 ments are the same as for resolve_xref().
13188 The method must return a list (potentially empty) of
13190 tuples ('domain:role', newnode), where 'domain:role' is
13191 the name of a role that could have created the same ref‐
13192 erence, e.g. 'py:func'. newnode is what resolve_xref()
13193 would return.
13194 New in version 1.3.
13196 resolve_xref(env, fromdocname, builder, typ, target, node, con‐
13199 tnode)
13200 Resolve the pending_xref node with the given typ and tar‐
13201 get.
13202 This method should return a new node, to replace the xref
13204 node, containing the contnode which is the markup content
13205 of the cross-reference.
13206 If no resolution can be found, None can be returned; the
13208 xref node will then given to the ‘missing-reference’
13209 event, and if that yields no resolution, replaced by con‐
13210 tnode.
13211 The method can also raise sphinx.environment.NoUri to
13213 suppress the ‘missing-reference’ event being emitted.
13214 role(name)
13216 Return a role adapter function that always gives the reg‐
13217 istered role its full name (‘domain:name’) as the first
13218 argument.
13219 dangling_warnings = {}
13221 role name -> a warning message if reference is missing
13222 data = None
13224 data value
13225 data_version = 0
13227 data version, bump this when the format of self.data
13228 changes
13229 directives = {}
13231 directive name -> directive class
13232 indices = []
13234 a list of Index subclasses
13235 initial_data = {}
13237 data value for a fresh environment
13238 label = ''
13240 domain label: longer, more descriptive (used in messages)
13241 name = ''
13243 domain name: should be short, but unique
13244 object_types = {}
13246 type (usually directive) name -> ObjType instance
13247 roles = {}
13249 role name -> role callable
13250 class sphinx.domains.ObjType(lname, *roles, **attrs)
13252 An ObjType is the description for a type of object that a domain
13253 can document. In the object_types attribute of Domain sub‐
13254 classes, object type names are mapped to instances of this
13255 class.
13256 Constructor arguments:
13258 · lname: localized name of the type (do not include domain name)
13260 · roles: all the roles that can refer to an object of this type
13262 · attrs: object attributes – currently only “searchprio” is
13264 known, which defines the object’s priority in the full-text
13265 search index, see Domain.get_objects().
13266 class sphinx.domains.Index(domain)
13268 An Index is the description for a domain-specific index. To add
13269 an index to a domain, subclass Index, overriding the three name
13270 attributes:
13271 · name is an identifier used for generating file names.
13273 · localname is the section title for the index.
13275 · shortname is a short name for the index, for use in the rela‐
13277 tion bar in HTML output. Can be empty to disable entries in
13278 the relation bar.
13279 and providing a generate() method. Then, add the index class to
13281 your domain’s indices list. Extensions can add indices to
13282 existing domains using add_index_to_domain().
13283 generate(docnames=None)
13285 Return entries for the index given by name. If docnames
13286 is given, restrict to entries referring to these doc‐
13287 names.
13288 The return value is a tuple of (content, collapse), where
13290 collapse is a boolean that determines if sub-entries
13291 should start collapsed (for output formats that support
13292 collapsing sub-entries).
13293 content is a sequence of (letter, entries) tuples, where
13295 letter is the “heading” for the given entries, usually
13296 the starting letter.
13297 entries is a sequence of single entries, where a single
13299 entry is a sequence [name, subtype, docname, anchor,
13300 extra, qualifier, descr]. The items in this sequence
13301 have the following meaning:
13302 · name – the name of the index entry to be displayed
13304 · subtype – sub-entry related type: 0 – normal entry 1 –
13306 entry with sub-entries 2 – sub-entry
13307 · docname – docname where the entry is located
13309 · anchor – anchor for the entry within docname
13311 · extra – extra info for the entry
13313 · qualifier – qualifier for the description
13315 · descr – description for the entry
13317 Qualifier and description are not rendered e.g. in LaTeX
13319 output.
13320 Parser API
13322 class sphinx.parsers.Parser
13323 A base class of source parsers. The additonal parsers should
13324 inherits this class instead of docutils.parsers.Parser. Com‐
13325 pared with docutils.parsers.Parser, this class improves accessi‐
13326 bility to Sphinx APIs.
13327 The subclasses can access following objects and functions:
13329 self.app
13331 The application object (sphinx.application.Sphinx)
13332 self.config
13334 The config object (sphinx.config.Config)
13335 self.env
13337 The environment object (sphinx.environment.BuildEnviron‐
13338 ment)
13339 self.warn()
13341 Emit a warning. (Same as sphinx.applica‐
13342 tion.Sphinx.warn())
13343 self.info()
13345 Emit a informational message. (Same as sphinx.applica‐
13346 tion.Sphinx.info())
13347 Doctree node classes added by Sphinx
13349 Nodes for domain-specific object descriptions
13350 class sphinx.addnodes.desc(rawsource='', *children, **attributes)
13351 Node for object descriptions.
13352 This node is similar to a “definition list” with one definition.
13354 It contains one or more desc_signature and a desc_content.
13355 class sphinx.addnodes.desc_signature(rawsource='', text='', *children,
13357 **attributes)
13358 Node for object signatures.
13359 The “term” part of the custom Sphinx definition list.
13361 As default the signature is a single line signature, but set
13363 is_multiline = True to describe a multi-line signature. In that
13364 case all child nodes must be desc_signature_line nodes.
13365 class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
13367 dren, **attributes)
13368 Node for a line in a multi-line object signatures.
13369 It should only be used in a desc_signature with is_multiline
13371 set. Set add_permalink = True for the line that should get the
13372 permalink.
13373 class sphinx.addnodes.desc_addname(rawsource='', text='', *children,
13375 **attributes)
13376 Node for additional name parts (module name, class name).
13377 class sphinx.addnodes.desc_type(rawsource='', text='', *children,
13379 **attributes)
13380 Node for return types or object type names.
13381 class sphinx.addnodes.desc_returns(rawsource='', text='', *children,
13383 **attributes)
13384 Node for a “returns” annotation (a la -> in Python).
13385 class sphinx.addnodes.desc_name(rawsource='', text='', *children,
13387 **attributes)
13388 Node for the main object name.
13389 class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *chil‐
13391 dren, **attributes)
13392 Node for a general parameter list.
13393 class sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
13395 **attributes)
13396 Node for a single parameter.
13397 class sphinx.addnodes.desc_optional(rawsource='', text='', *children,
13399 **attributes)
13400 Node for marking optional parts of the parameter list.
13401 class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
13403 **attributes)
13404 Node for signature annotations (not Python 3-style annotations).
13405 class sphinx.addnodes.desc_content(rawsource='', *children,
13407 **attributes)
13408 Node for object description content.
13409 This is the “definition” part of the custom Sphinx definition
13411 list.
13412 New admonition-like constructs
13414 class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
13415 **attributes)
13416 Node for version change entries.
13417 Currently used for “versionadded”, “versionchanged” and “depre‐
13419 cated” directives.
13420 class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
13422 Custom “see also” admonition.
13423 Other paragraph-level nodes
13425 class sphinx.addnodes.compact_paragraph(rawsource='', text='', *chil‐
13426 dren, **attributes)
13427 Node for a compact paragraph (which never makes a <p> node).
13428 New inline nodes
13430 class sphinx.addnodes.index(rawsource='', text='', *children,
13431 **attributes)
13432 Node for index entries.
13433 This node is created by the index directive and has one
13435 attribute, entries. Its value is a list of 5-tuples of (entry‐
13436 type, entryname, target, ignored, key).
13437 entrytype is one of “single”, “pair”, “double”, “triple”.
13439 key is categolziation characters (usually it is single charac‐
13441 ter) for general index page. For the detail of this, please see
13442 also: glossary and issue #2320.
13443 class sphinx.addnodes.pending_xref(rawsource='', *children,
13445 **attributes)
13446 Node for cross-references that cannot be resolved without com‐
13447 plete information about all documents.
13448 These nodes are resolved before writing output, in BuildEnviron‐
13450 ment.resolve_references.
13451 class sphinx.addnodes.literal_emphasis(rawsource='', text='', *chil‐
13453 dren, **attributes)
13454 Node that behaves like emphasis, but further text processors are
13455 not applied (e.g. smartypants for HTML output).
13456 class sphinx.addnodes.abbreviation(rawsource='', text='', *children,
13458 **attributes)
13459 Node for abbreviations with explanations.
13460 class sphinx.addnodes.download_reference(rawsource='', text='', *chil‐
13462 dren, **attributes)
13463 Node for download references, similar to pending_xref.
13464 Special nodes
13466 class sphinx.addnodes.only(rawsource='', *children, **attributes)
13467 Node for “only” directives (conditional inclusion based on
13468 tags).
13469 class sphinx.addnodes.meta(rawsource='', *children, **attributes)
13471 Node for meta directive – same as docutils’ standard meta node,
13472 but pickleable.
13473 class sphinx.addnodes.highlightlang(rawsource='', *children,
13475 **attributes)
13476 Inserted to set the highlight language and line number options
13477 for subsequent code blocks.
13478 You should not need to generate the nodes below in extensions.
13480 class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
13482 Node to insert a glossary.
13483 class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
13485 Node for inserting a “TOC tree”.
13486 class sphinx.addnodes.start_of_file(rawsource='', *children,
13488 **attributes)
13489 Node to mark start of a new file, used in the LaTeX builder
13490 only.
13491 class sphinx.addnodes.productionlist(rawsource='', *children,
13493 **attributes)
13494 Node for grammar production lists.
13495 Contains production nodes.
13497 class sphinx.addnodes.production(rawsource='', text='', *children,
13499 **attributes)
13500 Node for a single grammar production rule.
13501 Logging API
13503 sphinx.util.logging.getLogger(name)
13504 Returns a logger wrapped by SphinxLoggerAdapter with the speci‐
13505 fied name.
13506 Example usage:
13508 from sphinx.util import logging # Load on top of python's logging module
13510 logger = logging.getLogger(__name__)
13512 logger.info('Hello, this is an extension!')
13513 class SphinxLoggerAdapter(logging.LoggerAdapter)
13515 error(level, msg, *args, **kwargs)
13517 critical(level, msg, *args, **kwargs)
13519 warning(level, msg, *args, **kwargs)
13521 Logs a message on this logger with the specified level.
13522 Basically, the arguments are as with python’s logging
13523 module.
13524 In addition, Sphinx logger supports following keyword
13526 arguments:
13527 type, *subtype*
13529 Categories of warning logs. It is used to sup‐
13530 press warnings by suppress_warnings setting.
13531 location
13533 Where the warning happened. It is used to include
13534 the path and line number in each log. It allows
13535 docname, tuple of docname and line number and
13536 nodes:
13537 logger = sphinx.util.logging.getLogger(__name__)
13539 logger.warning('Warning happened!', location='index')
13540 logger.warning('Warning happened!', location=('chapter1/index', 10))
13541 logger.warning('Warning happened!', location=some_node)
13542 color The color of logs. By default, warning level logs
13544 are colored as "darkred". The others are not col‐
13545 ored.
13546 log(level, msg, *args, **kwargs)
13548 info(level, msg, *args, **kwargs)
13550 verbose(level, msg, *args, **kwargs)
13552 debug(level, msg, *args, **kwargs)
13554 Logs a message to this logger with the specified level.
13555 Basically, the arguments are as with python’s logging
13556 module.
13557 In addition, Sphinx logger supports following keyword
13559 arguments:
13560 nonl If true, the logger does not fold lines at the end
13562 of the log message. The default is False.
13563 color The color of logs. By default, debug level logs
13565 are colored as "darkgray", and debug2 level ones
13566 are "lightgray". The others are not colored.
13567 pending_logging()
13569 Marks all logs as pending:
13570 with pending_logging():
13572 logger.warning('Warning message!') # not flushed yet
13573 some_long_process()
13574 # the warning is flushed here
13576 pending_warnings()
13578 Marks warning logs as pending. Similar to pending_logging().
13579 Deprecated APIs
13581 On developing Sphinx, we are always careful to the compatibility of our
13582 APIs. But, sometimes, the change of interface are needed for some rea‐
13583 sons. In such cases, we’ve marked them as deprecated. And they are
13584 kept during the two major versions (for more details, please see depre‐
13585 cation-policy).
13586 The following is a list of deprecated interface.
13588 deprecated APIs
13590┌──────────────────────────────┬────────────┬──────────────────┬───────────────────────────────┐
13591│Target │ Deprecated │ (will be) │ Alternatives │
13592│ │ │ Removed │ │
13593├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13594│sphinx.build_main() │ 1.7 │ 2.0 │ sphinx.cmd.build.build_main() │
13595├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13596│sphinx.ext.inter‐ │ 1.7 │ 2.0 │ sphinx.ext.inter‐ │
13597│sphinx.debug() │ │ │ sphinx.inspect_main() │
13598├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13599│sphinx.ext.autodoc.for‐ │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
13600│mat_annotation() │ │ │ │
13601├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13602│sphinx.ext.autodoc.for‐ │ 1.7 │ 2.0 │ sphinx.util.inspect.Signature │
13603│matargspec() │ │ │ │
13604├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13605│sphinx.ext.autodoc.AutodocRe‐ │ 1.7 │ 2.0 │ sphinx.util.docu‐ │
13606│porter │ │ │ tils.switch_source_input() │
13607├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13608│sphinx.ext.autodoc.add_docu‐ │ 1.7 │ 2.0 │ add_autodocumenter() │
13609│menter() │ │ │ │
13610├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13611│sphinx.ext.autodoc.AutoDirec‐ │ 1.7 │ 2.0 │ add_autodocumenter() │
13612│tive._register │ │ │ │
13613├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13614│AutoDirective._special_attr‐ │ 1.7 │ 2.0 │ add_autodoc_attrgetter() │
13615│getters │ │ │ │
13616├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13617│Sphinx.warn(), Sphinx.info() │ 1.6 │ 2.0 │ logging-api │
13618├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13619│BuildEnvironment.set_warn‐ │ 1.6 │ 2.0 │ logging-api │
13620│func() │ │ │ │
13621├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13622│BuildEnvironment.note_toc‐ │ 1.6 │ 2.0 │ Toctree.note() (in │
13623│tree() │ │ │ sphinx.environ‐ │
13624│ │ │ │ ment.adapters.toctree) │
13625├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13626│BuildEnviron‐ │ 1.6 │ 2.0 │ Toctree.get_toc_for() (in │
13627│ment.get_toc_for() │ │ │ sphinx.environ‐ │
13628│ │ │ │ ment.adapters.toctree) │
13629├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13630│BuildEnvironment.get_toc‐ │ 1.6 │ 2.0 │ Toctree.get_toctree_for() (in │
13631│tree_for() │ │ │ sphinx.environ‐ │
13632│ │ │ │ ment.adapters.toctree) │
13633├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13634│BuildEnvironment.cre‐ │ 1.6 │ 2.0 │ IndexEntries.create_index() │
13635│ate_index() │ │ │ (in sphinx.environ‐ │
13636│ │ │ │ ment.adapters.indexentries) │
13637├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13638│sphinx.websupport │ 1.6 │ 2.0 │ sphinxcontrib-websupport │
13639├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13640│StandaloneHTML‐ │ 1.6 │ 2.0 │ add_stylesheet() │
13641│Builder.css_files │ │ │ │
13642├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13643│Sphinx.status_iterator() │ 1.6 │ 1.7 │ sphinx.util.status_iterator() │
13644├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13645│Sphinx.old_status_iterator() │ 1.6 │ 1.7 │ sphinx.util.old_status_itera‐ │
13646│ │ │ │ tor() │
13647└──────────────────────────────┴────────────┴──────────────────┴───────────────────────────────┘
13648│Sphinx._directive_helper() │ 1.6 │ 1.7 │ sphinx.util.docutils.direc‐ │
13652│ │ │ │ tive_helper() │
13653├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13654│sphinx.util.compat.Directive │ 1.6 │ 1.7 │ docutils.parsers.rst.Direc‐ │
13655│ │ │ │ tive │
13656├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13657│sphinx.util.compat.docu‐ │ 1.6 │ 1.7 │ sphinx.util.docutils.__ver‐ │
13658│tils_version │ │ │ sion_info__ │
13659└──────────────────────────────┴────────────┴──────────────────┴───────────────────────────────┘
13660 NOTE:
13662 On deprecating on public APIs (internal functions and classes), we
13663 also follow the policy as much as possible.
13664
13666 New in version 1.1.
13667 Sphinx provides a Python API to easily integrate Sphinx documentation
13670 into your web application. To learn more read the websupportquick‐
13671 start.
13672 Web Support Quick Start
13674 Building Documentation Data
13675 To make use of the web support package in your application you’ll need
13676 to build the data it uses. This data includes pickle files represent‐
13677 ing documents, search indices, and node data that is used to track
13678 where comments and other things are in a document. To do this you will
13679 need to create an instance of the WebSupport class and call its build()
13680 method:
13681 from sphinxcontrib.websupport import WebSupport
13683 support = WebSupport(srcdir='/path/to/rst/sources/',
13685 builddir='/path/to/build/outdir',
13686 search='xapian')
13687 support.build()
13689 This will read reStructuredText sources from srcdir and place the nec‐
13691 essary data in builddir. The builddir will contain two sub-directo‐
13692 ries: one named “data” that contains all the data needed to display
13693 documents, search through documents, and add comments to documents.
13694 The other directory will be called “static” and contains static files
13695 that should be served from “/static”.
13696 NOTE:
13698 If you wish to serve static files from a path other than “/static”,
13699 you can do so by providing the staticdir keyword argument when cre‐
13700 ating the WebSupport object.
13701 Integrating Sphinx Documents Into Your Webapp
13703 Now that the data is built, it’s time to do something useful with it.
13704 Start off by creating a WebSupport object for your application:
13705 from sphinxcontrib.websupport import WebSupport
13707 support = WebSupport(datadir='/path/to/the/data',
13709 search='xapian')
13710 You’ll only need one of these for each set of documentation you will be
13712 working with. You can then call its get_document() method to access
13713 individual documents:
13714 contents = support.get_document('contents')
13716 This will return a dictionary containing the following items:
13718 · body: The main body of the document as HTML
13720 · sidebar: The sidebar of the document as HTML
13722 · relbar: A div containing links to related documents
13724 · title: The title of the document
13726 · css: Links to CSS files used by Sphinx
13728 · script: JavaScript containing comment options
13730 This dict can then be used as context for templates. The goal is to be
13732 easy to integrate with your existing templating system. An example
13733 using Jinja2 is:
13734 {%- extends "layout.html" %}
13736 {%- block title %}
13738 {{ document.title }}
13739 {%- endblock %}
13740 {% block css %}
13742 {{ super() }}
13743 {{ document.css|safe }}
13744 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
13745 {% endblock %}
13746 {%- block script %}
13748 {{ super() }}
13749 {{ document.script|safe }}
13750 {%- endblock %}
13751 {%- block relbar %}
13753 {{ document.relbar|safe }}
13754 {%- endblock %}
13755 {%- block body %}
13757 {{ document.body|safe }}
13758 {%- endblock %}
13759 {%- block sidebar %}
13761 {{ document.sidebar|safe }}
13762 {%- endblock %}
13763 Authentication
13765 To use certain features such as voting, it must be possible to authen‐
13766 ticate users. The details of the authentication are left to your
13767 application. Once a user has been authenticated you can pass the
13768 user’s details to certain WebSupport methods using the username and
13769 moderator keyword arguments. The web support package will store the
13770 username with comments and votes. The only caveat is that if you allow
13771 users to change their username you must update the websupport package’s
13772 data:
13773 support.update_username(old_username, new_username)
13775 username should be a unique string which identifies a user, and modera‐
13777 tor should be a boolean representing whether the user has moderation
13778 privileges. The default value for moderator is False.
13779 An example Flask function that checks whether a user is logged in and
13781 then retrieves a document is:
13782 from sphinxcontrib.websupport.errors import *
13784 @app.route('/<path:docname>')
13786 def doc(docname):
13787 username = g.user.name if g.user else ''
13788 moderator = g.user.moderator if g.user else False
13789 try:
13790 document = support.get_document(docname, username, moderator)
13791 except DocumentNotFoundError:
13792 abort(404)
13793 return render_template('doc.html', document=document)
13794 The first thing to notice is that the docname is just the request path.
13796 This makes accessing the correct document easy from a single view. If
13797 the user is authenticated, then the username and moderation status are
13798 passed along with the docname to get_document(). The web support pack‐
13799 age will then add this data to the COMMENT_OPTIONS that are used in the
13800 template.
13801 NOTE:
13803 This only works if your documentation is served from your document
13804 root. If it is served from another directory, you will need to pre‐
13805 fix the url route with that directory, and give the docroot keyword
13806 argument when creating the web support object:
13807 support = WebSupport(..., docroot='docs')
13809 @app.route('/docs/<path:docname>')
13811 Performing Searches
13813 To use the search form built-in to the Sphinx sidebar, create a func‐
13814 tion to handle requests to the url ‘search’ relative to the documenta‐
13815 tion root. The user’s search query will be in the GET parameters, with
13816 the key q. Then use the get_search_results() method to retrieve search
13817 results. In Flask that would be like this:
13818 @app.route('/search')
13820 def search():
13821 q = request.args.get('q')
13822 document = support.get_search_results(q)
13823 return render_template('doc.html', document=document)
13824 Note that we used the same template to render our search results as we
13826 did to render our documents. That’s because get_search_results()
13827 returns a context dict in the same format that get_document() does.
13828 Comments & Proposals
13830 Now that this is done it’s time to define the functions that handle the
13831 AJAX calls from the script. You will need three functions. The first
13832 function is used to add a new comment, and will call the web support
13833 method add_comment():
13834 @app.route('/docs/add_comment', methods=['POST'])
13836 def add_comment():
13837 parent_id = request.form.get('parent', '')
13838 node_id = request.form.get('node', '')
13839 text = request.form.get('text', '')
13840 proposal = request.form.get('proposal', '')
13841 username = g.user.name if g.user is not None else 'Anonymous'
13842 comment = support.add_comment(text, node_id='node_id',
13843 parent_id='parent_id',
13844 username=username, proposal=proposal)
13845 return jsonify(comment=comment)
13846 You’ll notice that both a parent_id and node_id are sent with the
13848 request. If the comment is being attached directly to a node, parent_id
13849 will be empty. If the comment is a child of another comment, then
13850 node_id will be empty. Then next function handles the retrieval of com‐
13851 ments for a specific node, and is aptly named get_data():
13852 @app.route('/docs/get_comments')
13854 def get_comments():
13855 username = g.user.name if g.user else None
13856 moderator = g.user.moderator if g.user else False
13857 node_id = request.args.get('node', '')
13858 data = support.get_data(node_id, username, moderator)
13859 return jsonify(**data)
13860 The final function that is needed will call process_vote(), and will
13862 handle user votes on comments:
13863 @app.route('/docs/process_vote', methods=['POST'])
13865 def process_vote():
13866 if g.user is None:
13867 abort(401)
13868 comment_id = request.form.get('comment_id')
13869 value = request.form.get('value')
13870 if value is None or comment_id is None:
13871 abort(400)
13872 support.process_vote(comment_id, g.user.id, value)
13873 return "success"
13874 Comment Moderation
13876 By default, all comments added through add_comment() are automatically
13877 displayed. If you wish to have some form of moderation, you can pass
13878 the displayed keyword argument:
13879 comment = support.add_comment(text, node_id='node_id',
13881 parent_id='parent_id',
13882 username=username, proposal=proposal,
13883 displayed=False)
13884 You can then create a new view to handle the moderation of comments.
13886 It will be called when a moderator decides a comment should be accepted
13887 and displayed:
13888 @app.route('/docs/accept_comment', methods=['POST'])
13890 def accept_comment():
13891 moderator = g.user.moderator if g.user else False
13892 comment_id = request.form.get('id')
13893 support.accept_comment(comment_id, moderator=moderator)
13894 return 'OK'
13895 Rejecting comments happens via comment deletion.
13897 To perform a custom action (such as emailing a moderator) when a new
13899 comment is added but not displayed, you can pass callable to the Web‐
13900 Support class when instantiating your support object:
13901 def moderation_callback(comment):
13903 """Do something..."""
13904 support = WebSupport(..., moderation_callback=moderation_callback)
13906 The moderation callback must take one argument, which will be the same
13908 comment dict that is returned by add_comment().
13909 The WebSupport Class
13911 class sphinxcontrib.websupport.WebSupport
13912 The main API class for the web support package. All interac‐
13913 tions with the web support package should occur through this
13914 class.
13915 The class takes the following keyword arguments:
13917 srcdir The directory containing reStructuredText source files.
13919 builddir
13921 The directory that build data and static files should be
13922 placed in. This should be used when creating a
13923 WebSupport object that will be used to build data.
13924 datadir
13926 The directory that the web support data is in. This
13927 should be used when creating a WebSupport object that
13928 will be used to retrieve data.
13929 search This may contain either a string (e.g. ‘xapian’) refer‐
13931 encing a built-in search adapter to use, or an instance
13932 of a subclass of BaseSearch.
13933 storage
13935 This may contain either a string representing a database
13936 uri, or an instance of a subclass of StorageBackend. If
13937 this is not provided, a new sqlite database will be cre‐
13938 ated.
13939 moderation_callback
13941 A callable to be called when a new comment is added that
13942 is not displayed. It must accept one argument: a dictio‐
13943 nary representing the comment that was added.
13944 staticdir
13946 If static files are served from a location besides
13947 '/static', this should be a string with the name of that
13948 location (e.g. '/static_files').
13949 docroot
13951 If the documentation is not served from the base path of
13952 a URL, this should be a string specifying that path (e.g.
13953 'docs').
13954 Changed in version 1.6: WebSupport class is moved to sphinxcontrib.web‐
13956 support from sphinx.websupport. Please add sphinxcontrib-websupport
13957 package in your dependency and use moved class instead.
13958 Methods
13961 WebSupport.build()
13962 Build the documentation. Places the data into the outdir direc‐
13963 tory. Use it like this:
13964 support = WebSupport(srcdir, builddir, search='xapian')
13966 support.build()
13967 This will read reStructured text files from srcdir. Then it will
13969 build the pickles and search index, placing them into builddir.
13970 It will also save node data to the database.
13971 WebSupport.get_document(docname, username='', moderator=False)
13973 Load and return a document from a pickle. The document will be a
13974 dict object which can be used to render a template:
13975 support = WebSupport(datadir=datadir)
13977 support.get_document('index', username, moderator)
13978 In most cases docname will be taken from the request path and
13980 passed directly to this function. In Flask, that would be some‐
13981 thing like this:
13982 @app.route('/<path:docname>')
13984 def index(docname):
13985 username = g.user.name if g.user else ''
13986 moderator = g.user.moderator if g.user else False
13987 try:
13988 document = support.get_document(docname, username,
13989 moderator)
13990 except DocumentNotFoundError:
13991 abort(404)
13992 render_template('doc.html', document=document)
13993 The document dict that is returned contains the following items
13995 to be used during template rendering.
13996 · body: The main body of the document as HTML
13998 · sidebar: The sidebar of the document as HTML
14000 · relbar: A div containing links to related documents
14002 · title: The title of the document
14004 · css: Links to css files used by Sphinx
14006 · script: Javascript containing comment options
14008 This raises DocumentNotFoundError if a document matching docname
14010 is not found.
14011 Parameters
14013 docname – the name of the document to load.
14014 WebSupport.get_data(node_id, username=None, moderator=False)
14016 Get the comments and source associated with node_id. If username
14017 is given vote information will be included with the returned
14018 comments. The default CommentBackend returns a dict with two
14019 keys, source, and comments. source is raw source of the node and
14020 is used as the starting point for proposals a user can add. com‐
14021 ments is a list of dicts that represent a comment, each having
14022 the following items:
14023 ┌──────────────┬────────────────────────────┐
14025 │Key │ Contents │
14026 ├──────────────┼────────────────────────────┤
14027 │text │ The comment text. │
14028 ├──────────────┼────────────────────────────┤
14029 │username │ The username that was │
14030 │ │ stored with the comment. │
14031 ├──────────────┼────────────────────────────┤
14032 │id │ The comment’s unique iden‐ │
14033 │ │ tifier. │
14034 ├──────────────┼────────────────────────────┤
14035 │rating │ The comment’s current rat‐ │
14036 │ │ ing. │
14037 ├──────────────┼────────────────────────────┤
14038 │age │ The time in seconds since │
14039 │ │ the comment was added. │
14040 ├──────────────┼────────────────────────────┤
14041 │time │ A dict containing time │
14042 │ │ information. It contains │
14043 │ │ the following keys: year, │
14044 │ │ month, day, hour, minute, │
14045 │ │ second, iso, and delta. │
14046 │ │ iso is the time formatted │
14047 │ │ in ISO 8601 format. delta │
14048 │ │ is a printable form of how │
14049 │ │ old the comment is (e.g. │
14050 │ │ “3 hours ago”). │
14051 ├──────────────┼────────────────────────────┤
14052 │vote │ If user_id was given, this │
14053 │ │ will be an integer repre‐ │
14054 │ │ senting the vote. 1 for an │
14055 │ │ upvote, -1 for a downvote, │
14056 │ │ or 0 if unvoted. │
14057 ├──────────────┼────────────────────────────┤
14058 │node │ The id of the node that │
14059 │ │ the comment is attached │
14060 │ │ to. If the comment’s par‐ │
14061 │ │ ent is another comment │
14062 │ │ rather than a node, this │
14063 │ │ will be null. │
14064 ├──────────────┼────────────────────────────┤
14065 │parent │ The id of the comment that │
14066 │ │ this comment is attached │
14067 │ │ to if it is not attached │
14068 │ │ to a node. │
14069 ├──────────────┼────────────────────────────┤
14070 │children │ A list of all children, in │
14071 │ │ this format. │
14072 ├──────────────┼────────────────────────────┤
14073 │proposal_diff │ An HTML representation of │
14074 │ │ the differences between │
14075 │ │ the the current source and │
14076 │ │ the user’s proposed │
14077 │ │ source. │
14078 └──────────────┴────────────────────────────┘
14079 Parameters
14081 · node_id – the id of the node to get comments for.
14083 · username – the username of the user viewing the com‐
14085 ments.
14086 · moderator – whether the user is a moderator.
14088 WebSupport.add_comment(text, node_id='', parent_id='', displayed=True,
14090 username=None, time=None, proposal=None, moderator=False)
14091 Add a comment to a node or another comment. Returns the comment
14092 in the same format as get_comments(). If the comment is being
14093 attached to a node, pass in the node’s id (as a string) with the
14094 node keyword argument:
14095 comment = support.add_comment(text, node_id=node_id)
14097 If the comment is the child of another comment, provide the par‐
14099 ent’s id (as a string) with the parent keyword argument:
14100 comment = support.add_comment(text, parent_id=parent_id)
14102 If you would like to store a username with the comment, pass in
14104 the optional username keyword argument:
14105 comment = support.add_comment(text, node=node_id,
14107 username=username)
14108 Parameters
14110 · parent_id – the prefixed id of the comment’s parent.
14112 · text – the text of the comment.
14114 · displayed – for moderation purposes
14116 · username – the username of the user making the comment.
14118 · time – the time the comment was created, defaults to
14120 now.
14121 WebSupport.process_vote(comment_id, username, value)
14123 Process a user’s vote. The web support package relies on the API
14124 user to perform authentication. The API user will typically
14125 receive a comment_id and value from a form, and then make sure
14126 the user is authenticated. A unique username must be passed in,
14127 which will also be used to retrieve the user’s past voting data.
14128 An example, once again in Flask:
14129 @app.route('/docs/process_vote', methods=['POST'])
14131 def process_vote():
14132 if g.user is None:
14133 abort(401)
14134 comment_id = request.form.get('comment_id')
14135 value = request.form.get('value')
14136 if value is None or comment_id is None:
14137 abort(400)
14138 support.process_vote(comment_id, g.user.name, value)
14139 return "success"
14140 Parameters
14142 · comment_id – the comment being voted on
14144 · username – the unique username of the user voting
14146 · value – 1 for an upvote, -1 for a downvote, 0 for an
14148 unvote.
14149 WebSupport.get_search_results(q)
14151 Perform a search for the query q, and create a set of search
14152 results. Then render the search results as html and return a
14153 context dict like the one created by get_document():
14154 document = support.get_search_results(q)
14156 Parameters
14158 q – the search query
14159 Search Adapters
14161 To create a custom search adapter you will need to subclass the
14162 BaseSearch class. Then create an instance of the new class and pass
14163 that as the search keyword argument when you create the WebSupport
14164 object:
14165 support = WebSupport(srcdir=srcdir,
14167 builddir=builddir,
14168 search=MySearch())
14169 For more information about creating a custom search adapter, please see
14171 the documentation of the BaseSearch class below.
14172 class sphinxcontrib.websupport.search.BaseSearch
14174 Defines an interface for search adapters.
14175 Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
14177 support.search from sphinx.websupport.search.
14178 BaseSearch Methods
14181 The following methods are defined in the BaseSearch class. Some
14182 methods do not need to be overridden, but some (add_document() and
14183 handle_query()) must be overridden in your subclass. For a working
14184 example, look at the built-in adapter for whoosh.
14185 BaseSearch.init_indexing(changed=[])
14187 Called by the builder to initialize the search indexer. changed
14188 is a list of pagenames that will be reindexed. You may want to
14189 remove these from the search index before indexing begins.
14190 Parameters
14192 changed – a list of pagenames that will be re-indexed
14193 BaseSearch.finish_indexing()
14195 Called by the builder when writing has been completed. Use this
14196 to perform any finalization or cleanup actions after indexing is
14197 complete.
14198 BaseSearch.feed(pagename, filename, title, doctree)
14200 Called by the builder to add a doctree to the index. Converts
14201 the doctree to text and passes it to add_document(). You proba‐
14202 bly won’t want to override this unless you need access to the
14203 doctree. Override add_document() instead.
14204 Parameters
14206 · pagename – the name of the page to be indexed
14208 · filename – the name of the original source file
14210 · title – the title of the page to be indexed
14212 · doctree – is the docutils doctree representation of the
14214 page
14215 BaseSearch.add_document(pagename, filename, title, text)
14217 Called by feed() to add a document to the search index. This
14218 method should should do everything necessary to add a single
14219 document to the search index.
14220 pagename is name of the page being indexed. It is the combina‐
14222 tion of the source files relative path and filename, minus the
14223 extension. For example, if the source file is
14224 “ext/builders.rst”, the pagename would be “ext/builders”. This
14225 will need to be returned with search results when processing a
14226 query.
14227 Parameters
14229 · pagename – the name of the page being indexed
14231 · filename – the name of the original source file
14233 · title – the page’s title
14235 · text – the full text of the page
14237 BaseSearch.query(q)
14239 Called by the web support api to get search results. This method
14240 compiles the regular expression to be used when extracting con‐
14241 text, then calls handle_query(). You won’t want to override
14242 this unless you don’t want to use the included extract_context()
14243 method. Override handle_query() instead.
14244 Parameters
14246 q – the search query string.
14247 BaseSearch.handle_query(q)
14249 Called by query() to retrieve search results for a search query
14250 q. This should return an iterable containing tuples of the fol‐
14251 lowing format:
14252 (<path>, <title>, <context>)
14254 path and title are the same values that were passed to
14256 add_document(), and context should be a short text snippet of
14257 the text surrounding the search query in the document.
14258 The extract_context() method is provided as a simple way to cre‐
14260 ate the context.
14261 Parameters
14263 q – the search query
14264 BaseSearch.extract_context(text, length=240)
14266 Extract the context for the search query from the document’s
14267 full text.
14268 Parameters
14270 · text – the full text of the document to create the con‐
14272 text for
14273 · length – the length of the context snippet to return.
14275 Storage Backends
14277 To create a custom storage backend you will need to subclass the
14278 StorageBackend class. Then create an instance of the new class and
14279 pass that as the storage keyword argument when you create the WebSup‐
14280 port object:
14281 support = WebSupport(srcdir=srcdir,
14283 builddir=builddir,
14284 storage=MyStorage())
14285 For more information about creating a custom storage backend, please
14287 see the documentation of the StorageBackend class below.
14288 class sphinxcontrib.websupport.storage.StorageBackend
14290 Defines an interface for storage backends.
14291 Changed in version 1.6: StorageBackend class is moved to sphinxcon‐
14293 trib.websupport.storage from sphinx.websupport.storage.
14294 StorageBackend Methods
14297 StorageBackend.pre_build()
14298 Called immediately before the build process begins. Use this to
14299 prepare the StorageBackend for the addition of nodes.
14300 StorageBackend.add_node(id, document, source)
14302 Add a node to the StorageBackend.
14303 Parameters
14305 · id – a unique id for the comment.
14307 · document – the name of the document the node belongs
14309 to.
14310 · source – the source files name.
14312 StorageBackend.post_build()
14314 Called after a build has completed. Use this to finalize the
14315 addition of nodes if needed.
14316 StorageBackend.add_comment(text, displayed, username, time, proposal,
14318 node_id, parent_id, moderator)
14319 Called when a comment is being added.
14320 Parameters
14322 · text – the text of the comment
14324 · displayed – whether the comment should be displayed
14326 · username – the name of the user adding the comment
14328 · time – a date object with the time the comment was
14330 added
14331 · proposal – the text of the proposal the user made
14333 · node_id – the id of the node that the comment is being
14335 added to
14336 · parent_id – the id of the comment’s parent comment.
14338 · moderator – whether the user adding the comment is a
14340 moderator
14341 StorageBackend.delete_comment(comment_id, username, moderator)
14343 Delete a comment.
14344 Raises UserNotAuthorizedError if moderator is False and username
14346 doesn’t match the username on the comment.
14347 Parameters
14349 · comment_id – The id of the comment being deleted.
14351 · username – The username of the user requesting the
14353 deletion.
14354 · moderator – Whether the user is a moderator.
14356 StorageBackend.get_data(node_id, username, moderator)
14358 Called to retrieve all data for a node. This should return a
14359 dict with two keys, source and comments as described by WebSup‐
14360 port’s get_data() method.
14361 Parameters
14363 · node_id – The id of the node to get data for.
14365 · username – The name of the user requesting the data.
14367 · moderator – Whether the requestor is a moderator.
14369 StorageBackend.process_vote(comment_id, username, value)
14371 Process a vote that is being cast. value will be either -1, 0,
14372 or 1.
14373 Parameters
14375 · comment_id – The id of the comment being voted on.
14377 · username – The username of the user casting the vote.
14379 · value – The value of the vote being cast.
14381 StorageBackend.update_username(old_username, new_username)
14383 If a user is allowed to change their username this method should
14384 be called so that there is not stagnate data in the storage sys‐
14385 tem.
14386 Parameters
14388 · old_username – The username being changed.
14390 · new_username – What the username is being changed to.
14392 StorageBackend.accept_comment(comment_id)
14394 Called when a moderator accepts a comment. After the method is
14395 called the comment should be displayed to all users.
14396 Parameters
14398 comment_id – The id of the comment being accepted.
14399
14401 This is a list of Frequently Asked Questions about Sphinx. Feel free
14402 to suggest new entries!
14403 How do I…
14405 … create PDF files without LaTeX?
14406 rinohtype provides a PDF builder that can be used as a drop-in
14407 replacement for the LaTeX builder. Alternatively, you can use
14408 rst2pdf version 0.12 or greater which comes with built-in Sphinx
14409 integration. See the builders section for details.
14410 … get section numbers?
14412 They are automatic in LaTeX output; for HTML, give a :numbered:
14413 option to the toctree directive where you want to start number‐
14414 ing.
14415 … customize the look of the built HTML files?
14417 Use themes, see theming.
14418 … add global substitutions or includes?
14420 Add them in the rst_epilog config value.
14421 … display the whole TOC tree in the sidebar?
14423 Use the toctree callable in a custom layout template, probably
14424 in the sidebartoc block.
14425 … write my own extension?
14427 See the extension tutorial.
14428 … convert from my existing docs using MoinMoin markup?
14430 The easiest way is to convert to xhtml, then convert xhtml to
14431 reST. You’ll still need to mark up classes and such, but the
14432 headings and code examples come through cleanly.
14433 … create HTML slides from Sphinx documents?
14435 See the “Hieroglyph” package at
14436 https://github.com/nyergler/hieroglyph.
14437 For many more extensions and other contributed stuff, see the
14439 sphinx-contrib repository.
14440 Using Sphinx with…
14442 Read the Docs
14443 https://readthedocs.org is a documentation hosting service based
14444 around Sphinx. They will host sphinx documentation, along with
14445 supporting a number of other features including version support,
14446 PDF generation, and more. The Getting Started guide is a good
14447 place to start.
14448 Epydoc There’s a third-party extension providing an api role which
14450 refers to Epydoc’s API docs for a given identifier.
14451 Doxygen
14453 Michael Jones is developing a reST/Sphinx bridge to doxygen
14454 called breathe.
14455 SCons Glenn Hutchings has written a SCons build script to build Sphinx
14457 documentation; it is hosted here:
14458 https://bitbucket.org/zondo/sphinx-scons
14459 PyPI Jannis Leidel wrote a setuptools command that automatically
14461 uploads Sphinx documentation to the PyPI package documentation
14462 area at http://pythonhosted.org/.
14463 GitHub Pages
14465 Directories starting with underscores are ignored by default
14466 which breaks static files in Sphinx. GitHub’s preprocessor can
14467 be disabled to support Sphinx HTML output properly.
14468 MediaWiki
14470 See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a
14471 project by Kevin Dunn.
14472 Google Analytics
14474 You can use a custom layout.html template, like this:
14475 {% extends "!layout.html" %}
14477 {%- block extrahead %}
14479 {{ super() }}
14480 <script type="text/javascript">
14481 var _gaq = _gaq || [];
14482 _gaq.push(['_setAccount', 'XXX account number XXX']);
14483 _gaq.push(['_trackPageview']);
14484 </script>
14485 {% endblock %}
14486 {% block footer %}
14488 {{ super() }}
14489 <div class="footer">This page uses <a href="http://analytics.google.com/">
14490 Google Analytics</a> to collect statistics. You can disable it by blocking
14491 the JavaScript coming from www.google-analytics.com.
14492 <script type="text/javascript">
14493 (function() {
14494 var ga = document.createElement('script');
14495 ga.src = ('https:' == document.location.protocol ?
14496 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
14497 ga.setAttribute('async', 'true');
14498 document.documentElement.firstChild.appendChild(ga);
14499 })();
14500 </script>
14501 </div>
14502 {% endblock %}
14503 Epub info
14505 The following list gives some hints for the creation of epub files:
14506 · Split the text into several files. The longer the individual HTML
14508 files are, the longer it takes the ebook reader to render them. In
14509 extreme cases, the rendering can take up to one minute.
14510 · Try to minimize the markup. This also pays in rendering time.
14512 · For some readers you can use embedded or external fonts using the CSS
14514 @font-face directive. This is extremely useful for code listings
14515 which are often cut at the right margin. The default Courier font
14516 (or variant) is quite wide and you can only display up to 60 charac‐
14517 ters on a line. If you replace it with a narrower font, you can get
14518 more characters on a line. You may even use FontForge and create
14519 narrow variants of some free font. In my case I get up to 70 charac‐
14520 ters on a line.
14521 You may have to experiment a little until you get reasonable results.
14523 · Test the created epubs. You can use several alternatives. The ones I
14525 am aware of are Epubcheck, Calibre, FBreader (although it does not
14526 render the CSS), and Bookworm. For Bookworm, you can download the
14527 source from https://code.google.com/archive/p/threepress and run your
14528 own local server.
14529 · Large floating divs are not displayed properly. If they cover more
14531 than one page, the div is only shown on the first page. In that case
14532 you can copy the epub.css from the sphinx/themes/epub/static/ direc‐
14533 tory to your local _static/ directory and remove the float settings.
14534 · Files that are inserted outside of the toctree directive must be man‐
14536 ually included. This sometimes applies to appendixes, e.g. the glos‐
14537 sary or the indices. You can add them with the epub_post_files
14538 option.
14539 · The handling of the epub cover page differs from the reStructuredText
14541 procedure which automatically resolves image paths and puts the
14542 images into the _images directory. For the epub cover page put the
14543 image in the html_static_path directory and reference it with its
14544 full path in the epub_cover config option.
14545 · kindlegen command can convert from epub3 resulting file to .mobi file
14547 for Kindle. You can get yourdoc.mobi under _build/epub after the fol‐
14548 lowing command:
14549 $ make epub
14551 $ kindlegen _build/epub/yourdoc.epub
14552 The kindlegen command doesn’t accept documents that have section
14554 titles surrounding toctree directive:
14555 Section Title
14557 =============
14558 .. toctree::
14560 subdocument
14562 Section After Toc Tree
14564 ======================
14565 kindlegen assumes all documents order in line, but the resulting doc‐
14567 ument has complicated order for kindlegen:
14568 ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
14570 If you get the following error, fix your document structure:
14572 Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
14574 Error(prcgen):E24001: The table of content could not be built.
14575 Texinfo info
14577 There are two main programs for reading Info files, info and GNU Emacs.
14578 The info program has less features but is available in most Unix envi‐
14579 ronments and can be quickly accessed from the terminal. Emacs provides
14580 better font and color display and supports extensive customization (of
14581 course).
14582 Displaying Links
14584 One noticeable problem you may encounter with the generated Info files
14585 is how references are displayed. If you read the source of an Info
14586 file, a reference to this section would look like:
14587 * note Displaying Links: target-id
14589 In the stand-alone reader, info, references are displayed just as they
14591 appear in the source. Emacs, on the other-hand, will by default
14592 replace *note: with see and hide the target-id. For example:
14593 Displaying Links
14594 The exact behavior of how Emacs displays references is dependent on the
14596 variable Info-hide-note-references. If set to the value of hide, Emacs
14597 will hide both the *note: part and the target-id. This is generally
14598 the best way to view Sphinx-based documents since they often make fre‐
14599 quent use of links and do not take this limitation into account. How‐
14600 ever, changing this variable affects how all Info documents are dis‐
14601 played and most do take this behavior into account.
14602 If you want Emacs to display Info files produced by Sphinx using the
14604 value hide for Info-hide-note-references and the default value for all
14605 other Info files, try adding the following Emacs Lisp code to your
14606 start-up file, ~/.emacs.d/init.el.
14607 (defadvice info-insert-file-contents (after
14609 sphinx-info-insert-file-contents
14610 activate)
14611 "Hack to make `Info-hide-note-references' buffer-local and
14612 automatically set to `hide' iff it can be determined that this file
14613 was created from a Texinfo file generated by Docutils or Sphinx."
14614 (set (make-local-variable 'Info-hide-note-references)
14615 (default-value 'Info-hide-note-references))
14616 (save-excursion
14617 (save-restriction
14618 (widen) (goto-char (point-min))
14619 (when (re-search-forward
14620 "^Generated by \\(Sphinx\\|Docutils\\)"
14621 (save-excursion (search-forward "\x1f" nil t)) t)
14622 (set (make-local-variable 'Info-hide-note-references)
14623 'hide)))))
14624 Notes
14626 The following notes may be helpful if you want to create Texinfo files:
14627 · Each section corresponds to a different node in the Info file.
14629 · Colons (:) cannot be properly escaped in menu entries and xrefs.
14631 They will be replaced with semicolons (;).
14632 · Links to external Info files can be created using the somewhat offi‐
14634 cial URI scheme info. For example:
14635 info:Texinfo#makeinfo_options
14637 · Inline markup
14639 The standard formatting for *strong* and _emphasis_ can result in
14641 ambiguous output when used to markup parameter names and other val‐
14642 ues. Since this is a fairly common practice, the default formatting
14643 has been changed so that emphasis and strong are now displayed like
14644 `literal's.
14645 The standard formatting can be re-enabled by adding the following to
14647 your conf.py:
14648 texinfo_elements = {'preamble': """
14650 @definfoenclose strong,*,*
14651 @definfoenclose emph,_,_
14652 """}
14653
14655 builder
14656 A class (inheriting from Builder) that takes parsed documents
14657 and performs an action on them. Normally, builders translate
14658 the documents to an output format, but it is also possible to
14659 use the builder builders that e.g. check for broken links in the
14660 documentation, or build coverage information.
14661 See builders for an overview over Sphinx’s built-in builders.
14663 configuration directory
14665 The directory containing conf.py. By default, this is the same
14666 as the source directory, but can be set differently with the -c
14667 command-line option.
14668 directive
14670 A reStructuredText markup element that allows marking a block of
14671 content with special meaning. Directives are supplied not only
14672 by docutils, but Sphinx and custom extensions can add their own.
14673 The basic directive syntax looks like this:
14674 .. directivename:: argument ...
14676 :option: value
14677 Content of the directive.
14679 See directives for more information.
14681 document name
14683 Since reST source files can have different extensions (some peo‐
14684 ple like .txt, some like .rst – the extension can be configured
14685 with source_suffix) and different OSes have different path sepa‐
14686 rators, Sphinx abstracts them: document names are always rela‐
14687 tive to the source directory, the extension is stripped, and
14688 path separators are converted to slashes. All values, parame‐
14689 ters and such referring to “documents” expect such document
14690 names.
14691 Examples for document names are index, library/zipfile, or ref‐
14693 erence/datamodel/types. Note that there is no leading or trail‐
14694 ing slash.
14695 domain A domain is a collection of markup (reStructuredText directives
14697 and roles) to describe and link to objects belonging together,
14698 e.g. elements of a programming language. Directive and role
14699 names in a domain have names like domain:name, e.g. py:function.
14700 Having domains means that there are no naming problems when one
14702 set of documentation wants to refer to e.g. C++ and Python
14703 classes. It also means that extensions that support the docu‐
14704 mentation of whole new languages are much easier to write. For
14705 more information about domains, see the chapter domains.
14706 environment
14708 A structure where information about all documents under the root
14709 is saved, and used for cross-referencing. The environment is
14710 pickled after the parsing stage, so that successive runs only
14711 need to read and parse new and changed documents.
14712 master document
14714 The document that contains the root toctree directive.
14715 object The basic building block of Sphinx documentation. Every “object
14717 directive” (e.g. function or object) creates such a block; and
14718 most objects can be cross-referenced to.
14719 RemoveInSphinxXXXWarning
14721 The feature which is warned will be removed in Sphinx-XXX ver‐
14722 sion. It usually caused from Sphinx extensions which is using
14723 deprecated. See also when-deprecation-warnings-are-displayed.
14724 role A reStructuredText markup element that allows marking a piece of
14726 text. Like directives, roles are extensible. The basic syntax
14727 looks like this: :rolename:`content`. See inlinemarkup for
14728 details.
14729 source directory
14731 The directory which, including its subdirectories, contains all
14732 source files for one Sphinx project.
14733
14735 Abstract
14736 This document describes the development process of Sphinx, a documenta‐
14737 tion system used by developers to document systems used by other devel‐
14738 opers to develop other systems that may also be documented using
14739 Sphinx.
14740 · Bug Reports and Feature Requests
14742 · Contributing to Sphinx
14744 · Getting Started
14746 · Core Developers
14748 · Locale updates
14750 · Coding Guide
14752 · Debugging Tips
14754 · Branch Model
14756 · Deprecating a feature
14758 · Deprecation policy
14760 · Unit Testing
14762 The Sphinx source code is managed using Git and is hosted on GitHub.
14764 git clone git://github.com/sphinx-doc/sphinx
14765 Community.INDENT 0.0
14766 sphinx-users <sphinx-users@googlegroups.com>
14768 Mailing list for user support.
14769 sphinx-dev <sphinx-dev@googlegroups.com>
14771 Mailing list for development related discussions.
14772 #sphinx-doc on irc.freenode.net
14774 IRC channel for development questions and user support.
14775 Bug Reports and Feature Requests
14777 If you have encountered a problem with Sphinx or have an idea for a new
14778 feature, please submit it to the issue tracker on GitHub or discuss it
14779 on the sphinx-dev mailing list.
14780 For bug reports, please include the output produced during the build
14782 process and also the log file Sphinx creates after it encounters an
14783 unhandled exception. The location of this file should be shown towards
14784 the end of the error message.
14785 Including or providing a link to the source files involved may help us
14787 fix the issue. If possible, try to create a minimal project that pro‐
14788 duces the error and post that instead.
14789 Contributing to Sphinx
14791 The recommended way for new contributors to submit code to Sphinx is to
14792 fork the repository on GitHub and then submit a pull request after com‐
14793 mitting the changes. The pull request will then need to be approved by
14794 one of the core developers before it is merged into the main reposi‐
14795 tory.
14796 1. Check for open issues or open a fresh issue to start a discussion
14798 around a feature idea or a bug.
14799 2. If you feel uncomfortable or uncertain about an issue or your
14801 changes, feel free to email the sphinx-dev mailing list.
14802 3. Fork the repository on GitHub to start making your changes to the
14804 master branch for next major version, or X.Y branch for next minor
14805 version (see Branch Model).
14806 4. Write a test which shows that the bug was fixed or that the feature
14808 works as expected.
14809 5. Send a pull request and bug the maintainer until it gets merged and
14811 published. Make sure to add yourself to AUTHORS and the change to
14812 CHANGES.
14813 Getting Started
14815 These are the basic steps needed to start developing on Sphinx.
14816 1. Create an account on GitHub.
14818 2. Fork the main Sphinx repository (sphinx-doc/sphinx) using the
14820 GitHub interface.
14821 3. Clone the forked repository to your machine.
14823 git clone https://github.com/USERNAME/sphinx
14825 cd sphinx
14826 4. Checkout the appropriate branch.
14828 For changes that should be included in the next minor release
14830 (namely bug fixes), use the X.Y branch.
14831 git checkout X.Y
14833 For new features or other substantial changes that should wait
14835 until the next major release, use the master branch (see Branch
14836 Model for detail).
14837 5. Setup a virtual environment.
14839 This is not necessary for unit testing, thanks to tox, but it is
14841 necessary if you wish to run sphinx-build locally or run unit tests
14842 without the help of tox.
14843 virtualenv ~/.venv
14845 . ~/.venv/bin/activate
14846 pip install -e .
14847 6. Create a new working branch. Choose any name you like.
14849 git checkout -b feature-xyz
14851 7. Hack, hack, hack.
14853 For tips on working with the code, see the Coding Guide.
14855 8. Test, test, test.
14857 Testing is best done through tox, which provides a number of tar‐
14859 gets and allows testing against multiple different Python environ‐
14860 ments:
14861 · To list all possible targets:
14863 tox -av
14865 · To run unit tests for a specific Python version, such as 3.6:
14867 tox -e py36
14869 · To run unit tests for a specific Python version and turn on dep‐
14871 recation warnings on so they’re shown in the test output:
14872 PYTHONWARNINGS=all tox -e py36
14874 · To run code style and type checks:
14876 tox -e mypy
14878 tox -e flake8
14879 · Arguments to pytest can be passed via tox, e.g. in order to run a
14881 particular test:
14882 tox -e py36 tests/test_module.py::test_new_feature
14884 · To build the documentation:
14886 tox -e docs
14888 · To build the documentation in multiple formats:
14890 tox -e docs -- -b html,latexpdf
14892 You can also test by installing dependencies in your local environ‐
14894 ment.
14895 pip install .[test]
14897 New unit tests should be included in the tests directory where nec‐
14899 essary:
14900 · For bug fixes, first add a test that fails without your changes
14902 and passes after they are applied.
14903 · Tests that need a sphinx-build run should be integrated in one of
14905 the existing test modules if possible. New tests that to
14906 @with_app and then build_all for a few assertions are not good
14907 since the test suite should not take more than a minute to run.
14908 9. Please add a bullet point to CHANGES if the fix or feature is not
14910 trivial (small doc updates, typo fixes). Then commit:
14911 git commit -m '#42: Add useful new feature that does this.'
14913 GitHub recognizes certain phrases that can be used to automatically
14915 update the issue tracker.
14916 For example:
14918 git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
14920 would close issue #42.
14922 10. Push changes in the branch to your forked repository on GitHub.
14924 git push origin feature-xyz
14926 11. Submit a pull request from your branch to the respective branch
14928 (master or X.Y).
14929 12. Wait for a core developer to review your changes.
14931 Core Developers
14933 The core developers of Sphinx have write access to the main repository.
14934 They can commit changes, accept/reject pull requests, and manage items
14935 on the issue tracker.
14936 You do not need to be a core developer or have write access to be
14938 involved in the development of Sphinx. You can submit patches or cre‐
14939 ate pull requests from forked repositories and have a core developer
14940 add the changes for you.
14941 The following are some general guidelines for core developers:
14943 · Questionable or extensive changes should be submitted as a pull
14945 request instead of being committed directly to the main repository.
14946 The pull request should be reviewed by another core developer before
14947 it is merged.
14948 · Trivial changes can be committed directly but be sure to keep the
14950 repository in a good working state and that all tests pass before
14951 pushing your changes.
14952 · When committing code written by someone else, please attribute the
14954 original author in the commit message and any relevant CHANGES entry.
14955 Locale updates
14957 The parts of messages in Sphinx that go into builds are translated into
14958 several locales. The translations are kept as gettext .po files trans‐
14959 lated from the master template sphinx/locale/sphinx.pot.
14960 Sphinx uses Babel to extract messages and maintain the catalog files.
14962 It is integrated in setup.py:
14963 · Use python setup.py extract_messages to update the .pot template.
14965 · Use python setup.py update_catalog to update all existing language
14967 catalogs in sphinx/locale/*/LC_MESSAGES with the current messages in
14968 the template file.
14969 · Use python setup.py compile_catalog to compile the .po files to
14971 binary .mo files and .js files.
14972 When an updated .po file is submitted, run compile_catalog to commit
14974 both the source and the compiled catalogs.
14975 When a new locale is submitted, add a new directory with the ISO 639-1
14977 language identifier and put sphinx.po in there. Don’t forget to update
14978 the possible values for language in doc/config.rst.
14979 The Sphinx core messages can also be translated on Transifex. There
14981 exists a client tool named tx in the Python package “transifex_client”,
14982 which can be used to pull translations in .po format from Transifex.
14983 To do this, go to sphinx/locale and then run tx pull -f -l LANG where
14984 LANG is an existing language identifier. It is good practice to run
14985 python setup.py update_catalog afterwards to make sure the .po file has
14986 the canonical Babel formatting.
14987 Coding Guide
14989 · Try to use the same code style as used in the rest of the project.
14990 See the Pocoo Styleguide for more information.
14991 · For non-trivial changes, please update the CHANGES file. If your
14993 changes alter existing behavior, please document this.
14994 · New features should be documented. Include examples and use cases
14996 where appropriate. If possible, include a sample that is displayed
14997 in the generated output.
14998 · When adding a new configuration variable, be sure to document it and
15000 update sphinx/quickstart.py if it’s important enough.
15001 · Use the included utils/check_sources.py script to check for common
15003 formatting issues (trailing whitespace, lengthy lines, etc).
15004 · Add appropriate unit tests.
15006 Debugging Tips
15008 · Delete the build cache before building documents if you make changes
15009 in the code by running the command make clean or using the
15010 sphinx-build -E option.
15011 · Use the sphinx-build -P option to run pdb on exceptions.
15013 · Use node.pformat() and node.asdom().toxml() to generate a printable
15015 representation of the document structure.
15016 · Set the configuration variable keep_warnings to True so warnings will
15018 be displayed in the generated output.
15019 · Set the configuration variable nitpicky to True so that Sphinx will
15021 complain about references without a known target.
15022 · Set the debugging options in the Docutils configuration file.
15024 · JavaScript stemming algorithms in sphinx/search/*.py (except en.py)
15026 are generated by this modified snowballcode generator. Generated JSX
15027 files are in this repository. You can get the resulting JavaScript
15028 files using the following command:
15029 $ npm install
15031 $ node_modules/.bin/grunt build # -> dest/*.global.js
15032 Branch Model
15034 Sphinx project uses following branches for developing.
15035 master Used for main development. All improvement and refactoring, bug
15037 fixes are allowed.
15038 X.Y Where X.Y is the MAJOR.MINOR release. Used to maintain current
15040 stable release. Only bug fixes and stable changes are allowed.
15041 Only the most recent stable release is currently retained. When
15042 a new version is released, the old release branch will be
15043 deleted and replaced by an equivalent tag.
15044 Deprecating a feature
15046 There are a couple reasons that code in Sphinx might be deprecated:
15047 · If a feature has been improved or modified in a backwards-incompati‐
15049 ble way, the old feature or behavior will be deprecated.
15050 · Sometimes Sphinx will include a backport of a Python library that’s
15052 not included in a version of Python that Sphinx currently supports.
15053 When Sphinx no longer needs to support the older version of Python
15054 that doesn’t include the library, the library will be deprecated in
15055 Sphinx.
15056 As the Deprecation policy describes, the first release of Sphinx that
15058 deprecates a feature (A.B) should raise a RemovedInSphinxXXWarning
15059 (where XX is the Sphinx version where the feature will be removed) when
15060 the deprecated feature is invoked. Assuming we have good test coverage,
15061 these warnings are converted to errors when running the test suite with
15062 warnings enabled:
15063 pytest -Wall
15065 Thus, when adding a RemovedInSphinxXXWarning you need to eliminate or
15067 silence any warnings generated when running the tests.
15068 Deprecation policy
15070 A feature release may deprecate certain features from previous
15071 releases. If a feature is deprecated in feature release 1.A, it will
15072 continue to work in all 1.A.x versions (for all versions of x) but
15073 raise warnings. Deprecated features will be removed in the first 1.B
15074 release, or 1.B.1 for features deprecated in the last 1.A.x feature
15075 release to ensure deprecations are done over at least 2 feature
15076 releases.
15077 So, for example, if we decided to start the deprecation of a function
15079 in Sphinx 1.4:
15080 · Sphinx 1.4.x will contain a backwards-compatible replica of the func‐
15082 tion which will raise a RemovedInSphinx16Warning.
15083 · Sphinx 1.5 (the version that follows 1.4) will still contain the
15085 backwards-compatible replica.
15086 · Sphinx 1.6 will remove the feature outright.
15088 The warnings are displayed by default. You can turn off display of
15090 these warnings with:
15091 · PYTHONWARNINGS= make html (Linux/Mac)
15093 · export PYTHONWARNINGS= and do make html (Linux/Mac)
15095 · set PYTHONWARNINGS= and do make html (Windows)
15097 Unit Testing
15099 Sphinx has been tested with pytest runner. Sphinx developers write unit
15100 tests using pytest notation. Utility functions and pytest fixtures for
15101 testing are provided in sphinx.testing. If you are a developer of
15102 Sphinx extensions, you can write unit tests with using pytest. At this
15103 time, sphinx.testing will help your test implementation.
15104 How to use pytest fixtures that are provided by sphinx.testing? You
15106 can require 'sphinx.testing.fixtures' in your test modules or con‐
15107 ftest.py files like this:
15108 pytest_plugins = 'sphinx.testing.fixtures'
15110 If you want to know more detailed usage, please refer to tests/con‐
15112 ftest.py and other test_*.py files under tests directory.
15113 NOTE:
15115 Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
15116 New in version 1.6: sphinx.testing as a experimental.
15118
15121 Release 1.7.6 (released Jul 17, 2018)
15122 Bugs fixed
15123 · #5037: LaTeX \sphinxupquote{} breaks in Russian
15124 · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
15126 · #5016: crashed when recommonmark.AutoStrictify is enabled
15128 · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
15130 · #5009: latex: a label for table is vanished if table does not have a
15132 caption
15133 · #5048: crashed with numbered toctree
15135 · #2410: C, render empty argument lists for macros.
15137 · C++, fix lookup of full template specializations with no template
15139 arguments.
15140 · #4667: C++, fix assertion on missing references in global scope when
15142 using intersphinx. Thanks to Alan M. Carroll.
15143 · #5019: autodoc: crashed by Form Feed Character
15145 · #5032: autodoc: loses the first staticmethod parameter for old styled
15147 classes
15148 · #5036: quickstart: Typing Ctrl-U clears the whole of line
15150 · #5066: html: “relations” sidebar is not shown by default
15152 · #5091: latex: curly braces in index entries are not handled correctly
15154 · #5070: epub: Wrong internal href fragment links
15156 · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
15158 · #4272: PDF builds of French projects have issues with XeTeX
15160 · #5076: napoleon raises RuntimeError with python 3.7
15162 · #5125: sphinx-build: Interface of sphinx:main() has changed
15164 · sphinx-build: sphinx.cmd.build.main() refers sys.argv instead of
15166 given argument
15167 · #5146: autosummary: warning is emitted when the first line of doc‐
15169 string ends with literal notation
15170 · autosummary: warnings of autosummary indicates wrong location (refs:
15172 #5146)
15173 · #5143: autodoc: crashed on inspecting dict like object which does not
15175 support sorting
15176 · #5139: autodoc: Enum argument missing if it shares value with another
15178 · #4946: py domain: rtype field could not handle “None” as a type
15180 · #5176: LaTeX: indexing of terms containing @, !, or " fails
15182 · #5161: html: crashes if copying static files are failed
15184 · #5167: autodoc: Fix formatting type annotations for tuples with more
15186 than two arguments
15187 · #3329: i18n: crashed by auto-symbol footnote references
15189 · #5158: autosummary: module summary has been broken when it starts
15191 with heading
15192 Release 1.7.5 (released May 29, 2018)
15194 Bugs fixed
15195 · #4924: html search: Upper characters problem in any other languages
15196 · #4932: apidoc: some subpackage is ignored if sibling subpackage con‐
15198 tains a module starting with underscore
15199 · #4863, #4938, #4939: i18n doesn’t handle node.title correctly tat
15201 used for contents, topic, admonition, table and section.
15202 · #4913: i18n: literal blocks in bullet list are not translated
15204 · #4962: C++, raised TypeError on duplicate declaration.
15206 · #4825: C++, properly parse expr roles and give better error messages
15208 when (escaped) line breaks are present.
15209 · C++, properly use desc_addname nodes for prefixes of names.
15211 · C++, parse pack expansions in function calls.
15213 · #4915, #4916: links on search page are broken when using dirhtml
15215 builder
15216 · #4969: autodoc: constructor method should not have return annotation
15218 · latex: deeply nested enumerated list which is beginning with non-1
15220 causes LaTeX engine crashed
15221 · #4978: latex: shorthandoff is not set up for Brazil locale
15223 · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
15225 · #4946: py domain: type field could not handle “None” as a type
15227 · #4979: latex: Incorrect escaping of curly braces in index entries
15229 · #4956: autodoc: Failed to extract document from a subclass of the
15231 class on mocked module
15232 · #4973: latex: glossary directive adds whitespace to each item
15234 · #4980: latex: Explicit labels on code blocks are duplicated
15236 · #4919: node.asdom() crashes if toctree has :numbered: option
15238 · #4914: autodoc: Parsing error when using dataclasses without default
15240 values
15241 · #4931: autodoc: crashed when handler for autodoc-skip-member raises
15243 an error
15244 · #4931: autodoc: crashed when subclass of mocked class are processed
15246 by napoleon module
15247 · #5007: sphinx-build crashes when error log contains a “%” character
15249 Release 1.7.4 (released Apr 25, 2018)
15251 Bugs fixed
15252 · #4885, #4887: domains: Crashed with duplicated objects
15253 · #4889: latex: sphinx.writers.latex causes recusrive import
15255 Release 1.7.3 (released Apr 23, 2018)
15257 Bugs fixed
15258 · #4769: autodoc loses the first staticmethod parameter
15259 · #4790: autosummary: too wide two column tables in PDF builds
15261 · #4795: Latex customization via _templates/longtable.tex_t is broken
15263 · #4789: imgconverter: confused by convert.exe of Windows
15265 · #4783: On windows, Sphinx crashed when drives of srcdir and outdir
15267 are different
15268 · #4812: autodoc ignores type annotated variables
15270 · #4817: wrong URLs on warning messages
15272 · #4784: latex: latex_show_urls assigns incorrect footnote numbers if
15274 hyperlinks exists inside substitutions
15275 · #4837: latex with class memoir Error: Font command \sf is not sup‐
15277 ported
15278 · #4803: latex: too slow in proportion to number of auto numbered foot‐
15280 notes
15281 · #4838: htmlhelp: The entries in .hhp file is not ordered
15283 · toctree directive tries to glob for URL having query_string
15285 · #4871: html search: Upper characters problem in German
15287 · #4717: latex: Compilation for German docs failed with LuaLaTeX and
15289 XeLaTeX
15290 · #4459: duplicated labels detector does not work well in parallel
15292 build
15293 · #4878: Crashed with extension which returns invalid metadata
15295 Release 1.7.2 (released Mar 21, 2018)
15297 Incompatible changes
15298 · #4520: apidoc: folders with an empty __init__.py are no longer
15299 excluded from TOC
15300 Bugs fixed
15302 · #4669: sphinx.build_main and sphinx.make_main throw NameError
15303 · #4685: autosummary emits meaningless warnings
15305 · autodoc: crashed when invalid options given
15307 · pydomain: always strip parenthesis if empty (refs: #1042)
15309 · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
15311 · #4701: viewcode: Misplaced <div> in viewcode html output
15313 · #4444: Don’t require numfig to use :numref: on sections
15315 · #4727: Option clash for package textcomp
15317 · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
15319 · #4716: Generation PDF file with TexLive on Windows, file not found
15321 error
15322 · #4574: vertical space before equation in latex
15324 · #4720: message when an image is mismatched for builder is not clear
15326 · #4655, #4684: Incomplete localization strings in Polish and Chinese
15328 · #2286: Sphinx crashes when error is happens in rendering HTML pages
15330 · #4688: Error to download remote images having long URL
15332 · #4754: sphinx/pycode/__init__.py raises AttributeError
15334 · #1435: qthelp builder should htmlescape keywords
15336 · epub: Fix docTitle elements of toc.ncx is not escaped
15338 · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
15340 · #4767: html: search highlighting breaks mathjax equations
15342 Release 1.7.1 (released Feb 23, 2018)
15344 Deprecated
15345 · #4623: sphinx.build_main() is deprecated.
15346 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
15348 has been changed (Since 1.7.0)
15349 · #4664: sphinx.ext.intersphinx.debug() is deprecated.
15351 For more details, see deprecation APIs list
15353 Bugs fixed
15355 · #4608: epub: Invalid meta tag is generated
15356 · #4260: autodoc: keyword only argument separator is not disappeared if
15358 it is appeared at top of the argument list
15359 · #4622: epub: epub_scheme does not effect to content.opf
15361 · #4627: graphviz: Fit graphviz images to page
15363 · #4617: quickstart: PROJECT_DIR argument is required
15365 · #4623: sphinx.build_main no longer exists in 1.7.0
15367 · #4615: The argument of sphinx.build has been changed in 1.7.0
15369 · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
15371 has been changed
15372 · #4630: Have order on msgids in sphinx.pot deterministic
15374 · #4563: autosummary: Incorrect end of line punctuation detection
15376 · #4577: Enumerated sublists with explicit start with wrong number
15378 · #4641: A external link in TOC cannot contain “?” with :glob: option
15380 · C++, add missing parsing of explicit casts and typeid in expression
15382 parsing.
15383 · C++, add missing parsing of this in expression parsing.
15385 · #4655: Fix incomplete localization strings in Polish
15387 · #4653: Fix error reporting for parameterless ImportErrors
15389 · #4664: Reading objects.inv fails again
15391 · #4662: any refs with term targets crash when an ambiguity is encoun‐
15393 tered
15394 Release 1.7.0 (released Feb 12, 2018)
15396 Dependencies
15397 1.7.0b1
15398 · Add packaging package
15400 Incompatible changes
15402 1.7.0b1
15403 · #3668: The arguments has changed of main functions for each command
15405 · #3893: Unknown html_theme_options throw warnings instead of errors
15407 · #3927: Python parameter/variable types should match classes, not all
15409 objects
15410 · #3962: sphinx-apidoc now recognizes given directory as an implicit
15412 namespace package when --implicit-namespaces option given, not subdi‐
15413 rectories of given directory.
15414 · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
15416 · #4226: apidoc: Generate new style makefile (make-mode)
15418 · #4274: sphinx-build returns 2 as an exit code on argument error
15420 · #4389: output directory will be created after loading extensions
15422 · autodoc does not generate warnings messages to the generated document
15424 even if keep_warnings is True. They are only emitted to stderr.
15425 · shebang line is removed from generated conf.py
15427 · #2557: autodoc: autodoc_mock_imports only mocks specified modules
15429 with their descendants. It does not mock their ancestors. If you
15430 want to mock them, please specify the name of ancestors explicitly.
15431 · #3620: html theme: move DOCUMENTATION_OPTIONS to independent
15433 JavaScript file (refs: #4295)
15434 · #4246: Limit width of text body for all themes. Conifigurable via
15436 theme options body_min_width and body_max_width.
15437 · #4771: apidoc: The exclude_patterns arguments are ignored if they are
15439 placed just after command line options
15440 1.7.0b2
15442 · #4467: html theme: Rename csss block to css
15444 Deprecated
15446 1.7.0b1
15447 · using a string value for html_sidebars is deprecated and only list
15449 values will be accepted at 2.0.
15450 · format_annotation() and formatargspec() is deprecated. Please use
15452 sphinx.util.inspect.Signature instead.
15453 · sphinx.ext.autodoc.AutodocReporter is replaced by sphinx.util.docu‐
15455 tils. switch_source_input() and now deprecated. It will be removed
15456 in Sphinx-2.0.
15457 · sphinx.ext.autodoc.add_documenter() and AutoDirective._register is
15459 now deprecated. Please use app.add_autodocumenter() instead.
15460 · AutoDirective._special_attrgetters is now deprecated. Please use
15462 app.add_autodoc_attrgetter() instead.
15463 Features added
15465 1.7.0b1
15466 · C++, handle decltype(auto).
15468 · #2406: C++, add proper parsing of expressions, including linking of
15470 identifiers.
15471 · C++, add a cpp:expr role for inserting inline C++ expressions or
15473 types.
15474 · C++, support explicit member instantiations with shorthand template
15476 prefix.
15477 · C++, make function parameters linkable, like template params.
15479 · #3638: Allow to change a label of reference to equation using
15481 math_eqref_format
15482 · Now suppress_warnings accepts following configurations:
15484 · ref.python (ref: #3866)
15486 · #3872: Add latex key to configure literal blocks caption position in
15488 PDF output (refs #3792, #1723)
15489 · In case of missing docstring try to retrieve doc from base classes
15491 (ref: #3140)
15492 · #4023: Clarify error message when any role has more than one target.
15494 · #3973: epub: allow to override build date
15496 · #3972: epub: Sort manifest entries by filename
15498 · #4052: viewcode: Sort before highlighting module code
15500 · #1448: qthelp: Add new config value; qthelp_namespace
15502 · #4140: html themes: Make body tag inheritable
15504 · #4168: improve zh search with jieba
15506 · HTML themes can set up default sidebars through theme.conf
15508 · #3160: html: Use <kdb> to represent :kbd: role
15510 · #4212: autosummary: catch all exceptions when importing modules
15512 · #4166: Add math_numfig for equation numbering by section (refs:
15514 #3991, #4080). Thanks to Oliver Jahn.
15515 · #4311: Let LaTeX obey numfig_secnum_depth for figures, tables, and
15517 code-blocks
15518 · #947: autodoc now supports ignore-module-all to ignore a module’s
15520 __all__
15521 · #4332: Let LaTeX obey math_numfig for equation numbering
15523 · #4093: sphinx-build creates empty directories for unknown tar‐
15525 gets/builders
15526 · Add top-classes option for the sphinx.ext.inheritance_diagram exten‐
15528 sion to limit the scope of inheritance graphs.
15529 · #4183: doctest: :pyversion: option also follows PEP-440 specification
15531 · #4235: html: Add manpages_url to make manpage roles to hyperlinks
15533 · #3570: autodoc: Do not display ‘typing.’ module for type hints
15535 · #4354: sphinx-build now emits finish message. Builders can modify it
15537 through Builder.epilog attribute
15538 · #4245: html themes: Add language to javascript vars list
15540 · #4079: html: Add notranslate class to each code-blocks, literals and
15542 maths to let Google Translate know they are not translatable
15543 · #4137: doctest: doctest block is always highlighted as python console
15545 (pycon)
15546 · #4137: doctest: testcode block is always highlighted as python
15548 · #3998: text: Assign section numbers by default. You can control it
15550 using text_add_secnumbers and text_secnumber_suffix
15551 1.7.0b2
15553 · #4271: sphinx-build supports an option called -j auto to adjust num‐
15555 bers of processes automatically.
15556 Features removed
15558 1.7.0b1
15559 · Configuration variables
15561 · html_use_smartypants
15563 · latex_keep_old_macro_names
15565 · latex_elements[‘footer’]
15567 · utility methods of sphinx.application.Sphinx class
15569 · buildername (property)
15571 · _display_chunk()
15573 · old_status_iterator()
15575 · status_iterator()
15577 · _directive_helper()
15579 · utility methods of sphinx.environment.BuildEnvironment class
15581 · currmodule (property)
15583 · currclass (property)
15585 · epub2 builder
15587 · prefix and colorfunc parameter for warn()
15589 · sphinx.util.compat module
15591 · sphinx.util.nodes.process_only_nodes()
15593 · LaTeX environment notice, use sphinxadmonition instead
15595 · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
15597 · C++, support of function concepts. Thanks to mickk-on-cpp.
15599 · Not used and previously not documented LaTeX macros \shortversion and
15601 \setshortversion
15602 Bugs fixed
15604 1.7.0b1
15605 · #3882: Update the order of files for HTMLHelp and QTHelp
15607 · #3962: sphinx-apidoc does not recognize implicit namespace packages
15609 correctly
15610 · #4094: C++, allow empty template argument lists.
15612 · C++, also hyperlink types in the name of declarations with qualified
15614 names.
15615 · C++, do not add index entries for declarations inside concepts.
15617 · C++, support the template disambiguator for dependent names.
15619 · #4314: For PDF ‘howto’ documents, numbering of code-blocks differs
15621 from the one of figures and tables
15622 · #4330: PDF ‘howto’ documents have an incoherent default LaTeX
15624 tocdepth counter setting
15625 · #4198: autosummary emits multiple ‘autodoc-process-docstring’ event.
15627 Thanks to Joel Nothman.
15628 · #4081: Warnings and errors colored the same when building
15630 · latex: Do not display ‘Release’ label if release is not set
15632 1.7.0b2
15634 · #4415: autodoc classifies inherited classmethods as regular methods
15636 · #4415: autodoc classifies inherited staticmethods as regular methods
15638 · #4472: DOCUMENTATION_OPTIONS is not defined
15640 · #4491: autodoc: prefer _MockImporter over other importers in
15642 sys.meta_path
15643 · #4490: autodoc: type annotation is broken with python 3.7.0a4+
15645 · utils package is no longer installed
15647 · #3952: apidoc: module header is too escaped
15649 · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
15651 · #4493: recommonmark raises AttributeError if AutoStructify enabled
15653 · #4209: intersphinx: In link title, “v” should be optional if target
15655 has no version
15656 · #4230: slowdown in writing pages with sphinx 1.6
15658 · #4522: epub: document is not rebuilt even if config changed
15660 1.7.0b3
15662 · #4019: inheritance_diagram AttributeError stoping make process
15664 · #4531: autosummary: methods are not treated as attributes
15666 · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
15668 · #4539: autodoc emits warnings for partialmethods
15670 · #4223: doctest: failing tests reported in wrong file, at wrong line
15672 · i18n: message catalogs are not compiled if specific filenames are
15674 given for sphinx-build as arguments (refs: #4560)
15675 · #4027: sphinx.ext.autosectionlabel now expects labels to be the same
15677 as they are in the raw source; no smart quotes, nothig fancy.
15678 · #4581: apidoc: Excluded modules still included
15680 Testing
15682 1.7.0b1
15683 · Add support for docutils 0.14
15685 · Add tests for the sphinx.ext.inheritance_diagram extension.
15687 Release 1.6.7 (released Feb 04, 2018)
15689 Bugs fixed
15690 · #1922: html search: Upper characters problem in French
15691 · #4412: Updated jQuery version from 3.1.0 to 3.2.1
15693 · #4438: math: math with labels with whitespace cause html error
15695 · #2437: make full reference for classes, aliased with “alias of”
15697 · #4434: pure numbers as link targets produce warning
15699 · #4477: Build fails after building specific files
15701 · #4449: apidoc: include “empty” packages that contain modules
15703 · #3917: citation labels are tranformed to ellipsis
15705 · #4501: graphviz: epub3 validation error caused if graph is not click‐
15707 able
15708 · #4514: graphviz: workaround for wrong map ID which graphviz generates
15710 · #4525: autosectionlabel does not support parallel build
15712 · #3953: Do not raise warning when there is a working intersphinx
15714 inventory
15715 · #4487: math: ValueError is raised on parallel build. Thanks to
15717 jschueller.
15718 · #2372: autosummary: invalid signatures are shown for type annotated
15720 functions
15721 · #3942: html: table is not aligned to center even if :align: center
15723 Release 1.6.6 (released Jan 08, 2018)
15725 Features added
15726 · #4181: autodoc: Sort dictionary keys when possible
15727 · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
15729 · Easier customizability of LaTeX macros involved in rendering of
15731 code-blocks
15732 · Show traceback if conf.py raises an exception (refs: #4369)
15734 · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
15736 · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
15738 Bugs fixed
15740 · #4334: sphinx-apidoc: Don’t generate references to non-existing files
15741 in TOC
15742 · #4206: latex: reST label between paragraphs loses paragraph break
15744 · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
15746 · #4221: napoleon depends on autodoc, but users need to load it manu‐
15748 ally
15749 · #2298: automodule fails to document a class attribute
15751 · #4099: C++: properly link class reference to class from inside con‐
15753 structor
15754 · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
15756 · #4249: PDF output: Pygments error highlighting increases line spacing
15758 in code blocks
15759 · #1238: Support :emphasize-lines: in PDF output
15761 · #4279: Sphinx crashes with pickling error when run with multiple pro‐
15763 cesses and remote image
15764 · #1421: Respect the quiet flag in sphinx-quickstart
15766 · #4281: Race conditions when creating output directory
15768 · #4315: For PDF ‘howto’ documents, latex_toplevel_sectioning='part'
15770 generates \chapter commands
15771 · #4214: Two todolist directives break sphinx-1.6.5
15773 · Fix links to external option docs with intersphinx (refs: #3769)
15775 · #4091: Private members not documented without :undoc-members:
15777 Release 1.6.5 (released Oct 23, 2017)
15779 Features added
15780 · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
15781 · #4112: Don’t override the smart_quotes setting if it was already set
15783 · #4125: Display reference texts of original and translated passages on
15785 i18n warning message
15786 · #4147: Include the exception when logging PO/MO file read/write
15788 Bugs fixed
15790 · #4085: Failed PDF build from image in parsed-literal using :align:
15791 option
15792 · #4100: Remove debug print from autodoc extension
15794 · #3987: Changing theme from alabaster causes HTML build to fail
15796 · #4096: C++, don’t crash when using the wrong role type. Thanks to
15798 mitya57.
15799 · #4070, #4111: crashes when the warning message contains format
15801 strings (again)
15802 · #4108: Search word highlighting breaks SVG images
15804 · #3692: Unable to build HTML if writing .buildinfo failed
15806 · #4152: HTML writer crashes if a field list is placed on top of the
15808 document
15809 · #4063: Sphinx crashes when labeling directive .. todolist::
15811 · #4134: [doc] docutils.conf is not documented explicitly
15813 · #4169: Chinese language doesn’t trigger Chinese search automatically
15815 · #1020: ext.todo todolist not linking to the page in pdflatex
15817 · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
15819 · #3739: :module: option is ignored at content of pyobjects
15821 · #4149: Documentation: Help choosing latex_engine
15823 · #4090: [doc] latex_additional_files with extra LaTeX macros should
15825 not use .tex extension
15826 · Failed to convert reST parser error to warning (refs: #4132)
15828 Release 1.6.4 (released Sep 26, 2017)
15830 Features added
15831 · #3926: Add autodoc_warningiserror to suppress the behavior of -W
15832 option during importing target modules on autodoc
15833 Bugs fixed
15835 · #3924: docname lost after dynamically parsing RST in extension
15836 · #3946: Typo in sphinx.sty (this was a bug with no effect in default
15838 context)
15839 ·
15841 pep and :rfc: does not supports default-role directive (refs:
15843 #3960)
15844 · #3960: default_role = ‘guilabel’ not functioning
15846 · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
15848 dows.
15849 · #4026: nature: Fix macOS Safari scrollbar color
15851 · #3877: Fix for C++ multiline signatures.
15853 · #4006: Fix crash on parallel build
15855 · #3969: private instance attributes causes AttributeError
15857 · #4041: C++, remove extra name linking in function pointers.
15859 · #4038: C, add missing documentation of member role.
15861 · #4044: An empty multicolumn cell causes extra row height in PDF out‐
15863 put
15864 · #4049: Fix typo in output of sphinx-build -h
15866 · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
15868 · Avoid indent after index entries in latex (refs: #4066)
15870 · #4070: crashes when the warning message contains format strings
15872 · #4067: Return non-zero exit status when make subprocess fails
15874 · #4055: graphviz: the :align: option does not work for SVG output
15876 · #4055: graphviz: the :align: center option does not work for latex
15878 output
15879 · #4051: warn() function for HTML theme outputs ‘None’ string
15881 Release 1.6.3 (released Jul 02, 2017)
15883 Features added
15884 · latex: hint that code-block continues on next page (refs: #3764,
15885 #3792)
15886 Bugs fixed
15888 · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
15889 · #3829: sphinx-quickstart template is incomplete regarding use of
15891 alabaster
15892 · #3772: ‘str object’ has no attribute ‘filename’
15894 · Emit wrong warnings if citation label includes hyphens (refs: #3565)
15896 · #3858: Some warnings are not colored when using –color option
15898 · #3775: Remove unwanted whitespace in default template
15900 · #3835: sphinx.ext.imgmath fails to convert SVG images if project
15902 directory name contains spaces
15903 · #3850: Fix color handling in make mode’s help command
15905 · #3865: use of self.env.warn in sphinx extension fails
15907 · #3824: production lists apply smart quotes transform since Sphinx
15909 1.6.1
15910 · latex: fix \sphinxbfcode swallows initial space of argument
15912 · #3878: Quotes in auto-documented class attributes should be straight
15914 quotes in PDF output
15915 · #3881: LaTeX figure floated to next page sometimes leaves extra ver‐
15917 tical whitespace
15918 · #3885: duplicated footnotes raises IndexError
15920 · #3873: Failure of deprecation warning mechanism of sphinx.util.com‐
15922 pat.Directive
15923 · #3874: Bogus warnings for “citation not referenced” for cross-file
15925 citations
15926 · #3860: Don’t download images when builders not supported images
15928 · #3860: Remote image URIs without filename break builders not sup‐
15930 ported remote images
15931 · #3833: command line messages are translated unintentionally with lan‐
15933 guage setting.
15934 · #3840: make checking epub_uid strict
15936 · #3851, #3706: Fix about box drawing characters for PDF output
15938 · #3900: autosummary could not find methods
15940 · #3902: Emit error if latex_documents contains non-unicode string in
15942 py2
15943 Release 1.6.2 (released May 28, 2017)
15945 Incompatible changes
15946 · #3789: Do not require typing module for python>=3.5
15947 Bugs fixed
15949 · #3754: HTML builder crashes if HTML theme appends own stylesheets
15950 · #3756: epub: Entity ‘mdash’ not defined
15952 · #3758: Sphinx crashed if logs are emitted in conf.py
15954 · #3755: incorrectly warns about dedent with literalinclude
15956 · #3742: RTD PDF builds of Sphinx own docs are missing an index entry
15958 in the bookmarks and table of contents. This is
15959 rtfd/readthedocs.org#2857 issue, a workaround is obtained using some
15960 extra LaTeX code in Sphinx’s own conf.py
15961 · #3770: Build fails when a “code-block” has the option emphasize-lines
15963 and the number indicated is higher than the number of lines
15964 · #3774: Incremental HTML building broken when using citations
15966 · #3763: got epubcheck validations error if epub_cover is set
15968 · #3779: ‘ImportError’ in sphinx.ext.autodoc due to broken
15970 ‘sys.meta_path’. Thanks to Tatiana Tereshchenko.
15971 · #3796: env.resolve_references() crashes when non-document node given
15973 · #3803: Sphinx crashes with invalid PO files
15975 · #3791: PDF “continued on next page” for long tables isn’t interna‐
15977 tionalized
15978 · #3788: smartquotes emits warnings for unsupported languages
15980 · #3807: latex Makefile for make latexpdf is only for unixen
15982 · #3781: double hyphens in option directive are compiled as endashes
15984 · #3817: latex builder raises AttributeError
15986 Release 1.6.1 (released May 16, 2017)
15988 Dependencies
15989 1.6b1
15990 · (updated) latex output is tested with Ubuntu trusty’s texlive pack‐
15992 ages (Feb. 2014) and earlier tex installations may not be fully com‐
15993 pliant, particularly regarding Unicode engines xelatex and lualatex
15994 · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
15996 X (refs: #3082)
15997 Incompatible changes
15999 1.6b1
16000 · #1061, #2336, #3235: Now generation of autosummary doesn’t contain
16002 imported members by default. Thanks to Luc Saffre.
16003 · LaTeX \includegraphics command isn’t overloaded: only \sphinxinclude‐
16005 graphics has the custom code to fit image to available width if over‐
16006 sized.
16007 · The subclasses of sphinx.domains.Index should override generate()
16009 method. The default implementation raises NotImplementedError
16010 · LaTeX positioned long tables horizontally centered, and short ones
16012 flushed left (no text flow around table.) The position now defaults
16013 to center in both cases, and it will obey Docutils 0.13 :align:
16014 option (refs #3415, #3377)
16015 · option directive also allows all punctuations for the option name
16017 (refs: #3366)
16018 · #3413: if literalinclude’s :start-after: is used, make :lines: rela‐
16020 tive (refs #3412)
16021 · literalinclude directive does not allow the combination of :diff:
16023 option and other options (refs: #3416)
16024 · LuaLaTeX engine uses fontspec like XeLaTeX. It is advised
16026 latex_engine = 'lualatex' be used only on up-to-date TeX installs
16027 (refs #3070, #3466)
16028 · latex_keep_old_macro_names default value has been changed from True
16030 to False. This means that some LaTeX macros for styling are by
16031 default defined only with \sphinx.. prefixed names. (refs: #3429)
16032 · Footer “Continued on next page” of LaTeX longtable’s now not framed
16034 (refs: #3497)
16035 · #3529: The arguments of BuildEnvironment.__init__ is changed
16037 · #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms
16039 only)
16040 · #3558: Emit warnings if footnotes and citations are not referenced.
16042 The warnings can be suppressed by suppress_warnings.
16043 · latex made available (non documented) colour macros from a file dis‐
16045 tributed with pdftex engine for Plain TeX. This is removed in order
16046 to provide better support for multiple TeX engines. Only interface
16047 from color or xcolor packages should be used by extensions of Sphinx
16048 latex writer. (refs #3550)
16049 · Builder.env is not filled at instantiation
16051 · #3594: LaTeX: single raw directive has been considered as block level
16053 element
16054 · #3639: If html_experimental_html5_writer is available, epub builder
16056 use it by default.
16057 · Sphinx.add_source_parser() raises an error if duplicated
16059 1.6b2
16061 · #3345: Replace the custom smartypants code with Docutils’
16063 smart_quotes. Thanks to Dmitry Shachnev, and to Günter Milde at
16064 Docutils.
16065 1.6b3
16067 · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
16069 · LaTeX package multirow is not used and not loaded by Sphinx anymore
16071 · Add line numbers to citation data in std domain
16073 1.6 final
16075 · LaTeX package threeparttable is not used and not loaded by Sphinx
16077 anymore (refs #3686, #3532, #3377)
16078 Features removed
16080 · Configuration variables
16081 · epub3_contributor
16083 · epub3_description
16085 · epub3_page_progression_direction
16087 · html_translator_class
16089 · html_use_modindex
16091 · latex_font_size
16093 · latex_paper_size
16095 · latex_preamble
16097 · latex_use_modindex
16099 · latex_use_parts
16101 · termsep node
16103 · defindex.html template
16105 · LDML format support in today, today_fmt and html_last_updated_fmt
16107 · :inline: option for the directives of sphinx.ext.graphviz extension
16109 · sphinx.ext.pngmath extension
16111 · sphinx.util.compat.make_admonition()
16113 Features added
16115 1.6b1
16116 · #3136: Add :name: option to the directives in sphinx.ext.graphviz
16118 · #2336: Add imported_members option to sphinx-autogen command to docu‐
16120 ment imported members.
16121 · C++, add :tparam-line-spec: option to templated declarations. When
16123 specified, each template parameter will be rendered on a separate
16124 line.
16125 · #3359: Allow sphinx.js in a user locale dir to override sphinx.js
16127 from Sphinx
16128 · #3303: Add :pyversion: option to the doctest directive.
16130 · #3378: (latex) support for :widths: option of table directives (refs:
16132 #3379, #3381)
16133 · #3402: Allow to suppress “download file not readable” warnings using
16135 suppress_warnings.
16136 · #3377: latex: Add support for Docutils 0.13 :align: option for tables
16138 (but does not implement text flow around table).
16139 · latex: footnotes from inside tables are hyperlinked (except from cap‐
16141 tions or headers) (refs: #3422)
16142 · Emit warning if over dedent has detected on literalinclude directive
16144 (refs: #3416)
16145 · Use for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
16147 and polyglossia). (refs: #3070, #3466)
16148 · Make 'extraclassoptions' key of latex_elements public (refs #3480)
16150 · #3463: Add warning messages for required EPUB3 metadata. Add default
16152 value to epub_description to avoid warning like other settings.
16153 · #3476: setuptools: Support multiple builders
16155 · latex: merged cells in LaTeX tables allow code-blocks, lists, block‐
16157 quotes… as do normal cells (refs: #3435)
16158 · HTML builder uses experimental HTML5 writer if html_experimen‐
16160 tal_html5_writer is True and docutils 0.13 or later is installed.
16161 · LaTeX macros to customize space before and after tables in PDF output
16163 (refs #3504)
16164 · #3348: Show decorators in literalinclude and viewcode directives
16166 · #3108: Show warning if :start-at: and other literalinclude options
16168 does not match to the text
16169 · #3609: Allow to suppress “duplicate citation” warnings using sup‐
16171 press_warnings
16172 · #2803: Discovery of builders by entry point
16174 · #1764, #1676: Allow setting ‘rel’ and ‘title’ attributes for
16176 stylesheets
16177 · #3589: Support remote images on non-HTML builders
16179 · #3589: Support images in Data URI on non-HTML builders
16181 · #2961: improve autodoc_mock_imports. Now the config value only
16183 requires to declare the top-level modules that should be mocked.
16184 Thanks to Robin Jarry.
16185 · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
16187 ture calculation. Thanks to Nathaniel J. Smith.
16188 · #3641: Epub theme supports HTML structures that are generated by
16190 HTML5 writer.
16191 · #3644 autodoc uses inspect instead of checking types. Thanks to
16193 Jeroen Demeyer.
16194 · Add a new extension; sphinx.ext.imgconverter. It converts images in
16196 the document to appropriate format for builders
16197 · latex: Use templates to render tables (refs #3389, 2a37b0e)
16199 1.6b2
16201 · LATEXMKOPTS variable for the Makefile in $BUILDDIR/latex to pass
16203 options to latexmk when executing make latexpdf (refs #3695, #3720)
16204 · Add a new event env-check-consistency to check consistency to exten‐
16206 sions
16207 · Add Domain.check_consistency() to check consistency
16209 Bugs fixed
16211 1.6b1
16212 · literalinclude directive expands tabs after dedent-ing (refs: #3416)
16214 · #1574: Paragraphs in table cell doesn’t work in Latex output
16216 · #3288: Table with merged headers not wrapping text
16218 · #3491: Inconsistent vertical space around table and longtable in PDF
16220 · #3506: Depart functions for all admonitions in HTML writer now prop‐
16222 erly pass node to depart_admonition.
16223 · #2693: Sphinx latex style file wrongly inhibits colours for section
16225 headings for latex+dvi(ps,pdf,pdfmx)
16226 · C++, properly look up any references.
16228 · #3624: sphinx.ext.intersphinx couldn’t load inventories compressed
16230 with gzip
16231 · #3551: PDF information dictionary is lacking author and title data
16233 · #3351: intersphinx does not refers context like py:module, py:class
16235 and so on.
16236 · Fail to load template file if the parent template is archived
16238 1.6b2
16240 · #3661: sphinx-build crashes on parallel build
16242 · #3669: gettext builder fails with “ValueError: substring not found”
16244 · #3660: Sphinx always depends on sphinxcontrib-websupport and its
16246 dependencies
16247 · #3472: smart quotes getting wrong in latex (at least with list of
16249 strings via autoattribute) (refs: #3345, #3666)
16250 1.6b3
16252 · #3588: No compact (p tag) html output in the i18n document build even
16254 when html_compact_lists is True.
16255 · The make latexpdf from 1.6b1 (for GNU/Linux and Mac OS, using
16257 latexmk) aborted earlier in case of LaTeX errors than was the case
16258 with 1.5 series, due to hard-coded usage of --halt-on-error option.
16259 (refs #3695)
16260 · #3683: sphinx.websupport module is not provided by default
16262 · #3683: Failed to build document if builder.css_file.insert() is
16264 called
16265 · #3714: viewcode extension not taking highlight_code='none' in account
16267 · #3698: Moving :doc: to std domain broke backwards compatibility
16269 · #3633: misdetect unreferenced citations
16271 1.6 final
16273 · LaTeX tables do not allow multiple paragraphs in a header cell
16275 · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
16277 · #3532: Figure or literal block captions in cells of short tables
16279 cause havoc in PDF output
16280 · Fix: in PDF captions of tables are rendered differently whether table
16282 is of longtable class or not (refs #3686)
16283 · #3725: Todo looks different from note in LaTeX output
16285 · #3479: stub-columns have no effect in LaTeX output
16287 · #3738: Nonsensical code in theming.py
16289 · #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
16291 options -pdfxe and -pdflua
16292 Deprecated
16294 1.6b1
16295 · sphinx.util.compat.Directive class is now deprecated. Please use
16297 instead docutils.parsers.rst.Directive
16298 · sphinx.util.compat.docutils_version is now deprecated
16300 · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
16302 deprecated. Please use sphinx.util.logging (logging-api) instead.
16303 · #3318: notice is now deprecated as LaTeX environment name and will be
16305 removed at Sphinx 1.7. Extension authors please use sphinxadmonition
16306 instead (as Sphinx does since 1.5.)
16307 · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
16309 recated. Please use sphinx.util:status_iterator() instead.
16310 · Sphinx._directive_helper() is deprecated. Please use
16312 sphinx.util.docutils.directive_helper() instead.
16313 · BuildEnvironment.set_warnfunc() is now deprecated
16315 · Following methods of BuildEnvironment is now deprecated.
16317 · BuildEnvironment.note_toctree()
16319 · BuildEnvironment.get_toc_for()
16321 · BuildEnvironment.get_toctree_for()
16323 · BuildEnvironment.create_index()
16325 Please use sphinx.environment.adapters modules instead.
16327 · latex package footnote is not loaded anymore by its bundled replace‐
16329 ment footnotehyper-sphinx. The redefined macros keep the same names
16330 as in the original package.
16331 · #3429: deprecate config setting latex_keep_old_macro_names. It will
16333 be removed at 1.7, and already its default value has changed from
16334 True to False.
16335 · #3221: epub2 builder is deprecated
16337 · #3254: sphinx.websupport is now separated into independent package;
16339 sphinxcontrib-websupport. sphinx.websupport will be removed in
16340 Sphinx-2.0.
16341 · #3628: sphinx_themes entry_point is deprecated. Please use
16343 sphinx.html_themes instead.
16344 1.6b2
16346 · #3662: builder.css_files is deprecated. Please use add_stylesheet()
16348 API instead.
16349 1.6 final
16351 · LaTeX \sphinxstylethead is deprecated at 1.6 and will be removed at
16353 1.7. Please move customization into new macro \sphinxstyletheadfam‐
16354 ily.
16355 Testing
16357 1.6 final
16358 · #3458: Add sphinx.testing (experimental)
16360 Release 1.6 (unreleased)
16362 · not released (because of package script error)
16363 Release 1.5.6 (released May 15, 2017)
16365 Bugs fixed
16366 · #3614: Sphinx crashes with requests-2.5.0
16367 · #3618: autodoc crashes with tupled arguments
16369 · #3664: No space after the bullet in items of a latex list produced by
16371 Sphinx
16372 · #3657: EPUB builder crashes if document startswith genindex exists
16374 · #3588: No compact (p tag) html output in the i18n document build even
16376 when html_compact_lists is True.
16377 · #3685: AttributeError when using 3rd party domains
16379 · #3702: LaTeX writer styles figure legends with a hard-coded \small
16381 · #3708: LaTeX writer allows irc scheme
16383 · #3717: Stop enforcing that favicon’s must be .ico
16385 · #3731, #3732: Protect isenumclass predicate against non-class argu‐
16387 ments
16388 · #3320: Warning about reference target not being found for container
16390 types
16391 · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
16393 Release 1.5.5 (released Apr 03, 2017)
16395 Bugs fixed
16396 · #3597: python domain raises UnboundLocalError if invalid name given
16397 · #3599: Move to new Mathjax CDN
16399 Release 1.5.4 (released Apr 02, 2017)
16401 Features added
16402 · #3470: Make genindex support all kinds of letters, not only Latin
16403 ones
16404 Bugs fixed
16406 · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc} leads
16407 to failed PDF build
16408 · EPUB file has duplicated nav.xhtml link in content.opf except first
16410 time build
16411 · #3488: objects.inv has broken when release or version contain return
16413 code
16414 · #2073, #3443, #3490: gettext builder that writes pot files unless the
16416 content are same without creation date. Thanks to Yoshiki Shibukawa.
16417 · #3487: intersphinx: failed to refer options
16419 · #3496: latex longtable’s last column may be much wider than its con‐
16421 tents
16422 · #3507: wrong quotes in latex output for productionlist directive
16424 · #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
16426 links rendered as code
16427 · #2665, #2607: Link names in C++ docfields, and make it possible for
16429 other domains.
16430 · #3542: C++, fix parsing error of non-type template argument with tem‐
16432 plate.
16433 · #3065, #3520: python domain fails to recognize nested class
16435 · #3575: Problems with pdflatex in a Turkish document built with sphinx
16437 has reappeared (refs #2997, #2397)
16438 · #3577: Fix intersphinx debug tool
16440 · A LaTeX command such as \\large inserted in the title items of
16442 latex_documents causes failed PDF build (refs #3551, #3567)
16443 Release 1.5.3 (released Feb 26, 2017)
16445 Features added
16446 · Support requests-2.0.0 (experimental) (refs: #3367)
16447 · (latex) PDF page margin dimensions may be customized (refs: #3387)
16449 · literalinclude directive allows combination of :pyobject: and :lines:
16451 options (refs: #3416)
16452 · #3400: make-mode doesn’t use subprocess on building docs
16454 Bugs fixed
16456 · #3370: the caption of code-block is not picked up for translation
16457 · LaTeX: release is not escaped (refs: #3362)
16459 · #3364: sphinx-quickstart prompts overflow on Console with 80 chars
16461 width
16462 · since 1.5, PDF’s TOC and bookmarks lack an entry for general Index
16464 (refs: #3383)
16465 · #3392: 'releasename' in latex_elements is not working
16467 · #3356: Page layout for Japanese 'manual' docclass has a shorter text
16469 area
16470 · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document gets
16472 wrong PDF page dimensions
16473 · #3399: quickstart: conf.py was not overwritten by template
16475 · #3366: option directive does not allow punctuations
16477 · #3410: return code in release breaks html search
16479 · #3427: autodoc: memory addresses are not stripped on Windows
16481 · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
16483 · #3349: Result of IndexBuilder.load() is broken
16485 · #3450:   is appeared in EPUB docs
16487 · #3418: Search button is misaligned in nature and pyramid theme
16489 · #3421: Could not translate a caption of tables
16491 · #3552: linkcheck raises UnboundLocalError
16493 Release 1.5.2 (released Jan 22, 2017)
16495 Incompatible changes
16496 · Dependency requirement updates: requests 2.4.0 or above (refs: #3268,
16497 #3310)
16498 Features added
16500 · #3241: emit latex warning if buggy titlesec (ref #3210)
16501 · #3194: Refer the $MAKE environment variable to determine make command
16503 · Emit warning for nested numbered toctrees (refs: #3142)
16505 · #978: intersphinx_mapping also allows a list as a parameter
16507 · #3340: (LaTeX) long lines in parsed-literal are wrapped like in
16509 code-block, inline math and footnotes are fully functional.
16510 Bugs fixed
16512 · #3246: xapian search adapter crashes
16513 · #3253: In Py2 environment, building another locale with a non-cap‐
16515 tioned toctree produces None captions
16516 · #185: References to section title including raw node has broken
16518 · #3255: In Py3.4 environment, autodoc doesn’t support documentation
16520 for attributes of Enum class correctly.
16521 · #3261: latex_use_parts makes sphinx crash
16523 · The warning type misc.highlighting_failure does not work
16525 · #3294: add_latex_package() make crashes non-LaTeX builders
16527 · The caption of table are rendered as invalid HTML (refs: #3287)
16529 · #3268: Sphinx crashes with requests package from Debian jessie
16531 · #3284: Sphinx crashes on parallel build with an extension which
16533 raises unserializable exception
16534 · #3315: Bibliography crashes on latex build with docclass ‘memoir’
16536 · #3328: Could not refer rubric implicitly
16538 · #3329: emit warnings if po file is invalid and can’t read it. Also
16540 writing mo too
16541 · #3337: Ugly rendering of definition list term’s classifier
16543 · #3335: gettext does not extract field_name of a field in a field_list
16545 · #2952: C++, fix refs to operator() functions.
16547 · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
16549 eral LaTeX output (ref #3342)
16550 · LaTeX writer: leave " character inside parsed-literal as is (ref
16552 #3341)
16553 · #3234: intersphinx failed for encoded inventories
16555 · #3158: too much space after captions in PDF output
16557 · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
16559 if with hyphen
16560 · LaTeX crash if the filename of an image inserted in parsed-literal
16562 via a substitution contains an hyphen (ref #3340)
16563 · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
16565 #3340)
16566 · Inline math in parsed-literal is not rendered well by LaTeX (ref
16568 #3340)
16569 · #3308: Parsed-literals don’t wrap very long lines with pdf builder
16571 (ref #3340)
16572 · #3295: Could not import extension sphinx.builders.linkcheck
16574 · #3285: autosummary: asterisks are escaped twice
16576 · LaTeX, pass dvipdfm option to geometry package for Japanese documents
16578 (ref #3363)
16579 · Fix parselinenos() could not parse left half open range (cf. “-4”)
16581 Release 1.5.1 (released Dec 13, 2016)
16583 Features added
16584 · #3214: Allow to suppress “unknown mimetype” warnings from epub
16585 builder using suppress_warnings.
16586 Bugs fixed
16588 · #3195: Can not build in parallel
16589 · #3198: AttributeError is raised when toctree has ‘self’
16591 · #3211: Remove untranslated sphinx locale catalogs (it was covered by
16593 untranslated it_IT)
16594 · #3212: HTML Builders crashes with docutils-0.13
16596 · #3207: more latex problems with references inside parsed-literal
16598 directive (\DUrole)
16599 · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
16601 · #3220: KeyError when having a duplicate citation
16603 · #3200: LaTeX: xref inside desc_name not allowed
16605 · #3228: build_sphinx command crashes when missing dependency
16607 · #2469: Ignore updates of catalog files for gettext builder. Thanks to
16609 Hiroshi Ohkubo.
16610 · #3183: Randomized jump box order in generated index page.
16612 Release 1.5 (released Dec 5, 2016)
16614 Incompatible changes
16615 1.5a1
16616 · latex, package fancybox is not longer a dependency of sphinx.sty
16618 · Use 'locales' as a default value of locale_dirs
16620 · latex, package ifthen is not any longer a dependency of sphinx.sty
16622 · latex, style file does not modify fancyvrb’s Verbatim (also available
16624 as OriginalVerbatim) but uses sphinxVerbatim for name of custom wrap‐
16625 per.
16626 · latex, package newfloat is not used (and not included) anymore (ref
16628 #2660; it was used since 1.3.4 and shipped with Sphinx since 1.4).
16629 · latex, literal blocks in tables do not use OriginalVerbatim but
16631 sphinxVerbatimintable which handles captions and wraps lines (ref
16632 #2704).
16633 · latex, replace pt by TeX equivalent bp if found in width or height
16635 attribute of an image.
16636 · latex, if width or height attribute of an image is given with no
16638 unit, use px rather than ignore it.
16639 · latex: Separate stylesheets of pygments to independent .sty file
16641 · #2454: The filename of sourcelink is now changed. The value of
16643 html_sourcelink_suffix will be appended to the original filename
16644 (like index.rst.txt).
16645 · sphinx.util.copy_static_entry() is now deprecated. Use
16647 sphinx.util.fileutil.copy_asset() instead.
16648 · sphinx.util.osutil.filecopy() skips copying if the file has not been
16650 changed (ref: #2510, #2753)
16651 · Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
16653 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634,
16654 #2773)
16655 · QtHelpBuilder doens’t generate search page (ref: #2352)
16657 · QtHelpBuilder uses nonav theme instead of default one to improve
16659 readability.
16660 · latex: To provide good default settings to Japanese documents, Sphinx
16662 uses jreport and jsbook as docclass if language is ja.
16663 · sphinx-quickstart now allows a project version is empty
16665 · Fix :download: role on epub/qthelp builder. They ignore the role
16667 because they don’t support it.
16668 · sphinx.ext.viewcode doesn’t work on epub building by default. view‐
16670 code_enable_epub option
16671 · sphinx.ext.viewcode disabled on singlehtml builder.
16673 · Use make-mode of sphinx-quickstart by default. To disable this, use
16675 -M option
16676 · Fix genindex.html, Sphinx’s document template, link address to itself
16678 to satisfy xhtml standard.
16679 · Use epub3 builder by default. And the old epub builder is renamed to
16681 epub2.
16682 · Fix epub and epub3 builders that contained links to genindex even if
16684 epub_use_index = False.
16685 · html_translator_class is now deprecated. Use Sphinx.set_translator()
16687 API instead.
16688 · Drop python 2.6 and 3.3 support
16690 · Drop epub3 builder’s epub3_page_progression_direction option (use
16692 epub3_writing_mode).
16693 · #2877: Rename latex_elements['footer'] to latex_elements['atendof‐
16695 body']
16696 1.5a2
16698 · #2983: Rename epub3_description and epub3_contributor to
16700 epub_description and epub_contributor.
16701 · Remove themes/basic/defindex.html; no longer used
16703 · Sphinx does not ship anymore (but still uses) LaTeX style file fncy‐
16705 chap
16706 · #2435: Slim down quickstarted conf.py
16708 · The sphinx.sty latex package does not load itself “hyperref”, as this
16710 is done later in the preamble of the latex output via 'hyperref' key.
16711 · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
16713 lary. The non-modified package is used.
16714 · #3057: By default, footnote marks in latex PDF output are not pre‐
16716 ceded by a space anymore, \sphinxBeforeFootnote allows user cus‐
16717 tomization if needed.
16718 · LaTeX target requires that option hyperfootnotes of package hyperref
16720 be left unchanged to its default (i.e. true) (refs: #3022)
16721 1.5 final
16723 · #2986: themes/basic/defindex.html is now deprecated
16725 · Emit warnings that will be deprecated in Sphinx 1.6 by default.
16727 Users can change the behavior by setting the environment variable
16728 PYTHONWARNINGS. Please refer when-deprecation-warnings-are-displayed.
16729 · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
16731 Deprecated
16733 These features are removed in Sphinx-1.6:
16734 · LDML format support in i18n feature
16736 · sphinx.addnodes.termsep
16738 · Some functions and classes in sphinx.util.pycompat: zip_longest,
16740 product, all, any, next, open, class_types, base_exception, relpath,
16741 StringIO, BytesIO. Please use the standard library version instead;
16742 If any deprecation warning like RemovedInSphinxXXXWarning are dis‐
16744 played, please refer when-deprecation-warnings-are-displayed.
16745 Features added
16747 1.5a1
16748 · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
16750 · Add :caption: option for sphinx.ext.inheritance_diagram.
16752 · #2471: Add config variable for default doctest flags.
16754 · Convert linkcheck builder to requests for better encoding handling
16756 · #2463, #2516: Add keywords of “meta” directive to search index
16758 · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
16760 · #2575: Now sphinx.ext.graphviz allows :align: option
16762 · Show warnings if unknown key is specified to latex_elements
16764 · Show warnings if no domains match with primary_domain (ref: #2001)
16766 · C++, show warnings when the kind of role is misleading for the kind
16768 of target it refers to (e.g., using the class role for a function).
16769 · latex, writer abstracts more of text styling into customizable
16771 macros, e.g. the visit_emphasis will output \sphinxstyleemphasis
16772 rather than \emph (which may be in use elsewhere or in an added LaTeX
16773 package). See list at end of sphinx.sty (ref: #2686)
16774 · latex, public names for environments and parameters used by note,
16776 warning, and other admonition types, allowing full customizability
16777 from the 'preamble' key or an input file (ref: feature request #2674,
16778 #2685)
16779 · latex, better computes column widths of some tables (as a result,
16781 there will be slight changes as tables now correctly fill the line
16782 width; ref: #2708)
16783 · latex, sphinxVerbatim environment is more easily customizable (ref:
16785 #2704). In addition to already existing VerbatimColor and Verbatim‐
16786 BorderColor:
16787 · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
16789 · booleans \ifsphinxverbatimwithframe and \ifsphinxverbatimwrap‐
16791 slines.
16792 · latex, captions for literal blocks inside tables are handled, and
16794 long code lines wrapped to fit table cell (ref: #2704)
16795 · #2597: Show warning messages as darkred
16797 · latex, allow image dimensions using px unit (default is 96px=1in)
16799 · Show warnings if invalid dimension units found
16801 · #2650: Add --pdb option to setup.py command
16803 · latex, make the use of \small for code listings customizable (ref
16805 #2721)
16806 · #2663: Add --warning-is-error option to setup.py command
16808 · Show warnings if deprecated latex options are used
16810 · Add sphinx.config.ENUM to check the config values is in candidates
16812 · math: Add hyperlink marker to each equations in HTML output
16814 · Add new theme nonav that doesn’t include any navigation links. This
16816 is for any help generator like qthelp.
16817 · #2680: sphinx.ext.todo now emits warnings if todo_emit_warnings
16819 enabled. Also, it emits an additional event named todo-defined to
16820 handle the TODO entries in 3rd party extensions.
16821 · Python domain signature parser now uses the xref mixin for ‘excep‐
16823 tions’, allowing exception classes to be autolinked.
16824 · #2513: Add latex_engine to switch the LaTeX engine by conf.py
16826 · #2682: C++, basic support for attributes (C++11 style and GNU style).
16828 The new configuration variables ‘cpp_id_attributes’ and
16829 ‘cpp_paren_attributes’ can be used to introduce custom attributes.
16830 · #1958: C++, add configuration variable ‘cpp_index_common_prefix’ for
16832 removing prefixes from the index text of C++ objects.
16833 · C++, added concept directive. Thanks to mickk-on-cpp.
16835 · C++, added support for template introduction syntax. Thanks to
16837 mickk-on-cpp.
16838 · #2725: latex builder: allow to use user-defined template file (exper‐
16840 imental)
16841 · apidoc now avoids invalidating cached files by not writing to files
16843 whose content doesn’t change. This can lead to significant perfor‐
16844 mance wins if apidoc is run frequently.
16845 · #2851: sphinx.ext.math emits missing-reference event if equation not
16847 found
16848 · #1210: eqref role now supports cross reference
16850 · #2892: Added -a (--append-syspath) option to sphinx-apidoc
16852 · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
16854 · #646: option directive support ‘.’ character as a part of options
16856 · Add document about kindlegen and fix document structure for it.
16858 · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
16860 · #2926: EPUB3 builder supports vertical mode (epub3_writing_mode
16862 option)
16863 · #2695: build_sphinx subcommand for setuptools handles exceptions as
16865 same as sphinx-build does
16866 · #326: numref role can also refer sections
16868 · #2916: numref role can also refer caption as an its linktext
16870 1.5a2
16872 · #3008: linkcheck builder ignores self-signed certificate URL
16874 · #3020: new 'geometry' key to latex_elements whose default uses LaTeX
16876 style file geometry.sty to set page layout
16877 · #2843: Add :start-at: and :end-at: options to literalinclude direc‐
16879 tive
16880 · #2527: Add :reversed: option to toctree directive
16882 · Add -t and -d option to sphinx-quickstart to support templating gen‐
16884 erated sphinx project.
16885 · #3028: Add {path} and {basename} to the format of figure_lan‐
16887 guage_filename
16888 · new 'hyperref' key in the latex_elements dictionary (ref #3030)
16890 · #3022: Allow code-blocks in footnotes for LaTeX PDF output
16892 1.5b1
16894 · #2513: A better default settings for XeLaTeX
16896 · #3096: 'maxlistdepth' key to work around LaTeX list limitations
16898 · #3060: autodoc supports documentation for attributes of Enum class.
16900 Now autodoc render just the value of Enum attributes instead of Enum
16901 attribute representation.
16902 · Add --extensions to sphinx-quickstart to support enable arbitrary
16904 extensions from command line (ref: #2904)
16905 · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
16907 · #3071: Autodoc: Allow mocked module decorators to pass-through func‐
16909 tions unchanged
16910 · #2495: linkcheck: Allow skipping anchor checking using
16912 linkcheck_anchors_ignore
16913 · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
16915 · #3116: allow word wrap in PDF output for inline literals (ref #3110)
16917 · #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to
16919 Nick Coghlan.
16920 · #3121: add inlineliteralwraps option to control if inline literal
16922 word-wraps in latex
16923 1.5 final
16925 · #3095: Add tls_verify and tls_cacerts to support self-signed HTTPS
16927 servers in linkcheck and intersphinx
16928 · #2215: make.bat generated by sphinx-quickstart can be called from
16930 another dir. Thanks to Timotheus Kampik.
16931 · #3185: Add new warning type misc.highlighting_failure
16933 Bugs fixed
16935 1.5a1
16936 · #2707: (latex) the column width is badly computed for tabular
16938 · #2799: Sphinx installs roles and directives automatically on import‐
16940 ing sphinx module. Now Sphinx installs them on running application.
16941 · sphinx.ext.autodoc crashes if target code imports * from mock modules
16943 by autodoc_mock_imports.
16944 · #1953: Sphinx.add_node does not add handlers the translator installed
16946 by html_translator_class
16947 · #1797: text builder inserts blank line on top
16949 · #2894: quickstart main() doesn’t use argv argument
16951 · #2874: gettext builder could not extract all text under the only
16953 directives
16954 · #2485: autosummary crashes with multiple source_suffix values
16956 · #1734: Could not translate the caption of toctree directive
16958 · Could not translate the content of meta directive (ref: #1734)
16960 · #2550: external links are opened in help viewer
16962 · #2687: Running Sphinx multiple times produces ‘already registered’
16964 warnings
16965 1.5a2
16967 · #2810: Problems with pdflatex in an Italian document
16969 · Use latex_elements.papersize to specify papersize of LaTeX in Make‐
16971 file
16972 · #2988: linkcheck: retry with GET request if denied HEAD request
16974 · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str implic‐
16976 itly” error if linkcheck_anchors enabled
16977 · #3004: Invalid link types “top” and “up” are used
16979 · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
16981 · #3000: option directive generates invalid HTML anchors
16983 · #2984: Invalid HTML has been generated if html_split_index enabled
16985 · #2986: themes/basic/defindex.html should be changed for html5
16987 friendly
16988 · #2987: Invalid HTML has been generated if multiple IDs are assigned
16990 to a list
16991 · #2891: HTML search does not provide all the results
16993 · #1986: Title in PDF Output
16995 · #147: Problem with latex chapter style
16997 · #3018: LaTeX problem with page layout dimensions and chapter titles
16999 · Fix an issue with \pysigline in LaTeX style file (ref #3023)
17001 · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
17003 · #3031: incompatibility with LaTeX package tocloft
17005 · #3003: literal blocks in footnotes are not supported by Latex
17007 · #3047: spacing before footnote in pdf output is not coherent and
17009 allows breaks
17010 · #3045: HTML search index creator should ignore “raw” content if now
17012 html
17013 · #3039: English stemmer returns wrong word if the word is capitalized
17015 · Fix make-mode Makefile template (ref #3056, #2936)
17017 1.5b1
17019 · #2432: Fix unwanted * between varargs and keyword only args. Thanks
17021 to Alex Grönholm.
17022 · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
17024 panese documents since PR#3030)
17025 · Better rendering of multiline signatures in html.
17027 · #777: LaTeX output “too deeply nested” (ref #3096)
17029 · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
17031 #3059)
17032 · #3019: LaTeX fails on description of C function with arguments (ref
17034 #3083)
17035 · fix latex inline literals where < > - gobbled a space
17037 1.5 final
17039 · #3069: Even if 'babel' key is set to empty string, LaTeX output con‐
17041 tains one \addto\captions...
17042 · #3123: user 'babel' key setting is not obeyed anymore
17044 · #3155: Fix JavaScript for html_sourcelink_suffix fails with IE and
17046 Opera
17047 · #3085: keep current directory after breaking build documentation.
17049 Thanks to Timotheus Kampik.
17050 · #3181: pLaTeX crashes with a section contains endash
17052 · #3180: latex: add stretch/shrink between successive singleline or
17054 multipleline cpp signatures (ref #3072)
17055 · #3128: globing images does not support .svgz file
17057 · #3015: fix a broken test on Windows.
17059 · #1843: Fix documentation of descriptor classes that have a custom
17061 metaclass. Thanks to Erik Bray.
17062 · #3190: util.split_docinfo fails to parse multi-line field bodies
17064 · #3024, #3037: In Python3, application.Sphinx._log crushed when the
17066 log message cannot be encoded into console encoding.
17067 Testing
17069 · To simplify, sphinx uses external mock package even if unittest.mock
17070 exists.
17071 Release 1.4.9 (released Nov 23, 2016)
17073 Bugs fixed
17074 · #2936: Fix doc/Makefile that can’t build man because doc/man exists
17075 · #3058: Using the same ‘caption’ attribute in multiple ‘toctree’
17077 directives results in warning / error
17078 · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
17080 · #3074: add_source_parser() crashes in debug mode
17082 · #3135: sphinx.ext.autodoc crashes with plain Callable
17084 · #3150: Fix query word splitter in JavaScript. It behaves as same as
17086 Python’s regular expression.
17087 · #3093: gettext build broken on substituted images.
17089 · #3093: gettext build broken on image node under note directive.
17091 · imgmath: crashes on showing error messages if image generation failed
17093 · #3117: LaTeX writer crashes if admonition is placed before first sec‐
17095 tion title
17096 · #3164: Change search order of sphinx.ext.inheritance_diagram
17098 Release 1.4.8 (released Oct 1, 2016)
17100 Bugs fixed
17101 · #2996: The wheel package of Sphinx got crash with ImportError
17102 Release 1.4.7 (released Oct 1, 2016)
17104 Bugs fixed
17105 · #2890: Quickstart should return an error consistently on all error
17106 conditions
17107 · #2870: flatten genindex columns’ heights.
17109 · #2856: Search on generated HTML site doesnt find some symbols
17111 · #2882: Fall back to a GET request on 403 status in linkcheck
17113 · #2902: jsdump.loads fails to load search index if keywords starts
17115 with underscore
17116 · #2900: Fix epub content.opf: add auto generated orphan files to
17118 spine.
17119 · #2899: Fix hasdoc() function in Jinja2 template. It can detect genin‐
17121 dex, search collectly.
17122 · #2901: Fix epub result: skip creating links from image tags to origi‐
17124 nal image files.
17125 · #2917: inline code is hyphenated on HTML
17127 · #1462: autosummary warns for namedtuple with attribute with trailing
17129 underscore
17130 · Could not reference equations if :nowrap: option specified
17132 · #2873: code-block overflow in latex (due to commas)
17134 · #1060, #2056: sphinx.ext.intersphinx: broken links are generated if
17136 relative paths are used in intersphinx_mapping
17137 · #2931: code-block directive with same :caption: causes warning of
17139 duplicate target. Now code-block and literalinclude does not define
17140 hyperlink target using its caption automatially.
17141 · #2962: latex: missing label of longtable
17143 · #2968: autodoc: show-inheritance option breaks docstrings
17145 Release 1.4.6 (released Aug 20, 2016)
17147 Incompatible changes
17148 · #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on
17149 six-1.5 or later
17150 Bugs fixed
17152 · applehelp: Sphinx crashes if hiutil or codesign commands not found
17153 · Fix make clean abort issue when build dir contains regular files like
17155 DS_Store.
17156 · Reduce epubcheck warnings/errors:
17158 · Fix DOCTYPE to html5
17160 · Change extension from .html to .xhtml.
17162 · Disable search page on epub results
17164 · #2778: Fix autodoc crashes if obj.__dict__ is a property method and
17166 raises exception
17167 · Fix duplicated toc in epub3 output.
17169 · #2775: Fix failing linkcheck with servers not supporting identidy
17171 encoding
17172 · #2833: Fix formatting instance annotations in ext.autodoc.
17174 · #1911: -D option of sphinx-build does not override the extensions
17176 variable
17177 · #2789: sphinx.ext.intersphinx generates wrong hyperlinks if the
17179 inventory is given
17180 · parsing errors for caption of code-blocks are displayed in document
17182 (ref: #2845)
17183 · #2846: singlehtml builder does not include figure numbers
17185 · #2816: Fix data from builds cluttering the Domain.initial_data class
17187 attributes
17188 Release 1.4.5 (released Jul 13, 2016)
17190 Incompatible changes
17191 · latex, inclusion of non-inline images from image directive resulted
17192 in non-coherent whitespaces depending on original image width; new
17193 behaviour by necessity differs from earlier one in some cases. (ref:
17194 #2672)
17195 · latex, use of \includegraphics to refer to Sphinx custom variant is
17197 deprecated; in future it will revert to original LaTeX macro, custom
17198 one already has alternative name \sphinxincludegraphics.
17199 Features added
17201 · new config option latex_keep_old_macro_names, defaults to True. If
17202 False, lets macros (for text styling) be defined only with
17203 \sphinx-prefixed names.
17204 · latex writer allows user customization of “shadowed” boxes (topics),
17206 via three length variables.
17207 · woff-format web font files now supported by the epub builder.
17209 Bugs fixed
17211 · jsdump fix for python 3: fixes the HTML search on python > 3
17212 · #2676: (latex) Error with verbatim text in captions since Sphinx
17214 1.4.4
17215 · #2629: memoir class crashes LaTeX. Fixed by
17217 latex_keep_old_macro_names=False (ref 2675)
17218 · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
17220 · #2679: float package needed for 'figure_align': 'H' latex option
17222 · #2671: image directive may lead to inconsistent spacing in pdf
17224 · #2705: toctree generates empty bullet_list if :titlesonly: specified
17226 · #2479: sphinx.ext.viewcode uses python2 highlighter by default
17228 · #2700: HtmlHelp builder has hard coded index.html
17230 · latex, since 1.4.4 inline literal text is followed by spurious space
17232 · #2722: C++, fix id generation for var/member declarations to include
17234 namespaces.
17235 · latex, images (from image directive) in lists or quoted blocks did
17237 not obey indentation (fixed together with #2671)
17238 · #2733: since Sphinx-1.4.4 make latexpdf generates lots of hyperref
17240 warnings
17241 · #2731: sphinx.ext.autodoc does not access propertymethods which
17243 raises any exceptions
17244 · #2666: C++, properly look up nested names involving constructors.
17246 · #2579: Could not refer a label including both spaces and colons via
17248 sphinx.ext.intersphinx
17249 · #2718: Sphinx crashes if the document file is not readable
17251 · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
17253 · #2723: extra spaces in latex pdf output from multirow cell
17255 · #2735: latexpdf Underfull \hbox (badness 10000) warnings from title
17257 page
17258 · #2667: latex crashes if resized images appeared in section title
17260 · #2763: (html) Provide default value for required alt attribute for
17262 image tags of SVG source, required to validate and now consistent w/
17263 other formats.
17264 Release 1.4.4 (released Jun 12, 2016)
17266 Bugs fixed
17267 · #2630: Latex sphinx.sty Notice Enviroment formatting problem
17268 · #2632: Warning directives fail in quote environment latex build
17270 · #2633: Sphinx crashes with old styled indices
17272 · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
17274 · #2622: Latex produces empty pages after title and table of contents
17276 · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
17278 · Let LaTeX use straight quotes also in inline code (ref #2627)
17280 · #2351: latex crashes if enumerated lists are placed on footnotes
17282 · #2646: latex crashes if math contains twice empty lines
17284 · #2480: sphinx.ext.autodoc: memory addresses were shown
17286 · latex: allow code-blocks appearing inside lists and quotes at maximal
17288 nesting depth (ref #777, #2624, #2651)
17289 · #2635: Latex code directives produce inconsistent frames based on
17291 viewing resolution
17292 · #2639: Sphinx now bundles iftex.sty
17294 · Failed to build PDF with framed.sty 0.95
17296 · Sphinx now bundles needspace.sty
17298 Release 1.4.3 (released Jun 5, 2016)
17300 Bugs fixed
17301 · #2530: got “Counter too large” error on building PDF if large num‐
17302 bered footnotes existed in admonitions
17303 · width option of figure directive does not work if align option speci‐
17305 fied at same time (ref: #2595)
17306 · #2590: The inputenc package breaks compiling under lualatex and xela‐
17308 tex
17309 · #2540: date on latex front page use different font
17311 · Suppress “document isn’t included in any toctree” warning if the doc‐
17313 ument is included (ref: #2603)
17314 · #2614: Some tables in PDF output will end up shifted if user sets non
17316 zero parindent in preamble
17317 · #2602: URL redirection breaks the hyperlinks generated by
17319 sphinx.ext.intersphinx
17320 · #2613: Show warnings if merged extensions are loaded
17322 · #2619: make sure amstext LaTeX package always loaded (ref: d657225,
17324 488ee52, 9d82cad and #2615)
17325 · #2593: latex crashes if any figures in the table
17327 Release 1.4.2 (released May 29, 2016)
17329 Features added
17330 · Now suppress_warnings accepts following configurations (ref: #2451,
17331 #2466):
17332 · app.add_node
17334 · app.add_directive
17336 · app.add_role
17338 · app.add_generic_role
17340 · app.add_source_parser
17342 · image.data_uri
17344 · image.nonlocal_uri
17346 · #2453: LaTeX writer allows page breaks in topic contents; and their
17348 horizontal extent now fits in the line width (with shadow in margin).
17349 Also warning-type admonitions allow page breaks and their vertical
17350 spacing has been made more coherent with the one for hint-type
17351 notices (ref #2446).
17352 · #2459: the framing of literal code-blocks in LaTeX output (and not
17354 only the code lines themselves) obey the indentation in lists or
17355 quoted blocks.
17356 · #2343: the long source lines in code-blocks are wrapped (without mod‐
17358 ifying the line numbering) in LaTeX output (ref #1534, #2304).
17359 Bugs fixed
17361 · #2370: the equations are slightly misaligned in LaTeX writer
17362 · #1817, #2077: suppress pep8 warnings on conf.py generated by
17364 sphinx-quickstart
17365 · #2407: building docs crash if document includes large data image URIs
17367 · #2436: Sphinx does not check version by needs_sphinx if loading
17369 extensions failed
17370 · #2397: Setup shorthandoff for turkish documents
17372 · #2447: VerbatimBorderColor wrongly used also for captions of PDF
17374 · #2456: C++, fix crash related to document merging (e.g., singlehtml
17376 and Latex builders).
17377 · #2446: latex(pdf) sets local tables of contents (or more generally
17379 topic nodes) in unbreakable boxes, causes overflow at bottom
17380 · #2476: Omit MathJax markers if :nowrap: is given
17382 · #2465: latex builder fails in case no caption option is provided to
17384 toctree directive
17385 · Sphinx crashes if self referenced toctree found
17387 · #2481: spelling mistake for mecab search splitter. Thanks to Naoki
17389 Sato.
17390 · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
17392 · intersphinx fails if mapping URL contains any port
17394 · #2088: intersphinx crashes if the mapping URL requires basic auth
17396 · #2304: auto line breaks in latexpdf codeblocks
17398 · #1534: Word wrap long lines in Latex verbatim blocks
17400 · #2460: too much white space on top of captioned literal blocks in PDF
17402 output
17403 · Show error reason when multiple math extensions are loaded (ref:
17405 #2499)
17406 · #2483: any figure number was not assigned if figure title contains
17408 only non text objects
17409 · #2501: Unicode subscript numbers are normalized in LaTeX
17411 · #2492: Figure directive with :figwidth: generates incorrect
17413 Latex-code
17414 · The caption of figure is always put on center even if :align: was
17416 specified
17417 · #2526: LaTeX writer crashes if the section having only images
17419 · #2522: Sphinx touches mo files under installed directory that caused
17421 permission error.
17422 · #2536: C++, fix crash when an immediately nested scope has the same
17424 name as the current scope.
17425 · #2555: Fix crash on any-references with unicode.
17427 · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
17429 · #2521: generated Makefile causes BSD make crashed if sphinx-build not
17431 found
17432 · #2470: typing backport package causes autodoc errors with python 2.7
17434 · sphinx.ext.intersphinx crashes if non-string value is used for key of
17436 intersphinx_mapping
17437 · #2518: intersphinx_mapping disallows non alphanumeric keys
17439 · #2558: unpack error on devhelp builder
17441 · #2561: Info builder crashes when a footnote contains a link
17443 · #2565: The descriptions of objects generated by sphinx.ext.autosum‐
17445 mary overflow lines at LaTeX writer
17446 · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
17448 · #2445: rst_prolog and rst_epilog affect to non reST sources
17450 · #2576: sphinx.ext.imgmath crashes if subprocess raises error
17452 · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
17454 · #2556: Xapian search does not work with Python 3
17456 · #2581: The search doesn’t work if language=”es” (spanish)
17458 · #2382: Adjust spacing after abbreviations on figure numbers in LaTeX
17460 writer
17461 · #2383: The generated footnote by latex_show_urls overflows lines
17463 · #2497, #2552: The label of search button does not fit for the button
17465 itself
17466 Release 1.4.1 (released Apr 12, 2016)
17468 Incompatible changes
17469 · The default format of today_fmt and html_last_updated_fmt is back to
17470 strftime format again. Locale Date Markup Language is also supported
17471 for backward compatibility until Sphinx-1.5.
17472 Translations
17474 · Added Welsh translation, thanks to Geraint Palmer.
17475 · Added Greek translation, thanks to Stelios Vitalis.
17477 · Added Esperanto translation, thanks to Dinu Gherman.
17479 · Added Hindi translation, thanks to Purnank H. Ghumalia.
17481 · Added Romanian translation, thanks to Razvan Stefanescu.
17483 Bugs fixed
17485 · C++, added support for extern and thread_local.
17486 · C++, type declarations are now using the prefixes typedef, using, and
17488 type, depending on the style of declaration.
17489 · #2413: C++, fix crash on duplicate declarations
17491 · #2394: Sphinx crashes when html_last_updated_fmt is invalid
17493 · #2408: dummy builder not available in Makefile and make.bat
17495 · #2412: hyperlink targets are broken in LaTeX builder
17497 · figure directive crashes if non paragraph item is given as caption
17499 · #2418: time formats no longer allowed in today_fmt
17501 · #2395: Sphinx crashes if unicode character in image filename
17503 · #2396: “too many values to unpack” in genindex-single
17505 · #2405: numref link in PDF jumps to the wrong location
17507 · #2414: missing number in PDF hyperlinks to code listings
17509 · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
17511 Release 1.4 (released Mar 28, 2016)
17513 Incompatible changes
17514 · Drop PorterStemmer package support. Use PyStemmer instead of Porter‐
17515 Stemmer to accelerate stemming.
17516 · sphinx_rtd_theme has become optional. Please install it manually.
17518 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
17519 · #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer.
17521 It enables to take title of roles as an argument of custom macros.
17522 · #2022: ‘Thumbs.db’ and ‘.DS_Store’ are added to exclude_patterns
17524 default values in conf.py that will be provided on sphinx-quickstart.
17525 · #2027, #2208: The html_title accepts string values only. And The None
17527 value cannot be accepted.
17528 · sphinx.ext.graphviz: show graph image in inline by default
17530 · #2060, #2224: The manpage role now generate sphinx.addnodes.manpage
17532 node instead of sphinx.addnodes.literal_emphasis node.
17533 · #2022: html_extra_path also copies dotfiles in the extra directory,
17535 and refers to exclude_patterns to exclude extra files and directo‐
17536 ries.
17537 · #2300: enhance autoclass:: to use the docstring of __new__ if
17539 __init__ method’s is missing of empty
17540 · #2251: Previously, under glossary directives, multiple terms for one
17542 definition are converted into single term node and the each terms in
17543 the term node are separated by termsep node. In new implementation,
17544 each terms are converted into individual term nodes and termsep node
17545 is removed. By this change, output layout of every builders are
17546 changed a bit.
17547 · The default highlight language is now Python 3. This means that
17549 source code is highlighted as Python 3 (which is mostly a superset of
17550 Python 2), and no parsing is attempted to distinguish valid code. To
17551 get the old behavior back, add highlight_language = "python" to
17552 conf.py.
17553 · Locale Date Markup Language like "MMMM dd, YYYY" is default format
17555 for today_fmt and html_last_updated_fmt. However strftime format
17556 like "%B %d, %Y" is also supported for backward compatibility until
17557 Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
17558 · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
17560 ing instead.
17561 · #2337: Use \url{URL} macro instead of \href{URL}{URL} in LaTeX
17563 writer.
17564 · #1498: manpage writer: don’t make whole of item in definition list
17566 bold if it includes strong node.
17567 · #582: Remove hint message from quick search box for html output.
17569 · #2378: Sphinx now bundles newfloat.sty
17571 Features added
17573 · #2092: add todo directive support in napoleon package.
17574 · #1962: when adding directives, roles or nodes from an extension, warn
17576 if such an element is already present (built-in or added by another
17577 extension).
17578 · #1909: Add “doc” references to Intersphinx inventories.
17580 · C++ type alias support (e.g., .. type:: T = int).
17582 · C++ template support for classes, functions, type aliases, and vari‐
17584 ables (#1729, #1314).
17585 · C++, added new scope management directives namespace-push and names‐
17587 pace-pop.
17588 · #1970: Keyboard shortcuts to navigate Next and Previous topics
17590 · Intersphinx: Added support for fetching Intersphinx inventories with
17592 URLs using HTTP basic auth.
17593 · C++, added support for template parameter in function info field
17595 lists.
17596 · C++, added support for pointers to member (function).
17598 · #2113: Allow :class: option to code-block directive.
17600 · #2192: Imgmath (pngmath with svg support).
17602 · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
17604 · #1906: Use xcolor over color for fcolorbox where available for LaTeX
17606 output.
17607 · #2216: Texinputs makefile improvements.
17609 · #2170: Support for Chinese language search index.
17611 · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
17613 · #1030: Make page reference names for latex_show_pagerefs translatable
17615 · #2162: Add Sphinx.add_source_parser() to add source_suffix and
17617 source_parsers from extension
17618 · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
17620 · #656: Add graphviz_dot option to graphviz directives to switch the
17622 dot command
17623 · #1939: Added the dummy builder: syntax check without output.
17625 · #2230: Add math_number_all option to number all displayed math in
17627 math extensions
17628 · #2235: needs_sphinx supports micro version comparison
17630 · #2282: Add “language” attribute to html tag in the “basic” theme
17632 · #1779: Add EPUB 3 builder
17634 · #1751: Add todo_link_only to avoid file path and line indication on
17636 todolist. Thanks to Francesco Montesano.
17637 · #2199: Use imagesize package to obtain size of images.
17639 · #1099: Add configurable retries to the linkcheck builder. Thanks to
17641 Alex Gaynor. Also don’t check anchors starting with !.
17642 · #2300: enhance autoclass:: to use the docstring of __new__ if
17644 __init__ method’s is missing of empty
17645 · #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for
17647 numfig feature
17648 · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
17650 erence sections using its title. Thanks to Tadhg O’Higgins.
17651 · #1854: Allow to choose Janome for Japanese splitter.
17653 · #1853: support custom text splitter on html search with lan‐
17655 guage='ja'.
17656 · #2320: classifier of glossary terms can be used for index entries
17658 grouping key. The classifier also be used for translation. See also
17659 glossary-directive.
17660 · #2308: Define \tablecontinued macro to redefine the style of contin‐
17662 ued label for longtables.
17663 · Select an image by similarity if multiple images are globbed by ..
17665 image:: filename.*
17666 · #1921: Support figure substitutions by language and figure_lan‐
17668 guage_filename
17669 · #2245: Add latex_elements["passoptionstopackages"] option to call
17671 PassOptionsToPackages in early stage of preambles.
17672 · #2340: Math extension: support alignment of multiple equations for
17674 MathJAX.
17675 · #2338: Define \titleref macro to redefine the style of title-refer‐
17677 ence roles.
17678 · Define \menuselection and \accelerator macros to redefine the style
17680 of menuselection roles.
17681 · Define \crossref macro to redefine the style of references
17683 · #2301: Texts in the classic html theme should be hyphenated.
17685 · #2355: Define \termref macro to redefine the style of term roles.
17687 · Add suppress_warnings to suppress arbitrary warning message (experi‐
17689 mental)
17690 · #2229: Fix no warning is given for unknown options
17692 · #2327: Add latex_toplevel_sectioning to switch the top level section‐
17694 ing of LaTeX document.
17695 Bugs fixed
17697 · #1913: C++, fix assert bug for enumerators in next-to-global and
17698 global scope.
17699 · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
17701 · C++, add missing support for ‘friend’ functions.
17703 · C++, add missing support for virtual base classes (thanks to Rapptz).
17705 · C++, add support for final classes.
17707 · C++, fix parsing of types prefixed with ‘enum’.
17709 · #2023: Dutch search support uses Danish stemming info.
17711 · C++, add support for user-defined literals.
17713 · #1804: Now html output wraps overflowed long-line-text in the side‐
17715 bar. Thanks to Hassen ben tanfous.
17716 · #2183: Fix porterstemmer causes make json to fail.
17718 · #1899: Ensure list is sent to OptParse.
17720 · #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx
17722 package option).
17723 · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
17725 · Fix broken LaTeX code is generated if unknown language is given
17727 · #1944: Fix rst_prolog breaks file-wide metadata
17729 · #2074: make gettext should use canonical relative paths for .pot.
17731 Thanks to anatoly techtonik.
17732 · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
17734 · #2251: Line breaks in .rst files are transferred to .pot files in a
17736 wrong way.
17737 · #794: Fix date formatting in latex output is not localized
17739 · Remove image/gif from supported_image_types of LaTeX writer (#2272)
17741 · Fix ValueError is raised if LANGUAGE is empty string
17743 · Fix unpack warning is shown when the directives generated from
17745 Sphinx.add_crossref_type is used
17746 · The default highlight language is now default. This means that
17748 source code is highlighted as Python 3 (which is mostly a superset of
17749 Python 2) if possible. To get the old behavior back, add high‐
17750 light_language = "python" to conf.py.
17751 · #2329: Refresh environment forcely if source directory has changed.
17753 · #2331: Fix code-blocks are filled by block in dvi; remove xcdraw
17755 option from xcolor package
17756 · Fix the confval type checker emits warnings if unicode is given to
17758 confvals which expects string value
17759 · #2360: Fix numref in LaTeX output is broken
17761 · #2361: Fix additional paragraphs inside the “compound” directive are
17763 indented
17764 · #2364: Fix KeyError ‘rootSymbol’ on Sphinx upgrade from older ver‐
17766 sion.
17767 · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
17769 · #2368: Ignore emacs lock files like .#foo.rst by default.
17771 · #2262: literal_block and its caption has been separated by pagebreak
17773 in LaTeX output.
17774 · #2319: Fix table counter is overrided by code-block’s in LaTeX.
17776 Thanks to jfbu.
17777 · Fix unpack warning if combinated with 3rd party domain extensions.
17779 · #1153: Fix figures in sidebar causes latex build error.
17781 · #2358: Fix user-preamble could not override the tocdepth definition.
17783 · #2358: Redece tocdepth if part or chapter is used for top_section‐
17785 level.
17786 · #2351: Fix footnote spacing
17788 · #2363: Fix toctree() in templates generates broken links in Single‐
17790 HTMLBuilder.
17791 · #2366: Fix empty hyperref is generated on toctree in HTML builder.
17793 Documentation
17795 · #1757: Fix for usage of html_last_updated_fmt. Thanks to Ralf Hem‐
17796 mecke.
17797 Release 1.3.6 (released Feb 29, 2016)
17799 Features added
17800 · #1873, #1876, #2278: Add page_source_suffix html context variable.
17801 This should be introduced with source_parsers feature. Thanks for
17802 Eric Holscher.
17803 Bugs fixed
17805 · #2265: Fix babel is used in spite of disabling it on latex_elements
17806 · #2295: Avoid mutating dictionary errors while enumerating members in
17808 autodoc with Python 3
17809 · #2291: Fix pdflatex “Counter too large” error from footnotes inside
17811 tables of contents
17812 · #2292: Fix some footnotes disappear from LaTeX output
17814 · #2287: sphinx.transforms.Locale always uses rst parser. Sphinx i18n
17816 feature should support parsers that specified source_parsers.
17817 · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user choice
17819 of math fonts
17820 · #2324: Print a hint how to increase the recursion limit when it is
17822 hit.
17823 · #1565, #2229: Revert new warning; the new warning will be triggered
17825 from version 1.4 on.
17826 · #2329: Refresh environment forcely if source directory has changed.
17828 · #2019: Fix the domain objects in search result are not escaped
17830 Release 1.3.5 (released Jan 24, 2016)
17832 Bugs fixed
17833 · Fix line numbers was not shown on warnings in LaTeX and texinfo
17834 builders
17835 · Fix filenames were not shown on warnings of citations
17837 · Fix line numbers was not shown on warnings in LaTeX and texinfo
17839 builders
17840 · Fix line numbers was not shown on warnings of indices
17842 · #2026: Fix LaTeX builder raises error if parsed-literal includes
17844 links
17845 · #2243: Ignore strange docstring types for classes, do not crash
17847 · #2247: Fix #2205 breaks make html for definition list with classi‐
17849 fiers that contains regular-expression like string
17850 · #1565: Sphinx will now emit a warning that highlighting was skipped
17852 if the syntax is incorrect for code-block, literalinclude and so on.
17853 · #2211: Fix paragraphs in table cell doesn’t work in Latex output
17855 · #2253: :pyobject: option of literalinclude directive can’t detect
17857 indented body block when the block starts with blank or comment
17858 lines.
17859 · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
17861 · Fix warning message for :numref: if target is in orphaned doc (ref:
17863 #2244)
17864 Release 1.3.4 (released Jan 12, 2016)
17866 Bugs fixed
17867 · #2134: Fix figure caption with reference causes latex build error
17868 · #2094: Fix rubric with reference not working in Latex
17870 · #2147: Fix literalinclude code in latex does not break in pages
17872 · #1833: Fix email addresses is showed again if latex_show_urls is not
17874 None
17875 · #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed
17877 svg
17878 · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
17880 · #1237: Fix footnotes not working in definition list in LaTeX
17882 · #2168: Fix raw directive does not work for text writer
17884 · #2171: Fix cannot linkcheck url with unicode
17886 · #2182: LaTeX: support image file names with more than 1 dots
17888 · #2189: Fix previous sibling link for first file in subdirectory uses
17890 last file, not intended previous from root toctree
17891 · #2003: Fix decode error under python2 (only) when make linkcheck is
17893 run
17894 · #2186: Fix LaTeX output of mathbb in math
17896 · #1480, #2188: LaTeX: Support math in section titles
17898 · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
17900 Bug
17901 · #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains
17903 non-ascii characters
17904 · #2193: Fix shutil.SameFileError if source directory and destination
17906 directory are same
17907 · #2178: Fix unparseable C++ cross-reference when referencing a func‐
17909 tion with :cpp:any:
17910 · #2206: Fix Sphinx latex doc build failed due to a footnotes
17912 · #2201: Fix wrong table caption for tables with over 30 rows
17914 · #2213: Set <blockquote> in the classic theme to fit with <p>
17916 · #1815: Fix linkcheck does not raise an exception if warniserror set
17918 to true and link is broken
17919 · #2197: Fix slightly cryptic error message for missing index.rst file
17921 · #1894: Unlisted phony targets in quickstart Makefile
17923 · #2125: Fix unifies behavior of collapsed fields (GroupedField and
17925 TypedField)
17926 · #1408: Check latex_logo validity before copying
17928 · #771: Fix latex output doesn’t set tocdepth
17930 · #1820: On Windows, console coloring is broken with colorama version
17932 0.3.3. Now sphinx use colorama>=0.3.5 to avoid this problem.
17933 · #2072: Fix footnotes in chapter-titles do not appear in PDF output
17935 · #1580: Fix paragraphs in longtable don’t work in Latex output
17937 · #1366: Fix centered image not centered in latex
17939 · #1860: Fix man page using :samp: with braces - font doesn’t reset
17941 · #1610: Sphinx crashes in japanese indexing in some systems
17943 · Fix Sphinx crashes if mecab initialization failed
17945 · #2160: Fix broken TOC of PDFs if section includes an image
17947 · #2172: Fix dysfunctional admonition py@lightbox in sphinx.sty. Thanks
17949 to jfbu.
17950 · #2198,#2205: make gettext generate broken msgid for definition lists.
17952 · #2062: Escape characters in doctests are treated incorrectly with
17954 Python 2.
17955 · #2225: Fix if the option does not begin with dash, linking is not
17957 performed
17958 · #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath,
17960 mathjax)
17961 · #1601, #2220: ‘any’ role breaks extended domains behavior. Affected
17963 extensions doesn’t support resolve_any_xref and resolve_xref returns
17964 problematic node instead of None. sphinxcontrib-httpdomain is one of
17965 them.
17966 · #2229: Fix no warning is given for unknown options
17968 Release 1.3.3 (released Dec 2, 2015)
17970 Bugs fixed
17971 · #2177: Fix parallel hangs
17972 · #2012: Fix exception occurred if numfig_format is invalid
17974 · #2142: Provide non-minified JS code in sphinx/search/non-mini‐
17976 fied-js/*.js for source distribution on PyPI.
17977 · #2148: Error while building devhelp target with non-ASCII document.
17979 Release 1.3.2 (released Nov 29, 2015)
17981 Features added
17982 · #1935: Make “numfig_format” overridable in latex_elements.
17983 Bugs fixed
17985 · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
17986 dows environment.
17987 · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
17989 patibility.
17990 · #1788: graphviz extension raises exception when caption option is
17992 present.
17993 · #1789: :pyobject: option of literalinclude directive includes follow‐
17995 ing lines after class definitions
17996 · #1790: literalinclude strips empty lines at the head and tail
17998 · #1802: load plugin themes automatically when theme.conf use it as
18000 ‘inherit’. Thanks to Takayuki Hirai.
18001 · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
18003 find base theme.
18004 · #1834: compatibility for docutils-0.13: handle_io_errors keyword
18006 argument for docutils.io.FileInput cause TypeError.
18007 · #1823: ‘.’ as <module_path> for sphinx-apidoc cause an unfriendly
18009 error. Now ‘.’ is converted to absolute path automatically.
18010 · Fix a crash when setting up extensions which do not support metadata.
18012 · #1784: Provide non-minified JS code in sphinx/search/non-mini‐
18014 fied-js/*.js
18015 · #1822, #1892: Fix regression for #1061. autosummary can’t generate
18017 doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
18018 · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
18020 Takayuki Hirai.
18021 · #1780, #1866: “make text” shows “class” keyword twice. Thanks to
18023 Takayuki Hirai.
18024 · #1871: Fix for LaTeX output of tables with one column and multirows.
18026 · Work around the lack of the HTMLParserError exception in Python 3.5.
18028 · #1949: Use safe_getattr in the coverage builder to avoid aborting
18030 with descriptors that have custom behavior.
18031 · #1915: Do not generate smart quotes in doc field type annotations.
18033 · #1796: On py3, automated .mo building caused UnicodeDecodeError.
18035 · #1923: Use babel features only if the babel latex element is
18037 nonempty.
18038 · #1942: Fix a KeyError in websupport.
18040 · #1903: Fix strange id generation for glossary terms.
18042 · make text will crush if a definition list item has more than 1 clas‐
18044 sifiers as: term : classifier1 : classifier2.
18045 · #1855: make gettext generates broken po file for definition lists
18047 with classifier.
18048 · #1869: Fix problems when dealing with files containing non-ASCII
18050 characters. Thanks to Marvin Schmidt.
18051 · #1798: Fix building LaTeX with references in titles.
18053 · #1725: On py2 environment, doctest with using non-ASCII characters
18055 causes 'ascii' codec can't decode byte exception.
18056 · #1540: Fix RuntimeError with circular referenced toctree
18058 · #1983: i18n translation feature breaks references which uses section
18060 name.
18061 · #1990: Use caption of toctree to title of tableofcontents in LaTeX
18063 · #1987: Fix ampersand is ignored in :menuselection: and :guilabel: on
18065 LaTeX builder
18066 · #1994: More supporting non-standard parser (like recommonmark parser)
18068 for Translation and WebSupport feature. Now node.rawsource is fall
18069 backed to node.astext() during docutils transforming.
18070 · #1989: “make blahblah” on Windows indicate help messages for
18072 sphinx-build every time. It was caused by wrong make.bat that gener‐
18073 ated by Sphinx-1.3.0/1.3.1.
18074 · On Py2 environment, conf.py that is generated by sphinx-quickstart
18076 should have u prefixed config value for ‘version’ and ‘release’.
18077 · #2102: On Windows + Py3, using |today| and non-ASCII date format will
18079 raise UnicodeEncodeError.
18080 · #1974: UnboundLocalError: local variable ‘domain’ referenced before
18082 assignment when using any role and sphinx.ext.intersphinx in same
18083 time.
18084 · #2121: multiple words search doesn’t find pages when words across on
18086 the page title and the page content.
18087 · #1884, #1885: plug-in html themes cannot inherit another plug-in
18089 theme. Thanks to Suzumizaki.
18090 · #1818: sphinx.ext.todo directive generates broken html class
18092 attribute as ‘admonition-‘ when language is specified with non-ASCII
18093 linguistic area like ‘ru’ or ‘ja’. To fix this, now todo directive
18094 can use :class: option.
18095 · #2140: Fix footnotes in table has broken in LaTeX
18097 · #2127: MecabBinder for html searching feature doesn’t work with
18099 Python 3. Thanks to Tomoko Uchida.
18100 Release 1.3.1 (released Mar 17, 2015)
18102 Bugs fixed
18103 · #1769: allows generating quickstart files/dirs for destination dir
18104 that doesn’t overwrite existent files/dirs. Thanks to WAKAYAMA shi‐
18105 rou.
18106 · #1773: sphinx-quickstart doesn’t accept non-ASCII character as a
18108 option argument.
18109 · #1766: the message “least Python 2.6 to run” is at best misleading.
18111 · #1772: cross reference in docstrings like :param .write: breaks
18113 building.
18114 · #1770, #1774: literalinclude with empty file occurs exception. Thanks
18116 to Takayuki Hirai.
18117 · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
18119 · #1776: source_suffix = ['.rst'] cause unfriendly error on prior ver‐
18121 sion.
18122 · #1771: automated .mo building doesn’t work properly.
18124 · #1783: Autodoc: Python2 Allow unicode string in __all__. Thanks to
18126 Jens Hedegaard Nielsen.
18127 · #1781: Setting html_domain_indices to a list raises a type check
18129 warnings.
18130 Release 1.3 (released Mar 10, 2015)
18132 Incompatible changes
18133 · Roles ref, term and menusel now don’t generate emphasis nodes any‐
18134 more. If you want to keep italic style, adapt your stylesheet.
18135 · Role numref uses %s as special character to indicate position of fig‐
18137 ure numbers instead # symbol.
18138 Features added
18140 · Add convenience directives and roles to the C++ domain: directive
18141 cpp:var as alias for cpp:member, role :cpp:var as alias for :cpp:mem‐
18142 ber, and role any for cross-reference to any C++ declaraction. #1577,
18143 #1744
18144 · The source_suffix config value can now be a list of multiple suf‐
18146 fixes.
18147 · Add the ability to specify source parsers by source suffix with the
18149 source_parsers config value.
18150 · #1675: A new builder, AppleHelpBuilder, has been added that builds
18152 Apple Help Books.
18153 Bugs fixed
18155 · 1.3b3 change breaks a previous gettext output that contains dupli‐
18156 cated msgid such as “foo bar” and “version changes in 1.3: foo bar”.
18157 · #1745: latex builder cause maximum recursion depth exceeded when a
18159 footnote has a footnote mark itself.
18160 · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
18162 · #1658, #1750: No link created (and warning given) if option does not
18164 begin with -, / or +. Thanks to Takayuki Hirai.
18165 · #1753: C++, added missing support for more complex declarations.
18167 · #1700: Add :caption: option for toctree.
18169 · #1742: :name: option is provided for toctree, code-block and literal‐
18171 include dirctives.
18172 · #1756: Incorrect section titles in search that was introduced from
18174 1.3b3.
18175 · #1746: C++, fixed name lookup procedure, and added missing lookups in
18177 declarations.
18178 · #1765: C++, fix old id generation to use fully qualified names.
18180 Documentation
18182 · #1651: Add vartype field descritpion for python domain.
18183 Release 1.3b3 (released Feb 24, 2015)
18185 Incompatible changes
18186 · Dependency requirement updates: docutils 0.11, Pygments 2.0
18187 · The gettext_enables config value has been renamed to gettext_addi‐
18189 tional_targets.
18190 · #1735: Use https://docs.python.org/ instead of http protocol. It was
18192 used for sphinx.ext.intersphinx and some documentation.
18193 Features added
18195 · #1346: Add new default theme;
18196 · Add ‘alabaster’ theme.
18198 · Add ‘sphinx_rtd_theme’ theme.
18200 · The ‘default’ html theme has been renamed to ‘classic’. ‘default’
18202 is still available, however it will emit notice a recommendation
18203 that using new ‘alabaster’ theme.
18204 · Added highlight_options configuration value.
18206 · The language config value is now available in the HTML templates.
18208 · The env-updated event can now return a value, which is interpreted as
18210 an iterable of additional docnames that need to be rewritten.
18211 · #772: Support for scoped and unscoped enums in C++. Enumerators in
18213 unscoped enums are injected into the parent scope in addition to the
18214 enum scope.
18215 · Add todo_include_todos config option to quickstart conf file, handled
18217 as described in documentation.
18218 · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
18220 nav-item-0, 1, 2…).
18221 · New option sphinx-quickstart --use-make-mode for generating Makefile
18223 that use sphinx-build make-mode.
18224 · #1235: i18n: several node can be translated if it is set to get‐
18226 text_additional_targets in conf.py. Supported nodes are:
18227 · ‘literal-block’
18229 · ‘doctest-block’
18231 · ‘raw’
18233 · ‘image’
18235 · #1227: Add html_scaled_image_link config option to conf.py, to con‐
18237 trol scaled image link.
18238 Bugs fixed
18240 · LaTeX writer now generates correct markup for cells spanning multiple
18241 rows.
18242 · #1674: Do not crash if a module’s __all__ is not a list of strings.
18244 · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
18246 · On windows, make-mode didn’t work on Win32 platform if sphinx was
18248 invoked as python sphinx-build.py.
18249 · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
18251 · #1690: toctrees with glob option now can also contain entries for
18253 single documents with explicit title.
18254 · #1591: html search results for C++ elements now has correct interpage
18256 links.
18257 · bizstyle theme: nested long title pages make long breadcrumb that
18259 breaks page layout.
18260 · bizstyle theme: all breadcrumb items become ‘Top’ on some mobile
18262 browser (iPhone5s safari).
18263 · #1722: restore toctree() template function behavior that was changed
18265 at 1.3b1.
18266 · #1732: i18n: localized table caption raises exception.
18268 · #1718: :numref: does not work with capital letters in the label
18270 · #1630: resolve CSS conflicts, div.container css target for literal
18272 block wrapper now renamed to div.literal-block-wrapper.
18273 · sphinx.util.pycompat has been restored in its backwards-compatibil‐
18275 ity; slated for removal in Sphinx 1.4.
18276 · #1719: LaTeX writer does not respect numref_format option in captions
18278 Release 1.3b2 (released Dec 5, 2014)
18280 Incompatible changes
18281 · update bundled ez_setup.py for setuptools-7.0 that requires Python
18282 2.6 or later.
18283 Features added
18285 · #1597: Added possibility to return a new template name from
18286 html-page-context.
18287 · PR#314, #1150: Configuration values are now checked for their type.
18289 A warning is raised if the configured and the default value do not
18290 have the same type and do not share a common non-trivial base class.
18291 Bugs fixed
18293 · PR#311: sphinx-quickstart does not work on python 3.4.
18294 · Fix autodoc_docstring_signature not working with signatures in class
18296 docstrings.
18297 · Rebuilding cause crash unexpectedly when source files were added.
18299 · #1607: Fix a crash when building latexpdf with “howto” class
18301 · #1251: Fix again. Sections which depth are lower than :tocdepth:
18303 should not be shown on localtoc sidebar.
18304 · make-mode didn’t work on Win32 platform if sphinx was installed by
18306 wheel package.
18307 Release 1.3b1 (released Oct 10, 2014)
18309 Incompatible changes
18310 · Dropped support for Python 2.5, 3.1 and 3.2.
18311 · Dropped support for docutils versions up to 0.9.
18313 · Removed the sphinx.ext.oldcmarkup extension.
18315 · The deprecated config values exclude_trees, exclude_dirnames and
18317 unused_docs have been removed.
18318 · A new node, sphinx.addnodes.literal_strong, has been added, for text
18320 that should appear literally (i.e. no smart quotes) in strong font.
18321 Custom writers will have to be adapted to handle this node.
18322 · PR#269, #1476: replace <tt> tag by <code>. User customized
18324 stylesheets should be updated If the css contain some styles for tt>
18325 tag. Thanks to Takeshi Komiya.
18326 · #1543: templates_path is automatically added to exclude_patterns to
18328 avoid reading autosummary rst templates in the templates directory.
18329 · Custom domains should implement the new Domain.resolve_any_xref
18331 method to make the any role work properly.
18332 · gettext builder: gettext doesn’t emit uuid information to generated
18334 pot files by default. Please set True to gettext_uuid to emit uuid
18335 information. Additionally, if the python-levenshtein 3rd-party pack‐
18336 age is installed, it will improve the calculation time.
18337 · gettext builder: disable extracting/apply ‘index’ node by default.
18339 Please set ‘index’ to gettext_enables to enable extracting index
18340 entries.
18341 · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
18343 Features added
18345 · Add support for Python 3.4.
18346 · Add support for docutils 0.12
18348 · Added sphinx.ext.napoleon extension for NumPy and Google style doc‐
18350 string support.
18351 · Added support for parallel reading (parsing) of source files with the
18353 sphinx-build -j option. Third-party extensions will need to be
18354 checked for compatibility and may need to be adapted if they store
18355 information in the build environment object. See env-merge-info.
18356 · Added the any role that can be used to find a cross-reference of any
18358 type in any domain. Custom domains should implement the new
18359 Domain.resolve_any_xref method to make this work properly.
18360 · Exception logs now contain the last 10 messages emitted by Sphinx.
18362 · Added support for extension versions (a string returned by setup(),
18364 these can be shown in the traceback log files). Version requirements
18365 for extensions can be specified in projects using the new
18366 needs_extensions config value.
18367 · Changing the default role within a document with the default-role
18369 directive is now supported.
18370 · PR#214: Added stemming support for 14 languages, so that the built-in
18372 document search can now handle these. Thanks to Shibukawa Yoshiki.
18373 · PR#296, PR#303, #76: numfig feature: Assign numbers to figures,
18375 tables and code-blocks. This feature is configured with numfig, num‐
18376 fig_secnum_depth and numfig_format. Also numref role is available.
18377 Thanks to Takeshi Komiya.
18378 · PR#202: Allow “.” and “~” prefixed references in :param: doc fields
18380 for Python.
18381 · PR#184: Add autodoc_mock_imports, allowing to mock imports of exter‐
18383 nal modules that need not be present when autodocumenting.
18384 · #925: Allow list-typed config values to be provided on the command
18386 line, like -D key=val1,val2.
18387 · #668: Allow line numbering of code-block and literalinclude direc‐
18389 tives to start at an arbitrary line number, with a new lineno-start
18390 option.
18391 · PR#172, PR#266: The code-block and literalinclude directives now can
18393 have a caption option that shows a filename before the code in the
18394 output. Thanks to Nasimul Haque, Takeshi Komiya.
18395 · Prompt for the document language in sphinx-quickstart.
18397 · PR#217: Added config values to suppress UUID and location information
18399 in generated gettext catalogs.
18400 · PR#236, #1456: apidoc: Add a -M option to put module documentation
18402 before submodule documentation. Thanks to Wes Turner and Luc Saffre.
18403 · #1434: Provide non-minified JS files for jquery.js and underscore.js
18405 to clarify the source of the minified files.
18406 · PR#252, #1291: Windows color console support. Thanks to meu31.
18408 · PR#255: When generating latex references, also insert latex tar‐
18410 get/anchor for the ids defined on the node. Thanks to Olivier
18411 Heurtier.
18412 · PR#229: Allow registration of other translators. Thanks to Russell
18414 Sim.
18415 · Add app.set_translator() API to register or override a Docutils
18417 translator class like html_translator_class.
18418 · PR#267, #1134: add ‘diff’ parameter to literalinclude. Thanks to
18420 Richard Wall and WAKAYAMA shirou.
18421 · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
18423 · Automatically compile *.mo files from *.po files when get‐
18425 text_auto_build is True (default) and *.po is newer than *.mo file.
18426 · #623: sphinx.ext.viewcode supports imported function/class aliases.
18428 · PR#275: sphinx.ext.intersphinx supports multiple target for the
18430 inventory. Thanks to Brigitta Sipocz.
18431 · PR#261: Added the env-before-read-docs event that can be connected to
18433 modify the order of documents before they are read by the environ‐
18434 ment.
18435 · #1284: Program options documented with option can now start with +.
18437 · PR#291: The caption of code-block is recognised as a title of ref
18439 target. Thanks to Takeshi Komiya.
18440 · PR#298: Add new API: add_latex_package(). Thanks to Takeshi Komiya.
18442 · #1344: add gettext_enables to enable extracting ‘index’ to gettext
18444 catalog output / applying translation catalog to generated documenta‐
18445 tion.
18446 · PR#301, #1583: Allow the line numbering of the directive literalin‐
18448 clude to match that of the included file, using a new lineno-match
18449 option. Thanks to Jeppe Pihl.
18450 · PR#299: add various options to sphinx-quickstart. Quiet mode option
18452 --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
18453 · #1623: Return types specified with :rtype: are now turned into links
18455 if possible.
18456 Bugs fixed
18458 · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
18459 · #1568: Fix a crash when a “centered” directive contains a reference.
18461 · Now sphinx.ext.autodoc works with python-2.5 again.
18463 · #1563: add_search_language() raises AssertionError for correct type
18465 of argument. Thanks to rikoman.
18466 · #1174: Fix smart quotes being applied inside roles like program or
18468 makevar.
18469 · PR#235: comment db schema of websupport lacked a length of the
18471 node_id field. Thanks to solos.
18472 · #1466,PR#241: Fix failure of the cpp domain parser to parse C+11
18474 “variadic templates” declarations. Thanks to Victor Zverovich.
18475 · #1459,PR#244: Fix default mathjax js path point to http:// that cause
18477 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k.
18478 · PR#157: autodoc remove spurious signatures from @property decorated
18480 attributes. Thanks to David Ham.
18481 · PR#159: Add coverage targets to quickstart generated Makefile and
18483 make.bat. Thanks to Matthias Troffaes.
18484 · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
18486 data, sub section number that is larger depth than :tocdepth: is
18487 shrunk.
18488 · PR#260: Encode underscore in citation labels for latex export. Thanks
18490 to Lennart Fricke.
18491 · PR#264: Fix could not resolve xref for figure node with :name:
18493 option. Thanks to Takeshi Komiya.
18494 · PR#265: Fix could not capture caption of graphviz node by xref.
18496 Thanks to Takeshi Komiya.
18497 · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke
18499 Andersen.
18500 · Hyperlinks to all found nested names and template arguments
18502 (#1103).
18503 · Support for function types everywhere, e.g., in std::func‐
18505 tion<bool(int, int)> (#1013).
18506 · Support for virtual functions.
18508 · Changed interpretation of function arguments to following standard
18510 prototype declarations, i.e., void f(arg) means that arg is the
18511 type of the argument, instead of it being the name.
18512 · Updated tests.
18514 · Updated documentation with elaborate description of what declara‐
18516 tions are supported and how the namespace declarations influence
18517 declaration and cross-reference lookup.
18518 · Index names may be different now. Elements are indexed by their
18520 fully qualified name. It should be rather easy to change this be‐
18521 haviour and potentially index by namespaces/classes as well.
18522 · PR#258, #939: Add dedent option for code-block and literalinclude.
18524 Thanks to Zafar Siddiqui.
18525 · PR#268: Fix numbering section does not work at singlehtml mode. It
18527 still ad-hoc fix because there is a issue that section IDs are con‐
18528 flicted. Thanks to Takeshi Komiya.
18529 · PR#273, #1536: Fix RuntimeError with numbered circular toctree.
18531 Thanks to Takeshi Komiya.
18532 · PR#274: Set its URL as a default title value if URL appears in toc‐
18534 tree. Thanks to Takeshi Komiya.
18535 · PR#276, #1381: rfc and pep roles support custom link text. Thanks to
18537 Takeshi Komiya.
18538 · PR#277, #1513: highlights for function pointers in argument list of
18540 c:function. Thanks to Takeshi Komiya.
18541 · PR#278: Fix section entries were shown twice if toctree has been put
18543 under only directive. Thanks to Takeshi Komiya.
18544 · #1547: pgen2 tokenizer doesn’t recognize ... literal (Ellipsis for
18546 py3).
18547 · PR#294: On LaTeX builder, wrap float environment on writing lit‐
18549 eral_block to avoid separation of caption and body. Thanks to Takeshi
18550 Komiya.
18551 · PR#295, #1520: make.bat latexpdf mechanism to cd back to the current
18553 directory. Thanks to Peter Suter.
18554 · PR#297, #1571: Add imgpath property to all builders. It make easier
18556 to develop builder extensions. Thanks to Takeshi Komiya.
18557 · #1584: Point to master doc in HTML “top” link.
18559 · #1585: Autosummary of modules broken in Sphinx-1.2.3.
18561 · #1610: Sphinx cause AttributeError when MeCab search option is
18563 enabled and python-mecab is not installed.
18564 · #1674: Do not crash if a module’s __all__ is not a list of strings.
18566 · #1673: Fix crashes with nitpick_ignore and :doc: references.
18568 · #1686: ifconfig directive doesn’t care about default config values.
18570 · #1642: Fix only one search result appearing in Chrome.
18572 Documentation
18574 · Add clarification about the syntax of tags. (doc/markup/misc.rst)
18575 Release 1.2.3 (released Sep 1, 2014)
18577 Features added
18578 · #1518: sphinx-apidoc command now has a --version option to show ver‐
18579 sion information and exit
18580 · New locales: Hebrew, European Portuguese, Vietnamese.
18582 Bugs fixed
18584 · #636: Keep straight single quotes in literal blocks in the LaTeX
18585 build.
18586 · #1419: Generated i18n sphinx.js files are missing message catalog
18588 entries from ‘.js_t’ and ‘.html’. The issue was introduced from
18589 Sphinx-1.1
18590 · #1363: Fix i18n: missing python domain’s cross-references with cur‐
18592 rentmodule directive or currentclass directive.
18593 · #1444: autosummary does not create the description from attributes
18595 docstring.
18596 · #1457: In python3 environment, make linkcheck cause “Can’t convert
18598 ‘bytes’ object to str implicitly” error when link target url has a
18599 hash part. Thanks to Jorge_C.
18600 · #1467: Exception on Python3 if nonexistent method is specified by
18602 automethod
18603 · #1441: autosummary can’t handle nested classes correctly.
18605 · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
18607 user-friendly error message.
18608 · #1502: In autodoc, fix display of parameter defaults containing back‐
18610 slashes.
18611 · #1226: autodoc, autosummary: importing setup.py by automodule will
18613 invoke setup process and execute sys.exit(). Now sphinx avoids Syste‐
18614 mExit exception and emits warnings without unexpected termination.
18615 · #1503: py:function directive generate incorrectly signature when
18617 specifying a default parameter with an empty list []. Thanks to Geert
18618 Jansen.
18619 · #1508: Non-ASCII filename raise exception on make singlehtml, latex,
18621 man, texinfo and changes.
18622 · #1531: On Python3 environment, docutils.conf with ‘source_link=true’
18624 in the general section cause type error.
18625 · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
18627 with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
18628 · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
18630 Thanks to Takeshi Komiya.
18631 · #1477: gettext does not extract nodes.line in a table or list.
18633 · #1544: make text generates wrong table when it has empty table cells.
18635 · #1522: Footnotes from table get displayed twice in LaTeX. This prob‐
18637 lem has been appeared from Sphinx-1.2.1 by #949.
18638 · #508: Sphinx every time exit with zero when is invoked from setup.py
18640 command. ex. python setup.py build_sphinx -b doctest return zero
18641 even if doctest failed.
18642 Release 1.2.2 (released Mar 2, 2014)
18644 Bugs fixed
18645 · PR#211: When checking for existence of the html_logo file, check the
18646 full relative path and not the basename.
18647 · PR#212: Fix traceback with autodoc and __init__ methods without doc‐
18649 string.
18650 · PR#213: Fix a missing import in the setup command.
18652 · #1357: Option names documented by option are now again allowed to not
18654 start with a dash or slash, and referencing them will work correctly.
18655 · #1358: Fix handling of image paths outside of the source directory
18657 when using the “wildcard” style reference.
18658 · #1374: Fix for autosummary generating overly-long summaries if first
18660 line doesn’t end with a period.
18661 · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
18663 · #1391: Actually prevent using “pngmath” and “mathjax” extensions at
18665 the same time in sphinx-quickstart.
18666 · #1386: Fix bug preventing more than one theme being added by the
18668 entry point mechanism.
18669 · #1370: Ignore “toctree” nodes in text writer, instead of raising.
18671 · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
18673 present.
18674 · #1367: Fix a change of PR#96 that break sphinx.util.doc‐
18676 fields.Field.make_field interface/behavior for item argument usage.
18677 Documentation
18679 · Extended the documentation about building extensions.
18680 Release 1.2.1 (released Jan 19, 2014)
18682 Bugs fixed
18683 · #1335: Fix autosummary template overloading with exclamation prefix
18684 like {% extends "!autosummary/class.rst" %} cause infinite recursive
18685 function call. This was caused by PR#181.
18686 · #1337: Fix autodoc with autoclass_content="both" uses useless
18688 object.__init__ docstring when class does not have __init__. This
18689 was caused by a change for #1138.
18690 · #1340: Can’t search alphabetical words on the HTML quick search gen‐
18692 erated with language=’ja’.
18693 · #1319: Do not crash if the html_logo file does not exist.
18695 · #603: Do not use the HTML-ized title for building the search index
18697 (that resulted in “literal” being found on every page with a literal
18698 in the title).
18699 · #751: Allow production lists longer than a page in LaTeX by using
18701 longtable.
18702 · #764: Always look for stopwords lowercased in JS search.
18704 · #814: autodoc: Guard against strange type objects that don’t have
18706 __bases__.
18707 · #932: autodoc: Do not crash if __doc__ is not a string.
18709 · #933: Do not crash if an option value is malformed (contains spaces
18711 but no option name).
18712 · #908: On Python 3, handle error messages from LaTeX correctly in the
18714 pngmath extension.
18715 · #943: In autosummary, recognize “first sentences” to pull from the
18717 docstring if they contain uppercase letters.
18718 · #923: Take the entire LaTeX document into account when caching png‐
18720 math-generated images. This rebuilds them correctly when png‐
18721 math_latex_preamble changes.
18722 · #901: Emit a warning when using docutils’ new “math” markup without a
18724 Sphinx math extension active.
18725 · #845: In code blocks, when the selected lexer fails, display line
18727 numbers nevertheless if configured.
18728 · #929: Support parsed-literal blocks in LaTeX output correctly.
18730 · #949: Update the tabulary.sty packed with Sphinx.
18732 · #1050: Add anonymous labels into objects.inv to be referenced via
18734 intersphinx.
18735 · #1095: Fix print-media stylesheet being included always in the
18737 “scrolls” theme.
18738 · #1085: Fix current classname not getting set if class description has
18740 :noindex: set.
18741 · #1181: Report option errors in autodoc directives more gracefully.
18743 · #1155: Fix autodocumenting C-defined methods as attributes in Python
18745 3.
18746 · #1233: Allow finding both Python classes and exceptions with the
18748 “class” and “exc” roles in intersphinx.
18749 · #1198: Allow “image” for the “figwidth” option of the figure direc‐
18751 tive as documented by docutils.
18752 · #1152: Fix pycode parsing errors of Python 3 code by including two
18754 grammar versions for Python 2 and 3, and loading the appropriate ver‐
18755 sion for the running Python version.
18756 · #1017: Be helpful and tell the user when the argument to option does
18758 not match the required format.
18759 · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
18761 the store environment for changes to have effect.
18762 · #1072: In the JS search, fix issues searching for upper-cased words
18764 by lowercasing words before stemming.
18765 · #1299: Make behavior of the math directive more consistent and avoid
18767 producing empty environments in LaTeX output.
18768 · #1308: Strip HTML tags from the content of “raw” nodes before feeding
18770 it to the search indexer.
18771 · #1249: Fix duplicate LaTeX page numbering for manual documents.
18773 · #1292: In the linkchecker, retry HEAD requests when denied by HTTP
18775 405. Also make the redirect code apparent and tweak the output a bit
18776 to be more obvious.
18777 · #1285: Avoid name clashes between C domain objects and section
18779 titles.
18780 · #848: Always take the newest code in incremental rebuilds with the
18782 sphinx.ext.viewcode extension.
18783 · #979, #1266: Fix exclude handling in sphinx-apidoc.
18785 · #1302: Fix regression in sphinx.ext.inheritance_diagram when docu‐
18787 menting classes that can’t be pickled.
18788 · #1316: Remove hard-coded font-face resources from epub theme.
18790 · #1329: Fix traceback with empty translation msgstr in .po files.
18792 · #1300: Fix references not working in translated documents in some
18794 instances.
18795 · #1283: Fix a bug in the detection of changed files that would try to
18797 access doctrees of deleted documents.
18798 · #1330: Fix exclude_patterns behavior with subdirectories in the
18800 html_static_path.
18801 · #1323: Fix emitting empty <ul> tags in the HTML writer, which is not
18803 valid HTML.
18804 · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
18806 Documentation
18808 · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
18809 Release 1.2 (released Dec 10, 2013)
18811 Features added
18812 · Added sphinx.version_info tuple for programmatic checking of the
18813 Sphinx version.
18814 Incompatible changes
18816 · Removed the sphinx.ext.refcounting extension – it is very specific to
18817 CPython and has no place in the main distribution.
18818 Bugs fixed
18820 · Restore versionmodified CSS class for versionadded/changed and depre‐
18821 cated directives.
18822 · PR#181: Fix html_theme_path = ['.'] is a trigger of rebuild all docu‐
18824 ments always (This change keeps the current “theme changes cause a
18825 rebuild” feature).
18826 · #1296: Fix invalid charset in HTML help generated HTML files for
18828 default locale.
18829 · PR#190: Fix gettext does not extract figure caption and rubric title
18831 inside other blocks. Thanks to Michael Schlenker.
18832 · PR#176: Make sure setup_command test can always import Sphinx. Thanks
18834 to Dmitry Shachnev.
18835 · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
18837 · #1269: Fix ResourceWarnings with Python 3.2 or later.
18839 · #1138: Fix: When autodoc_docstring_signature = True and auto‐
18841 class_content = 'init' or 'both', __init__ line should be removed
18842 from class documentation.
18843 Release 1.2 beta3 (released Oct 3, 2013)
18845 Features added
18846 · The Sphinx error log files will now include a list of the loaded
18847 extensions for help in debugging.
18848 Incompatible changes
18850 · PR#154: Remove “sphinx” prefix from LaTeX class name except ‘sphinx‐
18851 manual’ and ‘sphinxhowto’. Now you can use your custom document class
18852 without ‘sphinx’ prefix. Thanks to Erik B.
18853 Bugs fixed
18855 · #1265: Fix i18n: crash when translating a section name that is
18856 pointed to from a named target.
18857 · A wrong condition broke the search feature on first page that is usu‐
18859 ally index.rst. This issue was introduced in 1.2b1.
18860 · #703: When Sphinx can’t decode filenames with non-ASCII characters,
18862 Sphinx now catches UnicodeError and will continue if possible instead
18863 of raising the exception.
18864 Release 1.2 beta2 (released Sep 17, 2013)
18866 Features added
18867 · apidoc now ignores “_private” modules by default, and has an option
18868 -P to include them.
18869 · apidoc now has an option to not generate headings for packages and
18871 modules, for the case that the module docstring already includes a
18872 reST heading.
18873 · PR#161: apidoc can now write each module to a standalone page instead
18875 of combining all modules in a package on one page.
18876 · Builders: rebuild i18n target document when catalog updated.
18878 · Support docutils.conf ‘writers’ and ‘html4css1 writer’ section in the
18880 HTML writer. The latex, manpage and texinfo writers also support
18881 their respective ‘writers’ sections.
18882 · The new html_extra_path config value allows to specify directories
18884 with files that should be copied directly to the HTML output direc‐
18885 tory.
18886 · Autodoc directives for module data and attributes now support an
18888 annotation option, so that the default display of the data/attribute
18889 value can be overridden.
18890 · PR#136: Autodoc directives now support an imported-members option to
18892 include members imported from different modules.
18893 · New locales: Macedonian, Sinhala, Indonesian.
18895 · Theme package collection by using setuptools plugin mechanism.
18897 Incompatible changes
18899 · PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Cre‐
18900 ation-Date that was generated by gettext builder. Thanks to masklinn
18901 and Jakub Wilk.
18902 Bugs fixed
18904 · PR#132: Updated jQuery version to 1.8.3.
18905 · PR#141, #982: Avoid crash when writing PNG file using Python 3.
18907 Thanks to Marcin Wojdyr.
18908 · PR#145: In parallel builds, sphinx drops second document file to
18910 write. Thanks to tychoish.
18911 · PR#151: Some styling updates to tables in LaTeX.
18913 · PR#153: The “extensions” config value can now be overridden.
18915 · PR#155: Added support for some C++11 function qualifiers.
18917 · Fix: ‘make gettext’ caused UnicodeDecodeError when templates contain
18919 utf-8 encoded strings.
18920 · #828: use inspect.getfullargspec() to be able to document functions
18922 with keyword-only arguments on Python 3.
18923 · #1090: Fix i18n: multiple cross references (term, ref, doc) in the
18925 same line return the same link.
18926 · #1157: Combination of ‘globaltoc.html’ and hidden toctree caused
18928 exception.
18929 · #1159: fix wrong generation of objects inventory for Python modules,
18931 and add a workaround in intersphinx to fix handling of affected
18932 inventories.
18933 · #1160: Citation target missing caused an AssertionError.
18935 · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
18937 · #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued
18939 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexan‐
18940 der Dupuy.
18941 · #1185: Don’t crash when a Python module has a wrong or no encoding
18943 declared, and non-ASCII characters are included.
18944 · #1188: sphinx-quickstart raises UnicodeEncodeError if “Project ver‐
18946 sion” includes non-ASCII characters.
18947 · #1189: “Title underline is too short” WARNING is given when using
18949 fullwidth characters to “Project name” on quickstart.
18950 · #1190: Output TeX/texinfo/man filename has no basename (only exten‐
18952 sion) when using non-ASCII characters in the “Project name” on quick‐
18953 start.
18954 · #1192: Fix escaping problem for hyperlinks in the manpage writer.
18956 · #1193: Fix i18n: multiple link references in the same line return the
18958 same link.
18959 · #1176: Fix i18n: footnote reference number missing for auto numbered
18961 named footnote and auto symbol footnote.
18962 · PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to
18964 tychoish.
18965 · #1204: Fix wrong generation of links to local intersphinx targets.
18967 · #1206: Fix i18n: gettext did not translate admonition directive’s
18969 title.
18970 · #1232: Sphinx generated broken ePub files on Windows.
18972 · #1259: Guard the debug output call when emitting events; to prevent
18974 the repr() implementation of arbitrary objects causing build fail‐
18975 ures.
18976 · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
18978 · #1234: Ignoring the string consists only of white-space characters.
18980 Release 1.2 beta1 (released Mar 31, 2013)
18982 Incompatible changes
18983 · Removed sphinx.util.compat.directive_dwim() and sphinx.roles.xfil‐
18984 eref_role() which were deprecated since version 1.0.
18985 · PR#122: the files given in latex_additional_files now override TeX
18987 files included by Sphinx, such as sphinx.sty.
18988 · PR#124: the node generated by versionadded, versionchanged and depre‐
18990 cated directives now includes all added markup (such as “New in ver‐
18991 sion X”) as child nodes, and no additional text must be generated by
18992 writers.
18993 · PR#99: the seealso directive now generates admonition nodes instead
18995 of the custom seealso node.
18996 Features added
18998 · Markup
18999 · The toctree directive and the toctree() template function now have
19001 an includehidden option that includes hidden toctree entries (bugs
19002 #790 and #1047). A bug in the maxdepth option for the toctree()
19003 template function has been fixed (bug #1046).
19004 · PR#99: Strip down seealso directives to normal admonitions. This
19006 removes their unusual CSS classes (admonition-see-also), inconsis‐
19007 tent LaTeX admonition title (“See Also” instead of “See also”), and
19008 spurious indentation in the text builder.
19009 · HTML builder
19011 · #783: Create a link to full size image if it is scaled with width
19013 or height.
19014 · #1067: Improve the ordering of the JavaScript search results:
19016 matches in titles come before matches in full text, and object
19017 results are better categorized. Also implement a pluggable search
19018 scorer.
19019 · #1053: The “rightsidebar” and “collapsiblesidebar” HTML theme
19021 options now work together.
19022 · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
19024 · Texinfo builder
19026 · An “Index” node is no longer added when there are no entries.
19028 · “deffn” categories are no longer capitalized if they contain capi‐
19030 tal letters.
19031 · desc_annotation nodes are now rendered.
19033 · strong and emphasis nodes are now formatted like literals. The rea‐
19035 son for this is because the standard Texinfo markup (*strong* and
19036 _emphasis_) resulted in confusing output due to the common usage of
19037 using these constructs for documenting parameter names.
19038 · Field lists formatting has been tweaked to better display “Info
19040 field lists”.
19041 · system_message and problematic nodes are now formatted in a similar
19043 fashion as done by the text builder.
19044 · “en-dash” and “em-dash” conversion of hyphens is no longer per‐
19046 formed in option directive signatures.
19047 · @ref is now used instead of @pxref for cross-references which pre‐
19049 vents the word “see” from being added before the link (does not
19050 affect the Info output).
19051 · The @finalout command has been added for better TeX output.
19053 · transition nodes are now formatted using underscores (“_”) instead
19055 of asterisks (“*”).
19056 · The default value for the paragraphindent has been changed from 2
19058 to 0 meaning that paragraphs are no longer indented by default.
19059 · #1110: A new configuration value texinfo_no_detailmenu has been
19061 added for controlling whether a @detailmenu is added in the “Top”
19062 node’s menu.
19063 · Detailed menus are no longer created except for the “Top” node.
19065 · Fixed an issue where duplicate domain indices would result in
19067 invalid output.
19068 · LaTeX builder:
19070 · PR#115: Add 'transition' item in latex_elements for customizing how
19072 transitions are displayed. Thanks to Jeff Klukas.
19073 · PR#114: The LaTeX writer now includes the “cmap” package by
19075 default. The 'cmappkg' item in latex_elements can be used to con‐
19076 trol this. Thanks to Dmitry Shachnev.
19077 · The 'fontpkg' item in latex_elements now defaults to '' when the
19079 language uses the Cyrillic script. Suggested by Dmitry Shachnev.
19080 · The latex_documents, texinfo_documents, and man_pages configuration
19082 values will be set to default values based on the master_doc if not
19083 explicitly set in conf.py. Previously, if these values were not
19084 set, no output would be generated by their respective builders.
19085 · Internationalization:
19087 · Add i18n capabilities for custom templates. For example: The
19089 Sphinx reference documentation in doc directory provides a
19090 sphinx.pot file with message strings from doc/_templates/*.html
19091 when using make gettext.
19092 · PR#61,#703: Add support for non-ASCII filename handling.
19094 · Other builders:
19096 · Added the Docutils-native XML and pseudo-XML builders. See XML‐
19098 Builder and PseudoXMLBuilder.
19099 · PR#45: The linkcheck builder now checks #anchors for existence.
19101 · PR#123, #1106: Add epub_use_index configuration value. If pro‐
19103 vided, it will be used instead of html_use_index for epub builder.
19104 · PR#126: Add epub_tocscope configuration value. The setting controls
19106 the generation of the epub toc. The user can now also include hid‐
19107 den toc entries.
19108 · PR#112: Add epub_show_urls configuration value.
19110 · Extensions:
19112 · PR#52: special_members flag to autodoc now behaves like members.
19114 · PR#47: Added sphinx.ext.linkcode extension.
19116 · PR#25: In inheritance diagrams, the first line of the class doc‐
19118 string is now the tooltip for the class.
19119 · Command-line interfaces:
19121 · PR#75: Added --follow-links option to sphinx-apidoc.
19123 · #869: sphinx-build now has the option -T for printing the full
19125 traceback after an unhandled exception.
19126 · sphinx-build now supports the standard --help and --version
19128 options.
19129 · sphinx-build now provides more specific error messages when called
19131 with invalid options or arguments.
19132 · sphinx-build now has a verbose option -v which can be repeated for
19134 greater effect. A single occurrence provides a slightly more ver‐
19135 bose output than normal. Two or more occurrences of this option
19136 provides more detailed output which may be useful for debugging.
19137 · Locales:
19139 · PR#74: Fix some Russian translation.
19141 · PR#54: Added Norwegian bokmaal translation.
19143 · PR#35: Added Slovak translation.
19145 · PR#28: Added Hungarian translation.
19147 · #1113: Add Hebrew locale.
19149 · #1097: Add Basque locale.
19151 · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
19153 · #1012: Update Estonian translation.
19155 · Optimizations:
19157 · Speed up building the search index by caching the results of the
19159 word stemming routines. Saves about 20 seconds when building the
19160 Python documentation.
19161 · PR#108: Add experimental support for parallel building with a new
19163 sphinx-build -j option.
19164 Documentation
19166 · PR#88: Added the “Sphinx Developer’s Guide” (doc/devguide.rst) which
19167 outlines the basic development process of the Sphinx project.
19168 · Added a detailed “Installing Sphinx” document (doc/install.rst).
19170 Bugs fixed
19172 · PR#124: Fix paragraphs in versionmodified are ignored when it has no
19173 dangling paragraphs. Fix wrong html output (nested <p> tag). Fix
19174 versionmodified is not translatable. Thanks to Nozomu Kaneko.
19175 · PR#111: Respect add_autodoc_attrgetter() even when inherited-members
19177 is set. Thanks to A. Jesse Jiryu Davis.
19178 · PR#97: Fix footnote handling in translated documents.
19180 · Fix text writer not handling visit_legend for figure directive con‐
19182 tents.
19183 · Fix text builder not respecting wide/fullwidth characters: title
19185 underline width, table layout width and text wrap width.
19186 · Fix leading space in LaTeX table header cells.
19188 · #1132: Fix LaTeX table output for multi-row cells in the first col‐
19190 umn.
19191 · #1128: Fix Unicode errors when trying to format time strings with a
19193 non-standard locale.
19194 · #1127: Fix traceback when autodoc tries to tokenize a non-Python
19196 file.
19197 · #1126: Fix double-hyphen to en-dash conversion in wrong places such
19199 as command-line option names in LaTeX.
19200 · #1123: Allow whitespaces in filenames given to literalinclude.
19202 · #1120: Added improvements about i18n for themes “basic”, “haiku” and
19204 “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
19205 · #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero
19207 G.
19208 · #1117: Handle .pyx files in sphinx-apidoc.
19210 · #1112: Avoid duplicate download files when referenced from documents
19212 in different ways (absolute/relative).
19213 · #1111: Fix failure to find uppercase words in search when
19215 html_search_language is ‘ja’. Thanks to Tomo Saito.
19216 · #1108: The text writer now correctly numbers enumerated lists with
19218 non-default start values (based on patch by Ewan Edwards).
19219 · #1102: Support multi-context “with” statements in autodoc.
19221 · #1090: Fix gettext not extracting glossary terms.
19223 · #1074: Add environment version info to the generated search index to
19225 avoid compatibility issues with old builds.
19226 · #1070: Avoid un-pickling issues when running Python 3 and the saved
19228 environment was created under Python 2.
19229 · #1069: Fixed error caused when autodoc would try to format signatures
19231 of “partial” functions without keyword arguments (patch by Artur Gas‐
19232 par).
19233 · #1062: sphinx.ext.autodoc use __init__ method signature for class
19235 signature.
19236 · #1055: Fix web support with relative path to source directory.
19238 · #1043: Fix sphinx-quickstart asking again for yes/no questions
19240 because input() returns values with an extra ‘r’ on Python 3.2.0 +
19241 Windows. Thanks to Régis Décamps.
19242 · #1041: Fix failure of the cpp domain parser to parse a const type
19244 with a modifier.
19245 · #1038: Fix failure of the cpp domain parser to parse C+11 “static
19247 constexpr” declarations. Thanks to Jakub Wilk.
19248 · #1029: Fix intersphinx_mapping values not being stable if the mapping
19250 has plural key/value set with Python 3.3.
19251 · #1028: Fix line block output in the text builder.
19253 · #1024: Improve Makefile/make.bat error message if Sphinx is not
19255 found. Thanks to Anatoly Techtonik.
19256 · #1018: Fix “container” directive handling in the text builder.
19258 · #1015: Stop overriding jQuery contains() in the JavaScript.
19260 · #1010: Make pngmath images transparent by default; IE7+ should handle
19262 it.
19263 · #1008: Fix test failures with Python 3.3.
19265 · #995: Fix table-of-contents and page numbering for the LaTeX “howto”
19267 class.
19268 · #976: Fix gettext does not extract index entries.
19270 · PR#72: #975: Fix gettext not extracting definition terms before docu‐
19272 tils 0.10.
19273 · #961: Fix LaTeX output for triple quotes in code snippets.
19275 · #958: Do not preserve environment.pickle after a failed build.
19277 · #955: Fix i18n transformation.
19279 · #940: Fix gettext does not extract figure caption.
19281 · #920: Fix PIL packaging issue that allowed to import Image without
19283 PIL namespace. Thanks to Marc Schlaich.
19284 · #723: Fix the search function on local files in WebKit based
19286 browsers.
19287 · #440: Fix coarse timestamp resolution in some filesystem generating a
19289 wrong list of outdated files.
19290 Release 1.1.3 (Mar 10, 2012)
19292 · PR#40: Fix safe_repr function to decode bytestrings with non-ASCII
19293 characters correctly.
19294 · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
19296 · PR#34: Restore Python 2.4 compatibility.
19298 · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
19300 the document class.
19301 · #695: When the highlight language “python” is specified explicitly,
19303 do not try to parse the code to recognize non-Python snippets.
19304 · #859: Fix exception under certain circumstances when not finding
19306 appropriate objects to link to.
19307 · #860: Do not crash when encountering invalid doctest examples, just
19309 emit a warning.
19310 · #864: Fix crash with some settings of modindex_common_prefix.
19312 · #862: Fix handling of -D and -A options on Python 3.
19314 · #851: Recognize and warn about circular toctrees, instead of running
19316 into recursion errors.
19317 · #853: Restore compatibility with docutils trunk.
19319 · #852: Fix HtmlHelp index entry links again.
19321 · #854: Fix inheritance_diagram raising attribute errors on builtins.
19323 · #832: Fix crashes when putting comments or lone terms in a glossary.
19325 · #834, #818: Fix HTML help language/encoding mapping for all Sphinx
19327 supported languages.
19328 · #844: Fix crashes when dealing with Unicode output in doctest exten‐
19330 sion.
19331 · #831: Provide --project flag in setup_command as advertised.
19333 · #875: Fix reading config files under Python 3.
19335 · #876: Fix quickstart test under Python 3.
19337 · #870: Fix spurious KeyErrors when removing documents.
19339 · #892: Fix single-HTML builder misbehaving with the master document in
19341 a subdirectory.
19342 · #873: Fix assertion errors with empty only directives.
19344 · #816: Fix encoding issues in the Qt help builder.
19346 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
19348 · #809: Include custom fixers in the source distribution.
19349 Release 1.1.1 (Nov 1, 2011)
19351 · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
19352 · #792: Include “sphinx-apidoc” in the source distribution.
19354 · #797: Don’t crash on a misformatted glossary.
19356 · #801: Make intersphinx work properly without SSL support.
19358 · #805: Make the Sphinx.add_index_to_domain method work correctly.
19360 · #780: Fix Python 2.5 compatibility.
19362 Release 1.1 (Oct 9, 2011)
19364 Incompatible changes
19365 · The py:module directive doesn’t output its platform option value any‐
19366 more. (It was the only thing that the directive did output, and
19367 therefore quite inconsistent.)
19368 · Removed support for old dependency versions; requirements are now:
19370 · Pygments >= 1.2
19372 · Docutils >= 0.7
19374 · Jinja2 >= 2.3
19376 Features added
19378 · Added Python 3.x support.
19379 · New builders and subsystems:
19381 · Added a Texinfo builder.
19383 · Added i18n support for content, a gettext builder and related util‐
19385 ities.
19386 · Added the websupport library and builder.
19388 · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
19390 source files containing autodoc directives to document modules and
19391 packages.
19392 · #273: Add an API for adding full-text search support for languages
19394 other than English. Add support for Japanese.
19395 · Markup:
19397 · #138: Added an index role, to make inline index entries.
19399 · #454: Added more index markup capabilities: marking see/seealso
19401 entries, and main entries for a given key.
19402 · #460: Allowed limiting the depth of section numbers for HTML using
19404 the toctree’s numbered option.
19405 · #586: Implemented improved glossary markup which allows multiple
19407 terms per definition.
19408 · #478: Added py:decorator directive to describe decorators.
19410 · C++ domain now supports array definitions.
19412 · C++ domain now supports doc fields (:param x: inside directives).
19414 · Section headings in only directives are now correctly handled.
19416 · Added emphasize-lines option to source code directives.
19418 · #678: C++ domain now supports superclasses.
19420 · HTML builder:
19422 · Added pyramid theme.
19424 · #559: html_add_permalinks is now a string giving the text to dis‐
19426 play in permalinks.
19427 · #259: HTML table rows now have even/odd CSS classes to enable
19429 “Zebra styling”.
19430 · #554: Add theme option sidebarwidth to the basic theme.
19432 · Other builders:
19434 · #516: Added new value of the latex_show_urls option to show the
19436 URLs in footnotes.
19437 · #209: Added text_newlines and text_sectionchars config values.
19439 · Added man_show_urls config value.
19441 · #472: linkcheck builder: Check links in parallel, use HTTP HEAD
19443 requests and allow configuring the timeout. New config values:
19444 linkcheck_timeout and linkcheck_workers.
19445 · #521: Added linkcheck_ignore config value.
19447 · #28: Support row/colspans in tables in the LaTeX builder.
19449 · Configuration and extensibility:
19451 · #537: Added nitpick_ignore.
19453 · #306: Added env-get-outdated event.
19455 · Application.add_stylesheet() now accepts full URIs.
19457 · Autodoc:
19459 · #564: Add autodoc_docstring_signature. When enabled (the default),
19461 autodoc retrieves the signature from the first line of the doc‐
19462 string, if it is found there.
19463 · #176: Provide private-members option for autodoc directives.
19465 · #520: Provide special-members option for autodoc directives.
19467 · #431: Doc comments for attributes can now be given on the same line
19469 as the assignment.
19470 · #437: autodoc now shows values of class data attributes.
19472 · autodoc now supports documenting the signatures of functools.par‐
19474 tial objects.
19475 · Other extensions:
19477 · Added the sphinx.ext.mathjax extension.
19479 · #443: Allow referencing external graphviz files.
19481 · Added inline option to graphviz directives, and fixed the default
19483 (block-style) in LaTeX output.
19484 · #590: Added caption option to graphviz directives.
19486 · #553: Added testcleanup blocks in the doctest extension.
19488 · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
19490 · #367: Added automatic exclusion of hidden members in inheritance
19492 diagrams, and an option to selectively enable it.
19493 · Added pngmath_add_tooltips.
19495 · The math extension displaymath directives now support name in addi‐
19497 tion to label for giving the equation label, for compatibility with
19498 Docutils.
19499 · New locales:
19501 · #221: Added Swedish locale.
19503 · #526: Added Iranian locale.
19505 · #694: Added Latvian locale.
19507 · Added Nepali locale.
19509 · #714: Added Korean locale.
19511 · #766: Added Estonian locale.
19513 · Bugs fixed:
19515 · #778: Fix “hide search matches” link on pages linked by search.
19517 · Fix the source positions referenced by the “viewcode” extension.
19519 Release 1.0.8 (Sep 23, 2011)
19521 · #627: Fix tracebacks for AttributeErrors in autosummary generation.
19522 · Fix the abbr role when the abbreviation has newlines in it.
19524 · #727: Fix the links to search results with custom object types.
19526 · #648: Fix line numbers reported in warnings about undefined refer‐
19528 ences.
19529 · #696, #666: Fix C++ array definitions and template arguments that are
19531 not type names.
19532 · #633: Allow footnotes in section headers in LaTeX output.
19534 · #616: Allow keywords to be linked via intersphinx.
19536 · #613: Allow Unicode characters in production list token names.
19538 · #720: Add dummy visitors for graphviz nodes for text and man.
19540 · #704: Fix image file duplication bug.
19542 · #677: Fix parsing of multiple signatures in C++ domain.
19544 · #637: Ignore Emacs lock files when looking for source files.
19546 · #544: Allow .pyw extension for importable modules in autodoc.
19548 · #700: Use $(MAKE) in quickstart-generated Makefiles.
19550 · #734: Make sidebar search box width consistent in browsers.
19552 · #644: Fix spacing of centered figures in HTML output.
19554 · #767: Safely encode SphinxError messages when printing them to
19556 sys.stderr.
19557 · #611: Fix LaTeX output error with a document with no sections but a
19559 link target.
19560 · Correctly treat built-in method descriptors as methods in autodoc.
19562 · #706: Stop monkeypatching the Python textwrap module.
19564 · #657: viewcode now works correctly with source files that have
19566 non-ASCII encoding.
19567 · #669: Respect the noindex flag option in py:module directives.
19569 · #675: Fix IndexErrors when including nonexisting lines with literal‐
19571 include.
19572 · #676: Respect custom function/method parameter separator strings.
19574 · #682: Fix JS incompatibility with jQuery >= 1.5.
19576 · #693: Fix double encoding done when writing HTMLHelp .hhk files.
19578 · #647: Do not apply SmartyPants in parsed-literal blocks.
19580 · C++ domain now supports array definitions.
19582 Release 1.0.7 (Jan 15, 2011)
19584 · #347: Fix wrong generation of directives of static methods in auto‐
19585 summary.
19586 · #599: Import PIL as from PIL import Image.
19588 · #558: Fix longtables with captions in LaTeX output.
19590 · Make token references work as hyperlinks again in LaTeX output.
19592 · #572: Show warnings by default when reference labels cannot be found.
19594 · #536: Include line number when complaining about missing reference
19596 targets in nitpicky mode.
19597 · #590: Fix inline display of graphviz diagrams in LaTeX output.
19599 · #589: Build using app.build() in setup command.
19601 · Fix a bug in the inheritance diagram exception that caused base
19603 classes to be skipped if one of them is a builtin.
19604 · Fix general index links for C++ domain objects.
19606 · #332: Make admonition boundaries in LaTeX output visible.
19608 · #573: Fix KeyErrors occurring on rebuild after removing a file.
19610 · Fix a traceback when removing files with globbed toctrees.
19612 · If an autodoc object cannot be imported, always re-read the document
19614 containing the directive on next build.
19615 · If an autodoc object cannot be imported, show the full traceback of
19617 the import error.
19618 · Fix a bug where the removal of download files and images wasn’t
19620 noticed.
19621 · #571: Implement ~ cross-reference prefix for the C domain.
19623 · Fix regression of LaTeX output with the fix of #556.
19625 · #568: Fix lookup of class attribute documentation on descriptors so
19627 that comment documentation now works.
19628 · Fix traceback with only directives preceded by targets.
19630 · Fix tracebacks occurring for duplicate C++ domain objects.
19632 · Fix JavaScript domain links to objects with $ in their name.
19634 Release 1.0.6 (Jan 04, 2011)
19636 · #581: Fix traceback in Python domain for empty cross-reference tar‐
19637 gets.
19638 · #283: Fix literal block display issues on Chrome browsers.
19640 · #383, #148: Support sorting a limited range of accented characters in
19642 the general index and the glossary.
19643 · #570: Try decoding -D and -A command-line arguments with the locale’s
19645 preferred encoding.
19646 · #528: Observe locale_dirs when looking for the JS translations file.
19648 · #574: Add special code for better support of Japanese documents in
19650 the LaTeX builder.
19651 · Regression of #77: If there is only one parameter given with :param:
19653 markup, the bullet list is now suppressed again.
19654 · #556: Fix missing paragraph breaks in LaTeX output in certain situa‐
19656 tions.
19657 · #567: Emit the autodoc-process-docstring event even for objects with‐
19659 out a docstring so that it can add content.
19660 · #565: In the LaTeX builder, not only literal blocks require different
19662 table handling, but also quite a few other list-like block elements.
19663 · #515: Fix tracebacks in the viewcode extension for Python objects
19665 that do not have a valid signature.
19666 · Fix strange reports of line numbers for warnings generated from
19668 autodoc-included docstrings, due to different behavior depending on
19669 docutils version.
19670 · Several fixes to the C++ domain.
19672 Release 1.0.5 (Nov 12, 2010)
19674 · #557: Add CSS styles required by docutils 0.7 for aligned images and
19675 figures.
19676 · In the Makefile generated by LaTeX output, do not delete pdf files on
19678 clean; they might be required images.
19679 · #535: Fix LaTeX output generated for line blocks.
19681 · #544: Allow .pyw as a source file extension.
19683 Release 1.0.4 (Sep 17, 2010)
19685 · #524: Open intersphinx inventories in binary mode on Windows, since
19686 version 2 contains zlib-compressed data.
19687 · #513: Allow giving non-local URIs for JavaScript files, e.g. in the
19689 JSMath extension.
19690 · #512: Fix traceback when intersphinx_mapping is empty.
19692 Release 1.0.3 (Aug 23, 2010)
19694 · #495: Fix internal vs. external link distinction for links coming
19695 from a docutils table-of-contents.
19696 · #494: Fix the maxdepth option for the toctree() template callable
19698 when used with collapse=True.
19699 · #507: Fix crash parsing Python argument lists containing brackets in
19701 string literals.
19702 · #501: Fix regression when building LaTeX docs with figures that don’t
19704 have captions.
19705 · #510: Fix inheritance diagrams for classes that are not picklable.
19707 · #497: Introduce separate background color for the sidebar collapse
19709 button, making it easier to see.
19710 · #502, #503, #496: Fix small layout bugs in several builtin themes.
19712 Release 1.0.2 (Aug 14, 2010)
19714 · #490: Fix cross-references to objects of types added by the
19715 add_object_type() API function.
19716 · Fix handling of doc field types for different directive types.
19718 · Allow breaking long signatures, continuing with backlash-escaped new‐
19720 lines.
19721 · Fix unwanted styling of C domain references (because of a namespace
19723 clash with Pygments styles).
19724 · Allow references to PEPs and RFCs with explicit anchors.
19726 · #471: Fix LaTeX references to figures.
19728 · #482: When doing a non-exact search, match only the given type of
19730 object.
19731 · #481: Apply non-exact search for Python reference targets with .name
19733 for modules too.
19734 · #484: Fix crash when duplicating a parameter in an info field list.
19736 · #487: Fix setting the default role to one provided by the oldcmarkup
19738 extension.
19739 · #488: Fix crash when json-py is installed, which provides a json mod‐
19741 ule but is incompatible to simplejson.
19742 · #480: Fix handling of target naming in intersphinx.
19744 · #486: Fix removal of ! for all cross-reference roles.
19746 Release 1.0.1 (Jul 27, 2010)
19748 · #470: Fix generated target names for reST domain objects; they are
19749 not in the same namespace.
19750 · #266: Add Bengali language.
19752 · #473: Fix a bug in parsing JavaScript object names.
19754 · #474: Fix building with SingleHTMLBuilder when there is no toctree.
19756 · Fix display names for objects linked to by intersphinx with explicit
19758 targets.
19759 · Fix building with the JSON builder.
19761 · Fix hyperrefs in object descriptions for LaTeX.
19763 Release 1.0 (Jul 23, 2010)
19765 Incompatible changes
19766 · Support for domains has been added. A domain is a collection of
19767 directives and roles that all describe objects belonging together,
19768 e.g. elements of a programming language. A few builtin domains are
19769 provided:
19770 · Python
19772 · C
19774 · C++
19776 · JavaScript
19778 · reStructuredText
19780 · The old markup for defining and linking to C directives is now depre‐
19782 cated. It will not work anymore in future versions without activat‐
19783 ing the oldcmarkup extension; in Sphinx 1.0, it is activated by
19784 default.
19785 · Removed support for old dependency versions; requirements are now:
19787 · docutils >= 0.5
19789 · Jinja2 >= 2.2
19791 · Removed deprecated elements:
19793 · exclude_dirs config value
19795 · sphinx.builder module
19797 Features added
19799 · General:
19800 · Added a “nitpicky” mode that emits warnings for all missing refer‐
19802 ences. It is activated by the sphinx-build -n command-line switch
19803 or the nitpicky config value.
19804 · Added latexpdf target in quickstart Makefile.
19806 · Markup:
19808 · The menuselection and guilabel roles now support ampersand acceler‐
19810 ators.
19811 · New more compact doc field syntax is now recognized: :param type
19813 name: description.
19814 · Added tab-width option to literalinclude directive.
19816 · Added titlesonly option to toctree directive.
19818 · Added the prepend and append options to the literalinclude direc‐
19820 tive.
19821 · #284: All docinfo metadata is now put into the document metadata,
19823 not just the author.
19824 · The ref role can now also reference tables by caption.
19826 · The include directive now supports absolute paths, which are inter‐
19828 preted as relative to the source directory.
19829 · In the Python domain, references like :func:`.name` now look for
19831 matching names with any prefix if no direct match is found.
19832 · Configuration:
19834 · Added rst_prolog config value.
19836 · Added html_secnumber_suffix config value to control section number‐
19838 ing format.
19839 · Added html_compact_lists config value to control docutils’ compact
19841 lists feature.
19842 · The html_sidebars config value can now contain patterns as keys,
19844 and the values can be lists that explicitly select which sidebar
19845 templates should be rendered. That means that the builtin sidebar
19846 contents can be included only selectively.
19847 · html_static_path can now contain single file entries.
19849 · The new universal config value exclude_patterns makes the old
19851 unused_docs, exclude_trees and exclude_dirnames obsolete.
19852 · Added html_output_encoding config value.
19854 · Added the latex_docclass config value and made the “twoside” docu‐
19856 mentclass option overridable by “oneside”.
19857 · Added the trim_doctest_flags config value, which is true by
19859 default.
19860 · Added html_show_copyright config value.
19862 · Added latex_show_pagerefs and latex_show_urls config values.
19864 · The behavior of html_file_suffix changed slightly: the empty string
19866 now means “no suffix” instead of “default suffix”, use None for
19867 “default suffix”.
19868 · New builders:
19870 · Added a builder for the Epub format.
19872 · Added a builder for manual pages.
19874 · Added a single-file HTML builder.
19876 · HTML output:
19878 · Inline roles now get a CSS class with their name, allowing styles
19880 to customize their appearance. Domain-specific roles get two
19881 classes, domain and domain-rolename.
19882 · References now get the class internal if they are internal to the
19884 whole project, as opposed to internal to the current page.
19885 · External references can be styled differently with the new exter‐
19887 nalrefs theme option for the default theme.
19888 · In the default theme, the sidebar can experimentally now be made
19890 collapsible using the new collapsiblesidebar theme option.
19891 · #129: Toctrees are now wrapped in a div tag with class toc‐
19893 tree-wrapper in HTML output.
19894 · The toctree callable in templates now has a maxdepth keyword argu‐
19896 ment to control the depth of the generated tree.
19897 · The toctree callable in templates now accepts a titles_only keyword
19899 argument.
19900 · Added htmltitle block in layout template.
19902 · In the JavaScript search, allow searching for object names includ‐
19904 ing the module name, like sys.argv.
19905 · Added new theme haiku, inspired by the Haiku OS user guide.
19907 · Added new theme nature.
19909 · Added new theme agogo, created by Andi Albrecht.
19911 · Added new theme scrolls, created by Armin Ronacher.
19913 · #193: Added a visitedlinkcolor theme option to the default theme.
19915 · #322: Improved responsiveness of the search page by loading the
19917 search index asynchronously.
19918 · Extension API:
19920 · Added html-collect-pages.
19922 · Added needs_sphinx config value and require_sphinx() application
19924 API method.
19925 · #200: Added add_stylesheet() application API method.
19927 · Extensions:
19929 · Added the viewcode extension.
19931 · Added the extlinks extension.
19933 · Added support for source ordering of members in autodoc, with
19935 autodoc_member_order = 'bysource'.
19936 · Added autodoc_default_flags config value, which can be used to
19938 select default flags for all autodoc directives.
19939 · Added a way for intersphinx to refer to named labels in other
19941 projects, and to specify the project you want to link to.
19942 · #280: Autodoc can now document instance attributes assigned in
19944 __init__ methods.
19945 · Many improvements and fixes to the autosummary extension, thanks to
19947 Pauli Virtanen.
19948 · #309: The graphviz extension can now output SVG instead of PNG
19950 images, controlled by the graphviz_output_format config value.
19951 · Added alt option to graphviz extension directives.
19953 · Added exclude argument to autodoc.between().
19955 · Translations:
19957 · Added Croatian translation, thanks to Bojan Mihelač.
19959 · Added Turkish translation, thanks to Firat Ozgul.
19961 · Added Catalan translation, thanks to Pau Fernández.
19963 · Added simplified Chinese translation.
19965 · Added Danish translation, thanks to Hjorth Larsen.
19967 · Added Lithuanian translation, thanks to Dalius Dobravolskas.
19969 · Bugs fixed:
19971 · #445: Fix links to result pages when using the search function of
19973 HTML built with the dirhtml builder.
19974 · #444: In templates, properly re-escape values treated with the
19976 “striptags” Jinja filter.
19977 Previous versions
19979 The changelog for versions before 1.0 can be found in the file
19980 CHANGES.old in the source distribution or at GitHub.
19981
19983 This is an (incomplete) alphabetic list of projects that use Sphinx or
19984 are experimenting with using it for their documentation. If you like
19985 to be included, please mail to the Google group.
19986 I’ve grouped the list into sections to make it easier to find interest‐
19988 ing examples.
19989 Documentation using the alabaster theme
19991 · Alabaster: https://alabaster.readthedocs.io/
19992 · Blinker: https://pythonhosted.org/blinker/
19994 · Calibre: https://manual.calibre-ebook.com/
19996 · Click: http://click.pocoo.org/ (customized)
19998 · coala: https://docs.coala.io/ (customized)
20000 · CodePy: https://documen.tician.de/codepy/
20002 · Fabric: http://docs.fabfile.org/
20004 · Fityk: http://fityk.nieto.pl/
20006 · Flask: http://flask.pocoo.org/docs/
20008 · Flask-OpenID: https://pythonhosted.org/Flask-OpenID/
20010 · Invoke: http://docs.pyinvoke.org/
20012 · Jinja: http://jinja.pocoo.org/docs/
20014 · Lino: http://www.lino-framework.org/ (customized)
20016 · marbl: https://getmarbl.readthedocs.io/
20018 · MDAnalysis: http://www.mdanalysis.org/docs/ (customized)
20020 · MeshPy: https://documen.tician.de/meshpy/
20022 · PyCUDA: https://documen.tician.de/pycuda/
20024 · PyOpenCL: https://documen.tician.de/pyopencl/
20026 · PyLangAcq: http://pylangacq.org/
20028 · pytest: https://docs.pytest.org/ (customized)
20030 · python-apt: https://apt.alioth.debian.org/python-apt-doc/
20032 · PyVisfile: https://documen.tician.de/pyvisfile/
20034 · Requests: http://www.python-requests.org/
20036 · searx: https://asciimoo.github.io/searx/
20038 · Tablib: http://docs.python-tablib.org/
20040 · urllib3: https://urllib3.readthedocs.io/ (customized)
20042 · Werkzeug: http://werkzeug.pocoo.org/docs/ (customized)
20044 Documentation using the classic theme
20046 · Advanced Generic Widgets:
20047 http://xoomer.virgilio.it/infinity77/AGW_Docs/ (customized)
20048 · Apache CouchDB: http://docs.couchdb.org/ (customized)
20050 · APSW: https://rogerbinns.github.io/apsw/
20052 · Arb: http://arblib.org/
20054 · Bazaar: http://doc.bazaar.canonical.com/ (customized)
20056 · Beautiful Soup:
20058 https://www.crummy.com/software/BeautifulSoup/bs4/doc/
20059 · Blender: https://docs.blender.org/api/current/
20061 · Bugzilla: https://bugzilla.readthedocs.io/
20063 · Buildbot: https://docs.buildbot.net/latest/
20065 · CMake: https://cmake.org/documentation/ (customized)
20067 · Chaco: http://docs.enthought.com/chaco/ (customized)
20069 · Cormoran: http://cormoran.nhopkg.org/docs/
20071 · DEAP: https://deap.readthedocs.io/ (customized)
20073 · Director: https://pythonhosted.org/director/
20075 · EZ-Draw:
20077 https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html
20078 (customized)
20079 · F2py: http://f2py.sourceforge.net/docs/
20081 · Generic Mapping Tools (GMT): http://gmt.soest.hawaii.edu/doc/latest/
20083 (customized)
20084 · Genomedata:
20086 https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/
20087 · GetFEM++: http://getfem.org/ (customized)
20089 · Glasgow Haskell Compiler:
20091 https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/
20092 (customized)
20093 · Grok: http://grok.zope.org/doc/current/ (customized)
20095 · GROMACS: http://manual.gromacs.org/documentation/
20097 · GSL Shell: http://www.nongnu.org/gsl-shell/
20099 · Hands-on Python Tutorial:
20101 http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
20102 · Kaa: http://api.freevo.org/kaa-base/ (customized)
20104 · Leo: http://leoeditor.com/
20106 · LEPL: http://www.acooke.org/lepl/ (customized)
20108 · Mayavi: http://docs.enthought.com/mayavi/mayavi/ (customized)
20110 · MediaGoblin: https://mediagoblin.readthedocs.io/ (customized)
20112 · mpmath: http://mpmath.org/doc/current/
20114 · OpenCV: http://docs.opencv.org/ (customized)
20116 · OpenEXR: http://excamera.com/articles/26/doc/index.html
20118 · OpenGDA: http://www.opengda.org/gdadoc/html/
20120 · Peach^3: https://peach3.nl/doc/latest/userdoc/ (customized)
20122 · Plone: https://docs.plone.org/ (customized)
20124 · PyEMD: https://pyemd.readthedocs.io/
20126 · Pyevolve: http://pyevolve.sourceforge.net/
20128 · Pygame: https://www.pygame.org/docs/ (customized)
20130 · PyMQI: https://pythonhosted.org/pymqi/
20132 · PyQt4: http://pyqt.sourceforge.net/Docs/PyQt4/ (customized)
20134 · PyQt5: http://pyqt.sourceforge.net/Docs/PyQt5/ (customized)
20136 · Python 2: https://docs.python.org/2/
20138 · Python 3: https://docs.python.org/3/ (customized)
20140 · Python Packaging Authority: https://www.pypa.io/ (customized)
20142 · Ring programming language: http://ring-lang.sourceforge.net/doc/
20144 (customized)
20145 · SageMath: https://doc.sagemath.org/ (customized)
20147 · Segway:
20149 http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
20150 · simuPOP:
20152 http://simupop.sourceforge.net/manual_release/build/userGuide.html
20153 (customized)
20154 · Sprox: http://sprox.org/ (customized)
20156 · SymPy: http://docs.sympy.org/
20158 · TurboGears: https://turbogears.readthedocs.io/ (customized)
20160 · tvtk: http://docs.enthought.com/mayavi/tvtk/
20162 · Varnish: https://www.varnish-cache.org/docs/ (customized, alabaster
20164 for index)
20165 · Waf: https://waf.io/apidocs/
20167 · wxPython Phoenix: https://wxpython.org/Phoenix/docs/html/main.html
20169 (customized)
20170 · z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
20172 · zc.async: https://pythonhosted.org/zc.async/ (customized)
20174 · Zope: https://docs.zope.org/zope2/ (customized)
20176 Documentation using the sphinxdoc theme
20178 · cartopy: http://scitools.org.uk/cartopy/docs/latest/
20179 · Jython: http://www.jython.org/docs/
20181 · Matplotlib: https://matplotlib.org/
20183 · MDAnalysis Tutorial: http://www.mdanalysis.org/MDAnalysisTutorial/
20185 · NetworkX: https://networkx.github.io/
20187 · PyCantonese: http://pycantonese.org/
20189 · Pyre: http://docs.danse.us/pyre/sphinx/
20191 · pySPACE: https://pyspace.github.io/pyspace/
20193 · Pysparse: http://pysparse.sourceforge.net/
20195 · PyTango:
20197 http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/
20198 · Python Wild Magic: https://vmlaker.github.io/pythonwildmagic/ (cus‐
20200 tomized)
20201 · Reteisi: http://www.reteisi.org/contents.html (customized)
20203 · Sqlkit: http://sqlkit.argolinux.org/ (customized)
20205 · Turbulenz: http://docs.turbulenz.com/
20207 Documentation using the nature theme
20209 · Alembic: http://alembic.zzzcomputing.com/
20210 · Cython: http://docs.cython.org/
20212 · easybuild: https://easybuild.readthedocs.io/
20214 · jsFiddle: http://doc.jsfiddle.net/
20216 · libLAS: https://www.liblas.org/ (customized)
20218 · Lmod: https://lmod.readthedocs.io/
20220 · MapServer: http://mapserver.org/ (customized)
20222 · Pandas: https://pandas.pydata.org/pandas-docs/stable/
20224 · pyglet: https://pyglet.readthedocs.io/ (customized)
20226 · Setuptools: https://setuptools.readthedocs.io/
20228 · Spring Python:
20230 https://docs.spring.io/spring-python/1.2.x/sphinx/html/
20231 · StatsModels: http://www.statsmodels.org/ (customized)
20233 · Sylli: http://sylli.sourceforge.net/
20235 Documentation using another builtin theme
20237 · Breathe: https://breathe.readthedocs.io/ (haiku)
20238 · MPipe: https://vmlaker.github.io/mpipe/ (sphinx13)
20240 · NLTK: http://www.nltk.org/ (agogo)
20242 · Programmieren mit PyGTK und Glade (German):
20244 http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo,
20245 customized)
20246 · PyPubSub: https://pypubsub.readthedocs.io/ (bizstyle)
20248 · Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/
20250 (pyramid)
20251 · Pyramid web framework:
20253 https://docs.pylonsproject.org/projects/pyramid/ (pyramid)
20254 · Sphinx: http://www.sphinx-doc.org/ (sphinx13) :-)
20256 · Valence: http://docs.valence.desire2learn.com/ (haiku, customized)
20258 Documentation using sphinx_rtd_theme
20260 · Annotator: http://docs.annotatorjs.org/
20261 · Ansible: https://docs.ansible.com/ (customized)
20263 · Arcade: http://arcade.academy/
20265 · aria2: https://aria2.github.io/manual/en/html/
20267 · ASE: https://wiki.fysik.dtu.dk/ase/
20269 · Autofac: http://docs.autofac.org/
20271 · BigchainDB: https://docs.bigchaindb.com/
20273 · Blocks: https://blocks.readthedocs.io/
20275 · bootstrap-datepicker: https://bootstrap-datepicker.readthedocs.io/
20277 · Certbot: https://letsencrypt.readthedocs.io/
20279 · Chainer: https://docs.chainer.org/ (customized)
20281 · CherryPy: http://docs.cherrypy.org/
20283 · Chainer: https://docs.chainer.org/
20285 · CodeIgniter: https://www.codeigniter.com/user_guide/
20287 · Conda: https://conda.io/docs/
20289 · Corda: https://docs.corda.net/
20291 · Dask: https://dask.pydata.org/
20293 · Databricks: https://docs.databricks.com/ (customized)
20295 · Dataiku DSS: https://doc.dataiku.com/
20297 · edX: http://docs.edx.org/
20299 · Electrum: http://docs.electrum.org/
20301 · Elemental: http://libelemental.org/documentation/dev/
20303 · ESWP3: https://eswp3.readthedocs.io/
20305 · Ethereum Homestead: http://www.ethdocs.org/
20307 · Fidimag: https://fidimag.readthedocs.io/
20309 · Flake8: http://flake8.pycqa.org/
20311 · GeoNode: http://docs.geonode.org/
20313 · Godot: https://godot.readthedocs.io/
20315 · Graylog: http://docs.graylog.org/
20317 · GPAW: https://wiki.fysik.dtu.dk/gpaw/ (customized)
20319 · HDF5 for Python (h5py): http://docs.h5py.org/
20321 · Hyperledger Fabric: https://hyperledger-fabric.readthedocs.io/
20323 · Hyperledger Sawtooth: https://intelledger.github.io/
20325 · IdentityServer: http://docs.identityserver.io/
20327 · Idris: http://docs.idris-lang.org/
20329 · javasphinx: https://bronto-javasphinx.readthedocs.io/
20331 · Julia: https://julia.readthedocs.io/
20333 · Jupyter Notebook: https://jupyter-notebook.readthedocs.io/
20335 · Lasagne: https://lasagne.readthedocs.io/
20337 · Linguistica: https://linguistica-uchicago.github.io/lxa5/
20339 · Linux kernel: https://www.kernel.org/doc/html/latest/index.html
20341 · MathJax: https://docs.mathjax.org/
20343 · MDTraj: http://mdtraj.org/latest/ (customized)
20345 · MICrobial Community Analysis (micca): http://micca.org/docs/latest/
20347 · MicroPython: https://docs.micropython.org/
20349 · Minds: https://www.minds.org/docs/ (customized)
20351 · Mink: http://mink.behat.org/
20353 · Mockery: http://docs.mockery.io/
20355 · mod_wsgi: https://modwsgi.readthedocs.io/
20357 · MoinMoin: https://moin-20.readthedocs.io/
20359 · Mopidy: https://docs.mopidy.com/
20361 · MyHDL: http://docs.myhdl.org/
20363 · Nextflow: https://www.nextflow.io/docs/latest/index.html
20365 · NICOS: https://forge.frm2.tum.de/nicos/doc/nicos-master/ (customized)
20367 · Pelican: http://docs.getpelican.com/
20369 · picamera: https://picamera.readthedocs.io/
20371 · Pillow: https://pillow.readthedocs.io/
20373 · pip: https://pip.pypa.io/
20375 · Paver: https://paver.readthedocs.io/
20377 · peewee: http://docs.peewee-orm.com/
20379 · Phinx: http://docs.phinx.org/
20381 · phpMyAdmin: https://docs.phpmyadmin.net/
20383 · PROS: https://pros.cs.purdue.edu/v5/ (customized)
20385 · Pweave: http://mpastell.com/pweave/
20387 · PyPy: http://doc.pypy.org/
20389 · python-sqlparse: https://sqlparse.readthedocs.io/
20391 · PyVISA: https://pyvisa.readthedocs.io/
20393 · Read The Docs: https://docs.readthedocs.io/
20395 · Free your information from their silos (French):
20397 http://redaction-technique.org/ (customized)
20398 · Releases Sphinx extension: https://releases.readthedocs.io/
20400 · Qtile: http://docs.qtile.org/
20402 · Quex: http://quex.sourceforge.net/doc/html/main.html
20404 · Satchmo: http://docs.satchmoproject.com/
20406 · Scapy: https://scapy.readthedocs.io/
20408 · SimPy: http://simpy.readthedocs.io/
20410 · SlamData: http://docs.slamdata.com/
20412 · Solidity: https://solidity.readthedocs.io/
20414 · Sonos Controller (SoCo): http://docs.python-soco.com/
20416 · Sphinx AutoAPI: https://sphinx-autoapi.readthedocs.io/
20418 · sphinx-argparse: https://sphinx-argparse.readthedocs.io/
20420 · Sphinx-Gallery: https://sphinx-gallery.readthedocs.io/ (customized)
20422 · StarUML: http://docs.staruml.io/
20424 · Sublime Text Unofficial Documentation: http://docs.sublimetext.info/
20426 · SunPy: http://docs.sunpy.org/
20428 · Sylius: http://docs.sylius.org/
20430 · Tango Controls: https://tango-controls.readthedocs.io/ (customized)
20432 · Topshelf: http://docs.topshelf-project.com/
20434 · Theano: http://www.deeplearning.net/software/theano/
20436 · ThreatConnect: https://docs.threatconnect.com/
20438 · Tuleap: https://tuleap.net/doc/en/
20440 · TYPO3: https://docs.typo3.org/ (customized)
20442 · uWSGI: https://uwsgi-docs.readthedocs.io/
20444 · Wagtail: http://docs.wagtail.io/
20446 · Web Application Attack and Audit Framework (w3af):
20448 http://docs.w3af.org/
20449 · Weblate: https://docs.weblate.org/
20451 · x265: https://x265.readthedocs.io/
20453 · ZeroNet: https://zeronet.readthedocs.io/
20455 Documentation using sphinx_bootstrap_theme
20457 · Bootstrap Theme:
20458 https://ryan-roemer.github.io/sphinx-bootstrap-theme/
20459 · C/C++ Software Development with Eclipse: http://eclipsebook.in/
20461 · Dataverse: http://guides.dataverse.org/
20463 · e-cidadania: https://e-cidadania.readthedocs.io/
20465 · Hangfire: http://docs.hangfire.io/
20467 · Hedge: https://documen.tician.de/hedge/
20469 · ObsPy: https://docs.obspy.org/
20471 · Open Dylan: https://opendylan.org/documentation/
20473 · Pootle: http://docs.translatehouse.org/projects/pootle/
20475 · PyUblas: https://documen.tician.de/pyublas/
20477 · seaborn: https://seaborn.pydata.org/
20479 Documentation using a custom theme or integrated in a website
20481 · Apache Cassandra: https://cassandra.apache.org/doc/
20482 · Astropy: http://docs.astropy.org/
20484 · Bokeh: https://bokeh.pydata.org/
20486 · Boto 3: https://boto3.readthedocs.io/
20488 · CakePHP: https://book.cakephp.org/
20490 · CasperJS: http://docs.casperjs.org/
20492 · Ceph: http://docs.ceph.com/docs/master/
20494 · Chef: https://docs.chef.io/
20496 · CKAN: http://docs.ckan.org/
20498 · Confluent Platform: http://docs.confluent.io/
20500 · Django: https://docs.djangoproject.com/
20502 · Doctrine: http://docs.doctrine-project.org/
20504 · Enterprise Toolkit for Acrobat products:
20506 https://www.adobe.com/devnet-docs/acrobatetk/
20507 · Gameduino: http://excamera.com/sphinx/gameduino/
20509 · gensim: https://radimrehurek.com/gensim/
20511 · GeoServer: http://docs.geoserver.org/
20513 · gevent: http://www.gevent.org/
20515 · GHC - Glasgow Haskell Compiler:
20517 http://downloads.haskell.org/~ghc/master/users-guide/
20518 · Guzzle: http://docs.guzzlephp.org/en/stable/
20520 · H2O.ai: http://docs.h2o.ai/
20522 · Istihza (Turkish Python documentation project):
20524 https://belgeler.yazbel.com/python-istihza/
20525 · Kombu: http://docs.kombu.me/
20527 · Lasso: http://lassoguide.com/
20529 · Mako: http://docs.makotemplates.org/
20531 · MirrorBrain: http://mirrorbrain.org/docs/
20533 · MongoDB: https://docs.mongodb.com/
20535 · Music21: http://web.mit.edu/music21/doc/
20537 · MyHDL: http://docs.myhdl.org/en/latest/
20539 · nose: https://nose.readthedocs.io/
20541 · ns-3: https://www.nsnam.org/documentation/
20543 · NumPy: https://docs.scipy.org/doc/numpy/reference/
20545 · ObjectListView: http://objectlistview.sourceforge.net/python/
20547 · OpenERP: https://doc.odoo.com/
20549 · OpenCV: http://docs.opencv.org/
20551 · OpenLayers: http://docs.openlayers.org/
20553 · OpenTURNS: http://openturns.github.io/openturns/master/
20555 · Open vSwitch: http://docs.openvswitch.org/
20557 · PlatformIO: http://docs.platformio.org/
20559 · PyEphem: http://rhodesmill.org/pyephem/
20561 · Pygments: http://pygments.org/docs/
20563 · Plone User Manual (German):
20565 https://www.hasecke.com/plone-benutzerhandbuch/4.0/
20566 · PSI4: http://www.psicode.org/psi4manual/master/index.html
20568 · PyMOTW: https://pymotw.com/2/
20570 · python-aspectlib: https://python-aspectlib.readthedocs.io/ (‐
20572 sphinx_py3doc_enhanced_theme)
20573 · QGIS: https://qgis.org/en/docs/index.html
20575 · qooxdoo: http://www.qooxdoo.org/current/
20577 · Roundup: http://www.roundup-tracker.org/
20579 · SaltStack: https://docs.saltstack.com/
20581 · scikit-learn: http://scikit-learn.org/stable/
20583 · SciPy: https://docs.scipy.org/doc/scipy/refrence/
20585 · Scrapy: https://doc.scrapy.org/
20587 · Seaborn: https://seaborn.pydata.org/
20589 · Selenium: http://docs.seleniumhq.org/docs/
20591 · Self: http://www.selflanguage.org/
20593 · Substance D: https://docs.pylonsproject.org/projects/substanced/
20595 · Sulu: http://docs.sulu.io/
20597 · SQLAlchemy: https://docs.sqlalchemy.org/
20599 · tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
20601 · Twisted: http://twistedmatrix.com/documents/current/
20603 · Ubuntu Packaging Guide: http://packaging.ubuntu.com/html/
20605 · WebFaction: https://docs.webfaction.com/
20607 · WTForms: https://wtforms.readthedocs.io/
20609 Homepages and other non-documentation sites
20611 · Arizona State University PHY494/PHY598/CHM598 Simulation approaches
20612 to Bio- and Nanophysics:
20613 https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/
20614 (classic)
20615 · Benoit Boissinot: https://bboissin.appspot.com/ (classic, customized)
20617 · Computer Networks, Parallelization, and Simulation Laboratory
20619 (CNPSLab): https://lab.miletic.net/ (sphinx_rtd_theme)
20620 · Deep Learning Tutorials: http://www.deeplearning.net/tutorial/
20622 (sphinxdoc)
20623 · Loyola University Chicago COMP 339-439 Distributed Systems course:
20625 http://books.cs.luc.edu/distributedsystems/ (sphinx_bootstrap_theme)
20626 · Pylearn2: http://www.deeplearning.net/software/pylearn2/ (sphinxdoc,
20628 customized)
20629 · SciPy Cookbook: https://scipy-cookbook.readthedocs.io/
20631 (sphinx_rtd_theme)
20632 · The Wine Cellar Book: https://www.thewinecellarbook.com/doc/en/
20634 (sphinxdoc)
20635 · Thomas Cokelaer’s Python, Sphinx and reStructuredText tutorials:
20637 http://thomas-cokelaer.info/tutorials/ (standard)
20638 · UC Berkeley ME233 Advanced Control Systems II course:
20640 https://berkeley-me233.github.io/ (sphinxdoc)
20641 Books produced using Sphinx
20643 · “Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski”:
20644 https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/
20645 · “Expert Python Programming”:
20647 https://www.packtpub.com/application-development/expert-python-programming
20648 · “Expert Python Programming” (Japanese translation):
20650 https://www.amazon.co.jp/dp/4048686291/
20651 · “LassoGuide”: http://www.lassosoft.com/Lasso-Documentation
20653 · “Learning Sphinx” (in Japanese):
20655 https://www.oreilly.co.jp/books/9784873116488/
20656 · “Mercurial: the definitive guide (Second edition)”:
20658 https://book.mercurial-scm.org/
20659 · “Pioneers and Prominent Men of Utah”: http://pioneers.rstebbing.com/
20661 · “Pomodoro Technique Illustrated” (Japanese translation):
20663 https://www.amazon.co.jp/dp/4048689525/
20664 · “Python Professional Programming” (in Japanese):
20666 http://www.amazon.co.jp/dp/4798032948/
20667 · “The repoze.bfg Web Application Framework”:
20669 https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
20670 · “Simple and Steady Way of Learning for Software Engineering” (in Ja‐
20672 panese): https://www.amazon.co.jp/dp/477414259X/
20673 · “Software-Dokumentation mit Sphinx”:
20675 https://www.amazon.de/dp/1497448689/
20676 · “Theoretical Physics Reference”: http://www.theoretical-physics.net/
20678 · “The Varnish Book”:
20680 https://info.varnish-software.com/the-varnish-book
20681 Theses produced using Sphinx
20683 · “A Web-Based System for Comparative Analysis of OpenStreetMap Data by
20684 the Use of CouchDB”:
20685 https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042
20686 · “Content Conditioning and Distribution for Dynamic Virtual Worlds”:
20688 https://www.cs.princeton.edu/research/techreps/TR-941-12
20689 · “The Sphinx Thesis Resource”: https://jterrace.github.io/sphinxtr/
20691
20693 Sphinx is written and maintained by Georg Brandl <georg@python.org>.
20694 Substantial parts of the templates were written by Armin Ronacher <‐
20696 armin.ronacher@active-4.com>.
20697 Other co-maintainers:
20699 · Takayuki Shimizukawa <shimizukawa@gmail.com>
20701 · Daniel Neuhäuser <@DasIch>
20703 · Jon Waltman <@jonwaltman>
20705 · Rob Ruana <@RobRuana>
20707 · Robert Lehmann <@lehmannro>
20709 · Roland Meister <@rolmei>
20711 · Takeshi Komiya <@tk0miya>
20713 · Jean-François Burnol <@jfbu>
20715 · Yoshiki Shibukawa <@shibu_jp>
20717 Other contributors, listed alphabetically, are:
20719 · Alastair Houghton – Apple Help builder
20721 · Alexander Todorov – inheritance_diagram tests and improvements
20723 · Andi Albrecht – agogo theme
20725 · Jakob Lykke Andersen – Rewritten C++ domain
20727 · Henrique Bastos – SVG support for graphviz extension
20729 · Daniel Bültmann – todo extension
20731 · Marco Buttu – doctest extension (pyversion option)
20733 · Etienne Desautels – apidoc module
20735 · Michael Droettboom – inheritance_diagram extension
20737 · Charles Duffy – original graphviz extension
20739 · Kevin Dunn – MathJax extension
20741 · Josip Dzolonga – coverage builder
20743 · Buck Evan – dummy builder
20745 · Matthew Fernandez – todo extension fix
20747 · Hernan Grecco – search improvements
20749 · Horst Gutmann – internationalization support
20751 · Martin Hans – autodoc improvements
20753 · Zac Hatfield-Dodds – doctest reporting improvements
20755 · Doug Hellmann – graphviz improvements
20757 · Tim Hoffmann – theme improvements
20759 · Timotheus Kampik - JS theme & search enhancements
20761 · Dave Kuhlman – original LaTeX writer
20763 · Blaise Laflamme – pyramid theme
20765 · Thomas Lamb – linkcheck builder
20767 · Łukasz Langa – partial support for autodoc
20769 · Ian Lee – quickstart improvements
20771 · Robert Lehmann – gettext builder (GSOC project)
20773 · Dan MacKinlay – metadata fixes
20775 · Martin Mahner – nature theme
20777 · Will Maier – directory HTML builder
20779 · Jacob Mason – websupport library (GSOC project)
20781 · Glenn Matthews – python domain signature improvements
20783 · Roland Meister – epub builder
20785 · Ezio Melotti – collapsible sidebar JavaScript
20787 · Bruce Mitchener – Minor epub improvement
20789 · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
20791 · Christopher Perkins – autosummary integration
20793 · Benjamin Peterson – unittests
20795 · T. Powers – HTML output improvements
20797 · Jeppe Pihl – literalinclude improvements
20799 · Rob Ruana – napoleon extension
20801 · Stefan Seefeld – toctree improvements
20803 · Gregory Szorc – performance improvements
20805 · Taku Shimizu – epub3 builder
20807 · Antonio Valentino – qthelp builder, docstring inheritance
20809 · Filip Vavera – napoleon todo directive
20811 · Pauli Virtanen – autodoc improvements, autosummary extension
20813 · Stefan van der Walt – autosummary extension
20815 · Thomas Waldmann – apidoc module fixes
20817 · John Waltman – Texinfo builder
20819 · Barry Warsaw – setup command improvements
20821 · Sebastian Wiesner – image handling, distutils support
20823 · Michael Wilson – Intersphinx HTTP basic auth support
20825 · Matthew Woodcraft – text output improvements
20827 · Joel Wurtz – cellspanning support in LaTeX
20829 · Hong Xu – svg support in imgmath extension and various bug fixes
20831 · Stephen Finucane – setup command improvements and documentation
20833 · Daniel Pizetta – inheritance diagram improvements
20835 Many thanks for all contributions!
20837 There are also a few modules or functions incorporated from other
20839 authors and projects:
20840 · sphinx.util.jsdump uses the basestring encoding from simplejson,
20842 written by Bob Ippolito, released under the MIT license
20843 · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
20845 Domain
20846 · modindex
20848 · glossary
20850
20852 Georg Brandl
20853
20855 2007-2018, Georg Brandl and the Sphinx team
208561.7.6 Aug 02, 2018 SPHINX-ALL(1)