1SPHINX-ALL(1)                       Sphinx                       SPHINX-ALL(1)
2
3
4

NAME

6       sphinx-all - Sphinx documentation generator system manual
7

INTRODUCTION

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
19       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
25       For  a  great  “introduction” to writing docs in general – the whys and
26       hows, see also Write the docs, written by Eric Holscher.
27
28   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
32       · Gerard Flanagan has written a script to convert pure HTML to reST; it
33         can be found at the Python Package Index.
34
35       · 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
39       · Marcin Wojdyr has written a script to convert Docbook  to  reST  with
40         Sphinx markup; it is at GitHub.
41
42       · Christophe  de  Vienne  wrote a tool to convert from Open/LibreOffice
43         documents to Sphinx: odt2sphinx.
44
45       · To convert different markups, Pandoc is a very helpful tool.
46
47   Use with other systems
48       See the pertinent section in the FAQ list.
49
50   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
57   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

FIRST STEPS WITH SPHINX

62       This  document  is meant to give a tutorial-like overview of all common
63       tasks while using Sphinx.
64
65       The green arrows designate “more info” links leading to  advanced  sec‐
66       tions about the described task.
67
68   Install Sphinx
69       Install Sphinx, either from a distribution package or from PyPI with
70
71          $ pip install Sphinx
72
73   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
80       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
84          $ sphinx-quickstart
85
86       and  answer its questions.  (Be sure to say yes to the “autodoc” exten‐
87       sion.)
88
89       There  is  also  an  automatic  “API  documentation”  generator  called
90       sphinx-apidoc; see /man/sphinx-apidoc for details.
91
92   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
101   reStructuredText directives
102       toctree  is  a  reStructuredText  directive,  a very versatile piece of
103       markup.  Directives can have arguments, options and content.
104
105       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
109       Options are given after the arguments, in form of a “field list”.   The
110       maxdepth is such an option for the toctree directive.
111
112       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
115       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
118       The toctree directive initially is empty, and looks like this:
119
120          .. toctree::
121             :maxdepth: 2
122
123       You add documents listing them in the content of the directive:
124
125          .. toctree::
126             :maxdepth: 2
127
128             intro
129             tutorial
130             ...
131
132       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
137       [image: more info] [image]
138        Read more about the toctree directive.
139
140       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
147   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
153       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
156       [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
160   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
165          $ sphinx-build -b html sourcedir builddir
166
167       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
171       [image: more info] [image]
172        Refer to the sphinx-build man page <sphinx-build> for all options that
173       sphinx-build supports.
174
175       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
178          $ make html
179
180       to build HTML docs in the build  directory  you  chose.   Execute  make
181       without an argument to see which targets are available.
182
183          How do I generate PDF documents?
184
185                 make  latexpdf runs the LaTeX builder and readily invokes the
186                 pdfTeX toolchain for you.
187
188   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
194       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
198          .. py:function:: enumerate(sequence[, start=0])
199
200             Return an iterator that yields tuples of an index and an item of the
201             *sequence*. (And so on.)
202
203       This is rendered like this:
204
205       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
209       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
213       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
216          .. function:: enumerate(sequence[, start=0])
217
218             ...
219
220       does  the  same  job  if  you  keep the default setting for the default
221       domain.
222
223       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
228          The :py:func:`enumerate` function can be used for ...
229
230       And here is the proof: A link to enumerate().
231
232       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
236       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
240       [image: more info] [image]
241        See domains for all the available domains and their directives/roles.
242
243   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
251       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
258       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
264       [image: more info] [image]
265        See build-config for documentation of all available config values.
266
267   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
274       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
279       For example, to document the function io.open(), reading its  signature
280       and docstring from the source file, you’d write this:
281
282          .. autofunction:: io.open
283
284       You  can  also  document  whole  classes or even modules automatically,
285       using member options for the auto directives, like
286
287          .. automodule:: io
288             :members:
289
290       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
294       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
299          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
303       [image: more info] [image]
304        See sphinx.ext.autodoc for the complete description of the features of
305       autodoc.
306
307   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
312       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
316       For  example,  to  link  to io.open() in the Python library manual, you
317       need to setup your intersphinx_mapping like:
318
319          intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
320
321       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
329       [image: more info] [image]
330        See sphinx.ext.intersphinx for the complete description  of  the  fea‐
331       tures of intersphinx.
332
333   More topics to be covered
334       · Other extensions:
335
336         · ext/math,
337
338         · ext/viewcode,
339
340         · ext/doctest,
341
342         · …
343
344       · Static files
345
346       · Selecting a theme
347
348       · setuptools
349
350       · Templating
351
352       · Using extensions
353
354       · Writing extensions
355

FOOTNOTES

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

MAN PAGES

362       These are the applications provided as part of Sphinx.
363
364   Core Applications
365   sphinx-quickstart
366   Synopsis
367       sphinx-quickstart
368
369   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
374   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
379       -h, --help, --version
380              Display usage summary or Sphinx version.
381       Structure Options.INDENT 0.0
382
383       --sep  If specified, separate source and build directories.
384
385       --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
392       -p PROJECT, --project=PROJECT
393              Project name will be set. (see project).
394
395       -a AUTHOR, --author=AUTHOR
396              Author names. (see copyright).
397
398       -v VERSION
399              Version of project. (see version).
400
401       -r RELEASE, --release=RELEASE
402              Release of project. (see release).
403
404       -l LANGUAGE, --language=LANGUAGE
405              Document language. (see language).
406
407       --suffix=SUFFIX
408              Source file suffix. (see source_suffix).
409
410       --master=MASTER
411              Master document name. (see master_doc).
412
413       --epub Use epub.
414       Extension Options.INDENT 0.0
415
416       --ext-autodoc
417              Enable sphinx.ext.autodoc extension.
418
419       --ext-doctest
420              Enable sphinx.ext.doctest extension.
421
422       --ext-intersphinx
423              Enable sphinx.ext.intersphinx extension.
424
425       --ext-todo
426              Enable sphinx.ext.todo extension.
427
428       --ext-coverage
429              Enable sphinx.ext.coverage extension.
430
431       --ext-imgmath
432              Enable sphinx.ext.imgmath extension.
433
434       --ext-mathjax
435              Enable sphinx.ext.mathjax extension.
436
437       --ext-ifconfig
438              Enable sphinx.ext.ifconfig extension.
439
440       --ext-viewcode
441              Enable sphinx.ext.viewcode extension.
442
443       --extensions=EXTENSIONS
444              Enable arbitary extensions.
445       Makefile and Batchfile Creation Options.INDENT 0.0
446
447       --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
451              Changed in version 1.5: make-mode is default.
452
453
454       --makefile, --no-makefile
455              Create (or not create) makefile.
456
457       --batchfile, --no-batchfile
458              Create (or not create) batchfile
459       Project templating
460
461       New in version 1.5: Project templating options for sphinx-quickstart
462
463
464       -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
469              · master_doc.rst_t
470
471              · conf.py_t
472
473              · Makefile_t
474
475              · Makefile.new_t
476
477              · make.bat_t
478
479              · make.bat.new_t
480
481              In detail, please refer the system template  files  Sphinx  pro‐
482              vides.  (sphinx/templates/quickstart)
483
484       -d NAME=VALUE
485              Define a template variable
486
487   See also
488       sphinx-build(1)
489
490   sphinx-build
491   Synopsis
492       sphinx-build [options] <sourcedir> <outputdir> [filenames …]
493
494   Description
495       sphinx-build  generates documentation from the files in <sourcedir> and
496       places it in the <outputdir>.
497
498       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
502       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
507       By  default,  everything  that  is  outdated is built.  Output only for
508       selected files can be built by specifying individual filenames.
509
510       For a list of available options, refer to sphinx-build -b.
511
512   Options
513       -b buildername
514              The most important option: it selects a builder.  The most  com‐
515              mon builders are:
516
517              html   Build HTML pages.  This is the default builder.
518
519              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
524              singlehtml
525                     Build a single HTML with the whole content.
526
527              htmlhelp, qthelp, devhelp, epub
528                     Build HTML files with additional information for building
529                     a documentation collection in one of these formats.
530
531              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
536              latex  Build LaTeX sources that can be compiled to a  PDF  docu‐
537                     ment using pdflatex.
538
539              man    Build manual pages in groff format for UNIX systems.
540
541              texinfo
542                     Build Texinfo files that can be processed into Info files
543                     using makeinfo.
544
545              text   Build plain text files.
546
547              gettext
548                     Build gettext-style message catalogs (.pot files).
549
550              doctest
551                     Run all doctests in the  documentation,  if  the  doctest
552                     extension is enabled.
553
554              linkcheck
555                     Check the integrity of all external links.
556
557              xml    Build Docutils-native XML files.
558
559              pseudoxml
560                     Build  compact pretty-printed “pseudo-XML” files display‐
561                     ing the internal structure of the  intermediate  document
562                     trees.
563
564              See  builders  for  a  list of all builders shipped with Sphinx.
565              Extensions can add their own builders.
566
567       -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
573              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
579              info   Build Texinfo files and run them through makeinfo.
580
581              IMPORTANT:
582                 Sphinx only recognizes the -M option if it is placed first.
583
584              New in version 1.2.1.
585
586
587       -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
591       -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
596       -t tag Define  the  tag tag.  This is relevant for only directives that
597              only include their content if this tag is set.
598
599              New in version 0.6.
600
601
602       -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
610       -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
616              New  in version 1.2: This option should be considered experimen‐
617              tal.
618
619
620              Changed in version 1.7: Support auto argument.
621
622
623       -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
630              New in version 0.3.
631
632
633       -C     Don’t look for a configuration file; only take options  via  the
634              -D option.
635
636              New in version 0.5.
637
638
639       -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
643              For lists, you can separate elements with a comma like this:  -D
644              html_theme_path=path1,path2.
645
646              For  dictionary  values,  supply  the  setting name and key like
647              this: -D latex_elements.docclass=scrartcl.
648
649              For boolean values, use 0 or 1 as the value.
650
651              Changed in version 0.6: The value can now be a dictionary value.
652
653
654              Changed in version 1.3: The value can now also be a list value.
655
656
657       -A name=value
658              Make the name assigned to value in the HTML templates.
659
660              New in version 0.5.
661
662
663       -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
667       -N     Do not emit colored output.
668
669       -v     Increase verbosity (loglevel).  This option can be given  up  to
670              three times to get more debug logging output.  It implies -T.
671
672              New in version 1.2.
673
674
675       -q     Do  not  output anything on standard output, only write warnings
676              and errors to standard error.
677
678       -Q     Do not output anything on standard output, also  suppress  warn‐
679              ings.  Only errors are written to standard error.
680
681       -w file
682              Write  warnings  (and  errors) to the given file, in addition to
683              standard error.
684
685       -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
688       -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
692              New in version 1.2.
693
694
695       -P     (Useful  for  debugging only.)  Run the Python debugger, pdb, if
696              an unhandled exception occurs while building.
697
698       -h, --help, --version
699              Display usage summary or Sphinx version.
700
701              New in version 1.2.
702
703
704       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
708   Environment Variables
709       The sphinx-build refers following environment variables:
710
711       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
715       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
719       PAPER  The value for ‘“papersize”` key of latex_elements.
720
721       SPHINXBUILD
722              The command to use instead of sphinx-build.
723
724       BUILDDIR
725              The  build  directory  to  use  instead  of  the  one  chosen in
726              sphinx-quickstart.
727
728       SPHINXOPTS
729              Additional options for sphinx-build.
730
731   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
737       To  disable  the deprecation warnings, please set PYTHONWARNINGS= envi‐
738       ronment variable to your environment. For example:
739
740       · PYTHONWARNINGS= make html (Linux/Mac)
741
742       · export PYTHONWARNINGS= and do make html (Linux/Mac)
743
744       · set PYTHONWARNINGS= and do make html (Windows)
745
746       · modify your Makefile/make.bat and set the environment variable
747
748   See also
749       sphinx-quickstart(1)
750
751   Additional Applications
752   sphinx-apidoc
753   Synopsis
754       sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames …]
755
756   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
761       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
765       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
770          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
774   Options
775       -o <outputdir>
776              Directory to place the output files. If it does not exist, it is
777              created.
778
779       -f, --force
780              Force overwritting of any existing generated files.
781
782       -l, --follow-links
783              Follow symbolic links.
784
785       -n, --dry-run
786              Do not create any files.
787
788       -s <suffix>
789              Suffix for the source files generated. Defaults to rst.
790
791       -d <maxdepth>
792              Maximum depth for the generated table of contents file.
793
794       -T, --no-toc
795              Do  not  create a table of contents file. Ignored when --full is
796              provided.
797
798       -F, --full
799              Generate a full Sphinx project (conf.py,  Makefile  etc.)  using
800              the same mechanism as sphinx-quickstart.
801
802       -e, --separate
803              Put documentation for each module on its own page.
804
805              New in version 1.2.
806
807
808       -E, --no-headings
809              Do not create headings for the modules/packages. This is useful,
810              for example, when docstrings already contain headings.
811
812       -P, --private
813              Include “_private” modules.
814
815              New in version 1.2.
816
817
818       --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
825              Interpret paths recursively according to PEP-0420.
826
827       -M, --module-first
828              Put module documentation before submodule documentation.
829
830       These options are used when --full is specified:
831
832       -a     Append module_path to sys.path.
833
834       -H <project>
835              Sets the project name to put in generated files (see project).
836
837       -A <author>
838              Sets the author name(s) to put in  generated  files  (see  copy‐
839              right).
840
841       -V <version>
842              Sets  the  project  version  to put in generated files (see ver‐
843              sion).
844
845       -R <release>
846              Sets  the  project  release  to  put  in  generated  files  (see
847              release).
848
849   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
855   See also
856       sphinx-build(1), sphinx-autogen(1)
857
858   sphinx-autogen
859   Synopsis
860       sphinx-autogen [options] <sourcefile> …
861
862   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
867       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
871   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
876       -s <suffix>, --suffix <suffix>
877              Default suffix to use for generated files. Defaults to rst.
878
879       -t <templates>, --templates <templates>
880              Custom template directory. Defaults to None.
881
882       -i, --imported-members
883              Document imported members.
884
885   Example
886       Given the following directory structure:
887
888          docs
889          ├── index.rst
890          └── ...
891          foobar
892          ├── foo
893          │   └── __init__.py
894          └── bar
895              ├── __init__.py
896              └── baz
897                  └── __init__.py
898
899       and assuming docs/index.rst contained the following:
900
901          Modules
902          =======
903
904          .. autosummary::
905             :toctree: modules
906
907             foobar.foo
908             foobar.bar
909             foobar.bar.baz
910
911       If you run the following:
912
913          $ PYTHONPATH=. sphinx-autodoc doc/index.rst
914
915       then the following stub files will be created in docs:
916
917          docs
918          ├── index.rst
919          └── modules
920              ├── foobar.bar.rst
921              ├── foobar.bar.baz.rst
922              └── foobar.foo.rst
923
924       and each of those files will contain a autodoc directive and some other
925       information.
926
927   See also
928       sphinx-build(1), sphinx-apidoc(1)
929

RESTRUCTUREDTEXT PRIMER

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
936       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
941   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
947   Inline markup
948       The standard reST inline markup is quite simple: use
949
950       · one asterisk: *text* for emphasis (italics),
951
952       · two asterisks: **text** for strong emphasis (boldface), and
953
954       · backquotes: ``text`` for code samples.
955
956       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
960       Be aware of some restrictions of this markup:
961
962       · it may not be nested,
963
964       · content may not start or end with whitespace: * text* is wrong,
965
966       · 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
970       These restrictions may be lifted in future versions of the docutils.
971
972       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
978       Standard reST provides the following roles:
979
980       · emphasis – alternate spelling for *emphasis*
981
982       · strong – alternate spelling for **strong**
983
984       · literal – alternate spelling for ``literal``
985
986       · subscript – subscript text
987
988       · superscript – superscript text
989
990       · title-reference – for titles of books, periodicals, and other materi‐
991         als
992
993       See inline-markup for roles added by Sphinx.
994
995   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
1000          * This is a bulleted list.
1001          * It has two items, the second
1002            item uses two lines.
1003
1004          1. This is a numbered list.
1005          2. It has two items too.
1006
1007          #. This is a numbered list.
1008          #. It has two items too.
1009
1010       Nested lists are possible, but be aware that  they  must  be  separated
1011       from the parent list items by blank lines:
1012
1013          * this is
1014          * a list
1015
1016            * with a nested list
1017            * and some subitems
1018
1019          * and here the parent list continues
1020
1021       Definition lists (ref) are created as follows:
1022
1023          term (up to a line of text)
1024             Definition of the term, which must be indented
1025
1026             and can even consist of multiple paragraphs
1027
1028          next term
1029             Description.
1030
1031       Note that the term cannot have more than one line of text.
1032
1033       Quoted  paragraphs  (ref)  are created by just indenting them more than
1034       the surrounding paragraphs.
1035
1036       Line blocks (ref) are a way of preserving line breaks:
1037
1038          | These lines are
1039          | broken exactly like in
1040          | the source file.
1041
1042       There are also several more special blocks available:
1043
1044       · field lists (ref)
1045
1046       · option lists (ref)
1047
1048       · quoted literal blocks (ref)
1049
1050       · doctest blocks (ref)
1051
1052   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
1057          This is a normal text paragraph. The next paragraph is a code sample::
1058
1059             It is not processed in any way, except
1060             that the indentation is removed.
1061
1062             It can span multiple lines.
1063
1064          This is a normal text paragraph again.
1065
1066       The handling of the :: marker is smart:
1067
1068       · If it occurs as a paragraph of its own, that paragraph is  completely
1069         left out of the document.
1070
1071       · If it is preceded by whitespace, the marker is removed.
1072
1073       · If it is preceded by non-whitespace, the marker is replaced by a sin‐
1074         gle colon.
1075
1076       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
1079   Tables
1080       For  grid  tables  (ref),  you  have to “paint” the cell grid yourself.
1081       They look like this:
1082
1083          +------------------------+------------+----------+----------+
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
1092       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
1096          =====  =====  =======
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
1105       Two more syntaxes are supported: CSV tables and List tables.  They  use
1106       an explicit markup block, see Directives section.
1107
1108   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
1114       IMPORTANT:
1115          There  must  be  a space between the link text and the opening < for
1116          the URL.
1117
1118       You can also separate the link and the target  definition  (ref),  like
1119       this:
1120
1121          This is a paragraph that contains `a link`_.
1122
1123          .. _a link: http://example.com/
1124
1125   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
1129   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
1134          =================
1135          This is a heading
1136          =================
1137
1138       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
1143       · # with overline, for parts
1144
1145       · * with overline, for chapters
1146
1147       · =, for sections
1148
1149       · -, for subsections
1150
1151       · ^, for subsubsections
1152
1153       · ", for paragraphs
1154
1155       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
1160   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
1165       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
1171   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
1176       Docutils supports the following directives:
1177
1178       · 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
1182       · Images:
1183
1184         · image (see also Images below)
1185
1186         · figure (an image with caption and optional legend)
1187
1188       · Additional body elements:
1189
1190         · contents (a local, i.e. for the current file only,  table  of  con‐
1191           tents)
1192
1193         · container  (a  container with a custom class, useful to generate an
1194           outer <div> in HTML)
1195
1196         · rubric (a heading without relation to the document sectioning)
1197
1198         · topic, sidebar (special highlighted body elements)
1199
1200         · parsed-literal (literal block that supports inline markup)
1201
1202         · epigraph (a block quote with optional attribution line)
1203
1204         · highlights,  pull-quote  (block  quotes  with   their   own   class
1205           attribute)
1206
1207         · compound (a compound paragraph)
1208
1209       · Special tables:
1210
1211         · table (a table with title)
1212
1213         · csv-table (a table generated from comma-separated values)
1214
1215         · list-table (a table generated from a list of lists)
1216
1217       · Special directives:
1218
1219         · raw (include raw target-format markup)
1220
1221         · 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
1225         · class (assign a class attribute to the next element) [1]
1226
1227       · HTML specifics:
1228
1229         · meta (generation of HTML <meta> tags)
1230
1231         · title (override document title)
1232
1233       · Influencing markup:
1234
1235         · default-role (set a new default role)
1236
1237         · role (create a new role)
1238
1239         Since  these  are  only  per-file, better use Sphinx’s facilities for
1240         setting the default_role.
1241
1242       Do not use the directives sectnum, header and footer.
1243
1244       Directives added by Sphinx are described in sphinxmarkup.
1245
1246       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
1250          .. function:: foo(x)
1251                        foo(y, z)
1252             :module: some.module.name
1253
1254             Return a line of text input from the user.
1255
1256       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
1262       The directive content follows after a blank line and is indented  rela‐
1263       tive to the directive start.
1264
1265   Images
1266       reST supports an image directive (ref), used like so:
1267
1268          .. image:: gnu.png
1269             (options)
1270
1271       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
1277       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
1281       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
1287       Sphinx  extends  the standard docutils behavior by allowing an asterisk
1288       for the extension:
1289
1290          .. image:: gnu.*
1291
1292       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
1300       Note that image file names should not contain spaces.
1301
1302       Changed in version 0.4: Added the support for file names ending  in  an
1303       asterisk.
1304
1305
1306       Changed in version 0.6: Image paths can now be absolute.
1307
1308
1309       Changed  in  version  1.5:  latex  target  supports  pixels (default is
1310       96px=1in).
1311
1312
1313   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
1318          Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
1319
1320          .. rubric:: Footnotes
1321
1322          .. [#f1] Text of the first footnote.
1323          .. [#f2] Text of the second footnote.
1324
1325       You can also explicitly number the footnotes ([1]_)  or  use  auto-num‐
1326       bered footnotes without names ([#]_).
1327
1328   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
1333          Lorem ipsum [Ref]_ dolor sit amet.
1334
1335          .. [Ref] Book or article reference, URL or whatever.
1336
1337       Citation  usage  is similar to footnote usage, but with a label that is
1338       not numeric or begins with #.
1339
1340   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
1345          .. |name| replace:: replacement *text*
1346
1347       or this:
1348
1349          .. |caution| image:: warning.png
1350                       :alt: Warning!
1351
1352       See the reST reference for substitutions for details.
1353
1354       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
1361       Sphinx defines some default substitutions, see default-substitutions.
1362
1363   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
1367          .. This is a comment.
1368
1369       You can indent text after a comment start to form multiline comments:
1370
1371          ..
1372             This whole indented block
1373             is a comment.
1374
1375             Still in the comment.
1376
1377   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
1384   Gotchas
1385       There are some problems one commonly runs  into  while  authoring  reST
1386       documents:
1387
1388       · 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
1393       · No nested inline markup: Something like *see :func:`foo`* is not pos‐
1394         sible.
1395

FOOTNOTES

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

SPHINX MARKUP CONSTRUCTS

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
1405   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
1412       NOTE:
1413          Simple “inclusion” of one file in  another  can  be  done  with  the
1414          include directive.
1415
1416       .. 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
1425              Consider  this example (taken from the Python docs’ library ref‐
1426              erence index):
1427
1428                 .. toctree::
1429                    :maxdepth: 2
1430
1431                    intro
1432                    strings
1433                    datatypes
1434                    numeric
1435                    (many more documents listed here)
1436
1437              This accomplishes two things:
1438
1439              · 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
1444              · 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
1450              Entries
1451
1452              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
1458                 .. toctree::
1459
1460                    intro
1461                    All about strings <strings>
1462                    datatypes
1463
1464              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
1468              You  can  also add external links, by giving an HTTP URL instead
1469              of a document name.
1470
1471              Section numbering
1472
1473              If you want to have section numbers even in  HTML  output,  give
1474              the toplevel toctree a numbered option.  For example:
1475
1476                 .. toctree::
1477                    :numbered:
1478
1479                    foo
1480                    bar
1481
1482              Numbering  then  starts at the heading of foo.  Sub-toctrees are
1483              automatically numbered (don’t give the numbered flag to those).
1484
1485              Numbering up to a specific depth is also possible, by giving the
1486              depth as a numeric argument to numbered.
1487
1488              Additional options
1489
1490              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
1494                 .. toctree::
1495                    :caption: Table of Contents
1496                    :name: mastertoc
1497
1498                    foo
1499
1500              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
1504                 .. toctree::
1505                    :titlesonly:
1506
1507                    foo
1508                    bar
1509
1510              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
1515                 .. toctree::
1516                    :glob:
1517
1518                    intro*
1519                    recipe/*
1520                    *
1521
1522              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
1526              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
1530              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
1534                 .. toctree::
1535                    :glob:
1536                    :reversed:
1537
1538                    recipe/*
1539
1540              You can also give a “hidden” option to the directive, like this:
1541
1542                 .. toctree::
1543                    :hidden:
1544
1545                    doc_1
1546                    doc_2
1547
1548              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
1553              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
1557                 .. toctree::
1558                    :includehidden:
1559
1560                    doc_1
1561                    doc_2
1562
1563              All other toctree entries can then be eliminated by the “hidden”
1564              option.
1565
1566              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
1572              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
1577              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
1582              Changed in version 0.3: Added “globbing” option.
1583
1584
1585              Changed in version 0.6: Added “numbered” and “hidden” options as
1586              well as external links and support for “self” references.
1587
1588
1589              Changed in version 1.0: Added “titlesonly” option.
1590
1591
1592              Changed in version 1.1: Added numeric argument to “numbered”.
1593
1594
1595              Changed in version 1.2: Added “includehidden” option.
1596
1597
1598              Changed in version 1.3: Added “caption” and “name” option.
1599
1600
1601   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
1605       The special document names (and pages generated for them) are:
1606
1607       · genindex, modindex, search
1608
1609         These are used for the general index, the Python  module  index,  and
1610         the search page, respectively.
1611
1612         The  general  index  is  populated  with  entries  from  modules, all
1613         index-generating object descriptions, and from index directives.
1614
1615         The Python module index contains one entry per py:module directive.
1616
1617         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
1622       · every name beginning with _
1623
1624         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
1629       WARNING:
1630          Be careful with unusual characters in filenames.  Some  formats  may
1631          interpret these characters in unexpected ways:
1632
1633          · Do  not  use  the  colon : for HTML based formats.  Links to other
1634            parts may not work.
1635
1636          · Do not use the plus + for the ePub format.  Some resources may not
1637            be found.
1638

FOOTNOTES

1640       [1]  The  LaTeX writer only refers the maxdepth option of first toctree
1641            directive in the document.
1642
1643       [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
1648   Paragraph-level markup
1649       These  directives create short paragraphs and can be used inside infor‐
1650       mation units as well as normal text:
1651
1652       .. 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
1658              Example:
1659
1660                 .. note::
1661
1662                    This function is not suitable for sending spam e-mails.
1663
1664       .. 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
1672       .. 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
1678              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
1682              Example:
1683
1684                 .. versionadded:: 2.5
1685                    The *spam* parameter.
1686
1687              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
1691       .. 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
1696       .. 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
1701                 .. deprecated:: 3.1
1702                    Use :func:`spam` instead.
1703
1704
1705                                        ----
1706
1707
1708
1709       .. 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
1714              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
1718              The content of the seealso directive should be a reST definition
1719              list. Example:
1720
1721                 .. seealso::
1722
1723                    Module :py:mod:`zipfile`
1724                       Documentation of the :py:mod:`zipfile` standard module.
1725
1726                    `GNU tar manual, Basic Tar Format <http://link>`_
1727                       Documentation for tar archive files, including GNU tar extensions.
1728
1729              There’s also a “short form” allowed that looks like this:
1730
1731                 .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
1732
1733              New in version 0.5: The short form.
1734
1735
1736       .. rubric:: title
1737              This directive creates a paragraph heading that is not  used  to
1738              create a table of contents node.
1739
1740              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
1746       .. centered::
1747              This directive creates a centered boldfaced line of  text.   Use
1748              it as follows:
1749
1750                 .. centered:: LICENSE AGREEMENT
1751
1752              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
1756
1757       .. 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
1763              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
1767                 .. hlist::
1768                    :columns: 3
1769
1770                    * A list of
1771                    * short items
1772                    * that should be
1773                    * displayed
1774                    * horizontally
1775
1776              New in version 0.6.
1777
1778
1779   Table-of-contents markup
1780       The toctree directive, which generates tables of contents  of  subdocu‐
1781       ments, is described in toctree-directive.
1782
1783       For local tables of contents, use the standard reST contents directive.
1784
1785   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
1791                 .. glossary::
1792
1793                    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
1799                    source directory
1800                       The directory which, including its subdirectories, contains all
1801                       source files for one Sphinx project.
1802
1803              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
1807                 .. glossary::
1808
1809                    term 1
1810                    term 2
1811                       Definition of both terms.
1812
1813              (When the glossary is sorted, the first term determines the sort
1814              order.)
1815
1816              If you want to specify “grouping key” for general index entries,
1817              you can put a “key” as “term : key”. For example:
1818
1819                 .. glossary::
1820
1821                    term 1 : A
1822                    term 2 : B
1823                       Definition of both terms.
1824
1825              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
1831              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
1835              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
1839
1840              Changed  in  version 1.1: Now supports multiple terms and inline
1841              markup in terms.
1842
1843
1844              Changed in version 1.4: Index key for glossary  term  should  be
1845              considered experimental.
1846
1847
1848   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
1856       .. 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
1863              The argument to productionlist serves to  distinguish  different
1864              sets of production lists that belong to different grammars.
1865
1866              Blank  lines  are  not  allowed  within productionlist directive
1867              arguments.
1868
1869              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
1875              Note that no further reST parsing is done in the production,  so
1876              that you don’t have to escape * or | characters.
1877
1878       The following is an example taken from the Python Reference Manual:
1879
1880          .. 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
1889   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
1894       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
1900          >>> 1 + 1
1901          2
1902          >>>
1903
1904       Syntax highlighting is done with Pygments and handled in a smart way:
1905
1906       · 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
1911       · 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
1917       · The highlighting language can be changed using the  highlight  direc‐
1918         tive, used as follows:
1919
1920         .. highlight:: language
1921                Example:
1922
1923                   .. highlight:: c
1924
1925                This  language  is  used until the next highlight directive is
1926                encountered.
1927
1928       · 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
1932         .. code-block:: language
1933                Use it like this:
1934
1935                   .. code-block:: ruby
1936
1937                      Some Ruby code.
1938
1939                The directive’s alias name sourcecode works as well.
1940
1941       · The valid values for the highlighting language are:
1942
1943         · none (no highlighting)
1944
1945         · python (the default when highlight_language isn’t set)
1946
1947         · guess (let Pygments guess the lexer based on contents,  only  works
1948           with certain well-recognizable languages)
1949
1950         · rest
1951
1952         · c
1953
1954         · … and any other lexer alias that Pygments supports.
1955
1956       · If highlighting with the selected language fails (i.e. Pygments emits
1957         an “Error” token), the block is not highlighted in any way.
1958
1959   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
1964          .. highlight:: python
1965             :linenothreshold: 5
1966
1967       This will produce line numbers for all code  blocks  longer  than  five
1968       lines.
1969
1970       For  code-block blocks, a linenos flag option can be given to switch on
1971       line numbers for the individual block:
1972
1973          .. code-block:: ruby
1974             :linenos:
1975
1976             Some more Ruby code.
1977
1978       The first line number can be selected with the lineno-start option.  If
1979       present, linenos flag is automatically activated:
1980
1981          .. code-block:: ruby
1982             :lineno-start: 10
1983
1984             Some more Ruby code, with line numbering starting at 10.
1985
1986       Additionally,  an  emphasize-lines option can be given to have Pygments
1987       emphasize particular lines:
1988
1989          .. code-block:: python
1990             :emphasize-lines: 3,5
1991
1992             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
1998       Changed in version 1.1: emphasize-lines has been added.
1999
2000
2001       Changed in version 1.3: lineno-start has been added.
2002
2003
2004       Changed in version 1.6.6: LaTeX supports the emphasize-lines option.
2005
2006
2007   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
2014                 .. literalinclude:: example.py
2015
2016              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
2020              Tabs  in  the  input are expanded if you give a tab-width option
2021              with the desired tab width.
2022
2023              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
2030                 .. literalinclude:: example.rb
2031                    :language: ruby
2032                    :emphasize-lines: 12,15-18
2033                    :linenos:
2034
2035              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
2039                 .. literalinclude:: example.py
2040                    :encoding: latin-1
2041
2042              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
2046                 .. literalinclude:: example.py
2047                    :pyobject: Timer.start
2048
2049              This  would only include the code lines belonging to the start()
2050              method in the Timer class within the file.
2051
2052              Alternately, you can specify exactly which lines to  include  by
2053              giving a lines option:
2054
2055                 .. literalinclude:: example.py
2056                    :lines: 1,3,5-10,20-
2057
2058              This  includes  the lines 1, 3, 5 to 10 and lines 20 to the last
2059              line.
2060
2061              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
2068              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
2072              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
2076              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
2081              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
2086              If  you  want  to show the diff of the code, you can specify the
2087              old file by giving a diff option:
2088
2089                 .. literalinclude:: example.py
2090                    :diff: example.py.orig
2091
2092              This shows the diff between example.py and example.py.orig  with
2093              unified diff format.
2094
2095              New in version 0.4.3: The encoding option.
2096
2097
2098              New  in  version  0.6:  The  pyobject,  lines,  start-after  and
2099              end-before options, as well as support for absolute filenames.
2100
2101
2102              New in version 1.0: The prepend and append options, as  well  as
2103              tab-width.
2104
2105
2106              New in version 1.3: The diff option.  The lineno-match option.
2107
2108
2109              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
2113
2114   Caption and name
2115       New in version 1.3.
2116
2117
2118       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
2122          .. code-block:: python
2123             :caption: this.py
2124             :name: this-py
2125
2126             print 'Explicit is better than implicit.'
2127
2128       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
2132   Dedent
2133       New in version 1.3.
2134
2135
2136       A  dedent  option can be given to strip indentation characters from the
2137       code block. For example:
2138
2139          .. literalinclude:: example.rb
2140             :language: ruby
2141             :dedent: 4
2142             :lines: 10-15
2143
2144       code-block also supports the dedent option.
2145

FOOTNOTES

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
2150   Inline markup
2151       Sphinx uses interpreted text roles to insert semantic markup into docu‐
2152       ments.  They are written as :rolename:`content`.
2153
2154       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
2161       See domains for roles added by domains.
2162
2163   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
2169       There  are  some additional facilities, however, that make cross-refer‐
2170       encing roles more versatile:
2171
2172       · 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
2176       · If you prefix the content with !, no reference/hyperlink will be cre‐
2177         ated.
2178
2179       · 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
2185         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
2188   Cross-referencing anything
2189       :any:  New in version 1.3.
2190
2191
2192              This convenience role tries to do its best to find a valid  tar‐
2193              get for its reference text.
2194
2195              · First, it tries standard cross-reference targets that would be
2196                referenced by doc, ref or option.
2197
2198                Custom objects added to the standard domain by extensions (see
2199                Sphinx.add_object_type()) are also searched.
2200
2201              · 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
2206              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
2210              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
2214                 .. function:: install()
2215
2216                    This function installs a `handler` for every signal known by the
2217                    `signal` module.  See the section `about-signals` for more information.
2218
2219              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
2223              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
2227   Cross-referencing objects
2228       These roles are described with their respective domains:
2229
2230       · Python
2231
2232       · C
2233
2234       · C++
2235
2236       · JavaScript
2237
2238       · ReST
2239
2240   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
2246              · If  you place a label directly before a section title, you can
2247                reference to it with :ref:`label-name`.  Example:
2248
2249                   .. _my-reference-label:
2250
2251                   Section to cross-reference
2252                   --------------------------
2253
2254                   This is the text of the section.
2255
2256                   It refers to the section itself, see :ref:`my-reference-label`.
2257
2258                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
2263                Automatic labels also work with figures: given
2264
2265                   .. _my-figure:
2266
2267                   .. figure:: whatever
2268
2269                      Figure caption
2270
2271                a  reference  :ref:`my-figure` would insert a reference to the
2272                figure with link text “Figure caption”.
2273
2274                The same works for tables that are given an  explicit  caption
2275                using the table directive.
2276
2277              · 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
2281              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
2286              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
2291   Cross-referencing documents
2292       New in version 0.6.
2293
2294
2295       There is also a way to directly link to documents:
2296
2297       :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
2303              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
2307   Referencing downloadable files
2308       New in version 0.6.
2309
2310
2311       :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
2316              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
2322              An example:
2323
2324                 See :download:`this example script <../example.py>`.
2325
2326              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
2330              The example.py file will be copied to the output directory,  and
2331              a suitable link generated to it.
2332
2333              Not  to  show  unavailable download links, you should wrap whole
2334              paragraphs that have this role:
2335
2336                 .. only:: builder_html
2337
2338                    See :download:`this example script <../example.py>`.
2339
2340   Cross-referencing figures by figure number
2341       New in version 1.3.
2342
2343
2344       Changed in version 1.5: numref role can also refer sections.  And  num‐
2345       ref allows {name} for the link text.
2346
2347
2348       :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
2354              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
2361              If  numfig  is  False,  figures  are  not numbered, so this role
2362              inserts not a reference but the label or the link text.
2363
2364   Cross-referencing other items of interest
2365       The following roles do possibly create a cross-reference,  but  do  not
2366       refer to objects:
2367
2368       :envvar:
2369              An  environment  variable.   Index  entries are generated.  Also
2370              generates a link to the matching envvar directive, if it exists.
2371
2372       :token:
2373              The name of a grammar token (used to create links  between  pro‐
2374              ductionlist directives).
2375
2376       :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
2380       :option:
2381              A command-line option to an executable program.  This  generates
2382              a link to a option directive, if it exists.
2383
2384       The following role creates a cross-reference to a term in a glossary:
2385
2386       :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
2392              If you use a term that’s not explained in a glossary, you’ll get
2393              a warning during build.
2394
2395   Other semantic markup
2396       The following roles don’t do anything  special  except  formatting  the
2397       text in a different style:
2398
2399       :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
2403              Example: :abbr:`LIFO (last-in, first-out)`.
2404
2405              New in version 0.6.
2406
2407
2408       :command:
2409              The name of an OS-level command, such as rm.
2410
2411       :dfn:  Mark  the  defining  instance  of a term in the text.  (No index
2412              entries are generated.)
2413
2414       :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
2417                 ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
2418
2419              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
2423       :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
2432              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
2437
2438       :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
2447       :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
2457       :makevar:
2458              The name of a make variable.
2459
2460       :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
2465       :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
2472              For example, to mark the selection “Start > Programs”, use  this
2473              markup:
2474
2475                 :menuselection:`Start --> Programs`
2476
2477              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
2482              menuselection also supports  ampersand  accelerators  just  like
2483              guilabel.
2484
2485       :mimetype:
2486              The  name  of  a  MIME  type, or a component of a MIME type (the
2487              major or minor portion, taken alone).
2488
2489       :newsgroup:
2490              The name of a Usenet newsgroup.
2491
2492       :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
2498       :regexp:
2499              A regular expression. Quotes should not be included.
2500
2501       :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
2506              If you don’t need the “variable part” indication, use the  stan‐
2507              dard ``code`` instead.
2508
2509       There is also an index role to generate index entries.
2510
2511       The following roles generate external links:
2512
2513       :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
2519       :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
2525       Note  that  there  are no special roles for including hyperlinks as you
2526       can use the standard reST markup for that purpose.
2527
2528   Substitutions
2529       The documentation system provides three substitutions that are  defined
2530       by default. They are set in the build configuration file.
2531
2532       |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
2538       |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
2543       |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
2549   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
2554          :fieldname: Field content
2555
2556       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
2564       At the moment, these metadata fields are recognized:
2565
2566       tocdepth
2567              The maximum depth for a table of contents of this file.
2568
2569              New in version 0.4.
2570
2571
2572       nocomments
2573              If set, the web application won’t display a comment form  for  a
2574              page generated from this source file.
2575
2576       orphan If  set, warnings about this file not being included in any toc‐
2577              tree will be suppressed.
2578
2579              New in version 1.0.
2580
2581
2582   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
2589                 .. sectionauthor:: Guido van Rossum <guido@python.org>
2590
2591              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
2596       .. 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
2602   Index-generating markup
2603       Sphinx automatically creates index entries from all object descriptions
2604       (like functions, classes or attributes) like discussed in domains.
2605
2606       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
2611       .. 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
2615              For example:
2616
2617                 .. index::
2618                    single: execution; context
2619                    module: __main__
2620                    module: sys
2621                    triple: module; search; path
2622
2623                 The execution context
2624                 ---------------------
2625
2626                 ...
2627
2628              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
2633              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
2637              The possible entry types are:
2638
2639              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
2644              pair   pair: loop; statement is  a  shortcut  that  creates  two
2645                     index  entries,  namely  loop;  statement  and statement;
2646                     loop.
2647
2648              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
2652              see    see: entry; other creates an index entry that refers from
2653                     entry to other.
2654
2655              seealso
2656                     Like see, but inserts “see also” instead of “see”.
2657
2658              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
2664              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
2668                 .. index:: Python
2669
2670              and one page contains
2671
2672                 .. index:: ! Python
2673
2674              then the backlink to the latter page  is  emphasized  among  the
2675              three backlinks.
2676
2677              For  index directives containing only “single” entries, there is
2678              a shorthand notation:
2679
2680                 .. index:: BNF, grammar, syntax, notation
2681
2682              This creates four index entries.
2683
2684              Changed in version 1.1: Added see and seealso types, as well  as
2685              marking main entries.
2686
2687
2688       :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
2693              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
2700                 This is a normal reST :index:`paragraph` that contains several
2701                 :index:`index entries <pair: index; entry>`.
2702
2703              New in version 1.1.
2704
2705
2706   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
2711                 .. only:: html and draft
2712
2713              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
2718              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
2724              These standard tags are set  after  the  configuration  file  is
2725              read, so they are not available there.
2726
2727              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
2734              New in version 0.6.
2735
2736
2737              Changed in version 1.2: Added the name of the  builder  and  the
2738              prefixes.
2739
2740
2741              WARNING:
2742                 This  directive  is designed to control only content of docu‐
2743                 ment.  It could not control sections, labels and so on.
2744
2745   Tables
2746       Use reStructuredText tables, i.e. either
2747
2748       · grid table syntax (ref),
2749
2750       · simple table syntax (ref),
2751
2752       · csv-table syntax,
2753
2754       · or list-table syntax.
2755
2756       The table directive serves as optional wrapper of the grid  and  simple
2757       syntaxes.
2758
2759       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
2763       .. 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
2769                 |l|l|l|
2770
2771              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
2776                              ┌──┬────────────────────────────┐
2777L │ flush   left  column  with │
2778                              │  │ automatic width            │
2779                              ├──┼────────────────────────────┤
2780R │ flush  right  column  with │
2781                              │  │ automatic width            │
2782                              ├──┼────────────────────────────┤
2783C │ centered column with auto‐ │
2784                              │  │ matic width                │
2785                              ├──┼────────────────────────────┤
2786J │ justified   column    with │
2787                              │  │ automatic width            │
2788                              └──┴────────────────────────────┘
2789
2790              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
2795              By default, Sphinx uses a table layout with J for every column.
2796
2797              New in version 0.3.
2798
2799
2800              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
2805
2806              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
2811                 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
2816                 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
2821              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
2826                 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
2835                 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
2841              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
2847              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
2853              This is used by the :widths: option of the table directive.
2854
2855              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
2859              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
2863              Sphinx’s merged cells interact  well  with  p{width},  \X{a}{b},
2864              Y{f} and tabulary’s columns.
2865
2866
2867              NOTE:
2868                 tabularcolumns conflicts with :widths: option of table direc‐
2869                 tives.  If  both  are  specified,  :widths:  option  will  be
2870                 ignored.
2871
2872   Math
2873       See math-support.
2874

FOOTNOTES

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
2880            Note  that the current builder tag is not available in conf.py, it
2881            is only available after the builder is initialized.
2882
2883            More markup is added by domains.
2884

SPHINX DOMAINS

2886       New in version 1.0.
2887
2888
2889   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
2899       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
2904       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
2910       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
2915       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
2919   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
2928          .. py:function:: spam(eggs)
2929                           ham(eggs)
2930
2931             Spam or ham the foo.
2932
2933       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
2937          .. py:function:: filterwarnings(action, message='', category=Warning, \
2938                                          module='', lineno=0, append=False)
2939             :noindex:
2940
2941       (This example also shows how to use the :noindex: flag.)
2942
2943       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
2947          The function :py:func:`spam` does a similar thing.
2948
2949       As  you  can see, both directive and role names contain the domain name
2950       and the directive name.  Default Domain
2951
2952       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
2957       .. 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
2961       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
2965       Directives and roles that belong to the default domain can be mentioned
2966       without giving the domain name, i.e.
2967
2968          .. function:: pyfunc()
2969
2970             Describes a Python function.
2971
2972          Reference to :func:`pyfunc`.
2973
2974   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
2978       In short:
2979
2980       · 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
2983       · If you prefix the content with !, no reference/hyperlink will be cre‐
2984         ated.
2985
2986       · 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
2990   The Python Domain
2991       The Python domain (name py) provides the following directives for  mod‐
2992       ule declarations:
2993
2994       .. 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
3000              This directive will also cause an entry  in  the  global  module
3001              index.
3002
3003              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
3010              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
3014              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
3018       .. 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
3027       The following directives are provided for module and class contents:
3028
3029       .. 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
3034                 .. py:function:: Timer.repeat(repeat=3, number=1000000)
3035
3036              For methods you should use py:method.
3037
3038              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
3043              This  information  can (in any py directive) optionally be given
3044              in a structured form, see Info field lists.
3045
3046       .. 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
3051       .. py:exception:: name
3052              Describes an exception class.  The signature can, but  need  not
3053              include parentheses with constructor arguments.
3054
3055       .. py:class:: name
3056
3057       .. 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
3062              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
3067                 .. py:class:: Foo
3068
3069                    .. py:method:: quux()
3070
3071                 -- or --
3072
3073                 .. py:class:: Bar
3074
3075                 .. py:method:: Bar.quux()
3076
3077              The first way is the preferred one.
3078
3079       .. 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
3084       .. 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
3090       .. py:staticmethod:: name(parameters)
3091              Like  py:method,  but  indicates  that  the  method  is a static
3092              method.
3093
3094              New in version 0.4.
3095
3096
3097       .. py:classmethod:: name(parameters)
3098              Like py:method, but indicates that the method is a class method.
3099
3100              New in version 0.6.
3101
3102
3103       .. py:decorator:: name
3104
3105       .. 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
3109                 def removename(func):
3110                     func.__name__ = ''
3111                     return func
3112
3113                 def setnewname(name):
3114                     def decorator(func):
3115                         func.__name__ = name
3116                         return func
3117                     return decorator
3118
3119              the descriptions should look like this:
3120
3121                 .. py:decorator:: removename
3122
3123                    Remove name of the decorated function.
3124
3125                 .. py:decorator:: setnewname(name)
3126
3127                    Set name of the decorated function to *name*.
3128
3129              (as opposed to .. py:decorator:: removename(func).)
3130
3131              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
3134       .. py:decoratormethod:: name
3135
3136       .. py:decoratormethod:: name(signature)
3137              Same as py:decorator, but for decorators that are methods.
3138
3139              Refer to a decorator method using the py:meth role.
3140
3141   Python Signatures
3142       Signatures of functions, methods and class constructors  can  be  given
3143       like they would be written in Python.
3144
3145       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
3149          .. py:function:: compile(source : string, filename, symbol='file') -> ast object
3150
3151       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
3155          compile(source[, filename[, symbol]])
3156
3157       It is customary to put the opening bracket before the comma.
3158
3159   Info field lists
3160       New in version 0.4.
3161
3162
3163       Inside  Python  object  description  directives,  reST field lists with
3164       these fields are recognized and formatted nicely:
3165
3166       · param, parameter, arg,  argument,  key,  keyword:  Description  of  a
3167         parameter.
3168
3169       · type: Type of a parameter.  Creates a link if possible.
3170
3171       · raises,  raise,  except, exception: That (and when) a specific excep‐
3172         tion is raised.
3173
3174       · var, ivar, cvar: Description of a variable.
3175
3176       · vartype: Type of a variable.  Creates a link if possible.
3177
3178       · returns, return: Description of the return value.
3179
3180       · rtype: Return type.  Creates a link if possible.
3181
3182       NOTE:
3183          In current release, all var, ivar and cvar are represented as “Vari‐
3184          able”.  There is no difference at all.
3185
3186       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
3190          .. py:function:: send_message(sender, recipient, message_body, [priority=1])
3191
3192             Send a message to a recipient
3193
3194             :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
3204       This will render like this:
3205
3206          send_message(sender, recipient, message_body[, priority=1])
3207                 Send a message to a recipient
3208
3209                 Parameters
3210
3211                        · sender (str) – The person sending the message
3212
3213                        · recipient (str) – The recipient of the message
3214
3215                        · message_body (str) – The body of the message
3216
3217                        · priority  (integer  or  None)  – The priority of the
3218                          message, can be a number 1-5
3219
3220                 Returns
3221                        the message id
3222
3223                 Return type
3224                        int
3225
3226                 Raises
3227
3228                        · ValueError – if the message_body exceeds 160 charac‐
3229                          ters
3230
3231                        · TypeError – if the message_body is not a basestring
3232
3233       It  is  also possible to combine parameter type and description, if the
3234       type is a single word, like this:
3235
3236          :param int priority: The priority of the message, can be a number 1-5
3237
3238       New in version 1.5.
3239
3240
3241       Container types such as lists and dictionaries can be linked  automati‐
3242       cally using the following syntax:
3243
3244          :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
3251       Multiple  types  in  a type field will be linked automatically if sepa‐
3252       rated by the word “or”:
3253
3254          :type an_arg: int or None
3255          :vartype a_var: str or int
3256          :rtype: float or str
3257
3258   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
3262       :py:mod:
3263              Reference a module; a dotted name may be used.  This should also
3264              be used for package names.
3265
3266       :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
3272       :py:data:
3273              Reference a module-level variable.
3274
3275       :py:const:
3276              Reference  a  “defined” constant.  This may be a Python variable
3277              that is not intended to be changed.
3278
3279       :py:class:
3280              Reference a class; a dotted name may be used.
3281
3282       :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
3288       :py:attr:
3289              Reference a data attribute of an object.
3290
3291       :py:exc:
3292              Reference an exception.  A dotted name may be used.
3293
3294       :py:obj:
3295              Reference  an  object  of  unspecified type.  Useful e.g. as the
3296              default_role.
3297
3298              New in version 0.4.
3299
3300
3301       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
3307       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
3314       A  similar  heuristic  is  used  to  determine  whether  the name is an
3315       attribute of the currently documented class.
3316
3317       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
3324       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
3328   The C Domain
3329       The C domain (name c) is suited for documentation of C API.
3330
3331       .. c:function:: function prototype
3332              Describes  a  C function. The signature should be given as in C,
3333              e.g.:
3334
3335                 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
3336
3337              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
3341              Note that you don’t have to backslash-escape  asterisks  in  the
3342              signature, as it is not parsed by the reST inliner.
3343
3344       .. c:member:: declaration
3345              Describes a C struct member. Example signature:
3346
3347                 .. c:member:: PyObject* PyTypeObject.tp_bases
3348
3349              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
3354       .. 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
3361       .. 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
3365       .. c:var:: declaration
3366              Describes a global C variable.  The signature should include the
3367              type, such as:
3368
3369                 .. c:var:: PyObject* PyClass_Type
3370
3371   Cross-referencing C constructs
3372       The following roles create cross-references to C-language constructs if
3373       they are defined in the documentation:
3374
3375       :c:func:
3376              Reference  a C-language function. Should include trailing paren‐
3377              theses.
3378
3379       :c:member:
3380              Reference a C-language member of a struct.
3381
3382       :c:macro:
3383              Reference a “simple” C macro, as defined above.
3384
3385       :c:type:
3386              Reference a C-language type.
3387
3388       :c:data:
3389              Reference a C-language variable.
3390
3391   The C++ Domain
3392       The C++ domain (name cpp) supports documenting C++ projects.
3393
3394   Directives
3395       The following directives are available. All declarations can start with
3396       a visibility statement (public, private or protected).
3397
3398       .. cpp:class:: class specifier
3399              Describe  a class/struct, possibly with specification of inheri‐
3400              tance, e.g.,:
3401
3402                 .. cpp:class:: MyClass : public MyBase, MyOtherBase
3403
3404              The class can be directly declared inside a nested scope, e.g.,:
3405
3406                 .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
3407
3408              A class template can be declared:
3409
3410                 .. cpp:class:: template<typename T, std::size_t N> std::array
3411
3412              or with a line break:
3413
3414                 .. cpp:class:: template<typename T, std::size_t N> \
3415                                std::array
3416
3417              Full and partial template specialisations can be declared:
3418
3419                 .. cpp:class:: template<> \
3420                                 std::array<bool, 256>
3421
3422                 .. cpp:class:: template<typename T> \
3423                                 std::array<T, 42>
3424
3425       .. cpp:function:: (member) function prototype
3426              Describe a function or member function, e.g.,:
3427
3428                 .. cpp:function:: bool myMethod(int arg1, std::string arg2)
3429
3430                    A function with parameters and types.
3431
3432                 .. cpp:function:: bool myMethod(int, double)
3433
3434                    A function with unnamed parameters.
3435
3436                 .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
3437
3438                    An overload for the indexing operator.
3439
3440                 .. cpp:function:: operator bool() const
3441
3442                    A casting operator.
3443
3444                 .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
3445
3446                    A constexpr function.
3447
3448                 .. cpp:function:: MyClass::MyClass(const MyClass&) = default
3449
3450                    A copy constructor with default implementation.
3451
3452              Function templates can also be described:
3453
3454                 .. cpp:function:: template<typename U> \
3455                                   void print(U &&u)
3456
3457              and function template specialisations:
3458
3459                 .. cpp:function:: template<> \
3460                                   void print(int i)
3461
3462       .. cpp:member:: (member) variable declaration
3463
3464       .. cpp:var:: (member) variable declaration
3465              Describe a variable or member variable, e.g.,:
3466
3467                 .. cpp:member:: std::string MyClass::myMember
3468
3469                 .. cpp:var:: std::string MyClass::myOtherMember[N][M]
3470
3471                 .. cpp:member:: int a = 42
3472
3473              Variable templates can also be described:
3474
3475                 .. cpp:member:: template<class T> \
3476                                 constexpr T pi = T(3.1415926535897932385)
3477
3478       .. cpp:type:: typedef declaration
3479
3480       .. cpp:type:: name
3481
3482       .. 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
3487                 .. cpp:type:: std::vector<int> MyList
3488
3489                    A typedef-like declaration of a type.
3490
3491                 .. cpp:type:: MyContainer::const_iterator
3492
3493                    Declaration of a type alias with unspecified type.
3494
3495                 .. cpp:type:: MyType = std::unordered_map<int, std::string>
3496
3497                    Declaration of a type alias.
3498
3499              A type alias can also be templated:
3500
3501                 .. cpp:type:: template<typename T> \
3502                               MyContainer = std::vector<T>
3503
3504              The example are rendered as follows.
3505
3506              typedef std::vector<int> MyList
3507                     A typedef-like declaration of a type.
3508
3509              type MyContainer::const_iterator
3510                     Declaration of a type alias with unspecified type.
3511
3512              using MyType = std::unordered_map<int, std::string>
3513                     Declaration of a type alias.
3514
3515              template<typename T> using MyContainer = std::vector<T>
3516
3517       .. cpp:enum:: unscoped enum declaration
3518
3519       .. cpp:enum-struct:: scoped enum declaration
3520
3521       .. 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
3527                 .. cpp:enum:: MyEnum
3528
3529                    An unscoped enum.
3530
3531                 .. cpp:enum:: MySpecificEnum : long
3532
3533                    An unscoped enum with specified underlying type.
3534
3535                 .. cpp:enum-class:: MyScopedEnum
3536
3537                    A scoped enum.
3538
3539                 .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type<MySpecificEnum>::type
3540
3541                    A scoped enum with non-default visibility, and with a specified underlying type.
3542
3543       .. cpp:enumerator:: name
3544
3545       .. cpp:enumerator:: name = constant
3546              Describe  an  enumerator,  optionally  with  its  value defined,
3547              e.g.,:
3548
3549                 .. cpp:enumerator:: MyEnum::myEnumerator
3550
3551                 .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
3552
3553       .. cpp:concept:: template-parameter-list name
3554
3555              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
3560              Describe a concept. It must have exactly  1  template  parameter
3561              list. The name may be a nested name. Example:
3562
3563                 .. cpp:concept:: template<typename It> std::Iterator
3564
3565                    Proxy to an element of a notional sequence that can be compared,
3566                    indirected, or incremented.
3567
3568                    **Notation**
3569
3570                    .. cpp:var:: It r
3571
3572                       An lvalue.
3573
3574                    **Valid Expressions**
3575
3576                    - :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
3579              This will render as follows:
3580
3581              template<typename It> concept std::Iterator
3582                     Proxy  to  an  element of a notional sequence that can be
3583                     compared, indirected, or incremented.
3584
3585                     Notation
3586
3587                     It r   An lvalue.
3588
3589                     Valid Expressions
3590
3591                     · *r, when r is dereferenceable.
3592
3593                     · ++r, with return type It&, when r is incrementable.
3594
3595   Options
3596       Some directives support options:
3597
3598       · :noindex:, see Basic Markup.
3599
3600       · :tparam-line-spec:, for templated declarations.  If  specified,  each
3601         template parameter will be rendered on a separate line.
3602
3603   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
3609       NOTE:
3610          Sphinx does not currently support requires clauses.
3611
3612   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
3617          .. cpp:function:: void f(auto &&arg)
3618
3619             A function template with a single unconstrained template parameter.
3620
3621          .. cpp:function:: void f(std::Iterator it)
3622
3623             A function template with a single template parameter, constrained by the
3624             Iterator concept.
3625
3626   Template Introductions
3627       Simple  constrained  function or class templates can be declared with a
3628       template introduction instead of a template parameter list:
3629
3630          .. cpp:function:: std::Iterator{It} void advance(It &it)
3631
3632              A function template with a template parameter constrained to be an Iterator.
3633
3634          .. cpp:class:: std::LessThanComparable{T} MySortedContainer
3635
3636              A class template with a template parameter constrained to be LessThanComparable.
3637
3638       They are rendered as follows.
3639
3640       std::Iterator{It} void advance(It &it)
3641              A function template with a template parameter constrained to  be
3642              an Iterator.
3643
3644       std::LessThanComparable{T} class MySortedContainer
3645              A  class  template  with  a template parameter constrained to be
3646              LessThanComparable.
3647
3648       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
3652   Inline Expressions and Tpes
3653       :cpp:expr:
3654                 A role for inserting a C++ expression or type as inline text.
3655                 For example:
3656
3657                     .. cpp:var:: int a = 42
3658
3659                     .. cpp:function:: int f(int i)
3660
3661                     An expression: :cpp:expr:`a * f(a)`.
3662                     A type: :cpp:expr:`const MySortedContainer<int>&`.
3663
3664                 will be rendered as follows:
3665
3666              int a = 42
3667
3668              int f(int i)
3669
3670              An expression: a * f(a).  A type: const MySortedContainer<int>&.
3671
3672   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
3680       .. 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
3686                 .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
3687
3688              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
3692              Using  NULL,  0,  or  nullptr as the scope will change to global
3693              scope.
3694
3695              A namespace declaration can also be templated, e.g.,:
3696
3697                 .. cpp:class:: template<typename T> \
3698                                std::vector
3699
3700                 .. cpp:namespace:: template<typename T> std::vector
3701
3702                 .. cpp:function:: std::size_t size() const
3703
3704              declares size  as  a  member  function  of  the  class  template
3705              std::vector.  Equivalently this could have been declared using:
3706
3707                 .. cpp:class:: template<typename T> \
3708                                std::vector
3709
3710                    .. cpp:function:: std::size_t size() const
3711
3712              or::
3713
3714                 .. cpp:class:: template<typename T> \
3715                                std::vector
3716
3717       .. cpp:namespace-push:: scope specification
3718              Change  the  scope relatively to the current scope. For example,
3719              after:
3720
3721                 .. cpp:namespace:: A::B
3722
3723                 .. cpp:namespace-push:: C::D
3724
3725              the current scope will be A::B::C::D.
3726
3727       .. cpp:namespace-pop::
3728              Undo the previous cpp:namespace-push directive (not just  pop  a
3729              scope).  For example, after:
3730
3731                 .. cpp:namespace:: A::B
3732
3733                 .. cpp:namespace-push:: C::D
3734
3735                 .. cpp:namespace-pop::
3736
3737              the current scope will be A::B (not A::B::C).
3738
3739              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
3744                 .. cpp:namespace:: nullptr
3745
3746                 .. cpp:namespace-push:: A::B
3747
3748   Info field lists
3749       The C++ directives support the following info  fields  (see  also  Info
3750       field lists):
3751
3752       · param, parameter, arg, argument: Description of a parameter.
3753
3754       · tparam: Description of a template parameter.
3755
3756       · returns, return: Description of a return value.
3757
3758       · throws, throw, exception: Description of a possibly thrown exception.
3759
3760   Cross-referencing
3761       These roles link to the given declaration types:
3762
3763       :cpp:any:
3764
3765       :cpp:class:
3766
3767       :cpp:func:
3768
3769       :cpp:member:
3770
3771       :cpp:var:
3772
3773       :cpp:type:
3774
3775       :cpp:concept:
3776
3777       :cpp:enum:
3778
3779       :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
3784          Note on References with Templates Parameters/Arguments
3785
3786                 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
3794          Note on References to Overloaded Functions
3795
3796                 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
3804   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
3808   Templated declarations
3809       Assume the following declarations.
3810
3811       class Wrapper
3812
3813              template<typename TOuter> class Outer
3814
3815                     template<typename TInner> class Inner
3816
3817       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
3823       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
3829       · Wrapper::Outer (Wrapper::Outer)
3830
3831       · Wrapper::Outer::Inner (Wrapper::Outer::Inner)
3832
3833       · template\<typename TInner>  Wrapper::Outer::Inner  (template<typename
3834         TInner> Wrapper::Outer::Inner)
3835
3836   (Full) Template Specialisations
3837       Assume the following declarations.
3838
3839       template<typename TOuter> class Outer
3840
3841              template<typename TInner> class Inner
3842
3843       template<> class Outer<int>
3844
3845              template<typename TInner> class Inner
3846
3847              template<> class Inner<bool>
3848
3849       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
3857   Partial Template Specialisations
3858       Assume the following declaration.
3859
3860       template<typename T> class Outer<T *>
3861
3862       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
3867   Configuration Variables
3868       See cpp-config.
3869
3870   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
3875       The standard domain is also where  custom  object  descriptions,  added
3876       using the add_object_type() API, are placed.
3877
3878       There  is  a  set  of directives allowing documenting command-line pro‐
3879       grams:
3880
3881       .. 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
3885                 .. option:: dest_dir
3886
3887                    Destination directory.
3888
3889                 .. option:: -m <module>, --module <module>
3890
3891                    Run a module as a script.
3892
3893              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
3898              cmdoption directive is a deprecated alias for the option  direc‐
3899              tive.
3900
3901       .. envvar:: name
3902              Describes  an  environment  variable that the documented code or
3903              program uses or defines.  Referencable by envvar.
3904
3905       .. 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
3910              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
3914                 .. program:: rm
3915
3916                 .. option:: -r
3917
3918                    Work recursively.
3919
3920                 .. program:: svn
3921
3922                 .. option:: -r revision
3923
3924                    Specify the revision to work upon.
3925
3926              then :option:`rm -r` would refer  to  the  first  option,  while
3927              :option:`svn -r` would refer to the second one.
3928
3929              The  program  name may contain spaces (in case you want to docu‐
3930              ment subcommands like svn add and svn commit separately).
3931
3932              New in version 0.5.
3933
3934
3935       There is also a very generic object description directive, which is not
3936       tied to any domain:
3937
3938       .. describe:: text
3939
3940       .. 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
3945                 .. describe:: PAPER
3946
3947                    You can set this variable to select a paper size.
3948
3949   The JavaScript Domain
3950       The JavaScript domain (name js) provides the following directives:
3951
3952       .. 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
3958              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
3963              To clear the current module, set the module name to null or None
3964
3965              New in version 1.6.
3966
3967
3968       .. 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
3973              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
3977                 .. js:function:: $.getJSON(href, callback[, errback])
3978
3979                    :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
3987              This is rendered as:
3988
3989                 $.getJSON(href, callback[, errback])
3990
3991                        Arguments
3992
3993                               · href (string) – An URI to the location of the
3994                                 resource.
3995
3996                               · callback – Gets called with the object.
3997
3998                               · errback – Gets called  in  case  the  request
3999                                 fails.  And  a  lot  of other text so we need
4000                                 multiple lines.
4001
4002                        Throws SomeError – For whatever reason in that case.
4003
4004                        Returns
4005                               Something.
4006
4007       .. 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
4011              New in version 1.6.
4012
4013
4014       .. 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
4018                 .. js:class:: MyAnimal(name[, age])
4019
4020                    :param string name: The name of the animal
4021                    :param number age: an optional age for the animal
4022
4023              This is rendered as:
4024
4025                 class MyAnimal(name[, age])
4026
4027                        Arguments
4028
4029                               · name (string) – The name of the animal
4030
4031                               · age (number) – an optional age for the animal
4032
4033       .. js:data:: name
4034              Describes a global variable or constant.
4035
4036       .. js:attribute:: object.name
4037              Describes the attribute name of object.
4038
4039       These roles are provided to refer to the described objects:
4040
4041       :js:mod:
4042
4043       :js:func:
4044
4045       :js:meth:
4046
4047       :js:class:
4048
4049       :js:data:
4050
4051       :js:attr:
4052
4053   The reStructuredText domain
4054       The reStructuredText domain (name rst) provides  the  following  direc‐
4055       tives:
4056
4057       .. 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
4062                 .. rst:directive:: foo
4063
4064                    Foo description.
4065
4066                 .. rst:directive:: .. bar:: baz
4067
4068                    Bar description.
4069
4070              will be rendered as:
4071
4072                 .. foo::
4073                        Foo description.
4074
4075                 .. bar:: baz
4076                        Bar description.
4077
4078       .. rst:role:: name
4079              Describes a reST role.  For example:
4080
4081                 .. rst:role:: foo
4082
4083                    Foo description.
4084
4085              will be rendered as:
4086
4087                 :foo:  Foo description.
4088
4089       These roles are provided to refer to the described objects:
4090
4091       :rst:dir:
4092
4093       :rst:role:
4094
4095   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

AVAILABLE BUILDERS

4102       These are the built-in Sphinx builders.  More builders can be added  by
4103       extensions.
4104
4105       The  builder’s  “name”  must  be given to the -b command-line option of
4106       sphinx-build to select a builder.
4107
4108       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
4115              name = 'html'
4116
4117              format = 'html'
4118
4119              supported_image_types    =    ['image/svg+xml',     'image/png',
4120              'image/gif', 'image/jpeg']
4121
4122       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
4131              name = 'dirhtml'
4132
4133              format = 'html'
4134
4135              supported_image_types     =    ['image/svg+xml',    'image/png',
4136              'image/gif', 'image/jpeg']
4137
4138              New in version 0.6.
4139
4140
4141       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
4147              name = 'singlehtml'
4148
4149              format = 'html'
4150
4151              supported_image_types     =    ['image/svg+xml',    'image/png',
4152              'image/gif', 'image/jpeg']
4153
4154              New in version 1.0.
4155
4156
4157       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
4163              name = 'htmlhelp'
4164
4165              format = 'html'
4166
4167              supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
4168
4169       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
4174              name = 'qthelp'
4175
4176              format = 'html'
4177
4178              supported_image_types     =    ['image/svg+xml',    'image/png',
4179              'image/gif', 'image/jpeg']
4180
4181       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
4185              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
4190              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
4197              name = 'applehelp'
4198
4199              format = 'html'
4200
4201              supported_image_types = ['image/png', 'image/gif', 'image/jpeg',
4202              'image/tiff', 'image/jp2', 'image/svg+xml']
4203
4204              New in version 1.3.
4205
4206
4207       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
4212              name = 'devhelp'
4213
4214              format = 'html'
4215
4216              supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
4217
4218       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
4226              name = 'epub'
4227
4228              format = 'html'
4229
4230              supported_image_types     =    ['image/svg+xml',    'image/png',
4231              'image/gif', 'image/jpeg']
4232
4233              New in version 1.4.
4234
4235
4236              Changed in version 1.5: Since Sphinx-1.5, the epub3  builder  is
4237              used for the default builder of epub.
4238
4239
4240       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
4248              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
4253              · texlive-latex-recommended
4254
4255              · texlive-fonts-recommended
4256
4257              · texlive-latex-extra
4258
4259              · latexmk (for make latexpdf on GNU/Linux and MacOS X)
4260
4261              · latex-xcolor (old Ubuntu)
4262
4263              · texlive-luatex, texlive-xetex (see latex_engine)
4264
4265              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
4269              Changed  in  version  1.6:  Formerly,  testing  had been done on
4270              Ubuntu precise (TeXLive 2009).
4271
4272
4273              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
4279                 One  can pass to latexmk options via the LATEXMKOPTS Makefile
4280                 variable. For example:
4281
4282                     make latexpdf LATEXMKOPTS="-silent"
4283
4284                 reduces console output to a minimum.
4285
4286                 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
4290                     make latexpdf LATEXMKOPTS="-xelatex"
4291
4292                 To pass options directly to the (pdf|xe|lua)latex executable,
4293                 use variable LATEXOPTS.
4294
4295                     make latexpdf LATEXOPTS="--interaction=nonstopmode"
4296
4297              name = 'latex'
4298
4299              format = 'latex'
4300
4301              supported_image_types    =    ['application/pdf',   'image/png',
4302              'image/jpeg']
4303
4304       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
4311       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
4316              name = 'text'
4317
4318              format = 'text'
4319
4320              supported_image_types = []
4321
4322              New in version 0.4.
4323
4324
4325       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
4330              name = 'man'
4331
4332              format = 'man'
4333
4334              supported_image_types = []
4335
4336              New in version 1.0.
4337
4338
4339       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
4345              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
4351              name = 'texinfo'
4352
4353              format = 'texinfo'
4354
4355              supported_image_types = ['image/png', 'image/jpeg', 'image/gif']
4356
4357              New in version 1.1.
4358
4359
4360       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
4366              A concrete subclass of this builder serializing to the PHP seri‐
4367              alization format could look like this:
4368
4369                 import phpserialize
4370
4371                 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
4378              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
4385              out_suffix
4386                     The suffix for all regular files.
4387
4388              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
4393              searchindex_filename
4394                     The filename for the search index Sphinx generates.
4395
4396              See Serialization builder details for details about  the  output
4397              format.
4398
4399              New in version 0.5.
4400
4401
4402       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
4408              See Serialization builder details for details about  the  output
4409              format.
4410
4411              name = 'pickle'
4412                     The old name web still works as well.
4413
4414              format = 'html'
4415
4416              supported_image_types     =    ['image/svg+xml',    'image/png',
4417              'image/gif', 'image/jpeg']
4418
4419              The file suffix is .fpickle.  The global context is called glob‐
4420              alcontext.pickle, the search index searchindex.pickle.
4421
4422       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
4428              See Serialization builder details for details about  the  output
4429              format.
4430
4431              name = 'json'
4432
4433              format = 'html'
4434
4435              supported_image_types     =    ['image/svg+xml',    'image/png',
4436              'image/gif', 'image/jpeg']
4437
4438              The file suffix is .fjson.  The global context is called global‐
4439              context.json, the search index searchindex.json.
4440
4441              New in version 0.5.
4442
4443
4444       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
4449              See the documentation on intl for further reference.
4450
4451              name = 'gettext'
4452
4453              format = ''
4454
4455              supported_image_types = []
4456
4457              New in version 1.1.
4458
4459
4460       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
4465              name = 'changes'
4466
4467              format = ''
4468
4469              supported_image_types = []
4470
4471       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
4475              name = 'dummy'
4476
4477              supported_image_types = []
4478
4479              New in version 1.4.
4480
4481
4482       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
4488              name = 'linkcheck'
4489
4490              format = ''
4491
4492              supported_image_types = []
4493
4494              Changed  in version 1.5: Since Sphinx-1.5, the linkcheck builder
4495              comes to use requests module.
4496
4497
4498       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
4503              name = 'xml'
4504
4505              format = 'xml'
4506
4507              supported_image_types = []
4508
4509              New in version 1.2.
4510
4511
4512       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
4520              name = 'pseudoxml'
4521
4522              format = 'pseudoxml'
4523
4524              supported_image_types = []
4525
4526              New in version 1.2.
4527
4528
4529       Built-in Sphinx extensions that offer more builders are:
4530
4531       · doctest
4532
4533       · coverage
4534
4535   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
4540       The  PickleHTMLBuilder is a builtin subclass that implements the pickle
4541       serialization interface.
4542
4543       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
4547       body   The HTML “body” (that is,  the  HTML  rendering  of  the  source
4548              file), as rendered by the HTML translator.
4549
4550       title  The title of the document, as HTML (may contain markup).
4551
4552       toc    The table of contents for the file, rendered as an HTML <ul>.
4553
4554       display_toc
4555              A boolean that is True if the toc contains more than one entry.
4556
4557       current_page_name
4558              The document name of the current file.
4559
4560       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
4566       sourcename
4567              The name of the source file under _sources.
4568
4569       The special files are located in the root output directory.  They are:
4570
4571       SerializingHTMLBuilder.globalcontext_filename
4572              A pickled dict with these keys:
4573
4574              project, copyright, release, version
4575                     The same values as given in the configuration file.
4576
4577              style  html_style.
4578
4579              last_updated
4580                     Date of last build.
4581
4582              builder
4583                     Name of the used builder, in the case of pickles this  is
4584                     always 'pickle'.
4585
4586              titles A dictionary of all documents’ titles, as HTML strings.
4587
4588       SerializingHTMLBuilder.searchindex_filename
4589              An  index  that can be used for searching the documentation.  It
4590              is a pickled list with these entries:
4591
4592              · A list of indexed docnames.
4593
4594              · A list of document titles, as HTML strings, in the same  order
4595                as the first list.
4596
4597              · 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
4601       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
4606   Todo
4607       Document common members.
4608
4609              Unlike the other pickle files this pickle file requires that the
4610              sphinx package is available on unpickling.
4611

THE BUILD CONFIGURATION FILE

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
4621       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
4626       Important points to note:
4627
4628       · If not otherwise  documented,  values  must  be  strings,  and  their
4629         default is the empty string.
4630
4631       · 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
4636       · Remember that document names use / as the path  separator  and  don’t
4637         contain the file name extension.
4638
4639       · 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
4645       · 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
4651       · 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
4659       SEE ALSO:
4660          Additional  configurations, such as adding stylesheets, javascripts,
4661          builders, etc. can be made through the /extdev/appapi.
4662
4663   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
4669              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
4674                 import sys, os
4675
4676                 sys.path.append(os.path.abspath('sphinxext'))
4677
4678                 extensions = ['extname']
4679
4680              That way, you can load an extension called extname from the sub‐
4681              directory sphinxext.
4682
4683              The configuration file itself can be an extension; for that, you
4684              only need to provide a setup() function in it.
4685
4686       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
4691              Changed in version 1.3: Can now be a list of extensions.
4692
4693
4694       source_encoding
4695              The  encoding  of all reST source files.  The recommended encod‐
4696              ing, and the default value, is 'utf-8-sig'.
4697
4698              New in version  0.5:  Previously,  Sphinx  accepted  only  UTF-8
4699              encoded sources.
4700
4701
4702       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
4711              For example:
4712
4713                 source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
4714
4715              NOTE:
4716                 Read more about how to use Markdown with Sphinx at markdown.
4717
4718              New in version 1.3.
4719
4720
4721       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
4726       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
4732              Example patterns:
4733
4734              · 'library/xml.rst' – ignores the library/xml.rst file (replaces
4735                entry in unused_docs)
4736
4737              · 'library/xml' – ignores the library/xml directory
4738
4739              · 'library/xml*'  –  ignores  all files and directories starting
4740                with library/xml
4741
4742              · '**/.svn' – ignores all .svn directories
4743
4744              exclude_patterns is also consulted when looking for static files
4745              in html_static_path and html_extra_path.
4746
4747              New in version 1.0.
4748
4749
4750       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
4755              Changed  in  version  1.3:  As  these  files are not meant to be
4756              built, they are automatically added to exclude_patterns.
4757
4758
4759       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
4767       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
4773                 rst_epilog = """
4774                 .. |psf| replace:: Python Software Foundation
4775                 """
4776
4777              New in version 0.6.
4778
4779
4780       rst_prolog
4781              A string of reStructuredText that will be included at the begin‐
4782              ning of every source file that is read.
4783
4784              New in version 1.0.
4785
4786
4787       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
4796              New in version 1.0.
4797
4798
4799       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
4806              The  default  role can always be set within individual documents
4807              using the standard reST default-role directive.
4808
4809              New in version 0.4.
4810
4811
4812       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
4818              The  default  is  False, the pre-0.5 behavior was to always keep
4819              them.
4820
4821              New in version 0.5.
4822
4823
4824       suppress_warnings
4825              A list of warning types to suppress arbitrary warning messages.
4826
4827              Sphinx supports following warning types:
4828
4829              · app.add_node
4830
4831              · app.add_directive
4832
4833              · app.add_role
4834
4835              · app.add_generic_role
4836
4837              · app.add_source_parser
4838
4839              · download.not_readable
4840
4841              · image.not_readable
4842
4843              · ref.term
4844
4845              · ref.ref
4846
4847              · ref.numref
4848
4849              · ref.keyword
4850
4851              · ref.option
4852
4853              · ref.citation
4854
4855              · ref.footnote
4856
4857              · ref.doc
4858
4859              · ref.python
4860
4861              · misc.highlighting_failure
4862
4863              · toc.secnum
4864
4865              · epub.unknown_project_files
4866
4867              You can choose from these types.
4868
4869              Now, this option should be considered experimental.
4870
4871              New in version 1.4.
4872
4873
4874              Changed in version 1.5: Added misc.highlighting_failure
4875
4876
4877              Changed in version 1.5.1: Added epub.unknown_project_files
4878
4879
4880              Changed in version 1.6: Added ref.footnote
4881
4882
4883       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
4888              New in version 1.0.
4889
4890
4891              Changed in version 1.4: also accepts micro version string
4892
4893
4894       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
4901              This requires that the extension specifies its version to Sphinx
4902              (see dev-extensions for how to do that).
4903
4904              New in version 1.3.
4905
4906
4907       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
4913                 · page - the manual page (man)
4914
4915                 · section - the manual section (1)
4916
4917                 · path - the  original  manual  page  and  section  specified
4918                   (man(1))
4919
4920              This also supports manpages specified as man.1.
4921
4922              NOTE:
4923                 This  currently  affects  only  HTML  writers  but  could  be
4924                 expanded in the future.
4925
4926              New in version 1.7.
4927
4928
4929       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
4934              New in version 1.0.
4935
4936
4937       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
4944              New in version 1.1.
4945
4946
4947       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
4951              NOTE:
4952                 The LaTeX builder always assigns numbers whether this  option
4953                 is enabled or not.
4954
4955              New in version 1.3.
4956
4957
4958       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
4963              Default  is  to  use 'Fig. %s' for 'figure', 'Table %s' for 'ta‐
4964              ble', 'Listing %s' for 'code-block' and 'Section' for 'section'.
4965
4966              New in version 1.3.
4967
4968
4969       numfig_secnum_depth
4970
4971              · if set to 0, figures, tables and code-blocks are  continuously
4972                numbered starting at 1.
4973
4974              · 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
4979              · 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
4983              · etc…
4984
4985              New in version 1.3.
4986
4987
4988              Changed in version 1.7: The LaTeX builder obeys this setting (if
4989              numfig is set to True).
4990
4991
4992       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
4998              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
5002
5003              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
5008       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
5015              New in version 1.6.6.
5016
5017
5018       smartquotes_excludes
5019              This is a dict whose default is:
5020
5021                 {'languages': ['ja'], 'builders': ['man', 'text']}
5022
5023              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
5028              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
5039              New in version 1.6.6.
5040
5041
5042       tls_verify
5043              If true, Sphinx  verifies  server  certifications.   Default  is
5044              True.
5045
5046              New in version 1.5.
5047
5048
5049       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
5055              New in version 1.5.
5056
5057
5058   Project information
5059       project
5060              The documented project’s name.
5061
5062       copyright
5063              A copyright statement in the style '2008, Author Name'.
5064
5065       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
5070       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
5075              If you don’t need the separation provided  between  version  and
5076              release, just set them both to the same value.
5077
5078       today
5079
5080       today_fmt
5081              These  values  determine how to format the current date, used as
5082              the replacement for |today|.
5083
5084              · If you set today to a non-empty value, it is used.
5085
5086              · Otherwise, the current time is formatted using time.strftime()
5087                and the format given in today_fmt.
5088
5089              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
5093       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
5098              New in version 0.5.
5099
5100
5101              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
5107
5108       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
5114              New in version 1.3.
5115
5116
5117       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
5122              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
5126
5127       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
5132       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
5137       show_authors
5138              A boolean that  decides  whether  codeauthor  and  sectionauthor
5139              directives produce any output in the built files.
5140
5141       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
5148              New in version 0.6.
5149
5150
5151       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
5156              New in version 0.6.
5157
5158
5159       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
5166              New in version 1.0.
5167
5168
5169              Changed in version 1.1: Now also removes <BLANKLINE>.
5170
5171
5172   Options for internationalization
5173       These options influence Sphinx’s Native Language Support.  See the doc‐
5174       umentation on intl for details.
5175
5176       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
5187              New in version 0.5.
5188
5189
5190              Changed in version 1.4: Support figure substitution
5191
5192
5193              Currently supported languages by Sphinx are:
5194
5195              · bn – Bengali
5196
5197              · ca – Catalan
5198
5199              · cs – Czech
5200
5201              · da – Danish
5202
5203              · de – German
5204
5205              · en – English
5206
5207              · es – Spanish
5208
5209              · et – Estonian
5210
5211              · eu – Basque
5212
5213              · fa – Iranian
5214
5215              · fi – Finnish
5216
5217              · fr – French
5218
5219              · he – Hebrew
5220
5221              · hr – Croatian
5222
5223              · hu – Hungarian
5224
5225              · id – Indonesian
5226
5227              · it – Italian
5228
5229              · ja – Japanese
5230
5231              · ko – Korean
5232
5233              · lt – Lithuanian
5234
5235              · lv – Latvian
5236
5237              · mk – Macedonian
5238
5239              · nb_NO – Norwegian Bokmal
5240
5241              · ne – Nepali
5242
5243              · nl – Dutch
5244
5245              · pl – Polish
5246
5247              · pt_BR – Brazilian Portuguese
5248
5249              · pt_PT – European Portuguese
5250
5251              · ru – Russian
5252
5253              · si – Sinhala
5254
5255              · sk – Slovak
5256
5257              · sl – Slovenian
5258
5259              · sv – Swedish
5260
5261              · tr – Turkish
5262
5263              · uk_UA – Ukrainian
5264
5265              · vi – Vietnamese
5266
5267              · zh_CN – Simplified Chinese
5268
5269              · zh_TW – Traditional Chinese
5270
5271       locale_dirs
5272              New in version 0.5.
5273
5274
5275              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
5279              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
5285              The default is ['locales'].
5286
5287              Changed in version 1.5: Use locales directory as a default value
5288
5289
5290       gettext_compact
5291              New in version 1.1.
5292
5293
5294              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
5297              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
5300       gettext_uuid
5301              If true, Sphinx generates uuid information for version  tracking
5302              in message catalogs. It is used for:
5303
5304              · Add uid line for each msgids in .pot files.
5305
5306              · Calculate  similarity  between new msgids and previously saved
5307                old msgids.  This calculation takes a long time.
5308
5309              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
5313              The default is False.
5314
5315              New in version 1.3.
5316
5317
5318       gettext_location
5319              If true, Sphinx generates location information for  messages  in
5320              message catalogs.
5321
5322              The default is True.
5323
5324              New in version 1.3.
5325
5326
5327       gettext_auto_build
5328              If  true,  Sphinx  builds  mo  file for each translation catalog
5329              files.
5330
5331              The default is True.
5332
5333              New in version 1.3.
5334
5335
5336       gettext_additional_targets
5337              To specify names to enable gettext  extracting  and  translation
5338              applying for i18n additionally. You can specify below names:
5339
5340              Index  index terms
5341
5342              Literal-block
5343                     literal blocks: :: and code-block.
5344
5345              Doctest-block
5346                     doctest block
5347
5348              Raw    raw content
5349
5350              Image  image/figure uri and alt
5351
5352              For   example:  gettext_additional_targets  =  ['literal-block',
5353              'image'].
5354
5355              The default is [].
5356
5357              New in version 1.3.
5358
5359
5360       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
5366              · {root}  -  the filename, including any path component, without
5367                the file extension, e.g. dirname/filename
5368
5369              · {path} - the directory path component of the filename, with  a
5370                trailing slash if non-empty, e.g. dirname/
5371
5372              · {basename}  -  the filename without the directory path or file
5373                extension components, e.g. filename
5374
5375              · {ext} - the file extension, e.g. .png
5376
5377              · {language} - the translation language, e.g. en
5378
5379              For example, setting  this  to  {path}{language}/{basename}{ext}
5380              will expand to dirname/en/filename.png instead.
5381
5382              New in version 1.4.
5383
5384
5385              Changed in version 1.5: Added {path} and {basename} tokens.
5386
5387
5388   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
5392       html_theme
5393              The “theme” that the HTML output should use.   See  the  section
5394              about theming.  The default is 'alabaster'.
5395
5396              New in version 0.6.
5397
5398
5399       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
5404              New in version 0.6.
5405
5406
5407       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
5412              New in version 0.6.
5413
5414
5415       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
5423       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
5429       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
5434              New in version 0.4.
5435
5436
5437       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
5442              New in version 0.5.
5443
5444
5445       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
5451              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
5455
5456       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
5463              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
5467
5468       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
5475              Changed in version 0.4: The paths in  html_static_path  can  now
5476              contain subdirectories.
5477
5478
5479              Changed  in version 1.0: The entries in html_static_path can now
5480              be single files.
5481
5482
5483       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
5490              As these files are not meant to be built, they are automatically
5491              added to exclude_patterns.
5492
5493              New in version 1.2.
5494
5495
5496              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
5501
5502       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
5508       html_use_smartypants
5509              If true, quotes and dashes are converted to typographically cor‐
5510              rect entities.  Default: True.
5511
5512              Deprecated since version  1.6:  To  disable  smart  quotes,  use
5513              rather smartquotes.
5514
5515
5516       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
5521              This value determines the text for the permalink; it defaults to
5522              "¶".  Set it to None or the empty string to disable permalinks.
5523
5524              New in version 0.6: Previously, this was always activated.
5525
5526
5527              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
5531
5532       html_sidebars
5533              Custom sidebar templates, must be a dictionary that  maps  docu‐
5534              ment names to template names.
5535
5536              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
5541              The values can be either lists or single strings.
5542
5543              · 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
5548                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
5553              · 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
5558              Deprecated   since  version  1.7:  a  single  string  value  for
5559              html_sidebars will be removed in 2.0
5560
5561
5562              Builtin sidebar templates that can be rendered are:
5563
5564              · localtoc.html – a fine-grained table of contents of  the  cur‐
5565                rent document
5566
5567              · globaltoc.html  –  a  coarse-grained table of contents for the
5568                whole documentation set, collapsed
5569
5570              · relations.html – two links to the previous and next documents
5571
5572              · sourcelink.html – a link to the source of  the  current  docu‐
5573                ment, if enabled in html_show_sourcelink
5574
5575              · searchbox.html – the “quick search” box
5576
5577              Example:
5578
5579                 html_sidebars = {
5580                    '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
5581                    'using/windows': ['windowssidebar.html', 'searchbox.html'],
5582                 }
5583
5584              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
5589              New in version 1.0: The ability to  use  globbing  keys  and  to
5590              specify multiple sidebars.
5591
5592
5593              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
5597       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
5601              Example:
5602
5603                 html_additional_pages = {
5604                     'download': 'customdownload.html',
5605                 }
5606
5607              This will render the template customdownload.html  as  the  page
5608              download.html.
5609
5610       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
5615              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
5620              New in version 1.0.
5621
5622
5623       html_use_index
5624              If true, add an index to the HTML documents.  Default is True.
5625
5626              New in version 0.4.
5627
5628
5629       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
5634              New in version 0.4.
5635
5636
5637       html_copy_source
5638              If true, the reST sources are included  in  the  HTML  build  as
5639              _sources/name.  The default is True.
5640
5641              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
5646       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
5650              New in version 0.6.
5651
5652
5653       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
5658              New in version 1.5.
5659
5660
5661       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
5669       html_file_suffix
5670              This  is  the  file  name  suffix for generated HTML files.  The
5671              default is ".html".
5672
5673              New in version 0.4.
5674
5675
5676       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
5681              New in version 0.6.
5682
5683
5684       html_show_copyright
5685              If true, “(C) Copyright …” is shown in the HTML footer.  Default
5686              is True.
5687
5688              New in version 1.0.
5689
5690
5691       html_show_sphinx
5692              If  true,  “Created  using  Sphinx” is shown in the HTML footer.
5693              Default is True.
5694
5695              New in version 0.4.
5696
5697
5698       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
5703              New in version 1.0.
5704
5705
5706       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
5712              New in version 1.0.
5713
5714
5715       html_secnumber_suffix
5716              Suffix  for section numbers.  Default: ". ".  Set to " " to sup‐
5717              press the final dot on section numbers.
5718
5719              New in version 1.0.
5720
5721
5722       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
5728              Support is present for these languages:
5729
5730              · da – Danish
5731
5732              · nl – Dutch
5733
5734              · en – English
5735
5736              · fi – Finnish
5737
5738              · fr – French
5739
5740              · de – German
5741
5742              · hu – Hungarian
5743
5744              · it – Italian
5745
5746              · ja – Japanese
5747
5748              · no – Norwegian
5749
5750              · pt – Portuguese
5751
5752              · ro – Romanian
5753
5754              · ru – Russian
5755
5756              · es – Spanish
5757
5758              · sv – Swedish
5759
5760              · tr – Turkish
5761
5762              · zh – Chinese
5763
5764                 Accelerating build speed
5765
5766                        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
5771                 · PorterStemmer (en)
5772
5773                 · PyStemmer (all languages)
5774
5775              New in version 1.1: With support for en and ja.
5776
5777
5778              Changed in version 1.3: Added additional languages.
5779
5780
5781       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
5786              The English support has no options.
5787
5788              The Japanese support has these options:
5789
5790              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
5797                     You can choose from these modules:
5798
5799                     ‘sphinx.search.ja.DefaultSplitter’
5800                            TinySegmenter algorithm. This is default splitter.
5801
5802                     ‘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
5808                     ‘sphinx.search.ja.JanomeSplitter’
5809                            Janome  binding.  To  use this splitter, Janome is
5810                            required.
5811
5812                     To keep compatibility, 'mecab',  'janome'  and  'default'
5813                     are  also  acceptable.  However  it will be deprecated in
5814                     Sphinx-1.6.
5815
5816              Other option values depend on splitter value which you choose.
5817
5818              Options for 'mecab':
5819
5820                     dic_enc
5821                             is the encoding for the MeCab algorithm.
5822
5823                     dict
5824                             is the dictionary to use for the MeCab algorithm.
5825
5826                     lib
5827                             is the library name for finding the MeCab library
5828                            via ctypes if the Python binding is not installed.
5829
5830                     For example:
5831
5832                        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
5839              Options for 'janome':
5840
5841                     user_dic
5842                             is the user dictionary file path for Janome.
5843
5844                     user_dic_enc
5845                             is  the  encoding  for  the  user dictionary file
5846                            specified by user_dic option. Default is ‘utf8’.
5847
5848              New in version 1.1.
5849
5850
5851              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
5855
5856              The Chinese support has these options:
5857
5858              · dict  – the jieba dictionary path if want to use  custom  dic‐
5859                tionary.
5860
5861       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
5866              New in version 1.2.
5867
5868
5869       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
5874              New in version 1.3.
5875
5876
5877       htmlhelp_basename
5878              Output  file  base  name  for  HTML  help  builder.   Default is
5879              'pydoc'.
5880
5881       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
5885              New in version 1.6.
5886
5887
5888   Options for Apple Help output
5889       New in version 1.3.
5890
5891
5892       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
5896       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
5901          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
5906       applehelp_bundle_name
5907              The basename for the Apple Help Book.  Defaults to  the  project
5908              name.
5909
5910       applehelp_bundle_id
5911              The bundle ID for the help book bundle.
5912
5913              WARNING:
5914                 You must set this value in order to generate Apple Help.
5915
5916       applehelp_dev_region
5917              The  development  region.  Defaults to 'en-us', which is Apple’s
5918              recommended setting.
5919
5920       applehelp_bundle_version
5921              The bundle version (as a string).  Defaults to '1'.
5922
5923       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
5929       applehelp_kb_product
5930              The  product  tag  for  use  with applehelp_kb_url.  Defaults to
5931              '<project>-<release>'.
5932
5933       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
5941              Defaults to None for no remote search.
5942
5943       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
5948              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
5953              Defaults to None for no remote content.
5954
5955       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
5963       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
5967       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
5974                                     ┌──────────┬──────┐
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
5992              Defaults to language, or if that is not set, to en.
5993
5994       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
5999              Defaults to language, or if that is not set, to en.
6000
6001       applehelp_title
6002              Specifies the help book title.  Defaults to '<project> Help'.
6003
6004       applehelp_codesign_identity
6005              Specifies the identity to use for code signing, or None if  code
6006              signing is not to be performed.
6007
6008              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
6012       applehelp_codesign_flags
6013              A  list of additional arguments to pass to codesign when signing
6014              the help book.
6015
6016              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
6020       applehelp_indexer_path
6021              The path to the hiutil program.  Defaults to '/usr/bin/hiutil'.
6022
6023       applehelp_codesign_path
6024              The path to the codesign program.  Defaults  to  '/usr/bin/code‐
6025              sign'.
6026
6027       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
6031              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
6035              Defaults to False.
6036
6037   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
6043       epub_basename
6044              The  basename  for  the  epub  file.  It defaults to the project
6045              name.
6046
6047       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
6053       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
6058              New in version 1.2.
6059
6060
6061       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
6065       epub_description
6066              The description of the document. The default value is 'unknown'.
6067
6068              New in version 1.4.
6069
6070
6071              Changed in version 1.5: Renamed from epub3_description
6072
6073
6074       epub_author
6075              The author of the document.  This is  put  in  the  Dublin  Core
6076              metadata.  The default value is 'unknown'.
6077
6078       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
6083              New in version 1.4.
6084
6085
6086              Changed in version 1.5: Renamed from epub3_contributor
6087
6088
6089       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
6093       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
6098       epub_copyright
6099              The copyright of the document.  It  defaults  to  the  copyright
6100              option but can be set independently for epub creation.
6101
6102       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
6108       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
6114       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
6120       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
6128                 epub_cover = ('_static/cover.png', 'epub-cover.html')
6129                 epub_cover = ('_static/cover.png', '')
6130                 epub_cover = ()
6131
6132              The default value is ().
6133
6134              New in version 1.1.
6135
6136
6137       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
6146                 epub_guide = (('cover', 'cover.html', u'Cover Page'),)
6147
6148              The default value is ().
6149
6150       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
6156                 epub_pre_files = [
6157                     ('index.html', 'Welcome'),
6158                 ]
6159
6160              The default value is [].
6161
6162       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
6169       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
6174       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
6180       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
6187       epub_tocscope
6188              This  setting  control  the scope of the epub table of contents.
6189              The setting can have the following values:
6190
6191              · 'default' – include  all  toc  entries  that  are  not  hidden
6192                (default)
6193
6194              · 'includehidden' – include all toc entries
6195
6196              New in version 1.2.
6197
6198
6199       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
6207              New in version 1.2.
6208
6209
6210       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
6217              New in version 1.2.
6218
6219
6220       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
6225              · 'inline' – display URLs inline in parentheses (default)
6226
6227              · 'footnote' – display URLs in footnotes
6228
6229              · 'no' – do not display URLs
6230
6231              The display of inline URLs can be customized by adding CSS rules
6232              for the class link-target.
6233
6234              New in version 1.2.
6235
6236
6237       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
6242              New in version 1.2.
6243
6244
6245       epub_writing_mode
6246              It  specifies  writing  direction.  It  can  accept 'horizontal'
6247              (default) and 'vertical'
6248
6249              ┌────────────────────┬─────────────────────┬─────────────────────┐
6250epub_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
6260       [2]  https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
6261
6262   Options for LaTeX output
6263       These options influence LaTeX output. See further latex.
6264
6265       latex_engine
6266              The  LaTeX  engine  to build the docs.  The setting can have the
6267              following values:
6268
6269              · 'pdflatex' – PDFLaTeX (default)
6270
6271              · 'xelatex' – XeLaTeX
6272
6273              · 'lualatex' – LuaLaTeX
6274
6275              · 'platex' – pLaTeX (default if language is 'ja')
6276
6277              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
6285              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
6298       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
6304              · 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
6309              · targetname:  file  name of the LaTeX file in the output direc‐
6310                tory.
6311
6312              · 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
6318              · 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
6323              · 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
6332              · 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
6338              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
6342
6343              New in version 0.3: The 6th item toctree_only.   Tuples  with  5
6344              items are still accepted.
6345
6346
6347       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
6352       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
6359              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
6364              New in version 1.4.
6365
6366
6367       latex_appendices
6368              A list of document names to append as an appendix to  all  manu‐
6369              als.
6370
6371       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
6376              This value can be a bool or a list of index names that should be
6377              generated, like for html_domain_indices.
6378
6379              New in version 1.0.
6380
6381
6382       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
6386              New in version 1.0.
6387
6388
6389       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
6394              · 'no' – do not display URLs (default)
6395
6396              · 'footnote' – display URLs in footnotes
6397
6398              · 'inline' – display URLs inline in parentheses
6399
6400              New in version 1.0.
6401
6402
6403              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
6407
6408       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
6415              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
6420              New in version 1.6.
6421
6422
6423       latex_elements
6424              New in version 0.5.
6425
6426
6427              A dictionary that contains LaTeX snippets  that  override  those
6428              Sphinx usually puts into the generated .tex files.
6429
6430              Keep  in  mind that backslashes must be doubled in Python string
6431              literals to avoid interpretation as escape sequences.
6432
6433              · Keys that you may want to override include:
6434
6435                'papersize'
6436                       Paper size option of the document class  ('a4paper'  or
6437                       'letterpaper'), default 'letterpaper'.
6438
6439                'pointsize'
6440                       Point size option of the document class ('10pt', '11pt'
6441                       or '12pt'), default '10pt'.
6442
6443                '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
6453                       New in version 1.5.
6454
6455
6456                'sphinxsetup'
6457                       A comma separated list of key=value package options for
6458                       the Sphinx LaTeX style, default empty. See latex.
6459
6460                       New in version 1.5.
6461
6462
6463                '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
6468                       New in version 1.4.
6469
6470
6471                '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
6478                       Changed in version 1.5: For latex_engine set to  'xela‐
6479                       tex', the default is '\\usepackage{polyglossia}\n\\set‐
6480                       mainlanguage{<language>}'.
6481
6482
6483                       Changed in version 1.6: 'lualatex'  uses  same  default
6484                       setting as 'xelatex'
6485
6486
6487                '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
6492                       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
6502                       Changed  in  version  1.2:  Defaults  to  ''  when  the
6503                       language uses the Cyrillic script.
6504
6505
6506                       Changed   in   version   1.5:   Defaults   to  ''  when
6507                       latex_engine is 'xelatex'.
6508
6509
6510                       Changed in  version  1.6:  Defaults  to  ''  also  with
6511                       'lualatex'.
6512
6513
6514                '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
6525                'preamble'
6526                       Additional preamble content, default empty. See latex.
6527
6528                'atendofbody'
6529                       Additional document content (right before the indices),
6530                       default empty.
6531
6532                       New in version 1.5.
6533
6534
6535                '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
6544                       New in version 1.3.
6545
6546
6547                'footer'
6548                       Additional footer content (before the indices), default
6549                       empty.
6550
6551                       Deprecated  since  version  1.5:  Use 'atendofbody' key
6552                       instead.
6553
6554
6555              · Keys that don’t need to be overridden unless in special  cases
6556                are:
6557
6558                '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
6563                       New in version 1.2.
6564
6565
6566                       Changed in version 1.6: Added this documentation.
6567
6568
6569                '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
6577                       WARNING:
6578
6579                          · Using this key may prove  incompatible  with  some
6580                            LaTeX  packages  or special document classes which
6581                            do their own list customization.
6582
6583                          · 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
6588                       New in version 1.5.
6589
6590
6591                'inputenc'
6592                       “inputenc”  package  inclusion, defaults to '\\usepack‐
6593                       age[utf8]{inputenc}' when  using  pdflatex.   Otherwise
6594                       empty.
6595
6596                       Changed   in   version  1.4.3:  Previously  '\\usepack‐
6597                       age[utf8]{inputenc}' was used for all compilers.
6598
6599
6600                'cmappkg'
6601                       “cmap” package inclusion, default '\\usepackage{cmap}'.
6602
6603                       New in version 1.2.
6604
6605
6606                'fontenc'
6607                       “fontenc”  package   inclusion,   default   '\\usepack‐
6608                       age[T1]{fontenc}'.
6609
6610                       Changed   in   version  1.5:  Defaults  to  '\\usepack‐
6611                       age{fontspec}' when latex_engine is 'xelatex'.
6612
6613
6614                       Changed in version 1.6: 'lualatex' also  uses  fontspec
6615                       per default.
6616
6617
6618                'geometry'
6619                       “geometry”  package  inclusion,  the default definition
6620                       is:
6621                          '\\usepackage{geometry}'
6622
6623                       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
6628                       which can be customized via corresponding ‘sphinxsetup’
6629                       options.
6630
6631                       New in version 1.5.
6632
6633
6634                       Changed   in   version   1.5.2:   dvipdfm   option   if
6635                       latex_engine is 'platex'.
6636
6637
6638                       New in version 1.5.3: The ‘sphinxsetup’  keys  for  the
6639                       margins.
6640
6641
6642                       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
6652
6653                '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
6659                       ATTENTION:
6660                          Loading  of  packages  “hyperref”  and  “hypcap”  is
6661                          mandatory.
6662
6663                       New  in  version  1.5:  Previously  this  was done from
6664                       inside sphinx.sty.
6665
6666
6667                '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
6673                '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
6679                '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
6687                       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
6692
6693                '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
6698                       New in version 1.2.
6699
6700
6701                       Changed  in  version  1.6:  Remove  unneeded  {}  after
6702                       \\hrule.
6703
6704
6705                '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
6713              · Keys that are set by other options and therefore should not be
6714                overridden are:
6715
6716                'docclass'  'classoptions'  'title'  'date' 'release' 'author'
6717                'logo' 'makeindex' 'shorthandoff'
6718
6719       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
6725              New in version 1.0.
6726
6727
6728              Changed  in version 1.5: In Japanese docs (language is 'ja'), by
6729              default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.
6730
6731
6732       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
6740              You  have to make sure yourself that the filenames don’t collide
6741              with those of any automatically copied files.
6742
6743              New in version 0.6.
6744
6745
6746              Changed in version 1.2: This overrides the files which  is  pro‐
6747              vided from Sphinx such as sphinx.sty.
6748
6749
6750   Options for text output
6751       These options influence text output.
6752
6753       text_newlines
6754              Determines  which end-of-line character(s) are used in text out‐
6755              put.
6756
6757              · 'unix': use Unix-style line endings (\n)
6758
6759              · 'windows': use Windows-style line endings (\r\n)
6760
6761              · 'native': use the line ending style of the platform the  docu‐
6762                mentation is built on
6763
6764              Default: 'unix'.
6765
6766              New in version 1.1.
6767
6768
6769       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
6774              The default is '*=-~"+`'.
6775
6776              New in version 1.1.
6777
6778
6779       text_add_secnumbers
6780              A  boolean  that decides whether section numbers are included in
6781              text output.  Default is True.
6782
6783              New in version 1.7.
6784
6785
6786       text_secnumber_suffix
6787              Suffix for section numbers in text output.  Default: ".  ".  Set
6788              to " " to suppress the final dot on section numbers.
6789
6790              New in version 1.7.
6791
6792
6793   Options for manual page output
6794       These options influence manual page output.
6795
6796       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
6801              · 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
6806              · 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
6811              · description:  description of the manual page.  This is used in
6812                the NAME section.
6813
6814              · 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
6818              · section: The manual page section.  Used for  the  output  file
6819                name as well as in the manual page header.
6820
6821              New in version 1.0.
6822
6823
6824       man_show_urls
6825              If true, add URL addresses after links.  Default is False.
6826
6827              New in version 1.1.
6828
6829
6830   Options for Texinfo output
6831       These options influence Texinfo output.
6832
6833       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
6839              · 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
6844              · targetname:  file  name  (no extension) of the Texinfo file in
6845                the output directory.
6846
6847              · 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
6852              · author:  Author for the Texinfo document.  Inserted as Texinfo
6853                markup.   Use  @*  to  separate  multiple  authors,   as   in:
6854                'John@*Sarah'.
6855
6856              · dir_entry: The name that will appear in the top-level DIR menu
6857                file.
6858
6859              · description: Descriptive text to appear in the  top-level  DIR
6860                menu file.
6861
6862              · category:  Specifies  the section which this entry will appear
6863                in the top-level DIR menu file.
6864
6865              · 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
6871              New in version 1.1.
6872
6873
6874       texinfo_appendices
6875              A list of document names to append as an appendix to  all  manu‐
6876              als.
6877
6878              New in version 1.1.
6879
6880
6881       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
6886              This value can be a bool or a list of index names that should be
6887              generated, like for html_domain_indices.
6888
6889              New in version 1.1.
6890
6891
6892       texinfo_show_urls
6893              Control how to display URL addresses.
6894
6895              · 'footnote' – display URLs in footnotes (default)
6896
6897              · 'no' – do not display URLs
6898
6899              · 'inline' – display URLs inline in parentheses
6900
6901              New in version 1.1.
6902
6903
6904       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
6909              New in version 1.2.
6910
6911
6912       texinfo_elements
6913              A dictionary that contains Texinfo snippets that override  those
6914              Sphinx usually puts into the generated .texi files.
6915
6916              · Keys that you may want to override include:
6917
6918                'paragraphindent'
6919                       Number of spaces to indent the first line of each para‐
6920                       graph, default 2.  Specify 0 for no indentation.
6921
6922                '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
6927                'preamble'
6928                       Texinfo markup inserted near the beginning of the file.
6929
6930                '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
6935              · Keys that are set by other options and therefore should not be
6936                overridden are:
6937
6938                'author'   'body'   'date'   'direntry'  'filename'  'project'
6939                'release' 'title'
6940
6941              New in version 1.1.
6942
6943
6944   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
6948       qthelp_basename
6949              The  basename  for  the qthelp file.  It defaults to the project
6950              name.
6951
6952       qthelp_namespace
6953              The  namespace  for   the   qthelp   file.    It   defaults   to
6954              org.sphinx.<project_name>.<project_version>.
6955
6956       qthelp_theme
6957              The HTML theme for the qthelp output.  This defaults to 'nonav'.
6958
6959       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
6964   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
6969                 linkcheck_ignore = [r'http://localhost:\d+/']
6970
6971              New in version 1.1.
6972
6973
6974       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
6978              New in version 1.4.
6979
6980
6981       linkcheck_timeout
6982              A  timeout  value,  in  seconds, for the linkcheck builder.  The
6983              default is to use Python’s global socket timeout.
6984
6985              New in version 1.1.
6986
6987
6988       linkcheck_workers
6989              The number  of  worker  threads  to  use  when  checking  links.
6990              Default is 5 threads.
6991
6992              New in version 1.1.
6993
6994
6995       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
7000              New in version 1.2.
7001
7002
7003       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
7011              New in version 1.5.
7012
7013
7014   Options for the XML builder
7015       xml_pretty
7016              If true, pretty-print the XML.  Default is True.
7017
7018              New in version 1.2.
7019
7020

FOOTNOTES

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
7027   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
7032              New in version 1.5.
7033
7034
7035       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
7040              New in version 1.5.
7041
7042
7043       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
7051              New in version 1.5.
7052
7053

EXAMPLE OF CONFIGURATION FILE

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
7069          # 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
7077          # -- General configuration ------------------------------------------------
7078
7079          # If your documentation needs a minimal Sphinx version, state it here.
7080          #
7081          # needs_sphinx = '1.0'
7082
7083          # 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
7088          # Add any paths that contain templates here, relative to this directory.
7089          templates_path = ['_templates']
7090
7091          # 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
7097          # The encoding of source files.
7098          #
7099          # source_encoding = 'utf-8-sig'
7100
7101          # The master toctree document.
7102          master_doc = 'index'
7103
7104          # General information about the project.
7105          project = u'test'
7106          copyright = u'2016, test'
7107          author = u'test'
7108
7109          # 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
7118          # 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
7125          # 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
7134          # 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
7139          # The reST default role (used for this markup: `text`) to use for all
7140          # documents.
7141          #
7142          # default_role = None
7143
7144          # If true, '()' will be appended to :func: etc. cross-reference text.
7145          #
7146          # add_function_parentheses = True
7147
7148          # 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
7153          # If true, sectionauthor and moduleauthor directives will be shown in the
7154          # output. They are ignored by default.
7155          #
7156          # show_authors = False
7157
7158          # The name of the Pygments (syntax highlighting) style to use.
7159          pygments_style = 'sphinx'
7160
7161          # A list of ignored prefixes for module index sorting.
7162          # modindex_common_prefix = []
7163
7164          # If true, keep warnings as "system message" paragraphs in the built documents.
7165          # keep_warnings = False
7166
7167          # If true, `todo` and `todoList` produce output, else they produce nothing.
7168          todo_include_todos = False
7169
7170
7171          # -- Options for HTML output ----------------------------------------------
7172
7173          # 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
7178          # 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
7184          # Add any paths that contain custom themes here, relative to this directory.
7185          # html_theme_path = []
7186
7187          # The name for this set of Sphinx documents.
7188          # "<project> v<release> documentation" by default.
7189          #
7190          # html_title = u'test vtest'
7191
7192          # A shorter title for the navigation bar.  Default is the same as html_title.
7193          #
7194          # html_short_title = None
7195
7196          # 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
7201          # 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
7207          # 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
7212          # 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
7218          # 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
7224          # Custom sidebar templates, maps document names to template names.
7225          #
7226          # html_sidebars = {}
7227
7228          # Additional templates that should be rendered to pages, maps page names to
7229          # template names.
7230          #
7231          # html_additional_pages = {}
7232
7233          # If false, no module index is generated.
7234          #
7235          # html_domain_indices = True
7236
7237          # If false, no index is generated.
7238          #
7239          # html_use_index = True
7240
7241          # If true, the index is split into individual pages for each letter.
7242          #
7243          # html_split_index = False
7244
7245          # If true, links to the reST sources are added to the pages.
7246          #
7247          # html_show_sourcelink = True
7248
7249          # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
7250          #
7251          # html_show_sphinx = True
7252
7253          # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
7254          #
7255          # html_show_copyright = True
7256
7257          # 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
7263          # This is the file name suffix for HTML files (e.g. ".xhtml").
7264          # html_file_suffix = None
7265
7266          # 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
7273          # 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
7279          # 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
7284          # Output file base name for HTML help builder.
7285          htmlhelp_basename = 'testdoc'
7286
7287          # -- Options for LaTeX output ---------------------------------------------
7288
7289          latex_elements = {
7290              # The paper size ('letterpaper' or 'a4paper').
7291              #
7292              # 'papersize': 'letterpaper',
7293
7294              # The font size ('10pt', '11pt' or '12pt').
7295              #
7296              # 'pointsize': '10pt',
7297
7298              # Additional stuff for the LaTeX preamble.
7299              #
7300              # 'preamble': '',
7301
7302              # Latex figure (float) alignment
7303              #
7304              # 'figure_align': 'htbp',
7305          }
7306
7307          # 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
7315          # 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
7320          # If true, show page references after internal links.
7321          #
7322          # latex_show_pagerefs = False
7323
7324          # If true, show URL addresses after external links.
7325          #
7326          # latex_show_urls = False
7327
7328          # Documents to append as an appendix to all manuals.
7329          #
7330          # latex_appendices = []
7331
7332          # If false, no module index is generated.
7333          #
7334          # latex_domain_indices = True
7335
7336
7337          # -- Options for manual page output ---------------------------------------
7338
7339          # 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
7346          # If true, show URL addresses after external links.
7347          #
7348          # man_show_urls = False
7349
7350
7351          # -- Options for Texinfo output -------------------------------------------
7352
7353          # 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
7362          # Documents to append as an appendix to all manuals.
7363          #
7364          # texinfo_appendices = []
7365
7366          # If false, no module index is generated.
7367          #
7368          # texinfo_domain_indices = True
7369
7370          # How to display URL addresses: 'footnote', 'no', or 'inline'.
7371          #
7372          # texinfo_show_urls = 'footnote'
7373
7374          # If true, do not generate a @detailmenu in the "Top" node's menu.
7375          #
7376          # texinfo_no_detailmenu = False
7377
7378          # -- A random example -----------------------------------------------------
7379
7380          import sys, os
7381          sys.path.insert(0, os.path.abspath('.'))
7382          exclude_patterns = ['zzz']
7383
7384          numfig = True
7385          #language = 'ja'
7386
7387          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
7395
7396          autosummary_generate = True
7397          html_theme = 'default'
7398          #source_suffix = ['.rst', '.txt']
7399
7400

INTERNATIONALIZATION

7402       New in version 1.1.
7403
7404
7405       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
7412       · Sphinx internationalization details
7413
7414       · Translating with sphinx-intl
7415
7416         · Quick guide
7417
7418         · Translating
7419
7420         · Update your po files by new pot files
7421
7422       · Using Transifex service for team translation
7423
7424       · Contributing to Sphinx reference translation
7425
7426   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
7431       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
7435       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
7443       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
7447       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
7451       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
7456       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
7461       · 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
7465            msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
7466
7467       · Set locale_dirs to ["locale/"].
7468
7469       · Set language to es (also possible via -D).
7470
7471       · Run your desired build.
7472
7473   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
7478       1. Install sphinx-intl  by  pip  install  sphinx-intl  or  easy_install
7479          sphinx-intl.
7480
7481       2. Add configurations to your conf.py:
7482
7483             locale_dirs = ['locale/']   # path is example but recommended.
7484             gettext_compact = False     # optional.
7485
7486          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
7490       3. Extract document’s translatable messages into pot files:
7491
7492             $ make gettext
7493
7494          As  a  result,  many  pot  files  are generated under _build/gettext
7495          directory.
7496
7497       4. Setup/Update your locale_dir:
7498
7499             $ sphinx-intl update -p _build/gettext -l de -l ja
7500
7501          Done. You got these directories that contain po files:
7502
7503          · ./locale/de/LC_MESSAGES/
7504
7505          · ./locale/ja/LC_MESSAGES/
7506
7507       5. Translate your po files under ./locale/<lang>/LC_MESSAGES/.
7508
7509       6. make translated document.
7510
7511          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
7514             $ make -e SPHINXOPTS="-D language='de'" html
7515
7516          command line (for Windows cmd.exe):
7517
7518             > set SPHINXOPTS=-D language='de'
7519             > .\make.bat html
7520
7521          command line (for PowerShell):
7522
7523             > Set-Item env:SPHINXOPTS "-D language='de'"
7524             > .\make.bat html
7525
7526       Congratulations!   You   got   the   translated  documentation  in  the
7527       _build/html directory.
7528
7529       New in version 1.3: sphinx-build that is invoked by make  command  will
7530       build po files into mo files.
7531
7532       If you are using 1.2.x or earlier, please invoke sphinx-intl build com‐
7533       mand before make command.
7534
7535
7536   Translating
7537       Translate po file under ./locale/de/LC_MESSAGES directory.  The case of
7538       builders.po file for sphinx document:
7539
7540          # a5600c3d2e3d48fc8c261ea0284db79b
7541          #: ../../builders.rst:4
7542          msgid "Available builders"
7543          msgstr "<FILL HERE BY TARGET LANGUAGE>"
7544
7545       Another  case,  msgid  is multi-line text and contains reStructuredText
7546       syntax:
7547
7548          # 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
7557       Please be careful not to break reST  notation.   Most  po-editors  will
7558       help you with that.
7559
7560   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
7566          $ sphinx-intl update -p _build/locale
7567
7568   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
7573       1. Install transifex-client
7574
7575          You need tx command to upload resources (pot files).
7576
7577             $ pip install transifex-client
7578
7579          SEE ALSO:
7580             Transifex Client documentation
7581
7582       2. Create your transifex account and create new project for your  docu‐
7583          ment
7584
7585          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
7589          For example:
7590
7591          Project ID
7592                 sphinx-document-test_1_0
7593
7594          Project URL
7595                 https://www.transifex.com/projects/p/sphinx-docu
7596                 ment-test_1_0/
7597
7598       3. Create config files for tx command
7599
7600          This process will create .tx/config in  the  current  directory,  as
7601          well as a ~/.transifexrc file that includes auth information.
7602
7603             $ 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
7612       4. Upload pot files to transifex service
7613
7614          Register pot files to .tx/config file:
7615
7616             $ cd /your/document/root
7617             $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
7618               --transifex-project-name sphinx-document-test_1_0
7619
7620          and upload pot files:
7621
7622             $ 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
7629       5. Forward the translation on transifex
7630
7631       6. Pull translated po files and make translated html
7632
7633          Get translated catalogs and build mo files (ex. for ‘de’):
7634
7635             $ 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
7642          Invoke make html (for BSD/GNU make):
7643
7644             $ make -e SPHINXOPTS="-D language='de'" html
7645
7646       That’s all!
7647
7648       TIP:
7649          Translating locally and on Transifex
7650
7651          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
7655          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
7658   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
7662       There is sphinx translation page for Sphinx (master) documentation.
7663
7664       1. Login to transifex service.
7665
7666       2. Go to sphinx translation page.
7667
7668       3. Click Request language and fill form.
7669
7670       4. Wait acceptance by transifex sphinx translation maintainers.
7671
7672       5. (after acceptance) translate on transifex.
7673

FOOTNOTES

7675       [1]  See the GNU gettext utilities for details on that software suite.
7676
7677       [2]  Because nobody expects the Spanish Inquisition!
7678

HTML THEMING SUPPORT

7680       New in version 0.6.
7681
7682
7683       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
7689       Themes are meant to be project-unaware, so they can be used for differ‐
7690       ent projects without change.
7691
7692   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
7699          html_theme = "classic"
7700          html_theme_options = {
7701              "rightsidebar": "true",
7702              "relbarbgcolor": "black"
7703          }
7704
7705       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
7709       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
7718          html_theme = "blue"
7719          html_theme_path = ["."]
7720
7721       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
7724          # installing theme package
7725          $ pip install sphinxjp.themes.dotted
7726
7727          # use it in your conf.py
7728          html_theme = "dotted"
7729
7730   Builtin themes
7731              ──────────────────────────────────────────────────────────
7732               Theme overview
7733              ──────────────────────────────────────────────────────────
7734               [image: alabaster] [image]   [image: classic] [image]
7735
7736
7737               alabaster                    classic
7738              ──────────────────────────────────────────────────────────
7739               [image: sphinxdoc] [image]   [image: scrolls] [image]
7740
7741
7742               sphinxdoc                    scrolls
7743              ──────────────────────────────────────────────────────────
7744               [image: agogo] [image]       [image:       traditional]
7745                                            [image]
7746
7747               agogo
7748                                            traditional
7749              ──────────────────────────────────────────────────────────
7750               [image: nature] [image]      [image: haiku] [image]
7751
7752
7753               nature                       haiku
7754              ──────────────────────────────────────────────────────────
7755               [image: pyramid] [image]     [image: bizstyle] [image]
7756
7757
7758               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
7832         · bgcolor (CSS color): Body background color.
7833
7834         · textcolor (CSS color): Body text color.
7835
7836         · linkcolor (CSS color): Body link color.
7837
7838         · visitedlinkcolor (CSS color): Body color for visited links.
7839
7840         · headbgcolor (CSS color): Background color for headings.
7841
7842         · headtextcolor (CSS color): Text color for headings.
7843
7844         · headlinkcolor (CSS color): Link color for headings.
7845
7846         · codebgcolor (CSS color): Background color for code blocks.
7847
7848         · codetextcolor (CSS color): Default text color for code  blocks,  if
7849           not set differently by the highlighting style.
7850
7851         · bodyfont (CSS font-family): Font for normal text.
7852
7853         · headfont (CSS font-family): Font for headings.
7854
7855       · 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
7859         NOTE:
7860            The  Sphinx  documentation  now  uses  an  adjusted version of the
7861            sphinxdoc theme.
7862
7863       · scrolls – A more lightweight theme, based on the Jinja documentation.
7864         The following color options are available:
7865
7866         · headerbordercolor
7867
7868         · subheadlinecolor
7869
7870         · linkcolor
7871
7872         · visitedlinkcolor
7873
7874         · admonitioncolor
7875
7876       · agogo  – A theme created by Andi Albrecht.  The following options are
7877         supported:
7878
7879         · bodyfont (CSS font family): Font for normal text.
7880
7881         · headerfont (CSS font family): Font for headings.
7882
7883         · pagewidth (CSS length): Width of the page content, default 70em.
7884
7885         · documentwidth (CSS length): Width of the  document  (without  side‐
7886           bar), default 50em.
7887
7888         · sidebarwidth (CSS length): Width of the sidebar, default 20em.
7889
7890         · bgcolor (CSS color): Background color.
7891
7892         · headerbg  (CSS  value  for “background”): background for the header
7893           area, default a grayish gradient.
7894
7895         · footerbg (CSS value for “background”): background  for  the  footer
7896           area, default a light gray gradient.
7897
7898         · linkcolor (CSS color): Body link color.
7899
7900         · headercolor1,  headercolor2  (CSS  color): colors for <h1> and <h2>
7901           headings.
7902
7903         · headerlinkcolor (CSS color): Color for the  backreference  link  in
7904           headings.
7905
7906         · textalign  (CSS  text-align  value):  Text  alignment for the body,
7907           default is justify.
7908
7909       · nature – A greenish theme.  There are  currently  no  options  beyond
7910         nosidebar and sidebarwidth.
7911
7912       · 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
7916       · haiku  – A theme without sidebar inspired by the Haiku OS user guide.
7917         The following options are supported:
7918
7919         · 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
7924         · textcolor,  headingcolor,  linkcolor,  visitedlinkcolor, hoverlink‐
7925           color (CSS colors): Colors for various body elements.
7926
7927       · traditional – A theme resembling the old Python documentation.  There
7928         are currently no options beyond nosidebar and sidebarwidth.
7929
7930       · 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
7934         · 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
7937         · 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
7940       · bizstyle – A simple bluish theme. The following options are supported
7941         beyond nosidebar and sidebarwidth:
7942
7943         · rightsidebar (true or false): Put the sidebar on  the  right  side.
7944           Defaults to False.
7945
7946       New  in  version  1.3:  ‘alabaster’,  ‘sphinx_rtd_theme’ and ‘bizstyle’
7947       theme.
7948
7949
7950       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
7954
7955   Creating themes
7956       As said, themes are either a directory or a zipfile (whose name is  the
7957       theme name), containing the following:
7958
7959       · A theme.conf file, see below.
7960
7961       · HTML templates, if needed.
7962
7963       · 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
7967       The  theme.conf  file  is  in  INI format [1] (readable by the standard
7968       Python ConfigParser module) and has the following structure:
7969
7970          [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
7976          [options]
7977          variable = default value
7978
7979       · 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
7985       · 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
7991       · 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
7995       · 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
7999       · 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
8004       New in version 1.7: sidebar settings
8005
8006
8007   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
8011       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
8015          # 'setup.py'
8016          setup(
8017              ...
8018              entry_points = {
8019                  'sphinx.html_themes': [
8020                      'name_of_theme = your_package',
8021                  ]
8022              },
8023              ...
8024          )
8025
8026          # 'your_package.py'
8027          from os import path
8028
8029          def setup(app):
8030              app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
8031
8032       If your  theme  package  contains  two  or  more  themes,  please  call
8033       add_html_theme() twice or more.
8034
8035       New in version 1.2: ‘sphinx_themes’ entry_points feature.
8036
8037
8038       Deprecated  since version 1.6: sphinx_themes entry_points has been dep‐
8039       recated.
8040
8041
8042       New in version 1.6: sphinx.html_themes entry_points feature.
8043
8044
8045   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
8050       · First, in the user’s templates_path directories.
8051
8052       · Then, in the selected theme.
8053
8054       · Then, in its base theme, its base’s base theme, etc.
8055
8056       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
8061   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
8067       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
8076       [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
8080   Third Party Themes
8081                          ┌───────────────────────────┬───┐
8082Theme overview             │   │
8083                          ├───────────────────────────┼───┤
8084                          │[image:  sphinx_rtd_theme] │   │
8085                          │[image]                    │   │
8086                          │                           │   │
8087                          │                           │   │
8088sphinx_rtd_theme           │   │
8089                          └───────────────────────────┴───┘
8090
8091       · 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
8096         Changed in version 1.4: sphinx_rtd_theme has become optional.
8097
8098

SETUPTOOLS INTEGRATION

8100       Sphinx  supports  integration  with  setuptools and distutils through a
8101       custom command - BuildDoc.
8102
8103   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
8108       For instance, from setup.py:
8109
8110          # this is only necessary when not using setuptools/distribute
8111          from sphinx.setup_command import BuildDoc
8112          cmdclass = {'build_sphinx': BuildDoc}
8113
8114          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
8131       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
8136       Or add this section in setup.cfg:
8137
8138          [build_sphinx]
8139          project = 'My project'
8140          version = 1.2
8141          release = 1.2.0
8142          source-dir = 'doc'
8143
8144       Once configured, call this by calling the relevant command on setup.py:
8145
8146          $ python setup.py build_sphinx
8147
8148   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
8153              This can also be set by passing the -E flag to setup.py.
8154
8155                 $ python setup.py build_sphinx -E
8156
8157       all-files
8158              A boolean that determines whether all files should be built from
8159              scratch.  Default is false.
8160
8161              This can also be set by passing the -a flag to setup.py:
8162
8163                 $ python setup.py build_sphinx -a
8164
8165       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
8172              This can also be set by passing the -s flag to setup.py:
8173
8174                 $ python setup.py build_sphinx -s $SOURCE_DIR
8175
8176       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
8181       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
8186              This can also be set by passing the -c flag to setup.py:
8187
8188                 $ python setup.py build_sphinx -c $CONFIG_DIR
8189
8190              New in version 1.0.
8191
8192
8193       builder
8194              The builder or list of builders to use. Default is html.
8195
8196              This can also be set by passing the -b flag to setup.py:
8197
8198                 $ python setup.py build_sphinx -b $BUILDER
8199
8200              Changed in version 1.6: This can now be a comma- or  space-sepa‐
8201              rated list of builders
8202
8203
8204       warning-is-error
8205              A  boolean  that ensures Sphinx warnings will result in a failed
8206              build.  Default is false.
8207
8208              This can also be set by passing the -W flag to setup.py:
8209
8210                 $ python setup.py build_sphinx -W
8211
8212              New in version 1.5.
8213
8214
8215       project
8216              The documented project’s name. Default is ''.
8217
8218              New in version 1.0.
8219
8220
8221       version
8222              The short X.Y version. Default is ''.
8223
8224              New in version 1.0.
8225
8226
8227       release
8228              The full version, including alpha/beta/rc tags. Default is ''.
8229
8230              New in version 1.0.
8231
8232
8233       today  How to format the current date,  used  as  the  replacement  for
8234              |today|.  Default is ''.
8235
8236              New in version 1.0.
8237
8238
8239       link-index
8240              A  boolean  that ensures index.html will be linked to the master
8241              doc. Default is false.
8242
8243              This can also be set by passing the -i flag to setup.py:
8244
8245                 $ python setup.py build_sphinx -i
8246
8247              New in version 1.0.
8248
8249
8250       copyright
8251              The copyright string. Default is ''.
8252
8253              New in version 1.3.
8254
8255
8256       pdb    A boolean to configure pdb on exception. Default is false.
8257
8258              New in version 1.5.
8259
8260

TEMPLATING

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
8268   Do I need to use Sphinx’s templates to produce HTML?
8269       No.  You have several other options:
8270
8271       · You can write a TemplateBridge  subclass  that  calls  your  template
8272         engine  of  choice,  and  set the template_bridge configuration value
8273         accordingly.
8274
8275       · You can write a custom  builder  that  derives  from  StandaloneHTML‐
8276         Builder and calls your template engine of choice.
8277
8278       · 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
8282   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
8289       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
8294       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
8298       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
8302       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
8308       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
8312          {% extends "!layout.html" %}
8313          {% block rootrellink %}
8314              <li><a href="http://project.invalid/">Project Homepage</a> &raquo;</li>
8315              {{ super() }}
8316          {% endblock %}
8317
8318       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
8322       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
8326   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
8331   Blocks
8332       The following blocks exist in the layout.html template:
8333
8334       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
8340       linktags
8341              This  block  adds a couple of <link> tags to the head section of
8342              the template.
8343
8344       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
8350       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
8358                 {% block relbar2 %}{% endblock %}
8359
8360       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
8369       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
8374       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
8380                 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
8381                 {% block sidebar2 %}{% endblock %}
8382
8383              (The  sidebar2 location for the sidebar is needed by the sphinx‐
8384              doc.css stylesheet, for example.)
8385
8386       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
8390       footer The  block  for  the footer div.  If you want a custom footer or
8391              markup before or after it, override this one.
8392
8393       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
8398       sidebartoc
8399              The table of contents within the sidebar.
8400
8401              Deprecated since version 1.0.
8402
8403
8404       sidebarrel
8405              The relation links (previous, next document) within the sidebar.
8406
8407              Deprecated since version 1.0.
8408
8409
8410       sidebarsourcelink
8411              The  “Show  source” link within the sidebar (normally only shown
8412              if this is enabled by html_show_sourcelink).
8413
8414              Deprecated since version 1.0.
8415
8416
8417       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
8421              Deprecated since version 1.0.
8422
8423
8424   Configuration Variables
8425       Inside  templates  you can set a couple of variables used by the layout
8426       template using the {% set %} tag:
8427
8428       reldelim1
8429              The delimiter for the items on the left side of the related bar.
8430              This  defaults  to  ' &raquo;' Each item in the related bar ends
8431              with the value of this variable.
8432
8433       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
8438       Overriding works like this:
8439
8440          {% extends "!layout.html" %}
8441          {% set reldelim1 = ' &gt;' %}
8442
8443       script_files
8444              Add additional script files here, like this:
8445
8446                 {% set script_files = script_files + ["_static/myscript.js"] %}
8447
8448   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
8452       pathto(document)
8453              Return  the  path  to  a  Sphinx document as a URL.  Use this to
8454              refer to built documents.
8455
8456       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
8461       hasdoc(document)
8462              Check if a document with the name document exists.
8463
8464       sidebar()
8465              Return the rendered sidebar.
8466
8467       relbar()
8468              Return the rendered relation bar.
8469
8470   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
8475       builder
8476              The name of the builder (e.g. html or htmlhelp).
8477
8478       copyright
8479              The value of copyright.
8480
8481       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
8485       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
8491       favicon
8492              The path to the HTML favicon in the static path, or ''.
8493
8494       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
8499       has_source
8500              True   if   the   reST   document   sources   are   copied   (if
8501              html_copy_source is True).
8502
8503       language
8504              The value of language.
8505
8506       last_updated
8507              The build date.
8508
8509       logo   The path to the HTML logo image in the static path, or ''.
8510
8511       master_doc
8512              The value of master_doc, for usage with pathto().
8513
8514       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
8520       project
8521              The value of project.
8522
8523       release
8524              The value of release.
8525
8526       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
8533       shorttitle
8534              The value of html_short_title.
8535
8536       show_source
8537              True if html_show_sourcelink is True.
8538
8539       sphinx_version
8540              The version of Sphinx used to build.
8541
8542       style  The name of the main  stylesheet,  as  given  by  the  theme  or
8543              html_style.
8544
8545       title  The title of the current document, as used in the <title> tag.
8546
8547       use_opensearch
8548              The value of html_use_opensearch.
8549
8550       version
8551              The value of version.
8552
8553       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
8557       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
8561       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
8564       display_toc
8565              A boolean that is True if the toc contains more than one entry.
8566
8567       meta   Document metadata (a dictionary), see metadata.
8568
8569       metatags
8570              A string containing the page’s HTML meta tags.
8571
8572       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
8577                 {% if next %}
8578                 <a href="{{ next.link|e }}">{{ next.title }}</a>
8579                 {% endif %}
8580
8581       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
8586       parents
8587              A  list  of parent documents for navigation, structured like the
8588              next item.
8589
8590       prev   Like next, but for the previous page.
8591
8592       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
8597       title  The page title.
8598
8599       toc    The local table of contents for the current  page,  rendered  as
8600              HTML bullet lists.
8601
8602       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
8607              · collapse  (True by default): if true, all TOC entries that are
8608                not ancestors of the current page are collapsed
8609
8610              · 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
8614              · titles_only (False by default): if  true,  put  only  toplevel
8615                document titles in the tree
8616
8617              · includehidden  (False  by default): if true, the TOC tree will
8618                also contain hidden entries.
8619

LATEX CUSTOMIZATION

8621       For details of the LaTeX/PDF builder command line invocation, refer  to
8622       LaTeXBuilder.
8623
8624   Basic customization
8625       The latex target does not benefit from prepared themes.
8626
8627       Basic  customization  is  obtained  via usage of the latex-options. For
8628       example:
8629
8630          # 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
8650       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
8654          '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
8658       It is then needed  to  set  appropriately  latex_additional_files,  for
8659       example:
8660
8661          latex_additional_files = ["mystyle.sty"]
8662
8663   The LaTeX style file options
8664       Additional  customization  is  possible via LaTeX options of the Sphinx
8665       style file.
8666
8667   The sphinxsetup interface
8668       The 'sphinxsetup' key of latex_elements provides  a  convenient  inter‐
8669       face:
8670
8671          latex_elements = {
8672              'sphinxsetup': 'key1=value1, key2=value2, ...',
8673          }
8674
8675       · some  values  may  be  LaTeX  macros,  then  the  backslashes must be
8676         Python-escaped, or the whole must be a Python raw string,
8677
8678       · LaTeX boolean keys require lowercase true or false values,
8679
8680       · spaces around the commas and equal signs are ignored,  spaces  inside
8681         LaTeX macros may be significant.
8682
8683       If  non-empty,  it will be passed as argument to the \sphinxsetup macro
8684       inside the document preamble, like this:
8685
8686          \usepackage{sphinx}
8687          \sphinxsetup{key1=value1, key2=value2,...}
8688
8689       New in version 1.5.
8690
8691
8692       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
8697              .. raw:: latex
8698
8699                 \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
8714          at the start of the chapter and:
8715
8716              .. raw:: latex
8717
8718                 \endgroup
8719
8720          at its end.
8721
8722          The colors used in the above are provided by the svgnames option  of
8723          the “xcolor” package:
8724
8725              latex_elements = {
8726                  'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
8727              }
8728
8729   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
8736                 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
8737
8738              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
8744              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
8750                     'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
8751
8752              New in version 1.5.3.
8753
8754
8755       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
8760              New in version 1.5.3.
8761
8762
8763       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
8769       verbatimwrapslines
8770              default true. Tells whether long lines in code-block’s  contents
8771              should wrap.
8772
8773       literalblockcappos
8774              default  t  for “top”. Decides the caption position. Alternative
8775              is b (“bottom”).
8776
8777              New in version 1.7.
8778
8779
8780       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
8785              New in version 1.6.3.
8786
8787
8788              Changed in version 1.7: the default changed from false to true.
8789
8790
8791       verbatimcontinuedalign, verbatimcontinuesalign
8792              default c. Horizontal position relative to the framed  contents:
8793              either l (left aligned), r (right aligned) or c (centered).
8794
8795              New in version 1.7.
8796
8797
8798       parsedliteralwraps
8799              default  true. Tells whether long lines in parsed-literal’s con‐
8800              tents should wrap.
8801
8802              New in version 1.5.2: set this option value to false to  recover
8803              former behaviour.
8804
8805
8806       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
8814              New in version 1.5: set this option value to  false  to  recover
8815              former behaviour.
8816
8817
8818       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
8823       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
8828                 \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
8829
8830              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
8835
8836       TitleColor
8837              default {rgb}{0.126,0.263,0.361}. The colour for titles (as con‐
8838              figured via use of package “titlesec”.)
8839
8840       WARNING:
8841          Colours  set via 'sphinxsetup'  must obey the syntax of the argument
8842          of the color/xcolor packages \definecolor command.
8843
8844       InnerLinkColor
8845              default {rgb}{0.208,0.374,0.486}. A colour passed to hyperref as
8846              value of linkcolor  and citecolor.
8847
8848       OuterLinkColor
8849              default {rgb}{0.216,0.439,0.388}. A colour passed to hyperref as
8850              value of filecolor, menucolor, and urlcolor.
8851
8852       VerbatimColor
8853              default {rgb}{1,1,1}. The background colour for code-blocks. The
8854              default is white.
8855
8856       VerbatimBorderColor
8857              default {rgb}{0,0,0}. The frame color, defaults to black.
8858
8859       VerbatimHighlightColor
8860              default {rgb}{0.878,1,1}. The color for highlighted lines.
8861
8862              New in version 1.6.6.
8863
8864
8865       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
8870       verbatimsep
8871              default  \fboxsep.  The  separation  between  code lines and the
8872              frame.
8873
8874       verbatimborder
8875              default \fboxrule. The width of the frame around code-blocks.
8876
8877       shadowsep
8878              default 5pt. The  separation  between  contents  and  frame  for
8879              contents and topic boxes.
8880
8881       shadowsize
8882              default 4pt. The width of the lateral “shadow” to the right.
8883
8884       shadowrule
8885              default \fboxrule. The width of the frame around topic boxes.
8886
8887       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
8892       noteborder, hintborder, importantborder, tipborder
8893              default 0.5pt. The width of the two horizontal rules.
8894
8895       warningBorderColor, cautionBorderColor,
8896              attentionBorderColor,     dangerBorderColor,    errorBorderColor
8897              default {rgb}{0,0,0} (black).  The  colour  for  the  admonition
8898              frame.
8899
8900       warningBgColor, cautionBgColor,
8901              attentionBgColor,     dangerBgColor,     errorBgColor    default
8902              {rgb}{1,1,1} (white). The background colours for the  respective
8903              admonitions.
8904
8905       warningBorder, cautionBorder,
8906              attentionBorder,  dangerBorder,  errorBorder  default  1pt.  The
8907              width of the frame.
8908
8909       AtStartFootnote
8910              default \mbox{ }. LaTeX macros inserted  at  the  start  of  the
8911              footnote text at bottom of page, after the footnote number.
8912
8913       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
8918              New in version 1.5.
8919
8920
8921       HeaderFamily
8922              default \sffamily\bfseries. Sets the font used by headings.
8923
8924   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
8929   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
8934         New  in  version  1.4.5: Use of \sphinx prefixed macro names to limit
8935         possibilities of conflict with LaTeX packages.
8936
8937
8938       · 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
8943         New in version 1.5: these macros were formerly hard-coded as non cus‐
8944         tomizable \texttt, \emph, etc…
8945
8946
8947         New in version 1.6: \sphinxstyletheadfamily which defaults to \sffam‐
8948         ily and allows multiple paragraphs in header cells of tables.
8949
8950
8951         New in version 1.6.3: \sphinxstylecodecontinued and \sphinxstylecode‐
8952         continues.
8953
8954
8955       · 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
8961         New in version 1.5.
8962
8963
8964       · 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
8968         Changed in version 1.5: formerly, the meaning of \tableofcontents was
8969         modified by Sphinx.
8970
8971
8972       · the  \maketitle  command  is  redefined by the class files sphinxman‐
8973         ual.cls and sphinxhowto.cls.
8974
8975   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
8980         New in version 1.5.6: formerly, the \small  was  hardcoded  in  LaTeX
8981         writer and the ending \par was lacking.
8982
8983
8984       · 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
8993         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
8997
8998       · the contents directive (with :local: option) and the topic  directive
8999         are implemented by environment sphinxShadowBox.
9000
9001         New  in  version  1.4.2:  former  code refactored into an environment
9002         allowing page breaks.
9003
9004
9005         Changed in version 1.5: options shadowsep, shadowsize,  shadowrule.
9006
9007
9008       · 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
9015         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
9019
9020         New  in  version  1.5: options verbatimwithframe, verbatimwrapslines,
9021         verbatimsep, verbatimborder.
9022
9023
9024         New in version 1.6.6: support for :emphasize-lines: option
9025
9026
9027         New in version 1.6.6: easier customizability of  the  formatting  via
9028         exposed to user LaTeX macros such as \sphinxVerbatimHighlightLine.
9029
9030
9031       · 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
9037         Changed in version 1.5: formerly, the original environments were mod‐
9038         ified by Sphinx.
9039
9040
9041   Miscellany
9042       · the section,  subsection,  …   headings  are  set  using   titlesec’s
9043         \titleformat command.
9044
9045       · 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
9050         Changed in version 1.5: formerly, use of fncychap with  other  styles
9051         than Bjarne was dysfunctional.
9052
9053
9054       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
9059          New  in  version  1.5: currently all template variables are unstable
9060          and undocumented.
9061
9062
9063          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
9067          New in version 1.6: currently all template  variables  are  unstable
9068          and undocumented.
9069
9070

MARKDOWN SUPPORT

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
9078   Configuration
9079       To  configure your Sphinx project for Markdown support, proceed as fol‐
9080       lows:
9081
9082       1. Install recommonmark:
9083
9084             pip install recommonmark
9085
9086       2. Add the Markdown parser to the source_parsers configuration variable
9087          in your Sphinx configuration file:
9088
9089             source_parsers = {
9090                '.md': 'recommonmark.parser.CommonMarkParser',
9091             }
9092
9093          You can replace .md with a filename extension of your choice.
9094
9095       3. Add the Markdown filename extension to the  source_suffix configura‐
9096          tion variable:
9097
9098             source_suffix = ['.rst', '.md']
9099
9100       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

SPHINX EXTENSIONS

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
9109       This chapter describes the extensions bundled with Sphinx.  For the API
9110       documentation on writing your own extension, see dev-extensions.
9111
9112   Builtin Sphinx extensions
9113       These  extensions  are  built  in  and  can  be activated by respective
9114       entries in the extensions configuration value:
9115
9116   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
9120       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
9126       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
9131          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
9135       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
9142       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
9147       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
9153       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
9157       .. automodule::
9158
9159       .. autoclass::
9160
9161       .. autoexception::
9162              Document  a  module,  class  or exception.  All three directives
9163              will by default only insert the docstring of the object itself:
9164
9165                 .. autoclass:: Noodle
9166
9167              will produce source like this:
9168
9169                 .. class:: Noodle
9170
9171                    Noodle's docstring.
9172
9173              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
9178              Therefore,  you  can also mix automatic and non-automatic member
9179              documentation, like so:
9180
9181                 .. autoclass:: Noodle
9182                    :members: eat, slurp
9183
9184                    .. method:: boil(time=10)
9185
9186                       Boil the noodle *time* minutes.
9187
9188              Options and advanced usage
9189
9190              · If you want to automatically document members, there’s a  mem‐
9191                bers option:
9192
9193                   .. automodule:: noodle
9194                      :members:
9195
9196                will document all module members (recursively), and
9197
9198                   .. autoclass:: Noodle
9199                      :members:
9200
9201                will  document all non-private member functions and properties
9202                (that is, those whose name doesn’t start with _).
9203
9204                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
9209                You can also give an explicit list of members; only these will
9210                then be documented:
9211
9212                   .. autoclass:: Noodle
9213                      :members: eat, slurp
9214
9215              · If you want to make the members option (or other flag  options
9216                described below) the default, see autodoc_default_flags.
9217
9218              · Members  without  docstrings will be left out, unless you give
9219                the undoc-members flag option:
9220
9221                   .. automodule:: noodle
9222                      :members:
9223                      :undoc-members:
9224
9225              · “Private” members (that  is,  those  named  like  _private  or
9226                __private) will be included if the private-members flag option
9227                is given.
9228
9229                New in version 1.1.
9230
9231
9232              · Python “special” members (that is,  those  named  like  __spe‐
9233                cial__) will be included if the special-members flag option is
9234                given:
9235
9236                   .. autoclass:: my.Class
9237                      :members:
9238                      :private-members:
9239                      :special-members:
9240
9241                would document both “private” and  “special”  members  of  the
9242                class.
9243
9244                New in version 1.1.
9245
9246
9247                Changed  in  version  1.2:  The option can now take arguments,
9248                i.e. the special members to document.
9249
9250
9251              · 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
9256                   .. autoclass:: Noodle
9257                      :members:
9258                      :inherited-members:
9259
9260                This can be combined with undoc-members to document all avail‐
9261                able members of the class or module.
9262
9263                Note: this will lead to markup errors if the inherited members
9264                come from a module whose docstrings are not reST formatted.
9265
9266                New in version 0.3.
9267
9268
9269              · 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
9274                   .. autoclass:: Noodle(type)
9275
9276                      .. automethod:: eat(persona)
9277
9278                This is useful if the signature from the method is hidden by a
9279                decorator.
9280
9281                New in version 0.4.
9282
9283
9284              · 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
9290                New in version 0.4.
9291
9292
9293              · 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
9298                New in version 0.4.
9299
9300
9301              · automodule also recognizes the synopsis, platform  and  depre‐
9302                cated options that the standard py:module directive supports.
9303
9304                New in version 0.5.
9305
9306
9307              · 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
9311                New in version 0.6.
9312
9313
9314              · 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
9319                New in version 0.6.
9320
9321
9322              · 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
9332                New in version 1.2.
9333
9334
9335              · 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
9339                New in version 1.3.
9340
9341
9342       .. autofunction::
9343
9344       .. autodata::
9345
9346       .. automethod::
9347
9348       .. autoattribute::
9349              These work exactly like autoclass etc., but  do  not  offer  the
9350              options used for automatic member documentation.
9351
9352              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
9357                 .. autodata:: CD_DRIVE
9358                    :annotation:
9359
9360              You can tell sphinx what should be printed after the name:
9361
9362                 .. autodata:: CD_DRIVE
9363                    :annotation: = your CD device name
9364
9365              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
9373              This  means  that  in  the  following  class   definition,   all
9374              attributes can be autodocumented:
9375
9376                 class Foo:
9377                     """Docstring for class Foo."""
9378
9379                     #: Doc comment for class attribute Foo.bar.
9380                     #: It can have multiple lines.
9381                     bar = 1
9382
9383                     flox = 1.5   #: Doc comment for Foo.flox. One line only.
9384
9385                     baz = 2
9386                     """Docstring for class attribute Foo.baz."""
9387
9388                     def __init__(self):
9389                         #: Doc comment for instance attribute qux.
9390                         self.qux = 3
9391
9392                         self.spam = 4
9393                         """Docstring for instance attribute spam."""
9394
9395              Changed  in  version  0.6:  autodata  and  autoattribute can now
9396              extract docstrings.
9397
9398
9399              Changed in version 1.1: Comment docs are now allowed on the same
9400              line after an assignment.
9401
9402
9403              Changed in version 1.2: autodata and autoattribute have an anno‐
9404              tation option.
9405
9406
9407              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
9415                 From  Python  2.5,  functools.wraps()  can  be used to create
9416                 well-behaved decorating functions.
9417
9418       There are also new config values that you can set:
9419
9420       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
9424              "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
9430              "both" Both the class’ and the __init__ method’s  docstring  are
9431                     concatenated and inserted.
9432
9433              "init" Only the __init__ method’s docstring is inserted.
9434
9435              New in version 0.3.
9436
9437
9438              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
9442              New in version 1.4.
9443
9444
9445       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
9451              Note that for source order, the module must be a  Python  module
9452              with the source code available.
9453
9454              New in version 0.6.
9455
9456
9457              Changed in version 1.0: Support for 'bysource'.
9458
9459
9460       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
9467              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
9472                 .. automodule:: foo
9473                    :no-undoc-members:
9474
9475              the directive will be  interpreted  as  if  only  :members:  was
9476              given.
9477
9478              New in version 1.0.
9479
9480
9481       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
9488              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
9493              New in version 1.1.
9494
9495
9496       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
9502                 autodoc_mock_imports = ["django"]
9503
9504              Will mock all imports under the django package.
9505
9506              New in version 1.3.
9507
9508
9509              Changed  in  version  1.6:  This  config  value only requires to
9510              declare the top-level modules that should be mocked.
9511
9512
9513       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
9519       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
9524              The default is True.
9525
9526              New in version 1.7.
9527
9528
9529   Docstring preprocessing
9530       autodoc provides the following additional events:
9531
9532       autodoc-process-docstring(app, what, name, obj, options, lines)
9533              New in version 0.4.
9534
9535
9536              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
9541              Parameters
9542
9543                     · app – the Sphinx application object
9544
9545                     · what – the type  of  the  object  which  the  docstring
9546                       belongs  to  (one  of  "module",  "class", "exception",
9547                       "function", "method", "attribute")
9548
9549                     · name – the fully qualified name of the object
9550
9551                     · obj – the object itself
9552
9553                     · 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
9558                     · lines – the lines of the docstring, see above
9559
9560       autodoc-process-signature(app,  what,  name,  obj,  options, signature,
9561       return_annotation)
9562              New in version 0.5.
9563
9564
9565              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
9569              Parameters
9570
9571                     · app – the Sphinx application object
9572
9573                     · what – the type  of  the  object  which  the  docstring
9574                       belongs  to  (one  of  "module",  "class", "exception",
9575                       "function", "method", "attribute")
9576
9577                     · name – the fully qualified name of the object
9578
9579                     · obj – the object itself
9580
9581                     · 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
9586                     · 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
9591                     · return_annotation – function  return  annotation  as  a
9592                       string  of  the form " -> annotation", or None if there
9593                       is no return annotation
9594
9595       The sphinx.ext.autodoc module provides factory functions  for  commonly
9596       needed docstring processing in event autodoc-process-docstring:
9597
9598       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
9603              Use like this (e.g. in the setup() function of conf.py):
9604
9605                 from sphinx.ext.autodoc import cut_lines
9606                 app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
9607
9608              This can (and should) be used in place of automodule_skip_lines.
9609
9610       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
9617              If  what  is a sequence of strings, only docstrings of a type in
9618              what will be processed.
9619
9620   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
9625       autodoc-skip-member(app, what, name, obj, skip, options)
9626              New in version 0.5.
9627
9628
9629              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
9633              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
9638              Parameters
9639
9640                     · app – the Sphinx application object
9641
9642                     · what  –  the  type  of  the  object which the docstring
9643                       belongs to  (one  of  "module",  "class",  "exception",
9644                       "function", "method", "attribute")
9645
9646                     · name – the fully qualified name of the object
9647
9648                     · obj – the object itself
9649
9650                     · skip  –  a boolean indicating if autodoc will skip this
9651                       member if the user handler does not override the  deci‐
9652                       sion
9653
9654                     · 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
9659   sphinx.ext.autosectionlabel – Allow reference sections using its title
9660       New in version 1.4.
9661
9662
9663       This extension allows you to refer sections its title.  This affects to
9664       the reference role (ref).
9665
9666       For example:
9667
9668          A Plain Title
9669          -------------
9670
9671          This is the text of the section.
9672
9673          It refers to the section title, see :ref:`A Plain Title`.
9674
9675       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
9681   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
9689   sphinx.ext.autosummary – Generate autodoc summaries
9690       New in version 0.6.
9691
9692
9693       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
9699       The sphinx.ext.autosummary extension does this in two parts:
9700
9701       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
9705       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
9711       .. 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
9716              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
9720              For example,
9721
9722                 .. currentmodule:: sphinx
9723
9724                 .. autosummary::
9725
9726                    environment.BuildEnvironment
9727                    util.relative_uri
9728
9729              produces a table like this:
9730
9731                   ┌──────────────────────────┬────────────────────────────┐
9732environment.BuildEnviron‐ │ The environment  in  which │
9733ment(app)                 │ the  ReST files are trans‐ │
9734                   │                          │ lated.                     │
9735                   ├──────────────────────────┼────────────────────────────┤
9736util.relative_uri(base,   │ Return a relative URL from │
9737                   │to)                       │ base to to.                │
9738                   └──────────────────────────┴────────────────────────────┘
9739
9740              Autosummary preprocesses the docstrings and signatures with  the
9741              same   autodoc-process-docstring  and  autodoc-process-signature
9742              hooks as autodoc.
9743
9744              Options
9745
9746              · If you want the autosummary table to also serve as  a  toctree
9747                entry, use the toctree option, for example:
9748
9749                   .. autosummary::
9750                      :toctree: DIRNAME
9751
9752                      sphinx.environment.BuildEnvironment
9753                      sphinx.util.relative_uri
9754
9755                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
9762              · If you don’t want the autosummary to show function  signatures
9763                in the listing, include the nosignatures option:
9764
9765                   .. autosummary::
9766                      :nosignatures:
9767
9768                      sphinx.environment.BuildEnvironment
9769                      sphinx.util.relative_uri
9770
9771              · You  can  specify  a custom template with the template option.
9772                For example,
9773
9774                   .. autosummary::
9775                      :template: mytemplate.rst
9776
9777                      sphinx.environment.BuildEnvironment
9778
9779                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
9783                New in version 1.0.
9784
9785
9786   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
9790       For example, the command
9791
9792          $ sphinx-autogen -o generated *.rst
9793
9794       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
9799          sphinx.util.relative_uri
9800          ========================
9801
9802          .. autofunction:: sphinx.util.relative_uri
9803
9804       If the -o option is not given, the script will place the  output  files
9805       in the directories specified in the :toctree: options.
9806
9807       For more information, refer to the sphinx-autogen documentation
9808
9809   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
9813       autosummary_generate
9814              Boolean indicating whether to scan all found documents for auto‐
9815              summary directives, and to generate stub pages for each.
9816
9817              Can  also  be a list of documents for which stub pages should be
9818              generated.
9819
9820              The new files will be placed in the directories specified in the
9821              :toctree: options of the directives.
9822
9823   Customizing templates
9824       New in version 1.0.
9825
9826
9827       You can customize the stub page templates, in a similar way as the HTML
9828       Jinja templates, see templating. (TemplateBridge is not supported.)
9829
9830       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
9835       Autosummary uses the following Jinja template files:
9836
9837       · autosummary/base.rst – fallback template
9838
9839       · autosummary/module.rst – template for modules
9840
9841       · autosummary/class.rst – template for classes
9842
9843       · autosummary/function.rst – template for functions
9844
9845       · autosummary/attribute.rst – template for class attributes
9846
9847       · autosummary/method.rst – template for class methods
9848
9849       The following variables available in the templates:
9850
9851       name   Name of the documented object, excluding the  module  and  class
9852              parts.
9853
9854       objname
9855              Name of the documented object, excluding the module parts.
9856
9857       fullname
9858              Full  name  of the documented object, including module and class
9859              parts.
9860
9861       module Name of the module the documented object belongs to.
9862
9863       class  Name of the class the documented object belongs to.  Only avail‐
9864              able for methods and attributes.
9865
9866       underline
9867              A string containing len(full_name) * '='. Use the underline fil‐
9868              ter instead.
9869
9870       members
9871              List containing names of all members of  the  module  or  class.
9872              Only available for modules and classes.
9873
9874       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
9879       classes
9880              List  containing  names of “public” classes in the module.  Only
9881              available for modules.
9882
9883       exceptions
9884              List containing names of  “public”  exceptions  in  the  module.
9885              Only available for modules.
9886
9887       methods
9888              List  containing  names  of “public” methods in the class.  Only
9889              available for classes.
9890
9891       attributes
9892              List containing names of “public” attributes in the class.  Only
9893              available for classes.
9894
9895       Additionally, the following filters are available
9896
9897       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
9903       underline(s, line='=')
9904              Add a title underline to a piece of text.
9905
9906       For instance, {{ fullname | escape | underline }}  should  be  used  to
9907       produce the title of a page.
9908
9909       NOTE:
9910          You can use the autosummary directive in the stub pages.  Stub pages
9911          are generated also based on these directives.
9912
9913   sphinx.ext.coverage – Collect doc coverage stats
9914       This extension features one additional builder, the CoverageBuilder.
9915
9916       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
9920   Todo
9921       Write this section.
9922
9923       Several  new  configuration  values  can  be  used  to specify what the
9924       builder should check:
9925
9926       coverage_ignore_modules
9927
9928       coverage_ignore_functions
9929
9930       coverage_ignore_classes
9931
9932       coverage_c_path
9933
9934       coverage_c_regexes
9935
9936       coverage_ignore_c_items
9937
9938       coverage_write_headline
9939              Set to False to not write headlines.
9940
9941              New in version 1.1.
9942
9943
9944       coverage_skip_undoc_in_source
9945              Skip objects that are not documented in the source with  a  doc‐
9946              string.  False by default.
9947
9948              New in version 1.1.
9949
9950
9951   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
9956       Within  one  document,  test  code is partitioned in groups, where each
9957       group consists of:
9958
9959       · zero or more setup code blocks (e.g. importing the module to test)
9960
9961       · one or more test blocks
9962
9963       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
9967       There are two kinds of test blocks:
9968
9969       · doctest-style  blocks  mimic  interactive  sessions  by  interleaving
9970         Python code (including the interpreter prompt) and output.
9971
9972       · code-output-style blocks consist of an ordinary piece of Python code,
9973         and optionally, a piece of output for that code.
9974
9975   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
9981       .. 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
9986       .. 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
9991              New in version 1.1.
9992
9993
9994       .. 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
10000              This directive supports three options:
10001
10002              · hide,  a  flag  option,  hides  the  doctest  block  in  other
10003                builders.   By  default  it  is shown as a highlighted doctest
10004                block.
10005
10006              · 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
10012              · 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
10017                   .. doctest::
10018                      :pyversion: > 3.3
10019
10020                The following operands are supported:
10021
10022                · ~=: Compatible release clause
10023
10024                · ==: Version matching clause
10025
10026                · !=: Version exclusion clause
10027
10028                · <=, >=: Inclusive ordered comparison clause
10029
10030                · <, >: Exclusive ordered comparison clause
10031
10032                · ===: Arbitrary equality clause.
10033
10034                pyversion option is followed PEP-440: Version Specifiers.
10035
10036                New in version 1.6.
10037
10038
10039                Changed  in  version 1.7: Supported PEP-440 operands and nota‐
10040                tions
10041
10042
10043              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
10048              Also, you can give inline doctest options, like in doctest:
10049
10050                 >>> datetime.date.now()   # doctest: +SKIP
10051                 datetime.date(2008, 1, 1)
10052
10053              They  will  be respected when the test is run, but stripped from
10054              presentation output.
10055
10056       .. testcode:: [group]
10057              A code block for a code-output-style test.
10058
10059              This directive supports one option:
10060
10061              · hide, a flag option, hides the code block in  other  builders.
10062                By default it is shown as a highlighted code block.
10063
10064              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
10070                     .. testcode::
10071
10072                        1+1        # this will give no output!
10073                        print 2+2  # this will give output
10074
10075                     .. testoutput::
10076
10077                        4
10078
10079                 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
10083       .. testoutput:: [group]
10084              The corresponding output, or the exception message, for the last
10085              testcode block.
10086
10087              This directive supports two options:
10088
10089              · 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
10093              · options,  a  string  option, can be used to give doctest flags
10094                (comma-separated) just like in normal doctest blocks.
10095
10096              Example:
10097
10098                 .. testcode::
10099
10100                    print 'Output     text.'
10101
10102                 .. testoutput::
10103                    :hide:
10104                    :options: -ELLIPSIS, +NORMALIZE_WHITESPACE
10105
10106                    Output text.
10107
10108       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
10111          The parrot module
10112          =================
10113
10114          .. testsetup:: *
10115
10116             import parrot
10117
10118          The parrot module is a module about parrots.
10119
10120          Doctest example:
10121
10122          .. doctest::
10123
10124             >>> parrot.voom(3000)
10125             This parrot wouldn't voom if you put 3000 volts through it!
10126
10127          Test-Output example:
10128
10129          .. testcode::
10130
10131             parrot.voom(3000)
10132
10133          This would output:
10134
10135          .. testoutput::
10136
10137             This parrot wouldn't voom if you put 3000 volts through it!
10138
10139   Configuration
10140       The doctest extension uses the following configuration values:
10141
10142       doctest_default_flags
10143              By default, these options are enabled:
10144
10145              · ELLIPSIS,  allowing you to put ellipses in the expected output
10146                that match anything in the actual output;
10147
10148              · IGNORE_EXCEPTION_DETAIL,  causing  everything  following   the
10149                leftmost  colon  and  any  module information in the exception
10150                name to be ignored;
10151
10152              · 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
10156              New in version 1.5.
10157
10158
10159       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
10164       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
10170              New in version 0.6.
10171
10172
10173       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
10179              New in version 1.1.
10180
10181
10182       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
10187              reST doctest blocks are simply doctests put into a paragraph  of
10188              their own, like so:
10189
10190                 Some documentation text.
10191
10192                 >>> print 1
10193                 1
10194
10195                 Some more documentation text.
10196
10197              (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
10201              If this value is left at its default value, the above snippet is
10202              interpreted by the doctest builder exactly like the following:
10203
10204                 Some documentation text.
10205
10206                 .. doctest::
10207
10208                    >>> print 1
10209                    1
10210
10211                 Some more documentation text.
10212
10213              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
10217              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
10224   sphinx.ext.extlinks – Markup to shorten external links
10225       Module author: Georg Brandl
10226
10227       New in version 1.0.
10228
10229
10230       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
10236       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
10241       The extension adds one new config value:
10242
10243       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
10249                 extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
10250                                       'issue ')}
10251
10252              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
10258              The  link  caption  depends on the second item in the tuple, the
10259              prefix:
10260
10261              · If the prefix is None, the link caption is the full URL.
10262
10263              · 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
10266              · 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
10270              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
10274       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
10278   sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
10279       New in version 1.4.
10280
10281
10282       This extension creates .nojekyll file on generated  HTML  directory  to
10283       publish the document on GitHub Pages.
10284
10285   sphinx.ext.graphviz – Add Graphviz graphs
10286       New in version 0.6.
10287
10288
10289       This extension allows you to embed Graphviz graphs in your documents.
10290
10291       It adds these directives:
10292
10293       .. graphviz::
10294              Directive  to  embed  graphviz  code.  The input code for dot is
10295              given as the content.  For example:
10296
10297                 .. graphviz::
10298
10299                    digraph foo {
10300                       "bar" -> "baz";
10301                    }
10302
10303              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
10307              You can also embed external dot files, by giving the  file  name
10308              as an argument to graphviz and no additional content:
10309
10310                 .. graphviz:: external.dot
10311
10312              As  for  all file references in Sphinx, if the filename is abso‐
10313              lute, it is taken as relative to the source directory.
10314
10315              Changed in version 1.1: Added support for external files.
10316
10317
10318       .. 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
10324              For example:
10325
10326                 .. graph:: foo
10327
10328                    "bar" -- "baz";
10329
10330              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
10335       .. 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
10341              For example:
10342
10343                 .. digraph:: foo
10344
10345                    "bar" -> "baz" -> "quux";
10346
10347       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
10351
10352       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
10355
10356       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
10359
10360       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
10364
10365       New in version 1.6: All three directives support a name option  to  set
10366       the label to graph.
10367
10368
10369       There are also these new config values:
10370
10371       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
10376              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
10381                 sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
10382
10383       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
10389       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
10397                 .. graphviz::
10398
10399                      digraph example {
10400                          a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
10401                          b [label="other"];
10402                          a -> b;
10403                      }
10404
10405              New in version 1.0: Previously, output always was PNG.
10406
10407
10408   sphinx.ext.ifconfig – Include content based on configuration
10409       This extension is quite simple, and features only one directive:
10410
10411       .. 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
10417              For example, one could write
10418
10419                 .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
10420
10421                    This stuff is only included in the built docs for unstable versions.
10422
10423              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
10426                 def setup(app):
10427                     app.add_config_value('releaselevel', '', 'env')
10428
10429              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
10433   sphinx.ext.imgconverter – Convert images to appropriate format for builders
10434       New in version 1.6.
10435
10436
10437       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
10442       Internally, this extension uses Imagemagick to convert images.
10443
10444   Configuration
10445       image_converter
10446              A  path  to  convert command.  By default, the imgconverter uses
10447              the command from search paths.
10448
10449       image_converter_args
10450              Additional command-line arguments to give to convert, as a list.
10451              The default is an empty list [].
10452
10453   sphinx.ext.inheritance_diagram – Include inheritance diagrams
10454       New in version 0.6.
10455
10456
10457       This extension allows you to include inheritance diagrams, rendered via
10458       the Graphviz extension.
10459
10460       It adds this directive:
10461
10462       .. 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
10468              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
10473              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
10479              It also supports a private-bases flag option; if given,  private
10480              base classes (those whose name starts with _) will be included.
10481
10482              You can use caption option to give a caption to the diagram.
10483
10484              Changed  in version 1.1: Added private-bases option; previously,
10485              all bases were always included.
10486
10487
10488              Changed in version 1.5: Added caption option
10489
10490
10491              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
10496                 """
10497                        A
10498                       / \
10499                      B   C
10500                     / \ / \
10501                    E   D   F
10502                 """
10503
10504                 class A(object):
10505                     pass
10506
10507                 class B(A):
10508                     pass
10509
10510                 class C(A):
10511                     pass
10512
10513                 class D(B, C):
10514                     pass
10515
10516                 class E(B):
10517                     pass
10518
10519                 class F(C):
10520                     pass
10521
10522              If  you  have specified a module in the inheritance diagram like
10523              this:
10524
10525                 .. inheritance-diagram:: dummy.test
10526                    :top-classes: dummy.test.B, dummy.test.C
10527
10528              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
10534              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
10538                 .. inheritance-diagram:: dummy.test.D dummy.test.E dummy.test.F
10539                    :top-classes: dummy.test.B, dummy.test.C
10540
10541              Changed in version 1.7: Added top-classes option  to  limit  the
10542              scope of inheritance graphs.
10543
10544
10545       New config values are:
10546
10547       inheritance_graph_attrs
10548              A  dictionary  of graphviz graph attributes for inheritance dia‐
10549              grams.
10550
10551              For example:
10552
10553                 inheritance_graph_attrs = dict(rankdir="LR", size='"6.0, 8.0"',
10554                                                fontsize=14, ratio='compress')
10555
10556       inheritance_node_attrs
10557              A dictionary of graphviz node attributes  for  inheritance  dia‐
10558              grams.
10559
10560              For example:
10561
10562                 inheritance_node_attrs = dict(shape='ellipse', fontsize=14, height=0.75,
10563                                               color='dodgerblue1', style='filled')
10564
10565       inheritance_edge_attrs
10566              A  dictionary  of  graphviz edge attributes for inheritance dia‐
10567              grams.
10568
10569       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
10575              For example:
10576
10577                 inheritance_alias = {'_pytest.Magic': 'pytest.Magic'}
10578
10579   sphinx.ext.intersphinx – Link to other projects’ documentation
10580       New in version 0.5.
10581
10582
10583       This  extension  can  generate  automatic links to the documentation of
10584       objects in other projects.
10585
10586       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
10593       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
10598       Behind the scenes, this works as follows:
10599
10600       · 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
10603       · 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
10608       · 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
10613       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
10617       intersphinx_mapping
10618              This  config  value  contains  the  locations and names of other
10619              projects that should be linked to in this documentation.
10620
10621              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
10626              When  fetching  remote  inventory  files, proxy settings will be
10627              read from the $HTTP_PROXY environment variable.
10628
10629              Old format for this config value
10630
10631              This is the format used before Sphinx 1.0.  It is  still  recog‐
10632              nized.
10633
10634              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
10640              New format for this config value
10641
10642              New in version 1.0.
10643
10644
10645              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
10652              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
10658              Example
10659
10660              To add links to modules  and  objects  in  the  Python  standard
10661              library documentation, use:
10662
10663                 intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None)}
10664
10665              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
10670              A second example, showing the meaning of a non-None value of the
10671              second tuple item:
10672
10673                 intersphinx_mapping = {'python': ('https://docs.python.org/3.4',
10674                                                   'python-inv.txt')}
10675
10676              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
10682              Multiple target for the inventory
10683
10684              New in version 1.3.
10685
10686
10687              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
10694                 intersphinx_mapping = {'python': ('https://docs.python.org/3.4',
10695                                                   (None, 'python-inv.txt'))}
10696
10697       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
10702       intersphinx_timeout
10703              The number of seconds for timeout.  The default is None, meaning
10704              do not timeout.
10705
10706              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
10711   sphinx.ext.linkcode – Add external links to source code
10712       Module author: Pauli Virtanen
10713
10714       New in version 1.2.
10715
10716
10717       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
10722       In your configuration, you need to specify a linkcode_resolve  function
10723       that returns an URL based on the object.
10724
10725       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
10730              The function should return None if no link is to be added.
10731
10732              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
10736              · py: module (name of the module), fullname (name of the object)
10737
10738              · c: names (list of names for the object)
10739
10740              · cpp: names (list of names for the object)
10741
10742              · javascript: object (name of the object), fullname (name of the
10743                item)
10744
10745              Example:
10746
10747                 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
10755   Math support in Sphinx
10756       New in version 0.5.
10757
10758
10759       Since mathematical notation isn’t natively supported  by  HTML  in  any
10760       way, Sphinx supports math in documentation with several extensions.
10761
10762       The  basic math support is contained in sphinx.ext.mathbase. Other math
10763       support extensions should, if possible, reuse that support too.
10764
10765       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
10770       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
10775       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
10779       mathbase provides the following config values:
10780
10781       math_number_all
10782              Set  this  option  to  True if you want all displayed math to be
10783              numbered.  The default is False.
10784
10785       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
10790              Example: 'Eq.{number}' is rendered as Eq.10
10791
10792       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
10798              New in version 1.7.
10799
10800
10801       mathbase defines these new markup elements:
10802
10803       :math: Role for inline math.  Use like this:
10804
10805                 Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
10806
10807       .. math::
10808              Directive for displayed math (math that takes the whole line for
10809              itself).
10810
10811              The directive supports multiple equations, which should be sepa‐
10812              rated by a blank line:
10813
10814                 .. math::
10815
10816                    (a + b)^2 = a^2 + 2ab + b^2
10817
10818                    (a - b)^2 = a^2 - 2ab + b^2
10819
10820              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
10824                 .. math::
10825
10826                    (a + b)^2  &=  (a + b)(a + b) \\
10827                               &=  a^2 + 2ab + b^2
10828
10829              For  more  details,  look  into the documentation of the AmSMath
10830              LaTeX package.
10831
10832              When the math is only one line of text, it can also be given  as
10833              a directive argument:
10834
10835                 .. math:: (a + b)^2 = a^2 + 2ab + b^2
10836
10837              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
10844              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
10849                 .. math::
10850                    :nowrap:
10851
10852                    \begin{eqnarray}
10853                       y    & = & ax^2 + bx + c \\
10854                       f(x) & = & x^2 + 2xy + y^2
10855                    \end{eqnarray}
10856
10857       :eq:   Role for cross-referencing equations via their label.  Example:
10858
10859                 .. math:: e^{i\pi} + 1 = 0
10860                    :label: euler
10861
10862                 Euler's identity, equation :eq:`euler`, was elected one of the most
10863                 beautiful mathematical formulas.
10864
10865   sphinx.ext.imgmath – Render math as images
10866       New in version 1.4.
10867
10868
10869       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
10873       There are various config values you can set to influence how the images
10874       are built:
10875
10876       imgmath_image_format
10877              The output image format. The default is  'png'.   It  should  be
10878              either 'png' or 'svg'.
10879
10880       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
10885              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
10890                 sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
10891
10892              This value should only contain the path to the latex executable,
10893              not further arguments; use imgmath_latex_args for that purpose.
10894
10895       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
10901       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
10907       imgmath_latex_args
10908              Additional  arguments  to give to latex, as a list.  The default
10909              is an empty list.
10910
10911       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
10917       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
10924       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
10929       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
10938              Unfortunately, this only works when the preview-latex package is
10939              installed. Therefore, the default for this option is False.
10940
10941              Currently this option is only used when imgmath_image_format  is
10942              'png'.
10943
10944       imgmath_add_tooltips
10945              Default:  True.  If false, do not add the LaTeX code as an “alt”
10946              attribute for math images.
10947
10948       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
10952   sphinx.ext.mathjax – Render math via JavaScript
10953       New in version 1.1.
10954
10955
10956       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
10960       Because  MathJax  (and  the  necessary  fonts) is very large, it is not
10961       included in Sphinx.
10962
10963       mathjax_path
10964              The path to the JavaScript file to include in the HTML files  in
10965              order to load MathJax.
10966
10967              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
10972              The path can be absolute or relative; if it is relative,  it  is
10973              relative to the _static directory of the built docs.
10974
10975              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
10980              You can also give a full http:// URL different from the CDN URL.
10981
10982   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
10986       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
10990              The path can be absolute or relative; if it is relative,  it  is
10991              relative to the _static directory of the built docs.
10992
10993              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
10998   sphinx.ext.napoleon – Support for NumPy and Google style docstrings
10999       Module author: Rob Ruana
11000
11001       New in version 1.3.
11002
11003
11004   Napoleon - Marching toward legible docstrings
11005       Are you tired of writing docstrings that look like this:
11006
11007          :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
11017       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
11021          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
11027          Returns:
11028              BufferedFileStorage: A buffered writable file descriptor
11029
11030       Much more legible, no?
11031
11032       Napoleon is a ../extensions that enables Sphinx to parse both NumPy and
11033       Google style docstrings - the style recommended by Khan Academy.
11034
11035       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
11041   Getting Started
11042       1. After  setting  up Sphinx to build your docs, enable napoleon in the
11043          Sphinx conf.py file:
11044
11045             # conf.py
11046
11047             # Add napoleon to the extensions list
11048             extensions = ['sphinx.ext.napoleon']
11049
11050       2. Use sphinx-apidoc to build your API documentation:
11051
11052             $ sphinx-apidoc -f -o docs/source projectdir
11053
11054   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
11060       All standard reStructuredText formatting still works as expected.
11061
11062   Docstring Sections
11063       All of the following section headers are supported:
11064
11065          · Args (alias of Parameters)
11066
11067          · Arguments (alias of Parameters)
11068
11069          · Attributes
11070
11071          · Example
11072
11073          · Examples
11074
11075          · Keyword Args (alias of Keyword Arguments)
11076
11077          · Keyword Arguments
11078
11079          · Methods
11080
11081          · Note
11082
11083          · Notes
11084
11085          · Other Parameters
11086
11087          · Parameters
11088
11089          · Return (alias of Returns)
11090
11091          · Returns
11092
11093          · Raises
11094
11095          · References
11096
11097          · See Also
11098
11099          · Todo
11100
11101          · Warning
11102
11103          · Warnings (alias of Warning)
11104
11105          · Warns
11106
11107          · Yield (alias of Yields)
11108
11109          · Yields
11110
11111   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
11116       Google style:
11117
11118          def func(arg1, arg2):
11119              """Summary line.
11120
11121              Extended description of function.
11122
11123              Args:
11124                  arg1 (int): Description of arg1
11125                  arg2 (str): Description of arg2
11126
11127              Returns:
11128                  bool: Description of return value
11129
11130              """
11131              return True
11132
11133       NumPy style:
11134
11135          def func(arg1, arg2):
11136              """Summary line.
11137
11138              Extended description of function.
11139
11140              Parameters
11141              ----------
11142              arg1 : int
11143                  Description of arg1
11144              arg2 : str
11145                  Description of arg2
11146
11147              Returns
11148              -------
11149              bool
11150                  Description of return value
11151
11152              """
11153              return True
11154
11155       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
11160       The Khan Academy recommends using Google style.
11161
11162       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
11166       SEE ALSO:
11167          For complete examples:
11168
11169          · example_google
11170
11171          · example_numpy
11172
11173   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
11179       Google style with Python 3 type annotations:
11180
11181          def func(arg1: int, arg2: str) -> bool:
11182              """Summary line.
11183
11184              Extended description of function.
11185
11186              Args:
11187                  arg1: Description of arg1
11188                  arg2: Description of arg2
11189
11190              Returns:
11191                  Description of return value
11192
11193              """
11194              return True
11195
11196       Google style with types in docstrings:
11197
11198          def func(arg1, arg2):
11199              """Summary line.
11200
11201              Extended description of function.
11202
11203              Args:
11204                  arg1 (int): Description of arg1
11205                  arg2 (str): Description of arg2
11206
11207              Returns:
11208                  bool: Description of return value
11209
11210              """
11211              return True
11212
11213       NOTE:
11214          Python  2/3  compatible  annotations  aren’t  currently supported by
11215          Sphinx and won’t show up in the docs.
11216
11217   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
11222          # conf.py
11223
11224          # Add any Sphinx extension module names here, as strings
11225          extensions = ['sphinx.ext.napoleon']
11226
11227          # 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
11240       napoleon_google_docstring
11241              True to parse Google style docstrings. False to disable  support
11242              for Google style docstrings. Defaults to True.
11243
11244       napoleon_numpy_docstring
11245              True  to  parse NumPy style docstrings. False to disable support
11246              for NumPy style docstrings. Defaults to True.
11247
11248       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
11254              If True:
11255
11256                 def __init__(self):
11257                     \"\"\"
11258                     This will be included in the docs because it has a docstring
11259                     \"\"\"
11260
11261                 def __init__(self):
11262                     # This will NOT be included in the docs
11263
11264       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
11269              If True:
11270
11271                 def _included(self):
11272                     """
11273                     This will be included in the docs because it has a docstring
11274                     """
11275                     pass
11276
11277                 def _skipped(self):
11278                     # This will NOT be included in the docs
11279                     pass
11280
11281       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
11286              If True:
11287
11288                 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
11294                 def __unicode__(self):
11295                     # This will NOT be included in the docs
11296                     return unicode(self.__class__.__name__)
11297
11298       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
11304              This NumPy style snippet will be converted as follows:
11305
11306                 Example
11307                 -------
11308                 This is just a quick example
11309
11310              If True:
11311
11312                 .. admonition:: Example
11313
11314                    This is just a quick example
11315
11316              If False:
11317
11318                 .. rubric:: Example
11319
11320                 This is just a quick example
11321
11322       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
11327              NOTE:
11328                 The singular Note section will always be converted  to  a  ..
11329                 note:: directive.
11330
11331              SEE ALSO:
11332                 napoleon_use_admonition_for_examples
11333
11334       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
11339              SEE ALSO:
11340                 napoleon_use_admonition_for_examples
11341
11342       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
11346              This NumPy style snippet will be converted as follows:
11347
11348                 Attributes
11349                 ----------
11350                 attr1 : int
11351                     Description of `attr1`
11352
11353              If True:
11354
11355                 :ivar attr1: Description of `attr1`
11356                 :vartype attr1: int
11357
11358              If False:
11359
11360                 .. attribute:: attr1
11361
11362                    *int*
11363
11364                    Description of `attr1`
11365
11366       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
11371              This NumPy style snippet will be converted as follows:
11372
11373                 Parameters
11374                 ----------
11375                 arg1 : str
11376                     Description of `arg1`
11377                 arg2 : int, optional
11378                     Description of `arg2`, defaults to 0
11379
11380              If True:
11381
11382                 :param arg1: Description of `arg1`
11383                 :type arg1: str
11384                 :param arg2: Description of `arg2`, defaults to 0
11385                 :type arg2: int, optional
11386
11387              If False:
11388
11389                 :parameters: * **arg1** (*str*) --
11390                                Description of `arg1`
11391                              * **arg2** (*int, optional*) --
11392                                Description of `arg2`, defaults to 0
11393
11394       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
11399              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
11405              SEE ALSO:
11406                 napoleon_use_param
11407
11408       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
11413              This NumPy style snippet will be converted as follows:
11414
11415                 Returns
11416                 -------
11417                 bool
11418                     True if successful, False otherwise
11419
11420              If True:
11421
11422                 :returns: True if successful, False otherwise
11423                 :rtype: bool
11424
11425              If False:
11426
11427                 :returns: *bool* -- True if successful, False otherwise
11428
11429   sphinx.ext.todo – Support for todo items
11430       Module author: Daniel Bültmann
11431
11432       New in version 0.5.
11433
11434
11435       There are two additional directives when using this extension:
11436
11437       .. todo::
11438              Use this directive like, for example, note.
11439
11440              It will only show up in  the  output  if  todo_include_todos  is
11441              True.
11442
11443              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
11447
11448       .. 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
11452       There is also an additional config value:
11453
11454       todo_include_todos
11455              If this is True, todo and todolist  produce  output,  else  they
11456              produce nothing.  The default is False.
11457
11458       todo_emit_warnings
11459              If  this  is  True,  todo emits a warning for each TODO entries.
11460              The default is False.
11461
11462              New in version 1.5.
11463
11464
11465       todo_link_only
11466              If this is True, todolist produce output without file  path  and
11467              line, The default is False.
11468
11469              New in version 1.4.
11470
11471
11472       autodoc provides the following an additional event:
11473
11474       todo-defined(app, node)
11475              New in version 1.5.
11476
11477
11478              Emitted   when   a   todo   is  defined.  node  is  the  defined
11479              sphinx.ext.todo.todo_node node.
11480
11481   sphinx.ext.viewcode – Add links to highlighted source code
11482       Module author: Georg Brandl
11483
11484       New in version 1.0.
11485
11486
11487       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
11495       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
11499       There is an additional config value:
11500
11501       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
11507              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
11512                 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
11516              New in version 1.3.
11517
11518
11519       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
11524              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
11528              The default is False.
11529
11530              New in version 1.5.
11531
11532
11533              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
11538                 Some  reader’s rendering result are corrupted and epubcheck’s
11539                 score becomes worse even if the reader supports.
11540
11541   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
11546       There are also several extensions hosted elsewhere.  The Sphinx  exten‐
11547       sion survey contains a comprehensive list.
11548
11549       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
11553   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
11559          import sys, os
11560
11561          sys.path.append(os.path.abspath('exts'))
11562
11563          extensions = ['foo']
11564
11565       You can also install extensions anywhere else on sys.path, e.g. in  the
11566       site-packages directory.
11567

DEVELOPING EXTENSIONS FOR SPHINX

11569       Since  many projects will need special features in their documentation,
11570       Sphinx is designed to be extensible on several levels.
11571
11572       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
11579       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
11584       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
11588   Discovery of builders by entry point
11589       New in version 1.6.
11590
11591
11592       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
11595       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
11602          setup(
11603              # ...
11604              entry_points={
11605                  'sphinx.builders': [
11606                      'mybuilder = my.extension.module',
11607                  ],
11608              }
11609          )
11610
11611       Note  that  it  is  still  necessary  to  register  the  builder  using
11612       add_builder() in the extension’s setup() function.
11613
11614   Extension metadata
11615       New in version 1.3.
11616
11617
11618       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
11622       · '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
11627       · '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
11632       · '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
11637   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
11643       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
11648   Important objects
11649       There  are  several key objects whose API you will use while writing an
11650       extension.  These are:
11651
11652       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
11658              If you have the environment object, the application is available
11659              as env.app.
11660
11661       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
11667              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
11671              If  you  have the application or builder object, the environment
11672              is available as app.env or builder.env.
11673
11674       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
11680              If  you have the application object, the builder is available as
11681              app.builder.
11682
11683       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
11687              The config is available as app.config or env.config.
11688
11689   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
11694       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
11700       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
11709          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
11713          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
11718          The parsed doctrees are stored on the disk, because it is not possi‐
11719          ble to hold all of them in memory.
11720
11721       Phase 2: Consistency checks
11722          Some checking is done to ensure no surprises in the built documents.
11723
11724       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
11731       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
11737       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
11742   Extension Design
11743       We want the extension to add the following to Sphinx:
11744
11745       · 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
11749       · A “todolist” directive that  creates  a  list  of  all  todo  entries
11750         throughout the documentation.
11751
11752       For that, we will need to add the following elements to Sphinx:
11753
11754       · New directives, called todo and todolist.
11755
11756       · 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
11761       · 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
11765       · 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
11769   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
11773          def setup(app):
11774              app.add_config_value('todo_include_todos', False, 'html')
11775
11776              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
11782              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
11787              return {'version': '0.1'}   # identifies the version of our extension
11788
11789       The calls in this function refer to classes and functions not yet writ‐
11790       ten.  What the individual calls do is the following:
11791
11792       · 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
11796         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
11800       · 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
11806         We need to create the two node classes todo and todolist later.
11807
11808       · add_directive() adds a new directive, given by name and class.
11809
11810         The handler functions are created later.
11811
11812       · 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
11816   The Node Classes
11817       Let’s start with the node classes:
11818
11819          from docutils import nodes
11820
11821          class todo(nodes.Admonition, nodes.Element):
11822              pass
11823
11824          class todolist(nodes.General, nodes.Element):
11825              pass
11826
11827          def visit_todo_node(self, node):
11828              self.visit_admonition(node)
11829
11830          def depart_todo_node(self, node):
11831              self.depart_admonition(node)
11832
11833       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
11838       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
11842   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
11849       The todolist directive is quite simple:
11850
11851          from docutils.parsers.rst import Directive
11852
11853          class TodolistDirective(Directive):
11854
11855              def run(self):
11856                  return [todolist('')]
11857
11858       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
11862       The todo directive function looks like this:
11863
11864          from sphinx.locale import _
11865
11866          class TodoDirective(Directive):
11867
11868              # this enables content in the directive
11869              has_content = True
11870
11871              def run(self):
11872                  env = self.state.document.settings.env
11873
11874                  targetid = "todo-%d" % env.new_serialno('todo')
11875                  targetnode = nodes.target('', '', ids=[targetid])
11876
11877                  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
11881                  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
11890                  return [targetnode, todo_node]
11891
11892       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
11896       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
11903       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
11908       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
11917       In  the  last  line,  the nodes that should be put into the doctree are
11918       returned: the target node and the admonition node.
11919
11920       The node structure that the directive returns looks like this:
11921
11922          +--------------------+
11923          | target node        |
11924          +--------------------+
11925          +--------------------+
11926          | todo node          |
11927          +--------------------+
11928            \__+--------------------+
11929               | admonition title   |
11930               +--------------------+
11931               | paragraph          |
11932               +--------------------+
11933               | ...                |
11934               +--------------------+
11935
11936   The Event Handlers
11937       Finally, let’s look at the event handlers.   First,  the  one  for  the
11938       env-purge-doc event:
11939
11940          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
11946       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
11954       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
11957          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
11962              # 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
11966              for node in doctree.traverse(todolist):
11967                  if not app.config.todo_include_todos:
11968                      node.replace_self([])
11969                      continue
11970
11971                  content = []
11972
11973                  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
11981                      # 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
11992                      # Insert into the todolist
11993                      content.append(todo_info['todo'])
11994                      content.append(para)
11995
11996                  node.replace_self(content)
11997
11998       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
12002       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
12012   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
12017       class sphinx.application.Sphinx
12018              This application object has the public API described in the fol‐
12019              lowing.
12020
12021   Extension setup
12022       These methods are usually called in an extension’s setup() function.
12023
12024       Examples  of  using  the  Sphinx  extension  API  can  be  seen  in the
12025       sphinx.ext package.
12026
12027       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
12031       Sphinx.add_builder(builder)
12032              Register  a  new builder.  builder must be a class that inherits
12033              from Builder.
12034
12035       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
12042              · '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
12046              · 'html' if a change in the setting needs a full rebuild of HTML
12047                documents.
12048
12049              · ''  if  a  change  in  the  setting  will not need any special
12050                rebuild.
12051
12052              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
12057
12058              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
12062
12063       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
12067              New in version 1.0.
12068
12069
12070       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
12075              New in version 1.0.
12076
12077
12078       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
12082              New in version 1.0.
12083
12084
12085       Sphinx.add_event(name)
12086              Register  an  event  called  name.  This is needed to be able to
12087              emit it.
12088
12089       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
12095              New in version 1.3.
12096
12097
12098       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
12103              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
12110                 class math(docutils.nodes.Element): pass
12111
12112                 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
12117                 app.add_node(math, html=(visit_math_html, depart_math_html))
12118
12119              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
12123              Changed in version 0.5: Added the support for keyword  arguments
12124              giving visit functions.
12125
12126
12127       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
12132              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
12138              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
12145              Other keyword arguments are used for node visitor functions. See
12146              the Sphinx.add_node() for details.
12147
12148              New in version 1.4.
12149
12150
12151       Sphinx.add_directive(name, func, content, arguments, **options)
12152
12153       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
12158              · 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
12164              · 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
12170                The   directive  class  must  inherit  from  the  class  docu‐
12171                tils.parsers.rst.Directive.
12172
12173              For example, the  (already  existing)  literalinclude  directive
12174              would be added like this:
12175
12176                 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
12183              Changed in version 0.6: Docutils 0.5-style directive classes are
12184              now supported.
12185
12186
12187       Sphinx.add_directive_to_domain(domain, name, func, content,  arguments,
12188       **options)
12189
12190       Sphinx.add_directive_to_domain(domain, name, directiveclass)
12191              Like  add_directive(),  but the directive is added to the domain
12192              named domain.
12193
12194              New in version 1.0.
12195
12196
12197       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
12202       Sphinx.add_role_to_domain(domain, name, role)
12203              Like add_role(), but the role  is  added  to  the  domain  named
12204              domain.
12205
12206              New in version 1.0.
12207
12208
12209       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
12213              New in version 0.6.
12214
12215
12216       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
12221              · 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
12227              · Create a new role  (called  rolename)  to  cross-reference  to
12228                these object descriptions.
12229
12230              · 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
12237              · 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
12241              For example, if you have this call in a custom Sphinx extension:
12242
12243                 app.add_object_type('directive', 'dir', 'pair: %s; directive')
12244
12245              you can use this markup in your documents:
12246
12247                 .. rst:directive:: function
12248
12249                    Document a function.
12250
12251                 <...>
12252
12253                 See also the :rst:dir:`function` directive.
12254
12255              For the directive, an index entry will be generated  as  if  you
12256              had prepended
12257
12258                 .. index:: pair: function; directive
12259
12260              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
12270              For  the  role content, you have the same syntactical possibili‐
12271              ties as for standard Sphinx roles (see xref-syntax).
12272
12273              This  method  is  also  available  under  the  deprecated  alias
12274              add_description_unit.
12275
12276       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
12282              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
12286                 app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
12287
12288              Example usage:
12289
12290                 .. topic:: application API
12291
12292                 The application API
12293                 -------------------
12294
12295                 <...>
12296
12297                 See also :topic:`this section <application API>`.
12298
12299              (Of course, the element following the topic directive needn’t be
12300              a section.)
12301
12302       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
12307       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
12312       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
12319              New in version 0.5.
12320
12321
12322       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
12328              New in version 1.0.
12329
12330
12331              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
12336
12337       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
12342                 app.add_latex_package('mypackage')             # => \usepackage{mypackage}
12343                 app.add_latex_package('mypackage', 'foo,bar')  # => \usepackage[foo,bar]{mypackage}
12344
12345              New in version 1.3.
12346
12347
12348       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
12352              New in version 0.6.
12353
12354
12355       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
12362              New in version 0.6.
12363
12364
12365       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
12372              New in version 0.6.
12373
12374
12375       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
12382              New in version 1.1.
12383
12384
12385       Sphinx.add_source_parser(suffix, parser)
12386              Register a parser class for specified suffix.
12387
12388              New in version 1.4.
12389
12390
12391       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
12395              New in version 1.6.
12396
12397
12398       Sphinx.add_env_collector(collector)
12399              Register an environment collector class (refs: collector-api)
12400
12401              New in version 1.6.
12402
12403
12404       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
12409              New in version 1.0.
12410
12411
12412       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
12417              The  method returns a “listener ID” that can be used as an argu‐
12418              ment to disconnect().
12419
12420       Sphinx.disconnect(listener_id)
12421              Unregister callback listener_id.
12422
12423       exception sphinx.application.ExtensionError
12424              All these methods raise this exception if something  went  wrong
12425              with the extension API.
12426
12427   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
12433       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
12437              New in version 0.5.
12438
12439
12440   Producing messages / logging
12441       The application object also provides support for emitting leveled  mes‐
12442       sages.
12443
12444       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
12449       Deprecated since version 1.6: Please use logging-api instead.
12450
12451
12452       Sphinx.warn(message, location=None, type=None, subtype=None)
12453              Emit a warning.
12454
12455              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
12459              type  and  subtype  are  used  to  suppress  warnings  with sup‐
12460              press_warnings.
12461
12462       Sphinx.info(message='', nonl=False)
12463              Emit an informational message.
12464
12465              If nonl is true, don’t emit a newline at the end (which  implies
12466              that more info output will follow soon.)
12467
12468       Sphinx.verbose(message, *args, **kwargs)
12469              Emit a verbose informational message.
12470
12471       Sphinx.debug(message, *args, **kwargs)
12472              Emit a debug-level informational message.
12473
12474       Sphinx.debug2(message, *args, **kwargs)
12475              Emit a lowlevel debug-level informational message.
12476
12477   Sphinx runtime information
12478       The application object also provides runtime information as attributes.
12479
12480       sphinx.application.srcdir
12481              Source directory.
12482
12483       sphinx.application.confdir
12484              Directory containing conf.py.
12485
12486       sphinx.application.doctreedir
12487              Directory for storing pickled doctrees.
12488
12489       sphinx.application.outdir
12490              Directory for storing built document.
12491
12492   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
12498          def source_read_handler(app, docname, source):
12499              print('do something here...')
12500
12501          def setup(app):
12502              app.connect('source-read', source_read_handler)
12503
12504       builder-inited(app)
12505              Emitted when the builder object has been created.  It is  avail‐
12506              able as app.builder.
12507
12508       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
12514              New in version 1.1.
12515
12516
12517       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
12523              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
12528              New in version 0.5.
12529
12530
12531       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
12539              You  can  also remove document names; do this with caution since
12540              it will make Sphinx treat changed files as unchanged.
12541
12542              New in version 1.3.
12543
12544
12545       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
12551              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
12555              New in version 0.5.
12556
12557
12558       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
12563       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
12570              Parameters
12571
12572                     · env – The build environment (app.builder.env).
12573
12574                     · 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
12579                     · 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
12583              New in version 0.5.
12584
12585
12586       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
12591              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
12595       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
12600              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
12605              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
12609              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
12615              New in version 1.3.
12616
12617
12618       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
12623              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
12627              New in version 0.5.
12628
12629
12630              Changed in version 1.3: The handlers’ return value is now used.
12631
12632
12633       env-check-consistency(env)
12634              Emmited  when  Consistency  checks phase.  You can check consis‐
12635              tency of metadata for whole of documents.
12636
12637              New in version 1.6: As a experimental event
12638
12639
12640       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
12645              New in version 1.0.
12646
12647
12648       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
12653              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
12659              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
12663              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
12667              You can return a string from the handler, it will  then  replace
12668              'page.html' as the HTML template for this page.
12669
12670              New in version 0.4.
12671
12672
12673              Changed  in version 1.3: The return value can now specify a tem‐
12674              plate name.
12675
12676
12677       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
12686              New in version 0.5.
12687
12688
12689   Checking the Sphinx version
12690       Use this to adapt your extension to API changes in Sphinx.
12691
12692       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
12696              New  in  version  1.2:  Before  version  1.2,  check  the string
12697              sphinx.__version__.
12698
12699
12700   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
12705              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
12709   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
12715              init(builder, theme=None, dirs=None)
12716                     Called by the builder to initialize the template system.
12717
12718                     builder  is  the  builder object; you’ll probably want to
12719                     look at the value of builder.config.templates_path.
12720
12721                     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
12725              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
12731              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
12735              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
12739   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
12745              Extensions  are  encouraged  to  derive  from this exception for
12746              their custom errors.
12747
12748              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
12752              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
12757       exception sphinx.errors.ConfigError
12758              Used for erroneous values or nonsensical combinations of config‐
12759              uration values.
12760
12761       exception sphinx.errors.ExtensionError
12762              Used for errors in setting up extensions.
12763
12764       exception sphinx.errors.ThemeError
12765              Used for errors to do with themes.
12766
12767       exception sphinx.errors.VersionRequirementError
12768              Raised  when  the  docs require a higher Sphinx version than the
12769              current one.
12770
12771   Build environment API
12772       class sphinx.environment.BuildEnvironment
12773              Attributes
12774
12775              app    Reference to the Sphinx (application) object.
12776
12777              config Reference to the Config object.
12778
12779              srcdir Source directory.
12780
12781              doctreedir
12782                     Directory for storing pickled doctrees.
12783
12784              found_docs
12785                     A set of all existing docnames.
12786
12787              metadata
12788                     Dictionary mapping docnames to “metadata” (see metadata).
12789
12790              titles Dictionary mapping docnames  to  the  docutils  node  for
12791                     their main title.
12792
12793              docname
12794                     Returns  the  docname  of  the  document  currently being
12795                     parsed.
12796
12797              Utility methods
12798
12799              warn(docname, msg, lineno=None, **kwargs)
12800                     Emit a warning.
12801
12802                     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
12806              warn_node(msg, node, **kwargs)
12807                     Like warn(), but with source information taken from node.
12808
12809              doc2path(docname, base=True, suffix=None)
12810                     Return the filename for the document name.
12811
12812                     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
12818              relfn2path(filename, docname=None)
12819                     Return paths to a file referenced from a document,  rela‐
12820                     tive to documentation root and absolute.
12821
12822                     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
12826              note_dependency(filename)
12827                     Add filename as a dependency of the current document.
12828
12829                     This means that the document will be rebuilt if this file
12830                     changes.
12831
12832                     filename should be absolute or  relative  to  the  source
12833                     directory.
12834
12835              new_serialno(category='')
12836                     Return a serial number, e.g. for index entry targets.
12837
12838                     The number is guaranteed to be unique in the current doc‐
12839                     ument.
12840
12841              note_reread()
12842                     Add the current document to the list  of  documents  that
12843                     will automatically be re-read at the next build.
12844
12845   Builder API
12846   Todo
12847       Expand this.
12848
12849       class sphinx.builders.Builder
12850              This is the base class for all builders.
12851
12852              These attributes should be set on builder classes:
12853
12854              name = ''
12855                     The builder’s name, for the -b command line option.
12856
12857              format = ''
12858                     The  builder’s output format, or ‘’ if no document output
12859                     is produced.
12860
12861              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
12866              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
12871              These methods are predefined and will be called from the  appli‐
12872              cation:
12873
12874              get_relative_uri(from_, to, typ=None)
12875                     Return a relative URI between two source filenames.
12876
12877                     May raise environment.NoUri if there’s no way to return a
12878                     sensible URI.
12879
12880              build_all()
12881                     Build all source files.
12882
12883              build_specific(filenames)
12884                     Only rebuild as much as needed for changes in  the  file‐
12885                     names.
12886
12887              build_update()
12888                     Only rebuild what was changed or added since last build.
12889
12890              build(docnames, summary=None, method='update')
12891                     Main build method.
12892
12893                     First updates the environment, and then calls write().
12894
12895              These methods can be overridden in concrete builder classes:
12896
12897              init() Load necessary templates and perform initialization.  The
12898                     default implementation does nothing.
12899
12900              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
12904                     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
12909              get_target_uri(docname, typ=None)
12910                     Return the target URI for a document name.
12911
12912                     typ can be used to qualify the  link  characteristic  for
12913                     individual builders.
12914
12915              prepare_writing(docnames)
12916                     A place where you can add logic before write_doc() is run
12917
12918              write_doc(docname, doctree)
12919                     Where you actually write something to the filesystem.
12920
12921              finish()
12922                     Finish the building process.
12923
12924                     The default implementation does nothing.
12925
12926   Environment Collector API
12927       class sphinx.environment.collectors.EnvironmentCollector
12928              An  EnvironmentCollector  is a specific data collector from each
12929              document.
12930
12931              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
12935              clear_doc(app, env, docname)
12936                     Remove specified data of a document.
12937
12938                     This method is called on the removal of the document.
12939
12940              get_outdated_docs(app, env, added, changed, removed)
12941                     Return a list of docnames to re-read.
12942
12943                     This methods is called before reading the documents.
12944
12945              get_updated_docs(app, env)
12946                     Return a list of docnames to re-read.
12947
12948                     This methods is called after reading the whole  of  docu‐
12949                     ments (experimental).
12950
12951              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
12956              process_doc(app, doctree)
12957                     Process a document and gather specific data from it.
12958
12959                     This method is called after the document is read.
12960
12961   Docutils markup API
12962       This  section  describes the API for adding ReST markup elements (roles
12963       and directives).
12964
12965   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
12971       class docutils.parsers.rst.Directive
12972              The markup syntax of the new directive is determined by the fol‐
12973              low five class attributes:
12974
12975              required_arguments = 0
12976                     Number of required directive arguments.
12977
12978              optional_arguments = 0
12979                     Number  of  optional  arguments  after the required argu‐
12980                     ments.
12981
12982              final_argument_whitespace = False
12983                     May the final argument contain whitespace?
12984
12985              option_spec = None
12986                     Mapping of option names to validator functions.
12987
12988                     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
12993                     There  are several predefined and possibly useful valida‐
12994                     tors in the docutils.parsers.rst.directives module.
12995
12996              has_content = False
12997                     May the directive have content?
12998
12999              New directives must implement the run() method:
13000
13001              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
13006              Instance attributes that are always set on the directive are:
13007
13008              name   The  directive  name  (useful  when  registering the same
13009                     directive class under multiple names).
13010
13011              arguments
13012                     The arguments given to the directive, as a list.
13013
13014              options
13015                     The options given to the directive, as a dictionary  map‐
13016                     ping option names to validated/converted values.
13017
13018              content
13019                     The directive content, if given, as a ViewList.
13020
13021              lineno The absolute line number on which the directive appeared.
13022                     This is not always a useful value; use srcline instead.
13023
13024              content_offset
13025                     Internal offset of  the  directive  content.   Used  when
13026                     calling nested_parse (see below).
13027
13028              block_text
13029                     The string containing the entire directive.
13030
13031              state
13032
13033              state_machine
13034                     The  state  and state machine which controls the parsing.
13035                     Used for nested_parse.
13036
13037   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
13043       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
13047       · The  constructor  takes a list of strings (lines) and a source (docu‐
13048         ment) name.
13049
13050       · The .append() method takes a line and a source name as well.
13051
13052   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
13056       · self.state.nested_parse
13057
13058       · sphinx.util.nodes.nested_parse_with_titles()  – this allows titles in
13059         the parsed content.
13060
13061       Both APIs parse the content into a given node. They are used like this:
13062
13063          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
13069       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
13074              from sphinx.util.docutils import switch_source_input
13075
13076              # 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
13083          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
13087
13088       If you don’t need the wrapping node, you can use any concrete node type
13089       and return node.children from the Directive.
13090
13091       SEE ALSO:
13092
13093          Creating directives
13094                 HOWTO of the Docutils documentation
13095
13096   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
13104              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
13111              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
13121              add_object_type(name, objtype)
13122                     Add an object type.
13123
13124              check_consistency()
13125                     Do consistency checks (experimental).
13126
13127              clear_doc(docname)
13128                     Remove traces of a document in the domain-specific inven‐
13129                     tories.
13130
13131              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
13136              get_full_qualified_name(node)
13137                     Return full qualified name for given node.
13138
13139              get_objects()
13140                     Return  an  iterable  of “object descriptions”, which are
13141                     tuples with five items:
13142
13143                     · name     – fully qualified name
13144
13145                     · dispname – name to display when searching/linking
13146
13147                     · type     – object type, a key in self.object_types
13148
13149                     · docname  – the document where it is to be found
13150
13151                     · anchor   – the anchor name for the object
13152
13153                     · priority – how “important” the  object  is  (determines
13154                       placement in search results)
13155
13156                       · 1: default priority (placed before full-text matches)
13157
13158                       · 0:  object is important (placed before default-prior‐
13159                         ity objects)
13160
13161                       · 2: object  is  unimportant  (placed  after  full-text
13162                         matches)
13163
13164                       · -1: object should not show up in search at all
13165
13166              get_type_name(type, primary=False)
13167                     Return full name for given ObjType.
13168
13169              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
13174              process_doc(env, docname, document)
13175                     Process a document after it is read by the environment.
13176
13177              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
13181              resolve_any_xref(env, fromdocname, builder, target, node, contn‐
13182              ode)
13183                     Resolve the pending_xref node with the given target.
13184
13185                     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
13189                     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
13195                     New in version 1.3.
13196
13197
13198              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
13203                     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
13207                     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
13212                     The method can  also  raise  sphinx.environment.NoUri  to
13213                     suppress the ‘missing-reference’ event being emitted.
13214
13215              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
13220              dangling_warnings = {}
13221                     role name -> a warning message if reference is missing
13222
13223              data = None
13224                     data value
13225
13226              data_version = 0
13227                     data  version,  bump  this  when  the format of self.data
13228                     changes
13229
13230              directives = {}
13231                     directive name -> directive class
13232
13233              indices = []
13234                     a list of Index subclasses
13235
13236              initial_data = {}
13237                     data value for a fresh environment
13238
13239              label = ''
13240                     domain label: longer, more descriptive (used in messages)
13241
13242              name = ''
13243                     domain name: should be short, but unique
13244
13245              object_types = {}
13246                     type (usually directive) name -> ObjType instance
13247
13248              roles = {}
13249                     role name -> role callable
13250
13251       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
13257              Constructor arguments:
13258
13259              · lname: localized name of the type (do not include domain name)
13260
13261              · roles: all the roles that can refer to an object of this type
13262
13263              · 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
13267       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
13272              · name is an identifier used for generating file names.
13273
13274              · localname is the section title for the index.
13275
13276              · 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
13280              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
13284              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
13289                     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
13294                     content is a sequence of (letter, entries) tuples,  where
13295                     letter  is  the  “heading” for the given entries, usually
13296                     the starting letter.
13297
13298                     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
13303                     · name – the name of the index entry to be displayed
13304
13305                     · subtype  – sub-entry related type: 0 – normal entry 1 –
13306                       entry with sub-entries 2 – sub-entry
13307
13308                     · docname – docname where the entry is located
13309
13310                     · anchor – anchor for the entry within docname
13311
13312                     · extra – extra info for the entry
13313
13314                     · qualifier – qualifier for the description
13315
13316                     · descr – description for the entry
13317
13318                     Qualifier and description are not rendered e.g. in  LaTeX
13319                     output.
13320
13321   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
13328              The subclasses can access following objects and functions:
13329
13330              self.app
13331                     The application object (sphinx.application.Sphinx)
13332
13333              self.config
13334                     The config object (sphinx.config.Config)
13335
13336              self.env
13337                     The environment object  (sphinx.environment.BuildEnviron‐
13338                     ment)
13339
13340              self.warn()
13341                     Emit     a     warning.    (Same    as    sphinx.applica‐
13342                     tion.Sphinx.warn())
13343
13344              self.info()
13345                     Emit a informational message.  (Same  as  sphinx.applica‐
13346                     tion.Sphinx.info())
13347
13348   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
13353              This node is similar to a “definition list” with one definition.
13354              It contains one or more desc_signature and a desc_content.
13355
13356       class sphinx.addnodes.desc_signature(rawsource='', text='',  *children,
13357       **attributes)
13358              Node for object signatures.
13359
13360              The “term” part of the custom Sphinx definition list.
13361
13362              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
13366       class sphinx.addnodes.desc_signature_line(rawsource='', text='', *chil‐
13367       dren, **attributes)
13368              Node for a line in a multi-line object signatures.
13369
13370              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
13374       class  sphinx.addnodes.desc_addname(rawsource='',  text='',  *children,
13375       **attributes)
13376              Node for additional name parts (module name, class name).
13377
13378       class   sphinx.addnodes.desc_type(rawsource='',   text='',   *children,
13379       **attributes)
13380              Node for return types or object type names.
13381
13382       class  sphinx.addnodes.desc_returns(rawsource='',  text='',  *children,
13383       **attributes)
13384              Node for a “returns” annotation (a la -> in Python).
13385
13386       class   sphinx.addnodes.desc_name(rawsource='',   text='',   *children,
13387       **attributes)
13388              Node for the main object name.
13389
13390       class sphinx.addnodes.desc_parameterlist(rawsource='', text='',  *chil‐
13391       dren, **attributes)
13392              Node for a general parameter list.
13393
13394       class  sphinx.addnodes.desc_parameter(rawsource='', text='', *children,
13395       **attributes)
13396              Node for a single parameter.
13397
13398       class sphinx.addnodes.desc_optional(rawsource='',  text='',  *children,
13399       **attributes)
13400              Node for marking optional parts of the parameter list.
13401
13402       class sphinx.addnodes.desc_annotation(rawsource='', text='', *children,
13403       **attributes)
13404              Node for signature annotations (not Python 3-style annotations).
13405
13406       class       sphinx.addnodes.desc_content(rawsource='',       *children,
13407       **attributes)
13408              Node for object description content.
13409
13410              This  is  the  “definition” part of the custom Sphinx definition
13411              list.
13412
13413   New admonition-like constructs
13414       class sphinx.addnodes.versionmodified(rawsource='', text='', *children,
13415       **attributes)
13416              Node for version change entries.
13417
13418              Currently  used for “versionadded”, “versionchanged” and “depre‐
13419              cated” directives.
13420
13421       class sphinx.addnodes.seealso(rawsource='', *children, **attributes)
13422              Custom “see also” admonition.
13423
13424   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
13429   New inline nodes
13430       class     sphinx.addnodes.index(rawsource='',    text='',    *children,
13431       **attributes)
13432              Node for index entries.
13433
13434              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
13438              entrytype is one of “single”, “pair”, “double”, “triple”.
13439
13440              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
13444       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
13449              These nodes are resolved before writing output, in BuildEnviron‐
13450              ment.resolve_references.
13451
13452       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
13457       class  sphinx.addnodes.abbreviation(rawsource='',  text='',  *children,
13458       **attributes)
13459              Node for abbreviations with explanations.
13460
13461       class sphinx.addnodes.download_reference(rawsource='', text='',  *chil‐
13462       dren, **attributes)
13463              Node for download references, similar to pending_xref.
13464
13465   Special nodes
13466       class sphinx.addnodes.only(rawsource='', *children, **attributes)
13467              Node  for  “only”  directives  (conditional  inclusion  based on
13468              tags).
13469
13470       class sphinx.addnodes.meta(rawsource='', *children, **attributes)
13471              Node for meta directive – same as docutils’ standard meta  node,
13472              but pickleable.
13473
13474       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
13479       You should not need to generate the nodes below in extensions.
13480
13481       class sphinx.addnodes.glossary(rawsource='', *children, **attributes)
13482              Node to insert a glossary.
13483
13484       class sphinx.addnodes.toctree(rawsource='', *children, **attributes)
13485              Node for inserting a “TOC tree”.
13486
13487       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
13492       class      sphinx.addnodes.productionlist(rawsource='',      *children,
13493       **attributes)
13494              Node for grammar production lists.
13495
13496              Contains production nodes.
13497
13498       class  sphinx.addnodes.production(rawsource='',   text='',   *children,
13499       **attributes)
13500              Node for a single grammar production rule.
13501
13502   Logging API
13503       sphinx.util.logging.getLogger(name)
13504              Returns  a logger wrapped by SphinxLoggerAdapter with the speci‐
13505              fied name.
13506
13507              Example usage:
13508
13509                 from sphinx.util import logging  # Load on top of python's logging module
13510
13511                 logger = logging.getLogger(__name__)
13512                 logger.info('Hello, this is an extension!')
13513
13514       class SphinxLoggerAdapter(logging.LoggerAdapter)
13515
13516              error(level, msg, *args, **kwargs)
13517
13518              critical(level, msg, *args, **kwargs)
13519
13520              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
13525                     In addition, Sphinx  logger  supports  following  keyword
13526                     arguments:
13527
13528                     type, *subtype*
13529                            Categories  of  warning  logs.  It is used to sup‐
13530                            press warnings by suppress_warnings setting.
13531
13532                     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
13538                               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
13543                     color  The color of logs.  By default, warning level logs
13544                            are colored as "darkred".  The others are not col‐
13545                            ored.
13546
13547              log(level, msg, *args, **kwargs)
13548
13549              info(level, msg, *args, **kwargs)
13550
13551              verbose(level, msg, *args, **kwargs)
13552
13553              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
13558                     In  addition,  Sphinx  logger  supports following keyword
13559                     arguments:
13560
13561                     nonl   If true, the logger does not fold lines at the end
13562                            of the log message.  The default is False.
13563
13564                     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
13568       pending_logging()
13569              Marks all logs as pending:
13570
13571                 with pending_logging():
13572                   logger.warning('Warning message!')  # not flushed yet
13573                   some_long_process()
13574
13575                 # the warning is flushed here
13576
13577       pending_warnings()
13578              Marks warning logs as pending.  Similar to pending_logging().
13579
13580   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
13587       The following is a list of deprecated interface.
13588
13589   deprecated APIs
13590┌──────────────────────────────┬────────────┬──────────────────┬───────────────────────────────┐
13591│Target                        │ Deprecated │ (will        be) │ Alternatives                  │
13592│                              │            │ Removed          │                               │
13593├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13594sphinx.build_main()           │ 1.7        │ 2.0              │ sphinx.cmd.build.build_main() 
13595├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13596sphinx.ext.inter‐             │ 1.7        │ 2.0              │ sphinx.ext.inter‐             
13597sphinx.debug()                │            │                  │ sphinx.inspect_main()         
13598├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13599sphinx.ext.autodoc.for‐       │ 1.7        │ 2.0              │ sphinx.util.inspect.Signature 
13600mat_annotation()              │            │                  │                               │
13601├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13602sphinx.ext.autodoc.for‐       │ 1.7        │ 2.0              │ sphinx.util.inspect.Signature 
13603matargspec()                  │            │                  │                               │
13604├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13605sphinx.ext.autodoc.AutodocRe‐ │ 1.7        │ 2.0              │ sphinx.util.docu‐             
13606porter                        │            │                  │ tils.switch_source_input()    
13607├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13608sphinx.ext.autodoc.add_docu‐  │ 1.7        │ 2.0              │ add_autodocumenter()          
13609menter()                      │            │                  │                               │
13610├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13611sphinx.ext.autodoc.AutoDirec‐ │ 1.7        │ 2.0              │ add_autodocumenter()          
13612tive._register                │            │                  │                               │
13613├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13614AutoDirective._special_attr‐  │ 1.7        │ 2.0              │ add_autodoc_attrgetter()      
13615getters                       │            │                  │                               │
13616├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13617Sphinx.warn(), Sphinx.info()  │ 1.6        │ 2.0              │ logging-api                   │
13618├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13619BuildEnvironment.set_warn‐    │ 1.6        │ 2.0              │ logging-api                   │
13620func()                        │            │                  │                               │
13621├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13622BuildEnvironment.note_toc‐    │ 1.6        │ 2.0              │ Toctree.note()            (in │
13623tree()                        │            │                  │ sphinx.environ‐               
13624│                              │            │                  │ ment.adapters.toctree)        │
13625├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13626BuildEnviron‐                 │ 1.6        │ 2.0              │ Toctree.get_toc_for()     (in │
13627ment.get_toc_for()            │            │                  │ sphinx.environ‐               
13628│                              │            │                  │ ment.adapters.toctree)        │
13629├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13630BuildEnvironment.get_toc‐     │ 1.6        │ 2.0              │ Toctree.get_toctree_for() (in │
13631tree_for()                    │            │                  │ sphinx.environ‐               
13632│                              │            │                  │ ment.adapters.toctree)        │
13633├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13634BuildEnvironment.cre‐         │ 1.6        │ 2.0              │ IndexEntries.create_index()   
13635ate_index()                   │            │                  │ (in           sphinx.environ‐ 
13636│                              │            │                  │ ment.adapters.indexentries)   │
13637├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13638sphinx.websupport             │ 1.6        │ 2.0              │ sphinxcontrib-websupport
13639├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13640StandaloneHTML‐               │ 1.6        │ 2.0              │ add_stylesheet()              
13641Builder.css_files             │            │                  │                               │
13642├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13643Sphinx.status_iterator()      │ 1.6        │ 1.7              │ sphinx.util.status_iterator() 
13644├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13645Sphinx.old_status_iterator()  │ 1.6        │ 1.7              │ sphinx.util.old_status_itera‐ 
13646│                              │            │                  │ tor()                         
13647└──────────────────────────────┴────────────┴──────────────────┴───────────────────────────────┘
13648
13649
13650
13651Sphinx._directive_helper()    │ 1.6        │ 1.7              │ sphinx.util.docutils.direc‐   
13652│                              │            │                  │ tive_helper()                 
13653├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13654sphinx.util.compat.Directive  │ 1.6        │ 1.7              │ docutils.parsers.rst.Direc‐   
13655│                              │            │                  │ tive                          
13656├──────────────────────────────┼────────────┼──────────────────┼───────────────────────────────┤
13657sphinx.util.compat.docu‐      │ 1.6        │ 1.7              │ sphinx.util.docutils.__ver‐   
13658tils_version                  │            │                  │ sion_info__                   
13659└──────────────────────────────┴────────────┴──────────────────┴───────────────────────────────┘
13660
13661       NOTE:
13662          On deprecating on public APIs (internal functions and  classes),  we
13663          also follow the policy as much as possible.
13664

SPHINX WEB SUPPORT

13666       New in version 1.1.
13667
13668
13669       Sphinx  provides  a Python API to easily integrate Sphinx documentation
13670       into your web application.  To learn  more  read  the  websupportquick‐
13671       start.
13672
13673   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
13682          from sphinxcontrib.websupport import WebSupport
13683
13684          support = WebSupport(srcdir='/path/to/rst/sources/',
13685                               builddir='/path/to/build/outdir',
13686                               search='xapian')
13687
13688          support.build()
13689
13690       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
13697       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
13702   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
13706          from sphinxcontrib.websupport import WebSupport
13707
13708          support = WebSupport(datadir='/path/to/the/data',
13709                               search='xapian')
13710
13711       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
13715          contents = support.get_document('contents')
13716
13717       This will return a dictionary containing the following items:
13718
13719       · body: The main body of the document as HTML
13720
13721       · sidebar: The sidebar of the document as HTML
13722
13723       · relbar: A div containing links to related documents
13724
13725       · title: The title of the document
13726
13727       · css: Links to CSS files used by Sphinx
13728
13729       · script: JavaScript containing comment options
13730
13731       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
13735          {%- extends "layout.html" %}
13736
13737          {%- block title %}
13738              {{ document.title }}
13739          {%- endblock %}
13740
13741          {% block css %}
13742              {{ super() }}
13743              {{ document.css|safe }}
13744              <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
13745          {% endblock %}
13746
13747          {%- block script %}
13748              {{ super() }}
13749              {{ document.script|safe }}
13750          {%- endblock %}
13751
13752          {%- block relbar %}
13753              {{ document.relbar|safe }}
13754          {%- endblock %}
13755
13756          {%- block body %}
13757              {{ document.body|safe }}
13758          {%- endblock %}
13759
13760          {%- block sidebar %}
13761              {{ document.sidebar|safe }}
13762          {%- endblock %}
13763
13764   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
13774          support.update_username(old_username, new_username)
13775
13776       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
13780       An  example  Flask function that checks whether a user is logged in and
13781       then retrieves a document is:
13782
13783          from sphinxcontrib.websupport.errors import *
13784
13785          @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
13795       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
13802       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
13808              support = WebSupport(..., docroot='docs')
13809
13810              @app.route('/docs/<path:docname>')
13811
13812   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
13819          @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
13825       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
13829   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
13835          @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
13847       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
13853          @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
13861       The  final  function  that is needed will call process_vote(), and will
13862       handle user votes on comments:
13863
13864          @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
13875   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
13880          comment = support.add_comment(text, node_id='node_id',
13881                                        parent_id='parent_id',
13882                                        username=username, proposal=proposal,
13883                                        displayed=False)
13884
13885       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
13889          @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
13896       Rejecting comments happens via comment deletion.
13897
13898       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
13902          def moderation_callback(comment):
13903              """Do something..."""
13904
13905          support = WebSupport(..., moderation_callback=moderation_callback)
13906
13907       The moderation callback must take one argument, which will be the  same
13908       comment dict that is returned by add_comment().
13909
13910   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
13916              The class takes the following keyword arguments:
13917
13918              srcdir The directory containing reStructuredText source files.
13919
13920              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
13925              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
13930              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
13934              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
13940              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
13945              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
13950              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
13955       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
13959
13960   Methods
13961       WebSupport.build()
13962              Build the documentation. Places the data into the outdir  direc‐
13963              tory. Use it like this:
13964
13965                 support = WebSupport(srcdir, builddir, search='xapian')
13966                 support.build()
13967
13968              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
13972       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
13976                 support = WebSupport(datadir=datadir)
13977                 support.get_document('index', username, moderator)
13978
13979              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
13983                 @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
13994              The document dict that is returned contains the following  items
13995              to be used during template rendering.
13996
13997              · body: The main body of the document as HTML
13998
13999              · sidebar: The sidebar of the document as HTML
14000
14001              · relbar: A div containing links to related documents
14002
14003              · title: The title of the document
14004
14005              · css: Links to css files used by Sphinx
14006
14007              · script: Javascript containing comment options
14008
14009              This raises DocumentNotFoundError if a document matching docname
14010              is not found.
14011
14012              Parameters
14013                     docname – the name of the document to load.
14014
14015       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
14024                        ┌──────────────┬────────────────────────────┐
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
14080              Parameters
14081
14082                     · node_id – the id of the node to get comments for.
14083
14084                     · username – the username of the user  viewing  the  com‐
14085                       ments.
14086
14087                     · moderator – whether the user is a moderator.
14088
14089       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
14096                 comment = support.add_comment(text, node_id=node_id)
14097
14098              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
14101                 comment = support.add_comment(text, parent_id=parent_id)
14102
14103              If you would like to store a username with the comment, pass  in
14104              the optional username keyword argument:
14105
14106                 comment = support.add_comment(text, node=node_id,
14107                                               username=username)
14108
14109              Parameters
14110
14111                     · parent_id – the prefixed id of the comment’s parent.
14112
14113                     · text – the text of the comment.
14114
14115                     · displayed – for moderation purposes
14116
14117                     · username – the username of the user making the comment.
14118
14119                     · time  –  the  time the comment was created, defaults to
14120                       now.
14121
14122       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
14130                 @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
14141              Parameters
14142
14143                     · comment_id – the comment being voted on
14144
14145                     · username – the unique username of the user voting
14146
14147                     · value  –  1  for an upvote, -1 for a downvote, 0 for an
14148                       unvote.
14149
14150       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
14155                 document = support.get_search_results(q)
14156
14157              Parameters
14158                     q – the search query
14159
14160   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
14166          support = WebSupport(srcdir=srcdir,
14167                               builddir=builddir,
14168                               search=MySearch())
14169
14170       For more information about creating a custom search adapter, please see
14171       the documentation of the BaseSearch class below.
14172
14173       class sphinxcontrib.websupport.search.BaseSearch
14174              Defines an interface for search adapters.
14175
14176       Changed in version 1.6: BaseSearch class is moved to sphinxcontrib.web‐
14177       support.search from sphinx.websupport.search.
14178
14179
14180   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
14186       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
14191              Parameters
14192                     changed – a list of pagenames that will be re-indexed
14193
14194       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
14199       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
14205              Parameters
14206
14207                     · pagename – the name of the page to be indexed
14208
14209                     · filename – the name of the original source file
14210
14211                     · title – the title of the page to be indexed
14212
14213                     · doctree – is the docutils doctree representation of the
14214                       page
14215
14216       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
14221              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
14228              Parameters
14229
14230                     · pagename – the name of the page being indexed
14231
14232                     · filename – the name of the original source file
14233
14234                     · title – the page’s title
14235
14236                     · text – the full text of the page
14237
14238       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
14245              Parameters
14246                     q – the search query string.
14247
14248       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
14253                 (<path>, <title>, <context>)
14254
14255              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
14259              The extract_context() method is provided as a simple way to cre‐
14260              ate the context.
14261
14262              Parameters
14263                     q – the search query
14264
14265       BaseSearch.extract_context(text, length=240)
14266              Extract the context for the search  query  from  the  document’s
14267              full text.
14268
14269              Parameters
14270
14271                     · text – the full text of the document to create the con‐
14272                       text for
14273
14274                     · length – the length of the context snippet to return.
14275
14276   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
14282          support = WebSupport(srcdir=srcdir,
14283                               builddir=builddir,
14284                               storage=MyStorage())
14285
14286       For  more  information  about creating a custom storage backend, please
14287       see the documentation of the StorageBackend class below.
14288
14289       class sphinxcontrib.websupport.storage.StorageBackend
14290              Defines an interface for storage backends.
14291
14292       Changed in version 1.6: StorageBackend class  is  moved  to  sphinxcon‐
14293       trib.websupport.storage from sphinx.websupport.storage.
14294
14295
14296   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
14301       StorageBackend.add_node(id, document, source)
14302              Add a node to the StorageBackend.
14303
14304              Parameters
14305
14306                     · id – a unique id for the comment.
14307
14308                     · document – the name of the document  the  node  belongs
14309                       to.
14310
14311                     · source – the source files name.
14312
14313       StorageBackend.post_build()
14314              Called  after  a  build  has completed. Use this to finalize the
14315              addition of nodes if needed.
14316
14317       StorageBackend.add_comment(text, displayed, username,  time,  proposal,
14318       node_id, parent_id, moderator)
14319              Called when a comment is being added.
14320
14321              Parameters
14322
14323                     · text – the text of the comment
14324
14325                     · displayed – whether the comment should be displayed
14326
14327                     · username – the name of the user adding the comment
14328
14329                     · time  –  a  date  object  with the time the comment was
14330                       added
14331
14332                     · proposal – the text of the proposal the user made
14333
14334                     · node_id – the id of the node that the comment is  being
14335                       added to
14336
14337                     · parent_id – the id of the comment’s parent comment.
14338
14339                     · moderator  –  whether  the user adding the comment is a
14340                       moderator
14341
14342       StorageBackend.delete_comment(comment_id, username, moderator)
14343              Delete a comment.
14344
14345              Raises UserNotAuthorizedError if moderator is False and username
14346              doesn’t match the username on the comment.
14347
14348              Parameters
14349
14350                     · comment_id – The id of the comment being deleted.
14351
14352                     · username  –  The  username  of  the user requesting the
14353                       deletion.
14354
14355                     · moderator – Whether the user is a moderator.
14356
14357       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
14362              Parameters
14363
14364                     · node_id – The id of the node to get data for.
14365
14366                     · username – The name of the user requesting the data.
14367
14368                     · moderator – Whether the requestor is a moderator.
14369
14370       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
14374              Parameters
14375
14376                     · comment_id – The id of the comment being voted on.
14377
14378                     · username – The username of the user casting the vote.
14379
14380                     · value – The value of the vote being cast.
14381
14382       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
14387              Parameters
14388
14389                     · old_username – The username being changed.
14390
14391                     · new_username – What the username is being changed to.
14392
14393       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
14397              Parameters
14398                     comment_id – The id of the comment being accepted.
14399

SPHINX FAQ

14401       This is a list of Frequently Asked Questions about Sphinx.   Feel  free
14402       to suggest new entries!
14403
14404   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
14411       … 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
14416       … customize the look of the built HTML files?
14417              Use themes, see theming.
14418
14419       … add global substitutions or includes?
14420              Add them in the rst_epilog config value.
14421
14422       … 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
14426       … write my own extension?
14427              See the extension tutorial.
14428
14429       … 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
14434       … create HTML slides from Sphinx documents?
14435              See          the         “Hieroglyph”         package         at
14436              https://github.com/nyergler/hieroglyph.
14437
14438       For  many  more  extensions  and  other  contributed  stuff,  see   the
14439       sphinx-contrib repository.
14440
14441   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
14449       Epydoc There’s  a  third-party  extension  providing  an api role which
14450              refers to Epydoc’s API docs for a given identifier.
14451
14452       Doxygen
14453              Michael Jones is developing  a  reST/Sphinx  bridge  to  doxygen
14454              called breathe.
14455
14456       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
14460       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
14464       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
14469       MediaWiki
14470              See   https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home,   a
14471              project by Kevin Dunn.
14472
14473       Google Analytics
14474              You can use a custom layout.html template, like this:
14475
14476                 {% extends "!layout.html" %}
14477
14478                 {%- 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
14487                 {% 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
14504   Epub info
14505       The following list gives some hints for the creation of epub files:
14506
14507       · 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
14511       · Try to minimize the markup.  This also pays in rendering time.
14512
14513       · 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
14522         You may have to experiment a little until you get reasonable results.
14523
14524       · 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
14530       · 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
14535       · 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
14540       · 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
14546       · 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
14550            $ make epub
14551            $ kindlegen _build/epub/yourdoc.epub
14552
14553         The  kindlegen  command  doesn’t  accept  documents that have section
14554         titles surrounding toctree directive:
14555
14556            Section Title
14557            =============
14558
14559            .. toctree::
14560
14561               subdocument
14562
14563            Section After Toc Tree
14564            ======================
14565
14566         kindlegen assumes all documents order in line, but the resulting doc‐
14567         ument has complicated order for kindlegen:
14568
14569            ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
14570
14571         If you get the following error, fix your document structure:
14572
14573            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
14576   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
14583   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
14588          * note Displaying Links: target-id
14589
14590       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
14595       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
14603       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
14608          (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
14625   Notes
14626       The following notes may be helpful if you want to create Texinfo files:
14627
14628       · Each section corresponds to a different node in the Info file.
14629
14630       · Colons (:) cannot be properly escaped  in  menu  entries  and  xrefs.
14631         They will be replaced with semicolons (;).
14632
14633       · Links  to external Info files can be created using the somewhat offi‐
14634         cial URI scheme info.  For example:
14635
14636            info:Texinfo#makeinfo_options
14637
14638       · Inline markup
14639
14640         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
14646         The standard formatting can be re-enabled by adding the following  to
14647         your conf.py:
14648
14649            texinfo_elements = {'preamble': """
14650            @definfoenclose strong,*,*
14651            @definfoenclose emph,_,_
14652            """}
14653

GLOSSARY

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
14662              See builders for an overview over Sphinx’s built-in builders.
14663
14664       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
14669       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
14675                 .. directivename:: argument ...
14676                    :option: value
14677
14678                    Content of the directive.
14679
14680              See directives for more information.
14681
14682       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
14692              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
14696       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
14701              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
14707       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
14713       master document
14714              The document that contains the root toctree directive.
14715
14716       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
14720       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
14725       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
14730       source directory
14731              The directory which, including its subdirectories, contains  all
14732              source files for one Sphinx project.
14733

SPHINX DEVELOPER’S GUIDE

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
14741       · Bug Reports and Feature Requests
14742
14743       · Contributing to Sphinx
14744
14745         · Getting Started
14746
14747         · Core Developers
14748
14749         · Locale updates
14750
14751       · Coding Guide
14752
14753         · Debugging Tips
14754
14755       · Branch Model
14756
14757       · Deprecating a feature
14758
14759       · Deprecation policy
14760
14761       · Unit Testing
14762
14763       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
14767       sphinx-users <sphinx-users@googlegroups.com>
14768              Mailing list for user support.
14769
14770       sphinx-dev <sphinx-dev@googlegroups.com>
14771              Mailing list for development related discussions.
14772
14773       #sphinx-doc on irc.freenode.net
14774              IRC channel for development questions and user support.
14775
14776   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
14781       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
14786       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
14790   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
14797       1. Check  for  open  issues or open a fresh issue to start a discussion
14798          around a feature idea or a bug.
14799
14800       2. If you feel uncomfortable  or  uncertain  about  an  issue  or  your
14801          changes, feel free to email the sphinx-dev mailing list.
14802
14803       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
14807       4. Write  a test which shows that the bug was fixed or that the feature
14808          works as expected.
14809
14810       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
14814   Getting Started
14815       These are the basic steps needed to start developing on Sphinx.
14816
14817       1.  Create an account on GitHub.
14818
14819       2.  Fork the  main  Sphinx  repository  (sphinx-doc/sphinx)  using  the
14820           GitHub interface.
14821
14822       3.  Clone the forked repository to your machine.
14823
14824              git clone https://github.com/USERNAME/sphinx
14825              cd sphinx
14826
14827       4.  Checkout the appropriate branch.
14828
14829           For  changes  that  should  be  included  in the next minor release
14830           (namely bug fixes), use the X.Y branch.
14831
14832              git checkout X.Y
14833
14834           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
14838       5.  Setup a virtual environment.
14839
14840           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
14844              virtualenv ~/.venv
14845              . ~/.venv/bin/activate
14846              pip install -e .
14847
14848       6.  Create a new working branch.  Choose any name you like.
14849
14850              git checkout -b feature-xyz
14851
14852       7.  Hack, hack, hack.
14853
14854           For tips on working with the code, see the Coding Guide.
14855
14856       8.  Test, test, test.
14857
14858           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
14862           · To list all possible targets:
14863
14864                  tox -av
14865
14866           · To run unit tests for a specific Python version, such as 3.6:
14867
14868                  tox -e py36
14869
14870           · 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
14873                  PYTHONWARNINGS=all tox -e py36
14874
14875           · To run code style and type checks:
14876
14877                  tox -e mypy
14878                  tox -e flake8
14879
14880           · Arguments to pytest can be passed via tox, e.g. in order to run a
14881             particular test:
14882
14883                  tox -e py36 tests/test_module.py::test_new_feature
14884
14885           · To build the documentation:
14886
14887                  tox -e docs
14888
14889           · To build the documentation in multiple formats:
14890
14891                  tox -e docs -- -b html,latexpdf
14892
14893           You can also test by installing dependencies in your local environ‐
14894           ment.
14895
14896              pip install .[test]
14897
14898           New unit tests should be included in the tests directory where nec‐
14899           essary:
14900
14901           · For bug fixes, first add a test that fails without  your  changes
14902             and passes after they are applied.
14903
14904           · 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
14909       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
14912              git commit -m '#42: Add useful new feature that does this.'
14913
14914           GitHub recognizes certain phrases that can be used to automatically
14915           update the issue tracker.
14916
14917           For example:
14918
14919              git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
14920
14921           would close issue #42.
14922
14923       10. Push changes in the branch to your forked repository on GitHub.
14924
14925              git push origin feature-xyz
14926
14927       11. Submit a pull request from your branch  to  the  respective  branch
14928           (master or X.Y).
14929
14930       12. Wait for a core developer to review your changes.
14931
14932   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
14937       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
14942       The following are some general guidelines for core developers:
14943
14944       · 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
14949       · 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
14953       · When  committing  code  written by someone else, please attribute the
14954         original author in the commit message and any relevant CHANGES entry.
14955
14956   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
14961       Sphinx uses Babel to extract messages and maintain the  catalog  files.
14962       It is integrated in setup.py:
14963
14964       · Use python setup.py extract_messages to update the .pot template.
14965
14966       · 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
14970       · Use  python  setup.py  compile_catalog  to  compile  the .po files to
14971         binary .mo files and .js files.
14972
14973       When an updated .po file is submitted, run  compile_catalog  to  commit
14974       both the source and the compiled catalogs.
14975
14976       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
14980       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
14988   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
14992       · For non-trivial changes, please update the  CHANGES  file.   If  your
14993         changes alter existing behavior, please document this.
14994
14995       · 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
14999       · When  adding a new configuration variable, be sure to document it and
15000         update sphinx/quickstart.py if it’s important enough.
15001
15002       · Use the included utils/check_sources.py script to  check  for  common
15003         formatting issues (trailing whitespace, lengthy lines, etc).
15004
15005       · Add appropriate unit tests.
15006
15007   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
15012       · Use the sphinx-build -P option to run pdb on exceptions.
15013
15014       · Use  node.pformat()  and node.asdom().toxml() to generate a printable
15015         representation of the document structure.
15016
15017       · Set the configuration variable keep_warnings to True so warnings will
15018         be displayed in the generated output.
15019
15020       · Set  the  configuration variable nitpicky to True so that Sphinx will
15021         complain about references without a known target.
15022
15023       · Set the debugging options in the Docutils configuration file.
15024
15025       · 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
15030            $ npm install
15031            $ node_modules/.bin/grunt build # -> dest/*.global.js
15032
15033   Branch Model
15034       Sphinx project uses following branches for developing.
15035
15036       master Used for main development.  All improvement and refactoring, bug
15037              fixes are allowed.
15038
15039       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
15045   Deprecating a feature
15046       There are a couple reasons that code in Sphinx might be deprecated:
15047
15048       · If a feature has been improved or modified in a  backwards-incompati‐
15049         ble way, the old feature or behavior will be deprecated.
15050
15051       · 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
15057       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
15064          pytest -Wall
15065
15066       Thus, when adding a RemovedInSphinxXXWarning you need to  eliminate  or
15067       silence any warnings generated when running the tests.
15068
15069   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
15078       So,  for  example, if we decided to start the deprecation of a function
15079       in Sphinx 1.4:
15080
15081       · Sphinx 1.4.x will contain a backwards-compatible replica of the func‐
15082         tion which will raise a RemovedInSphinx16Warning.
15083
15084       · Sphinx  1.5  (the  version  that  follows 1.4) will still contain the
15085         backwards-compatible replica.
15086
15087       · Sphinx 1.6 will remove the feature outright.
15088
15089       The warnings are displayed by default. You  can  turn  off  display  of
15090       these warnings with:
15091
15092       · PYTHONWARNINGS= make html (Linux/Mac)
15093
15094       · export PYTHONWARNINGS= and do make html (Linux/Mac)
15095
15096       · set PYTHONWARNINGS= and do make html (Windows)
15097
15098   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
15105       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
15109          pytest_plugins = 'sphinx.testing.fixtures'
15110
15111       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
15114       NOTE:
15115          Prior to Sphinx - 1.5.2, Sphinx was running the test with nose.
15116
15117       New in version 1.6: sphinx.testing as a experimental.
15118
15119

CHANGES IN SPHINX

15121   Release 1.7.6 (released Jul 17, 2018)
15122   Bugs fixed
15123       · #5037: LaTeX \sphinxupquote{} breaks in Russian
15124
15125       · sphinx.testing uses deprecated pytest API; Node.get_marker(name)
15126
15127       · #5016: crashed when recommonmark.AutoStrictify is enabled
15128
15129       · #5022: latex: crashed with docutils package provided by Debian/Ubuntu
15130
15131       · #5009: latex: a label for table is vanished if table does not have  a
15132         caption
15133
15134       · #5048: crashed with numbered toctree
15135
15136       · #2410: C, render empty argument lists for macros.
15137
15138       · C++,  fix  lookup  of  full template specializations with no template
15139         arguments.
15140
15141       · #4667: C++, fix assertion on missing references in global scope  when
15142         using intersphinx. Thanks to Alan M. Carroll.
15143
15144       · #5019: autodoc: crashed by Form Feed Character
15145
15146       · #5032: autodoc: loses the first staticmethod parameter for old styled
15147         classes
15148
15149       · #5036: quickstart: Typing Ctrl-U clears the whole of line
15150
15151       · #5066: html: “relations” sidebar is not shown by default
15152
15153       · #5091: latex: curly braces in index entries are not handled correctly
15154
15155       · #5070: epub: Wrong internal href fragment links
15156
15157       · #5104: apidoc: Interface of sphinx.apidoc:main() has changed
15158
15159       · #4272: PDF builds of French projects have issues with XeTeX
15160
15161       · #5076: napoleon raises RuntimeError with python 3.7
15162
15163       · #5125: sphinx-build: Interface of sphinx:main() has changed
15164
15165       · sphinx-build:  sphinx.cmd.build.main()  refers  sys.argv  instead  of
15166         given argument
15167
15168       · #5146:  autosummary:  warning  is emitted when the first line of doc‐
15169         string ends with literal notation
15170
15171       · autosummary: warnings of autosummary indicates wrong location  (refs:
15172         #5146)
15173
15174       · #5143: autodoc: crashed on inspecting dict like object which does not
15175         support sorting
15176
15177       · #5139: autodoc: Enum argument missing if it shares value with another
15178
15179       · #4946: py domain: rtype field could not handle “None” as a type
15180
15181       · #5176: LaTeX: indexing of terms containing @, !, or " fails
15182
15183       · #5161: html: crashes if copying static files are failed
15184
15185       · #5167: autodoc: Fix formatting type annotations for tuples with  more
15186         than two arguments
15187
15188       · #3329: i18n: crashed by auto-symbol footnote references
15189
15190       · #5158:  autosummary:  module  summary  has been broken when it starts
15191         with heading
15192
15193   Release 1.7.5 (released May 29, 2018)
15194   Bugs fixed
15195       · #4924: html search: Upper characters problem in any other languages
15196
15197       · #4932: apidoc: some subpackage is ignored if sibling subpackage  con‐
15198         tains a module starting with underscore
15199
15200       · #4863,  #4938,  #4939:  i18n  doesn’t handle node.title correctly tat
15201         used for contents, topic, admonition, table and section.
15202
15203       · #4913: i18n: literal blocks in bullet list are not translated
15204
15205       · #4962: C++, raised TypeError on duplicate declaration.
15206
15207       · #4825: C++, properly parse expr roles and give better error  messages
15208         when (escaped) line breaks are present.
15209
15210       · C++, properly use desc_addname nodes for prefixes of names.
15211
15212       · C++, parse pack expansions in function calls.
15213
15214       · #4915,  #4916:  links  on  search  page are broken when using dirhtml
15215         builder
15216
15217       · #4969: autodoc: constructor method should not have return annotation
15218
15219       · latex: deeply nested enumerated list which is  beginning  with  non-1
15220         causes LaTeX engine crashed
15221
15222       · #4978: latex: shorthandoff is not set up for Brazil locale
15223
15224       · #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/
15225
15226       · #4946: py domain: type field could not handle “None” as a type
15227
15228       · #4979: latex: Incorrect escaping of curly braces in index entries
15229
15230       · #4956:  autodoc:  Failed  to  extract document from a subclass of the
15231         class on mocked module
15232
15233       · #4973: latex: glossary directive adds whitespace to each item
15234
15235       · #4980: latex: Explicit labels on code blocks are duplicated
15236
15237       · #4919: node.asdom() crashes if toctree has :numbered: option
15238
15239       · #4914: autodoc: Parsing error when using dataclasses without  default
15240         values
15241
15242       · #4931:  autodoc:  crashed when handler for autodoc-skip-member raises
15243         an error
15244
15245       · #4931: autodoc: crashed when subclass of mocked class  are  processed
15246         by napoleon module
15247
15248       · #5007: sphinx-build crashes when error log contains a “%” character
15249
15250   Release 1.7.4 (released Apr 25, 2018)
15251   Bugs fixed
15252       · #4885, #4887: domains: Crashed with duplicated objects
15253
15254       · #4889: latex: sphinx.writers.latex causes recusrive import
15255
15256   Release 1.7.3 (released Apr 23, 2018)
15257   Bugs fixed
15258       · #4769: autodoc loses the first staticmethod parameter
15259
15260       · #4790: autosummary: too wide two column tables in PDF builds
15261
15262       · #4795: Latex customization via _templates/longtable.tex_t is broken
15263
15264       · #4789: imgconverter: confused by convert.exe of Windows
15265
15266       · #4783:  On  windows,  Sphinx crashed when drives of srcdir and outdir
15267         are different
15268
15269       · #4812: autodoc ignores type annotated variables
15270
15271       · #4817: wrong URLs on warning messages
15272
15273       · #4784: latex: latex_show_urls assigns incorrect footnote  numbers  if
15274         hyperlinks exists inside substitutions
15275
15276       · #4837:  latex  with  class memoir Error: Font command \sf is not sup‐
15277         ported
15278
15279       · #4803: latex: too slow in proportion to number of auto numbered foot‐
15280         notes
15281
15282       · #4838: htmlhelp: The entries in .hhp file is not ordered
15283
15284       · toctree directive tries to glob for URL having query_string
15285
15286       · #4871: html search: Upper characters problem in German
15287
15288       · #4717:  latex:  Compilation  for German docs failed with LuaLaTeX and
15289         XeLaTeX
15290
15291       · #4459: duplicated labels detector does  not  work  well  in  parallel
15292         build
15293
15294       · #4878: Crashed with extension which returns invalid metadata
15295
15296   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
15301   Bugs fixed
15302       · #4669: sphinx.build_main and sphinx.make_main throw NameError
15303
15304       · #4685: autosummary emits meaningless warnings
15305
15306       · autodoc: crashed when invalid options given
15307
15308       · pydomain: always strip parenthesis if empty (refs: #1042)
15309
15310       · #4689: autosummary: unexpectedly strips docstrings containing “i.e.”
15311
15312       · #4701: viewcode: Misplaced <div> in viewcode html output
15313
15314       · #4444: Don’t require numfig to use :numref: on sections
15315
15316       · #4727: Option clash for package textcomp
15317
15318       · #4725: Sphinx does not work with python 3.5.0 and 3.5.1
15319
15320       · #4716: Generation PDF file with TexLive on Windows,  file  not  found
15321         error
15322
15323       · #4574: vertical space before equation in latex
15324
15325       · #4720: message when an image is mismatched for builder is not clear
15326
15327       · #4655, #4684: Incomplete localization strings in Polish and Chinese
15328
15329       · #2286: Sphinx crashes when error is happens in rendering HTML pages
15330
15331       · #4688: Error to download remote images having long URL
15332
15333       · #4754: sphinx/pycode/__init__.py raises AttributeError
15334
15335       · #1435: qthelp builder should htmlescape keywords
15336
15337       · epub: Fix docTitle elements of toc.ncx is not escaped
15338
15339       · #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
15340
15341       · #4767: html: search highlighting breaks mathjax equations
15342
15343   Release 1.7.1 (released Feb 23, 2018)
15344   Deprecated
15345       · #4623: sphinx.build_main() is deprecated.
15346
15347       · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
15348         has been changed (Since 1.7.0)
15349
15350       · #4664: sphinx.ext.intersphinx.debug() is deprecated.
15351
15352       For more details, see deprecation APIs list
15353
15354   Bugs fixed
15355       · #4608: epub: Invalid meta tag is generated
15356
15357       · #4260: autodoc: keyword only argument separator is not disappeared if
15358         it is appeared at top of the argument list
15359
15360       · #4622: epub: epub_scheme does not effect to content.opf
15361
15362       · #4627: graphviz: Fit graphviz images to page
15363
15364       · #4617: quickstart: PROJECT_DIR argument is required
15365
15366       · #4623: sphinx.build_main no longer exists in 1.7.0
15367
15368       · #4615: The argument of sphinx.build has been changed in 1.7.0
15369
15370       · autosummary: The interface of sphinx.ext.autosummary.get_documenter()
15371         has been changed
15372
15373       · #4630: Have order on msgids in sphinx.pot deterministic
15374
15375       · #4563: autosummary: Incorrect end of line punctuation detection
15376
15377       · #4577: Enumerated sublists with explicit start with wrong number
15378
15379       · #4641: A external link in TOC cannot contain “?” with :glob: option
15380
15381       · C++, add missing parsing of explicit casts and typeid  in  expression
15382         parsing.
15383
15384       · C++, add missing parsing of this in expression parsing.
15385
15386       · #4655: Fix incomplete localization strings in Polish
15387
15388       · #4653: Fix error reporting for parameterless ImportErrors
15389
15390       · #4664: Reading objects.inv fails again
15391
15392       · #4662:  any refs with term targets crash when an ambiguity is encoun‐
15393         tered
15394
15395   Release 1.7.0 (released Feb 12, 2018)
15396   Dependencies
15397       1.7.0b1
15398
15399       · Add packaging package
15400
15401   Incompatible changes
15402       1.7.0b1
15403
15404       · #3668: The arguments has changed of main functions for each command
15405
15406       · #3893: Unknown html_theme_options throw warnings instead of errors
15407
15408       · #3927: Python parameter/variable types should match classes, not  all
15409         objects
15410
15411       · #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
15415       · #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
15416
15417       · #4226: apidoc: Generate new style makefile (make-mode)
15418
15419       · #4274: sphinx-build returns 2 as an exit code on argument error
15420
15421       · #4389: output directory will be created after loading extensions
15422
15423       · autodoc does not generate warnings messages to the generated document
15424         even if keep_warnings is True.  They are only emitted to stderr.
15425
15426       · shebang line is removed from generated conf.py
15427
15428       · #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
15432       · #3620:  html  theme:  move   DOCUMENTATION_OPTIONS   to   independent
15433         JavaScript file (refs: #4295)
15434
15435       · #4246:  Limit  width  of  text body for all themes. Conifigurable via
15436         theme options body_min_width and body_max_width.
15437
15438       · #4771: apidoc: The exclude_patterns arguments are ignored if they are
15439         placed just after command line options
15440
15441       1.7.0b2
15442
15443       · #4467: html theme: Rename csss block to css
15444
15445   Deprecated
15446       1.7.0b1
15447
15448       · using  a  string  value for html_sidebars is deprecated and only list
15449         values will be accepted at 2.0.
15450
15451       · format_annotation() and formatargspec() is  deprecated.   Please  use
15452         sphinx.util.inspect.Signature instead.
15453
15454       · 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
15458       · sphinx.ext.autodoc.add_documenter()  and  AutoDirective._register  is
15459         now deprecated.  Please use app.add_autodocumenter() instead.
15460
15461       · AutoDirective._special_attrgetters is  now  deprecated.   Please  use
15462         app.add_autodoc_attrgetter() instead.
15463
15464   Features added
15465       1.7.0b1
15466
15467       · C++, handle decltype(auto).
15468
15469       · #2406:  C++,  add proper parsing of expressions, including linking of
15470         identifiers.
15471
15472       · C++, add a cpp:expr role for  inserting  inline  C++  expressions  or
15473         types.
15474
15475       · C++,  support  explicit member instantiations with shorthand template
15476         prefix.
15477
15478       · C++, make function parameters linkable, like template params.
15479
15480       · #3638: Allow to  change  a  label  of  reference  to  equation  using
15481         math_eqref_format
15482
15483       · Now suppress_warnings accepts following configurations:
15484
15485         · ref.python (ref: #3866)
15486
15487       · #3872:  Add latex key to configure literal blocks caption position in
15488         PDF output (refs #3792, #1723)
15489
15490       · In case of missing docstring try to retrieve doc  from  base  classes
15491         (ref: #3140)
15492
15493       · #4023: Clarify error message when any role has more than one target.
15494
15495       · #3973: epub: allow to override build date
15496
15497       · #3972: epub: Sort manifest entries by filename
15498
15499       · #4052: viewcode: Sort before highlighting module code
15500
15501       · #1448: qthelp: Add new config value; qthelp_namespace
15502
15503       · #4140: html themes: Make body tag inheritable
15504
15505       · #4168: improve zh search with jieba
15506
15507       · HTML themes can set up default sidebars through theme.conf
15508
15509       · #3160: html: Use <kdb> to represent :kbd: role
15510
15511       · #4212: autosummary: catch all exceptions when importing modules
15512
15513       · #4166:  Add  math_numfig  for  equation  numbering  by section (refs:
15514         #3991, #4080). Thanks to Oliver Jahn.
15515
15516       · #4311: Let LaTeX obey numfig_secnum_depth for  figures,  tables,  and
15517         code-blocks
15518
15519       · #947:  autodoc  now  supports  ignore-module-all to ignore a module’s
15520         __all__
15521
15522       · #4332: Let LaTeX obey math_numfig for equation numbering
15523
15524       · #4093:  sphinx-build  creates  empty  directories  for  unknown  tar‐
15525         gets/builders
15526
15527       · Add  top-classes option for the sphinx.ext.inheritance_diagram exten‐
15528         sion to limit the scope of inheritance graphs.
15529
15530       · #4183: doctest: :pyversion: option also follows PEP-440 specification
15531
15532       · #4235: html: Add manpages_url to make manpage roles to hyperlinks
15533
15534       · #3570: autodoc: Do not display ‘typing.’ module for type hints
15535
15536       · #4354: sphinx-build now emits finish message.  Builders can modify it
15537         through Builder.epilog attribute
15538
15539       · #4245: html themes: Add language to javascript vars list
15540
15541       · #4079:  html: Add notranslate class to each code-blocks, literals and
15542         maths to let Google Translate know they are not translatable
15543
15544       · #4137: doctest: doctest block is always highlighted as python console
15545         (pycon)
15546
15547       · #4137: doctest: testcode block is always highlighted as python
15548
15549       · #3998:  text:  Assign section numbers by default.  You can control it
15550         using text_add_secnumbers and text_secnumber_suffix
15551
15552       1.7.0b2
15553
15554       · #4271: sphinx-build supports an option called -j auto to adjust  num‐
15555         bers of processes automatically.
15556
15557   Features removed
15558       1.7.0b1
15559
15560       · Configuration variables
15561
15562         · html_use_smartypants
15563
15564         · latex_keep_old_macro_names
15565
15566         · latex_elements[‘footer’]
15567
15568       · utility methods of sphinx.application.Sphinx class
15569
15570         · buildername (property)
15571
15572         · _display_chunk()
15573
15574         · old_status_iterator()
15575
15576         · status_iterator()
15577
15578         · _directive_helper()
15579
15580       · utility methods of sphinx.environment.BuildEnvironment class
15581
15582         · currmodule (property)
15583
15584         · currclass (property)
15585
15586       · epub2 builder
15587
15588       · prefix and colorfunc parameter for warn()
15589
15590       · sphinx.util.compat module
15591
15592       · sphinx.util.nodes.process_only_nodes()
15593
15594       · LaTeX environment notice, use sphinxadmonition instead
15595
15596       · LaTeX \sphinxstylethead, use \sphinxstyletheadfamily
15597
15598       · C++, support of function concepts. Thanks to mickk-on-cpp.
15599
15600       · Not used and previously not documented LaTeX macros \shortversion and
15601         \setshortversion
15602
15603   Bugs fixed
15604       1.7.0b1
15605
15606       · #3882: Update the order of files for HTMLHelp and QTHelp
15607
15608       · #3962: sphinx-apidoc does not recognize implicit  namespace  packages
15609         correctly
15610
15611       · #4094: C++, allow empty template argument lists.
15612
15613       · C++,  also hyperlink types in the name of declarations with qualified
15614         names.
15615
15616       · C++, do not add index entries for declarations inside concepts.
15617
15618       · C++, support the template disambiguator for dependent names.
15619
15620       · #4314: For PDF ‘howto’ documents, numbering  of  code-blocks  differs
15621         from the one of figures and tables
15622
15623       · #4330:  PDF  ‘howto’  documents  have  an  incoherent  default  LaTeX
15624         tocdepth counter setting
15625
15626       · #4198: autosummary emits multiple ‘autodoc-process-docstring’  event.
15627         Thanks to Joel Nothman.
15628
15629       · #4081: Warnings and errors colored the same when building
15630
15631       · latex: Do not display ‘Release’ label if release is not set
15632
15633       1.7.0b2
15634
15635       · #4415: autodoc classifies inherited classmethods as regular methods
15636
15637       · #4415: autodoc classifies inherited staticmethods as regular methods
15638
15639       · #4472: DOCUMENTATION_OPTIONS is not defined
15640
15641       · #4491:   autodoc:   prefer  _MockImporter  over  other  importers  in
15642         sys.meta_path
15643
15644       · #4490: autodoc: type annotation is broken with python 3.7.0a4+
15645
15646       · utils package is no longer installed
15647
15648       · #3952: apidoc: module header is too escaped
15649
15650       · #4275: Formats accepted by sphinx.util.i18n.format_date are limited
15651
15652       · #4493: recommonmark raises AttributeError if AutoStructify enabled
15653
15654       · #4209: intersphinx: In link title, “v” should be optional  if  target
15655         has no version
15656
15657       · #4230: slowdown in writing pages with sphinx 1.6
15658
15659       · #4522: epub: document is not rebuilt even if config changed
15660
15661       1.7.0b3
15662
15663       · #4019: inheritance_diagram AttributeError stoping make process
15664
15665       · #4531: autosummary: methods are not treated as attributes
15666
15667       · #4538: autodoc: sphinx.ext.autodoc.Options has been moved
15668
15669       · #4539: autodoc emits warnings for partialmethods
15670
15671       · #4223: doctest: failing tests reported in wrong file, at wrong line
15672
15673       · i18n:  message  catalogs  are  not compiled if specific filenames are
15674         given for sphinx-build as arguments (refs: #4560)
15675
15676       · #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
15679       · #4581: apidoc: Excluded modules still included
15680
15681   Testing
15682       1.7.0b1
15683
15684       · Add support for docutils 0.14
15685
15686       · Add tests for the sphinx.ext.inheritance_diagram extension.
15687
15688   Release 1.6.7 (released Feb 04, 2018)
15689   Bugs fixed
15690       · #1922: html search: Upper characters problem in French
15691
15692       · #4412: Updated jQuery version from 3.1.0 to 3.2.1
15693
15694       · #4438: math: math with labels with whitespace cause html error
15695
15696       · #2437: make full reference for classes, aliased with “alias of”
15697
15698       · #4434: pure numbers as link targets produce warning
15699
15700       · #4477: Build fails after building specific files
15701
15702       · #4449: apidoc: include “empty” packages that contain modules
15703
15704       · #3917: citation labels are tranformed to ellipsis
15705
15706       · #4501: graphviz: epub3 validation error caused if graph is not click‐
15707         able
15708
15709       · #4514: graphviz: workaround for wrong map ID which graphviz generates
15710
15711       · #4525: autosectionlabel does not support parallel build
15712
15713       · #3953: Do not raise warning  when  there  is  a  working  intersphinx
15714         inventory
15715
15716       · #4487:  math:  ValueError  is  raised  on  parallel  build. Thanks to
15717         jschueller.
15718
15719       · #2372: autosummary: invalid signatures are shown for  type  annotated
15720         functions
15721
15722       · #3942: html: table is not aligned to center even if :align: center
15723
15724   Release 1.6.6 (released Jan 08, 2018)
15725   Features added
15726       · #4181: autodoc: Sort dictionary keys when possible
15727
15728       · VerbatimHighlightColor is a new LaTeX ‘sphinxsetup’ key (refs: #4285)
15729
15730       · Easier  customizability  of  LaTeX  macros  involved  in rendering of
15731         code-blocks
15732
15733       · Show traceback if conf.py raises an exception (refs: #4369)
15734
15735       · Add smartquotes to disable smart quotes through conf.py (refs: #3967)
15736
15737       · Add smartquotes_action and smartquotes_excludes (refs: #4142, #4357)
15738
15739   Bugs fixed
15740       · #4334: sphinx-apidoc: Don’t generate references to non-existing files
15741         in TOC
15742
15743       · #4206: latex: reST label between paragraphs loses paragraph break
15744
15745       · #4231: html: Apply fixFirefoxAnchorBug only under Firefox
15746
15747       · #4221:  napoleon  depends on autodoc, but users need to load it manu‐
15748         ally
15749
15750       · #2298: automodule fails to document a class attribute
15751
15752       · #4099: C++: properly link class reference to class from  inside  con‐
15753         structor
15754
15755       · #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
15756
15757       · #4249: PDF output: Pygments error highlighting increases line spacing
15758         in code blocks
15759
15760       · #1238: Support :emphasize-lines: in PDF output
15761
15762       · #4279: Sphinx crashes with pickling error when run with multiple pro‐
15763         cesses and remote image
15764
15765       · #1421: Respect the quiet flag in sphinx-quickstart
15766
15767       · #4281: Race conditions when creating output directory
15768
15769       · #4315:  For  PDF  ‘howto’ documents, latex_toplevel_sectioning='part'
15770         generates \chapter commands
15771
15772       · #4214: Two todolist directives break sphinx-1.6.5
15773
15774       · Fix links to external option docs with intersphinx (refs: #3769)
15775
15776       · #4091: Private members not documented without :undoc-members:
15777
15778   Release 1.6.5 (released Oct 23, 2017)
15779   Features added
15780       · #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
15781
15782       · #4112: Don’t override the smart_quotes setting if it was already set
15783
15784       · #4125: Display reference texts of original and translated passages on
15785         i18n warning message
15786
15787       · #4147: Include the exception when logging PO/MO file read/write
15788
15789   Bugs fixed
15790       · #4085:  Failed  PDF  build from image in parsed-literal using :align:
15791         option
15792
15793       · #4100: Remove debug print from autodoc extension
15794
15795       · #3987: Changing theme from alabaster causes HTML build to fail
15796
15797       · #4096: C++, don’t crash when using the wrong  role  type.  Thanks  to
15798         mitya57.
15799
15800       · #4070,  #4111:  crashes  when  the  warning  message  contains format
15801         strings (again)
15802
15803       · #4108: Search word highlighting breaks SVG images
15804
15805       · #3692: Unable to build HTML if writing .buildinfo failed
15806
15807       · #4152: HTML writer crashes if a field list is placed on  top  of  the
15808         document
15809
15810       · #4063: Sphinx crashes when labeling directive .. todolist::
15811
15812       · #4134: [doc] docutils.conf is not documented explicitly
15813
15814       · #4169: Chinese language doesn’t trigger Chinese search automatically
15815
15816       · #1020: ext.todo todolist not linking to the page in pdflatex
15817
15818       · #3965: New quickstart generates wrong SPHINXBUILD in Makefile
15819
15820       · #3739: :module: option is ignored at content of pyobjects
15821
15822       · #4149: Documentation: Help choosing latex_engine
15823
15824       · #4090:  [doc]  latex_additional_files  with extra LaTeX macros should
15825         not use .tex extension
15826
15827       · Failed to convert reST parser error to warning (refs: #4132)
15828
15829   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
15834   Bugs fixed
15835       · #3924: docname lost after dynamically parsing RST in extension
15836
15837       · #3946:  Typo  in sphinx.sty (this was a bug with no effect in default
15838         context)
15839
15840       ·
15841
15842         pep    and :rfc: does  not  supports  default-role  directive  (refs:
15843                #3960)
15844
15845       · #3960: default_role = ‘guilabel’ not functioning
15846
15847       · Missing texinputs_win/Makefile to be used in latexpdf builder on win‐
15848         dows.
15849
15850       · #4026: nature: Fix macOS Safari scrollbar color
15851
15852       · #3877: Fix for C++ multiline signatures.
15853
15854       · #4006: Fix crash on parallel build
15855
15856       · #3969: private instance attributes causes AttributeError
15857
15858       · #4041: C++, remove extra name linking in function pointers.
15859
15860       · #4038: C, add missing documentation of member role.
15861
15862       · #4044: An empty multicolumn cell causes extra row height in PDF  out‐
15863         put
15864
15865       · #4049: Fix typo in output of sphinx-build -h
15866
15867       · #4062: hashlib.sha1() must take bytes, not unicode on Python 3
15868
15869       · Avoid indent after index entries in latex (refs: #4066)
15870
15871       · #4070: crashes when the warning message contains format strings
15872
15873       · #4067: Return non-zero exit status when make subprocess fails
15874
15875       · #4055: graphviz: the :align: option does not work for SVG output
15876
15877       · #4055:  graphviz:  the  :align: center option does not work for latex
15878         output
15879
15880       · #4051: warn() function for HTML theme outputs ‘None’ string
15881
15882   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
15887   Bugs fixed
15888       · #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
15889
15890       · #3829:  sphinx-quickstart  template  is  incomplete  regarding use of
15891         alabaster
15892
15893       · #3772: ‘str object’ has no attribute ‘filename’
15894
15895       · Emit wrong warnings if citation label includes hyphens (refs: #3565)
15896
15897       · #3858: Some warnings are not colored when using –color option
15898
15899       · #3775: Remove unwanted whitespace in default template
15900
15901       · #3835: sphinx.ext.imgmath fails to  convert  SVG  images  if  project
15902         directory name contains spaces
15903
15904       · #3850: Fix color handling in make mode’s help command
15905
15906       · #3865: use of self.env.warn in sphinx extension fails
15907
15908       · #3824:  production  lists  apply  smart quotes transform since Sphinx
15909         1.6.1
15910
15911       · latex: fix \sphinxbfcode swallows initial space of argument
15912
15913       · #3878: Quotes in auto-documented class attributes should be  straight
15914         quotes in PDF output
15915
15916       · #3881:  LaTeX figure floated to next page sometimes leaves extra ver‐
15917         tical whitespace
15918
15919       · #3885: duplicated footnotes raises IndexError
15920
15921       · #3873: Failure of deprecation warning mechanism  of  sphinx.util.com‐
15922         pat.Directive
15923
15924       · #3874:  Bogus  warnings  for “citation not referenced” for cross-file
15925         citations
15926
15927       · #3860: Don’t download images when builders not supported images
15928
15929       · #3860: Remote image URIs without filename  break  builders  not  sup‐
15930         ported remote images
15931
15932       · #3833: command line messages are translated unintentionally with lan‐
15933         guage setting.
15934
15935       · #3840: make checking epub_uid strict
15936
15937       · #3851, #3706: Fix about box drawing characters for PDF output
15938
15939       · #3900: autosummary could not find methods
15940
15941       · #3902: Emit error if latex_documents contains non-unicode  string  in
15942         py2
15943
15944   Release 1.6.2 (released May 28, 2017)
15945   Incompatible changes
15946       · #3789: Do not require typing module for python>=3.5
15947
15948   Bugs fixed
15949       · #3754: HTML builder crashes if HTML theme appends own stylesheets
15950
15951       · #3756: epub: Entity ‘mdash’ not defined
15952
15953       · #3758: Sphinx crashed if logs are emitted in conf.py
15954
15955       · #3755: incorrectly warns about dedent with literalinclude
15956
15957       · #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
15962       · #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
15965       · #3774: Incremental HTML building broken when using citations
15966
15967       · #3763: got epubcheck validations error if epub_cover is set
15968
15969       · #3779:    ‘ImportError’   in   sphinx.ext.autodoc   due   to   broken
15970         ‘sys.meta_path’.  Thanks to Tatiana Tereshchenko.
15971
15972       · #3796: env.resolve_references() crashes when non-document node given
15973
15974       · #3803: Sphinx crashes with invalid PO files
15975
15976       · #3791: PDF “continued on next page” for long  tables  isn’t  interna‐
15977         tionalized
15978
15979       · #3788: smartquotes emits warnings for unsupported languages
15980
15981       · #3807: latex Makefile for make latexpdf is only for unixen
15982
15983       · #3781: double hyphens in option directive are compiled as endashes
15984
15985       · #3817: latex builder raises AttributeError
15986
15987   Release 1.6.1 (released May 16, 2017)
15988   Dependencies
15989       1.6b1
15990
15991       · (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
15995       · (added) latexmk is required for make latexpdf on GNU/Linux and Mac OS
15996         X (refs: #3082)
15997
15998   Incompatible changes
15999       1.6b1
16000
16001       · #1061, #2336, #3235: Now generation of  autosummary  doesn’t  contain
16002         imported members by default. Thanks to Luc Saffre.
16003
16004       · 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
16008       · The  subclasses  of  sphinx.domains.Index  should override generate()
16009         method.  The default implementation raises NotImplementedError
16010
16011       · 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
16016       · option  directive  also  allows  all punctuations for the option name
16017         (refs: #3366)
16018
16019       · #3413: if literalinclude’s :start-after: is used, make :lines:  rela‐
16020         tive (refs #3412)
16021
16022       · literalinclude  directive  does  not  allow the combination of :diff:
16023         option and other options (refs: #3416)
16024
16025       · 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
16029       · 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
16033       · Footer “Continued on next page” of LaTeX longtable’s now  not  framed
16034         (refs: #3497)
16035
16036       · #3529: The arguments of BuildEnvironment.__init__ is changed
16037
16038       · #3082:  Use  latexmk  for  pdf (and dvi) targets (Unix-like platforms
16039         only)
16040
16041       · #3558: Emit warnings if footnotes and citations are  not  referenced.
16042         The warnings can be suppressed by suppress_warnings.
16043
16044       · 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
16050       · Builder.env is not filled at instantiation
16051
16052       · #3594: LaTeX: single raw directive has been considered as block level
16053         element
16054
16055       · #3639: If html_experimental_html5_writer is available,  epub  builder
16056         use it by default.
16057
16058       · Sphinx.add_source_parser() raises an error if duplicated
16059
16060       1.6b2
16061
16062       · #3345:   Replace   the   custom   smartypants   code  with  Docutils’
16063         smart_quotes.  Thanks to Dmitry Shachnev,  and  to  Günter  Milde  at
16064         Docutils.
16065
16066       1.6b3
16067
16068       · LaTeX package eqparbox is not used and not loaded by Sphinx anymore
16069
16070       · LaTeX package multirow is not used and not loaded by Sphinx anymore
16071
16072       · Add line numbers to citation data in std domain
16073
16074       1.6 final
16075
16076       · LaTeX  package  threeparttable  is  not used and not loaded by Sphinx
16077         anymore (refs #3686, #3532, #3377)
16078
16079   Features removed
16080       · Configuration variables
16081
16082         · epub3_contributor
16083
16084         · epub3_description
16085
16086         · epub3_page_progression_direction
16087
16088         · html_translator_class
16089
16090         · html_use_modindex
16091
16092         · latex_font_size
16093
16094         · latex_paper_size
16095
16096         · latex_preamble
16097
16098         · latex_use_modindex
16099
16100         · latex_use_parts
16101
16102       · termsep node
16103
16104       · defindex.html template
16105
16106       · LDML format support in today, today_fmt and html_last_updated_fmt
16107
16108       · :inline: option for the directives of sphinx.ext.graphviz extension
16109
16110       · sphinx.ext.pngmath extension
16111
16112       · sphinx.util.compat.make_admonition()
16113
16114   Features added
16115       1.6b1
16116
16117       · #3136: Add :name: option to the directives in sphinx.ext.graphviz
16118
16119       · #2336: Add imported_members option to sphinx-autogen command to docu‐
16120         ment imported members.
16121
16122       · C++,  add  :tparam-line-spec: option to templated declarations.  When
16123         specified, each template parameter will be  rendered  on  a  separate
16124         line.
16125
16126       · #3359:  Allow  sphinx.js  in  a user locale dir to override sphinx.js
16127         from Sphinx
16128
16129       · #3303: Add :pyversion: option to the doctest directive.
16130
16131       · #3378: (latex) support for :widths: option of table directives (refs:
16132         #3379, #3381)
16133
16134       · #3402:  Allow to suppress “download file not readable” warnings using
16135         suppress_warnings.
16136
16137       · #3377: latex: Add support for Docutils 0.13 :align: option for tables
16138         (but does not implement text flow around table).
16139
16140       · latex: footnotes from inside tables are hyperlinked (except from cap‐
16141         tions or headers) (refs: #3422)
16142
16143       · Emit warning if over dedent has detected on literalinclude  directive
16144         (refs: #3416)
16145
16146       · Use  for LuaLaTeX same default settings as for XeLaTeX (i.e. fontspec
16147         and polyglossia). (refs: #3070, #3466)
16148
16149       · Make 'extraclassoptions' key of latex_elements public (refs #3480)
16150
16151       · #3463: Add warning messages for required EPUB3 metadata. Add  default
16152         value to epub_description to avoid warning like other settings.
16153
16154       · #3476: setuptools: Support multiple builders
16155
16156       · latex:  merged cells in LaTeX tables allow code-blocks, lists, block‐
16157         quotes… as do normal cells (refs: #3435)
16158
16159       · HTML  builder  uses  experimental  HTML5  writer  if  html_experimen‐
16160         tal_html5_writer is True and docutils 0.13 or later is installed.
16161
16162       · LaTeX macros to customize space before and after tables in PDF output
16163         (refs #3504)
16164
16165       · #3348: Show decorators in literalinclude and viewcode directives
16166
16167       · #3108: Show warning if :start-at: and  other  literalinclude  options
16168         does not match to the text
16169
16170       · #3609:  Allow  to  suppress  “duplicate citation” warnings using sup‐
16171         press_warnings
16172
16173       · #2803: Discovery of builders by entry point
16174
16175       · #1764,  #1676:  Allow  setting  ‘rel’  and  ‘title’  attributes   for
16176         stylesheets
16177
16178       · #3589: Support remote images on non-HTML builders
16179
16180       · #3589: Support images in Data URI on non-HTML builders
16181
16182       · #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
16186       · #3449: On py3, autodoc use inspect.signature for more accurate signa‐
16187         ture calculation. Thanks to Nathaniel J. Smith.
16188
16189       · #3641: Epub theme supports HTML  structures  that  are  generated  by
16190         HTML5 writer.
16191
16192       · #3644  autodoc  uses  inspect  instead  of  checking types. Thanks to
16193         Jeroen Demeyer.
16194
16195       · Add a new extension; sphinx.ext.imgconverter. It converts  images  in
16196         the document to appropriate format for builders
16197
16198       · latex: Use templates to render tables (refs #3389, 2a37b0e)
16199
16200       1.6b2
16201
16202       · LATEXMKOPTS  variable  for  the  Makefile  in $BUILDDIR/latex to pass
16203         options to latexmk when executing make latexpdf (refs #3695, #3720)
16204
16205       · Add a new event env-check-consistency to check consistency to  exten‐
16206         sions
16207
16208       · Add Domain.check_consistency() to check consistency
16209
16210   Bugs fixed
16211       1.6b1
16212
16213       · literalinclude directive expands tabs after dedent-ing (refs: #3416)
16214
16215       · #1574: Paragraphs in table cell doesn’t work in Latex output
16216
16217       · #3288: Table with merged headers not wrapping text
16218
16219       · #3491: Inconsistent vertical space around table and longtable in PDF
16220
16221       · #3506:  Depart functions for all admonitions in HTML writer now prop‐
16222         erly pass node to depart_admonition.
16223
16224       · #2693: Sphinx latex style file wrongly inhibits colours  for  section
16225         headings for latex+dvi(ps,pdf,pdfmx)
16226
16227       · C++, properly look up any references.
16228
16229       · #3624:  sphinx.ext.intersphinx  couldn’t  load inventories compressed
16230         with gzip
16231
16232       · #3551: PDF information dictionary is lacking author and title data
16233
16234       · #3351: intersphinx does not refers context like  py:module,  py:class
16235         and so on.
16236
16237       · Fail to load template file if the parent template is archived
16238
16239       1.6b2
16240
16241       · #3661: sphinx-build crashes on parallel build
16242
16243       · #3669: gettext builder fails with “ValueError: substring not found”
16244
16245       · #3660:  Sphinx  always  depends  on  sphinxcontrib-websupport and its
16246         dependencies
16247
16248       · #3472: smart quotes getting wrong in latex (at  least  with  list  of
16249         strings via autoattribute) (refs: #3345, #3666)
16250
16251       1.6b3
16252
16253       · #3588: No compact (p tag) html output in the i18n document build even
16254         when html_compact_lists is True.
16255
16256       · 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
16261       · #3683: sphinx.websupport module is not provided by default
16262
16263       · #3683:  Failed  to  build  document  if  builder.css_file.insert() is
16264         called
16265
16266       · #3714: viewcode extension not taking highlight_code='none' in account
16267
16268       · #3698: Moving :doc: to std domain broke backwards compatibility
16269
16270       · #3633: misdetect unreferenced citations
16271
16272       1.6 final
16273
16274       · LaTeX tables do not allow multiple paragraphs in a header cell
16275
16276       · LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
16277
16278       · #3532: Figure or literal block captions  in  cells  of  short  tables
16279         cause havoc in PDF output
16280
16281       · Fix: in PDF captions of tables are rendered differently whether table
16282         is of longtable class or not (refs #3686)
16283
16284       · #3725: Todo looks different from note in LaTeX output
16285
16286       · #3479: stub-columns have no effect in LaTeX output
16287
16288       · #3738: Nonsensical code in theming.py
16289
16290       · #3746: PDF builds fail with latexmk 4.48 or earlier due to  undefined
16291         options -pdfxe and -pdflua
16292
16293   Deprecated
16294       1.6b1
16295
16296       · sphinx.util.compat.Directive  class  is  now  deprecated.  Please use
16297         instead docutils.parsers.rst.Directive
16298
16299       · sphinx.util.compat.docutils_version is now deprecated
16300
16301       · #2367: Sphinx.warn(), Sphinx.info() and other logging methods are now
16302         deprecated.  Please use sphinx.util.logging (logging-api) instead.
16303
16304       · #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
16308       · Sphinx.status_iterator() and Sphinx.old_status_iterator() is now dep‐
16309         recated.  Please use sphinx.util:status_iterator() instead.
16310
16311       · Sphinx._directive_helper()     is     deprecated.     Please      use
16312         sphinx.util.docutils.directive_helper() instead.
16313
16314       · BuildEnvironment.set_warnfunc() is now deprecated
16315
16316       · Following methods of BuildEnvironment is now deprecated.
16317
16318         · BuildEnvironment.note_toctree()
16319
16320         · BuildEnvironment.get_toc_for()
16321
16322         · BuildEnvironment.get_toctree_for()
16323
16324         · BuildEnvironment.create_index()
16325
16326         Please use sphinx.environment.adapters modules instead.
16327
16328       · 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
16332       · #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
16336       · #3221: epub2 builder is deprecated
16337
16338       · #3254:  sphinx.websupport  is now separated into independent package;
16339         sphinxcontrib-websupport.   sphinx.websupport  will  be  removed   in
16340         Sphinx-2.0.
16341
16342       · #3628:   sphinx_themes   entry_point   is   deprecated.   Please  use
16343         sphinx.html_themes instead.
16344
16345       1.6b2
16346
16347       · #3662: builder.css_files is deprecated.  Please use  add_stylesheet()
16348         API instead.
16349
16350       1.6 final
16351
16352       · 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
16356   Testing
16357       1.6 final
16358
16359       · #3458: Add sphinx.testing (experimental)
16360
16361   Release 1.6 (unreleased)
16362       · not released (because of package script error)
16363
16364   Release 1.5.6 (released May 15, 2017)
16365   Bugs fixed
16366       · #3614: Sphinx crashes with requests-2.5.0
16367
16368       · #3618: autodoc crashes with tupled arguments
16369
16370       · #3664: No space after the bullet in items of a latex list produced by
16371         Sphinx
16372
16373       · #3657: EPUB builder crashes if document startswith genindex exists
16374
16375       · #3588: No compact (p tag) html output in the i18n document build even
16376         when html_compact_lists is True.
16377
16378       · #3685: AttributeError when using 3rd party domains
16379
16380       · #3702: LaTeX writer styles figure legends with a hard-coded \small
16381
16382       · #3708: LaTeX writer allows irc scheme
16383
16384       · #3717: Stop enforcing that favicon’s must be .ico
16385
16386       · #3731,  #3732:  Protect isenumclass predicate against non-class argu‐
16387         ments
16388
16389       · #3320: Warning about reference target not being found  for  container
16390         types
16391
16392       · Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
16393
16394   Release 1.5.5 (released Apr 03, 2017)
16395   Bugs fixed
16396       · #3597: python domain raises UnboundLocalError if invalid name given
16397
16398       · #3599: Move to new Mathjax CDN
16399
16400   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
16405   Bugs fixed
16406       · #3445: setting 'inputenc' key to \\usepackage[utf8x]{inputenc}  leads
16407         to failed PDF build
16408
16409       · EPUB  file  has duplicated nav.xhtml link in content.opf except first
16410         time build
16411
16412       · #3488: objects.inv has broken when release or version contain  return
16413         code
16414
16415       · #2073, #3443, #3490: gettext builder that writes pot files unless the
16416         content are same without creation date. Thanks to Yoshiki Shibukawa.
16417
16418       · #3487: intersphinx: failed to refer options
16419
16420       · #3496: latex longtable’s last column may be much wider than its  con‐
16421         tents
16422
16423       · #3507: wrong quotes in latex output for productionlist directive
16424
16425       · #3533:  Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of
16426         links rendered as code
16427
16428       · #2665, #2607: Link names in C++ docfields, and make it  possible  for
16429         other domains.
16430
16431       · #3542: C++, fix parsing error of non-type template argument with tem‐
16432         plate.
16433
16434       · #3065, #3520: python domain fails to recognize nested class
16435
16436       · #3575: Problems with pdflatex in a Turkish document built with sphinx
16437         has reappeared (refs #2997, #2397)
16438
16439       · #3577: Fix intersphinx debug tool
16440
16441       · A  LaTeX  command  such  as  \\large  inserted  in the title items of
16442         latex_documents causes failed PDF build (refs #3551, #3567)
16443
16444   Release 1.5.3 (released Feb 26, 2017)
16445   Features added
16446       · Support requests-2.0.0 (experimental) (refs: #3367)
16447
16448       · (latex) PDF page margin dimensions may be customized (refs: #3387)
16449
16450       · literalinclude directive allows combination of :pyobject: and :lines:
16451         options (refs: #3416)
16452
16453       · #3400: make-mode doesn’t use subprocess on building docs
16454
16455   Bugs fixed
16456       · #3370: the caption of code-block is not picked up for translation
16457
16458       · LaTeX: release is not escaped (refs: #3362)
16459
16460       · #3364:  sphinx-quickstart  prompts  overflow on Console with 80 chars
16461         width
16462
16463       · since 1.5, PDF’s TOC and bookmarks lack an entry  for  general  Index
16464         (refs: #3383)
16465
16466       · #3392: 'releasename' in latex_elements is not working
16467
16468       · #3356:  Page layout for Japanese 'manual' docclass has a shorter text
16469         area
16470
16471       · #3394: When 'pointsize' is not 10pt, Japanese 'manual' document  gets
16472         wrong PDF page dimensions
16473
16474       · #3399: quickstart: conf.py was not overwritten by template
16475
16476       · #3366: option directive does not allow punctuations
16477
16478       · #3410: return code in release breaks html search
16479
16480       · #3427: autodoc: memory addresses are not stripped on Windows
16481
16482       · #3428: xetex build tests fail due to fontspec v2.6 defining \strong
16483
16484       · #3349: Result of IndexBuilder.load() is broken
16485
16486       · #3450: &nbsp is appeared in EPUB docs
16487
16488       · #3418: Search button is misaligned in nature and pyramid theme
16489
16490       · #3421: Could not translate a caption of tables
16491
16492       · #3552: linkcheck raises UnboundLocalError
16493
16494   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
16499   Features added
16500       · #3241: emit latex warning if buggy titlesec (ref #3210)
16501
16502       · #3194: Refer the $MAKE environment variable to determine make command
16503
16504       · Emit warning for nested numbered toctrees (refs: #3142)
16505
16506       · #978: intersphinx_mapping also allows a list as a parameter
16507
16508       · #3340: (LaTeX) long lines  in  parsed-literal  are  wrapped  like  in
16509         code-block, inline math and footnotes are fully functional.
16510
16511   Bugs fixed
16512       · #3246: xapian search adapter crashes
16513
16514       · #3253:  In  Py2  environment, building another locale with a non-cap‐
16515         tioned toctree produces None captions
16516
16517       · #185: References to section title including raw node has broken
16518
16519       · #3255: In Py3.4 environment, autodoc  doesn’t  support  documentation
16520         for attributes of Enum class correctly.
16521
16522       · #3261: latex_use_parts makes sphinx crash
16523
16524       · The warning type misc.highlighting_failure does not work
16525
16526       · #3294: add_latex_package() make crashes non-LaTeX builders
16527
16528       · The caption of table are rendered as invalid HTML (refs: #3287)
16529
16530       · #3268: Sphinx crashes with requests package from Debian jessie
16531
16532       · #3284:  Sphinx  crashes  on  parallel  build  with an extension which
16533         raises unserializable exception
16534
16535       · #3315: Bibliography crashes on latex build with docclass ‘memoir’
16536
16537       · #3328: Could not refer rubric implicitly
16538
16539       · #3329: emit warnings if po file is invalid and can’t  read  it.  Also
16540         writing mo too
16541
16542       · #3337: Ugly rendering of definition list term’s classifier
16543
16544       · #3335: gettext does not extract field_name of a field in a field_list
16545
16546       · #2952: C++, fix refs to operator() functions.
16547
16548       · Fix Unicode super- and subscript digits in code-block and parsed-lit‐
16549         eral LaTeX output (ref #3342)
16550
16551       · LaTeX writer: leave " character  inside  parsed-literal  as  is  (ref
16552         #3341)
16553
16554       · #3234: intersphinx failed for encoded inventories
16555
16556       · #3158: too much space after captions in PDF output
16557
16558       · #3317: An URL in parsed-literal contents gets wrongly rendered in PDF
16559         if with hyphen
16560
16561       · LaTeX crash if the filename of an image  inserted  in  parsed-literal
16562         via a substitution contains an hyphen (ref #3340)
16563
16564       · LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref
16565         #3340)
16566
16567       · Inline math in parsed-literal is not  rendered  well  by  LaTeX  (ref
16568         #3340)
16569
16570       · #3308:  Parsed-literals  don’t  wrap very long lines with pdf builder
16571         (ref #3340)
16572
16573       · #3295: Could not import extension sphinx.builders.linkcheck
16574
16575       · #3285: autosummary: asterisks are escaped twice
16576
16577       · LaTeX, pass dvipdfm option to geometry package for Japanese documents
16578         (ref #3363)
16579
16580       · Fix parselinenos() could not parse left half open range (cf. “-4”)
16581
16582   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
16587   Bugs fixed
16588       · #3195: Can not build in parallel
16589
16590       · #3198: AttributeError is raised when toctree has ‘self’
16591
16592       · #3211: Remove untranslated sphinx locale catalogs (it was covered  by
16593         untranslated it_IT)
16594
16595       · #3212: HTML Builders crashes with docutils-0.13
16596
16597       · #3207:  more  latex  problems  with  references inside parsed-literal
16598         directive (\DUrole)
16599
16600       · #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
16601
16602       · #3220: KeyError when having a duplicate citation
16603
16604       · #3200: LaTeX: xref inside desc_name not allowed
16605
16606       · #3228: build_sphinx command crashes when missing dependency
16607
16608       · #2469: Ignore updates of catalog files for gettext builder. Thanks to
16609         Hiroshi Ohkubo.
16610
16611       · #3183: Randomized jump box order in generated index page.
16612
16613   Release 1.5 (released Dec 5, 2016)
16614   Incompatible changes
16615       1.5a1
16616
16617       · latex, package fancybox is not longer a dependency of sphinx.sty
16618
16619       · Use 'locales' as a default value of locale_dirs
16620
16621       · latex, package ifthen is not any longer a dependency of sphinx.sty
16622
16623       · 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
16627       · 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
16630       · latex, literal blocks in  tables  do  not  use  OriginalVerbatim  but
16631         sphinxVerbatimintable  which  handles  captions  and wraps lines (ref
16632         #2704).
16633
16634       · latex, replace pt by TeX equivalent bp if found in  width  or  height
16635         attribute of an image.
16636
16637       · latex,  if  width  or  height  attribute of an image is given with no
16638         unit, use px rather than ignore it.
16639
16640       · latex: Separate stylesheets of pygments to independent .sty file
16641
16642       · #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
16646       · sphinx.util.copy_static_entry()    is    now     deprecated.      Use
16647         sphinx.util.fileutil.copy_asset() instead.
16648
16649       · sphinx.util.osutil.filecopy()  skips copying if the file has not been
16650         changed (ref: #2510, #2753)
16651
16652       · 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
16656       · QtHelpBuilder doens’t generate search page (ref: #2352)
16657
16658       · QtHelpBuilder uses nonav theme instead  of  default  one  to  improve
16659         readability.
16660
16661       · latex: To provide good default settings to Japanese documents, Sphinx
16662         uses jreport and jsbook as docclass if language is ja.
16663
16664       · sphinx-quickstart now allows a project version is empty
16665
16666       · Fix :download: role on epub/qthelp  builder.  They  ignore  the  role
16667         because they don’t support it.
16668
16669       · sphinx.ext.viewcode  doesn’t  work on epub building by default. view‐
16670         code_enable_epub option
16671
16672       · sphinx.ext.viewcode disabled on singlehtml builder.
16673
16674       · Use make-mode of sphinx-quickstart by default.  To disable this,  use
16675         -M option
16676
16677       · Fix genindex.html, Sphinx’s document template, link address to itself
16678         to satisfy xhtml standard.
16679
16680       · Use epub3 builder by default.  And the old epub builder is renamed to
16681         epub2.
16682
16683       · Fix  epub and epub3 builders that contained links to genindex even if
16684         epub_use_index = False.
16685
16686       · html_translator_class is now deprecated.  Use Sphinx.set_translator()
16687         API instead.
16688
16689       · Drop python 2.6 and 3.3 support
16690
16691       · Drop  epub3  builder’s  epub3_page_progression_direction  option (use
16692         epub3_writing_mode).
16693
16694       · #2877: Rename  latex_elements['footer']  to  latex_elements['atendof‐
16695         body']
16696
16697       1.5a2
16698
16699       · #2983:    Rename    epub3_description    and   epub3_contributor   to
16700         epub_description and epub_contributor.
16701
16702       · Remove themes/basic/defindex.html; no longer used
16703
16704       · Sphinx does not ship anymore (but still uses) LaTeX style file  fncy‐
16705         chap
16706
16707       · #2435: Slim down quickstarted conf.py
16708
16709       · 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
16712       · Sphinx does not ship anymore a custom modified LaTeX style file tabu‐
16713         lary.  The non-modified package is used.
16714
16715       · #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
16719       · LaTeX  target requires that option hyperfootnotes of package hyperref
16720         be left unchanged to its default (i.e. true) (refs: #3022)
16721
16722       1.5 final
16723
16724       · #2986: themes/basic/defindex.html is now deprecated
16725
16726       · 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
16730       · #2454: new JavaScript variable SOURCELINK_SUFFIX is added
16731
16732   Deprecated
16733       These features are removed in Sphinx-1.6:
16734
16735       · LDML format  support in i18n feature
16736
16737       · sphinx.addnodes.termsep
16738
16739       · 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
16743       If any deprecation  warning  like  RemovedInSphinxXXXWarning  are  dis‐
16744       played, please refer when-deprecation-warnings-are-displayed.
16745
16746   Features added
16747       1.5a1
16748
16749       · #2951: Add --implicit-namespaces PEP-0420 support to apidoc.
16750
16751       · Add :caption: option for sphinx.ext.inheritance_diagram.
16752
16753       · #2471: Add config variable for default doctest flags.
16754
16755       · Convert linkcheck builder to requests for better encoding handling
16756
16757       · #2463, #2516: Add keywords of “meta” directive to search index
16758
16759       · :maxdepth: option of toctree affects secnumdepth (ref: #2547)
16760
16761       · #2575: Now sphinx.ext.graphviz allows :align: option
16762
16763       · Show warnings if unknown key is specified to latex_elements
16764
16765       · Show warnings if no domains match with primary_domain (ref: #2001)
16766
16767       · 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
16770       · 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
16775       · 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
16780       · 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
16784       · latex, sphinxVerbatim environment is more easily  customizable  (ref:
16785         #2704).   In addition to already existing VerbatimColor and Verbatim‐
16786         BorderColor:
16787
16788         · two lengths \sphinxverbatimsep and \sphinxverbatimborder,
16789
16790         · booleans  \ifsphinxverbatimwithframe   and   \ifsphinxverbatimwrap‐
16791           slines.
16792
16793       · latex,  captions  for  literal  blocks inside tables are handled, and
16794         long code lines wrapped to fit table cell (ref: #2704)
16795
16796       · #2597: Show warning messages as darkred
16797
16798       · latex, allow image dimensions using px unit (default is 96px=1in)
16799
16800       · Show warnings if invalid dimension units found
16801
16802       · #2650: Add --pdb option to setup.py command
16803
16804       · latex, make the use of \small for  code  listings  customizable  (ref
16805         #2721)
16806
16807       · #2663: Add --warning-is-error option to setup.py command
16808
16809       · Show warnings if deprecated latex options are used
16810
16811       · Add sphinx.config.ENUM to check the config values is in candidates
16812
16813       · math: Add hyperlink marker to each equations in HTML output
16814
16815       · Add  new theme nonav that doesn’t include any navigation links.  This
16816         is for any help generator like qthelp.
16817
16818       · #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
16822       · Python domain signature parser now uses the xref  mixin  for  ‘excep‐
16823         tions’, allowing exception classes to be autolinked.
16824
16825       · #2513: Add latex_engine to switch the LaTeX engine by conf.py
16826
16827       · #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
16831       · #1958:  C++, add configuration variable ‘cpp_index_common_prefix’ for
16832         removing prefixes from the index text of C++ objects.
16833
16834       · C++, added concept directive. Thanks to mickk-on-cpp.
16835
16836       · C++, added  support  for  template  introduction  syntax.  Thanks  to
16837         mickk-on-cpp.
16838
16839       · #2725: latex builder: allow to use user-defined template file (exper‐
16840         imental)
16841
16842       · 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
16846       · #2851: sphinx.ext.math emits missing-reference event if equation  not
16847         found
16848
16849       · #1210: eqref role now supports cross reference
16850
16851       · #2892: Added -a (--append-syspath) option to sphinx-apidoc
16852
16853       · #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
16854
16855       · #646: option directive support ‘.’ character as a part of options
16856
16857       · Add document about kindlegen and fix document structure for it.
16858
16859       · #2474: Add intersphinx_timeout option to sphinx.ext.intersphinx
16860
16861       · #2926:  EPUB3  builder  supports  vertical  mode  (epub3_writing_mode
16862         option)
16863
16864       · #2695: build_sphinx subcommand for setuptools handles  exceptions  as
16865         same as sphinx-build does
16866
16867       · #326: numref role can also refer sections
16868
16869       · #2916: numref role can also refer caption as an its linktext
16870
16871       1.5a2
16872
16873       · #3008: linkcheck builder ignores self-signed certificate URL
16874
16875       · #3020:  new 'geometry' key to latex_elements whose default uses LaTeX
16876         style file geometry.sty to set page layout
16877
16878       · #2843: Add :start-at: and :end-at: options to  literalinclude  direc‐
16879         tive
16880
16881       · #2527: Add :reversed: option to toctree directive
16882
16883       · Add  -t and -d option to sphinx-quickstart to support templating gen‐
16884         erated sphinx project.
16885
16886       · #3028: Add  {path}  and  {basename}  to  the  format  of  figure_lan‐
16887         guage_filename
16888
16889       · new 'hyperref' key in the latex_elements dictionary (ref #3030)
16890
16891       · #3022: Allow code-blocks in footnotes for LaTeX PDF output
16892
16893       1.5b1
16894
16895       · #2513: A better default settings for XeLaTeX
16896
16897       · #3096: 'maxlistdepth' key to work around LaTeX list limitations
16898
16899       · #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
16903       · Add  --extensions  to  sphinx-quickstart  to support enable arbitrary
16904         extensions from command line (ref: #2904)
16905
16906       · #3104, #3122: 'sphinxsetup' for key=value styling of Sphinx LaTeX
16907
16908       · #3071: Autodoc: Allow mocked module decorators to pass-through  func‐
16909         tions unchanged
16910
16911       · #2495:    linkcheck:    Allow    skipping   anchor   checking   using
16912         linkcheck_anchors_ignore
16913
16914       · #3083: let Unicode no-break space act like LaTeX ~ (fixed #3019)
16915
16916       · #3116: allow word wrap in PDF output for inline literals (ref #3110)
16917
16918       · #930: sphinx-apidoc allow wildcards for excluding  paths.  Thanks  to
16919         Nick Coghlan.
16920
16921       · #3121:  add  inlineliteralwraps  option  to control if inline literal
16922         word-wraps in latex
16923
16924       1.5 final
16925
16926       · #3095: Add tls_verify and tls_cacerts to  support  self-signed  HTTPS
16927         servers in linkcheck and intersphinx
16928
16929       · #2215:  make.bat  generated  by  sphinx-quickstart can be called from
16930         another dir.  Thanks to Timotheus Kampik.
16931
16932       · #3185: Add new warning type misc.highlighting_failure
16933
16934   Bugs fixed
16935       1.5a1
16936
16937       · #2707: (latex) the column width is badly computed for tabular
16938
16939       · #2799: Sphinx installs roles and directives automatically on  import‐
16940         ing sphinx module.  Now Sphinx installs them on running application.
16941
16942       · sphinx.ext.autodoc crashes if target code imports * from mock modules
16943         by autodoc_mock_imports.
16944
16945       · #1953: Sphinx.add_node does not add handlers the translator installed
16946         by html_translator_class
16947
16948       · #1797: text builder inserts blank line on top
16949
16950       · #2894: quickstart main() doesn’t use argv argument
16951
16952       · #2874:  gettext  builder  could  not  extract all text under the only
16953         directives
16954
16955       · #2485: autosummary crashes with multiple source_suffix values
16956
16957       · #1734: Could not translate the caption of toctree directive
16958
16959       · Could not translate the content of meta directive (ref: #1734)
16960
16961       · #2550: external links are opened in help viewer
16962
16963       · #2687: Running Sphinx multiple times  produces  ‘already  registered’
16964         warnings
16965
16966       1.5a2
16967
16968       · #2810: Problems with pdflatex in an Italian document
16969
16970       · Use  latex_elements.papersize  to specify papersize of LaTeX in Make‐
16971         file
16972
16973       · #2988: linkcheck: retry with GET request if denied HEAD request
16974
16975       · #2990: linkcheck raises “Can’t convert ‘bytes’ object to str  implic‐
16976         itly” error if linkcheck_anchors enabled
16977
16978       · #3004: Invalid link types “top” and “up” are used
16979
16980       · #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
16981
16982       · #3000: option directive generates invalid HTML anchors
16983
16984       · #2984: Invalid HTML has been generated if html_split_index enabled
16985
16986       · #2986:   themes/basic/defindex.html   should  be  changed  for  html5
16987         friendly
16988
16989       · #2987: Invalid HTML has been generated if multiple IDs  are  assigned
16990         to a list
16991
16992       · #2891: HTML search does not provide all the results
16993
16994       · #1986: Title in PDF Output
16995
16996       · #147: Problem with latex chapter style
16997
16998       · #3018: LaTeX problem with page layout dimensions and chapter titles
16999
17000       · Fix an issue with \pysigline in LaTeX style file (ref #3023)
17001
17002       · #3038: sphinx.ext.math* raises TypeError if labels are duplicated
17003
17004       · #3031: incompatibility with LaTeX package tocloft
17005
17006       · #3003: literal blocks in footnotes are not supported by Latex
17007
17008       · #3047:  spacing  before  footnote  in  pdf output is not coherent and
17009         allows breaks
17010
17011       · #3045: HTML search index creator should ignore “raw” content  if  now
17012         html
17013
17014       · #3039: English stemmer returns wrong word if the word is capitalized
17015
17016       · Fix make-mode Makefile template (ref #3056, #2936)
17017
17018       1.5b1
17019
17020       · #2432:  Fix  unwanted * between varargs and keyword only args. Thanks
17021         to Alex Grönholm.
17022
17023       · #3062: Failed to build PDF using 1.5a2 (undefined \hypersetup for Ja‐
17024         panese documents since PR#3030)
17025
17026       · Better rendering of multiline signatures in html.
17027
17028       · #777: LaTeX output “too deeply nested” (ref #3096)
17029
17030       · Let LaTeX image inclusion obey scale before textwidth fit (ref #2865,
17031         #3059)
17032
17033       · #3019: LaTeX fails on description of C function with  arguments  (ref
17034         #3083)
17035
17036       · fix latex inline literals where < > - gobbled a space
17037
17038       1.5 final
17039
17040       · #3069:  Even if 'babel' key is set to empty string, LaTeX output con‐
17041         tains one \addto\captions...
17042
17043       · #3123: user 'babel' key setting is not obeyed anymore
17044
17045       · #3155: Fix JavaScript for html_sourcelink_suffix fails  with  IE  and
17046         Opera
17047
17048       · #3085:  keep  current  directory  after breaking build documentation.
17049         Thanks to Timotheus Kampik.
17050
17051       · #3181: pLaTeX crashes with a section contains endash
17052
17053       · #3180: latex: add stretch/shrink  between  successive  singleline  or
17054         multipleline cpp signatures (ref #3072)
17055
17056       · #3128: globing images does not support .svgz file
17057
17058       · #3015: fix a broken test on Windows.
17059
17060       · #1843:  Fix  documentation  of  descriptor classes that have a custom
17061         metaclass.  Thanks to Erik Bray.
17062
17063       · #3190: util.split_docinfo fails to parse multi-line field bodies
17064
17065       · #3024, #3037: In Python3, application.Sphinx._log  crushed  when  the
17066         log message cannot be encoded into console encoding.
17067
17068   Testing
17069       · To  simplify, sphinx uses external mock package even if unittest.mock
17070         exists.
17071
17072   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
17076       · #3058: Using the  same  ‘caption’  attribute  in  multiple  ‘toctree’
17077         directives results in warning / error
17078
17079       · #3068: Allow the ‘=’ character in the -D option of sphinx-build.py
17080
17081       · #3074: add_source_parser() crashes in debug mode
17082
17083       · #3135: sphinx.ext.autodoc crashes with plain Callable
17084
17085       · #3150:  Fix  query word splitter in JavaScript. It behaves as same as
17086         Python’s regular expression.
17087
17088       · #3093: gettext build broken on substituted images.
17089
17090       · #3093: gettext build broken on image node under note directive.
17091
17092       · imgmath: crashes on showing error messages if image generation failed
17093
17094       · #3117: LaTeX writer crashes if admonition is placed before first sec‐
17095         tion title
17096
17097       · #3164: Change search order of sphinx.ext.inheritance_diagram
17098
17099   Release 1.4.8 (released Oct 1, 2016)
17100   Bugs fixed
17101       · #2996: The wheel package of Sphinx got crash with ImportError
17102
17103   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
17108       · #2870: flatten genindex columns’ heights.
17109
17110       · #2856: Search on generated HTML site doesnt find some symbols
17111
17112       · #2882: Fall back to a GET request on 403 status in linkcheck
17113
17114       · #2902: jsdump.loads fails to load search  index  if  keywords  starts
17115         with underscore
17116
17117       · #2900:  Fix  epub  content.opf:  add  auto  generated orphan files to
17118         spine.
17119
17120       · #2899: Fix hasdoc() function in Jinja2 template. It can detect genin‐
17121         dex, search collectly.
17122
17123       · #2901: Fix epub result: skip creating links from image tags to origi‐
17124         nal image files.
17125
17126       · #2917: inline code is hyphenated on HTML
17127
17128       · #1462: autosummary warns for namedtuple with attribute with  trailing
17129         underscore
17130
17131       · Could not reference equations if :nowrap: option specified
17132
17133       · #2873: code-block overflow in latex (due to commas)
17134
17135       · #1060,  #2056:  sphinx.ext.intersphinx: broken links are generated if
17136         relative paths are used in intersphinx_mapping
17137
17138       · #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
17142       · #2962: latex: missing label of longtable
17143
17144       · #2968: autodoc: show-inheritance option breaks docstrings
17145
17146   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
17151   Bugs fixed
17152       · applehelp: Sphinx crashes if hiutil or codesign commands not found
17153
17154       · Fix make clean abort issue when build dir contains regular files like
17155         DS_Store.
17156
17157       · Reduce epubcheck warnings/errors:
17158
17159         · Fix DOCTYPE to html5
17160
17161         · Change extension from .html to .xhtml.
17162
17163         · Disable search page on epub results
17164
17165       · #2778: Fix autodoc crashes if obj.__dict__ is a property  method  and
17166         raises exception
17167
17168       · Fix duplicated toc in epub3 output.
17169
17170       · #2775:  Fix  failing  linkcheck  with servers not supporting identidy
17171         encoding
17172
17173       · #2833: Fix formatting instance annotations in ext.autodoc.
17174
17175       · #1911: -D option of sphinx-build does  not  override  the  extensions
17176         variable
17177
17178       · #2789:  sphinx.ext.intersphinx  generates  wrong  hyperlinks  if  the
17179         inventory is given
17180
17181       · parsing errors for caption of code-blocks are displayed  in  document
17182         (ref: #2845)
17183
17184       · #2846: singlehtml builder does not include figure numbers
17185
17186       · #2816:  Fix data from builds cluttering the Domain.initial_data class
17187         attributes
17188
17189   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
17196       · 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
17200   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
17205       · latex  writer allows user customization of “shadowed” boxes (topics),
17206         via three length variables.
17207
17208       · woff-format web font files now supported by the epub builder.
17209
17210   Bugs fixed
17211       · jsdump fix for python 3: fixes the HTML search on python > 3
17212
17213       · #2676: (latex) Error with verbatim  text  in  captions  since  Sphinx
17214         1.4.4
17215
17216       · #2629:      memoir      class     crashes     LaTeX.     Fixed     by
17217         latex_keep_old_macro_names=False (ref 2675)
17218
17219       · #2684: sphinx.ext.intersphinx crashes with six-1.4.1
17220
17221       · #2679: float package needed for 'figure_align': 'H' latex option
17222
17223       · #2671: image directive may lead to inconsistent spacing in pdf
17224
17225       · #2705: toctree generates empty bullet_list if :titlesonly: specified
17226
17227       · #2479: sphinx.ext.viewcode uses python2 highlighter by default
17228
17229       · #2700: HtmlHelp builder has hard coded index.html
17230
17231       · latex, since 1.4.4 inline literal text is followed by spurious space
17232
17233       · #2722: C++, fix id generation for var/member declarations to  include
17234         namespaces.
17235
17236       · latex,  images  (from  image directive) in lists or quoted blocks did
17237         not obey indentation (fixed together with #2671)
17238
17239       · #2733: since Sphinx-1.4.4 make latexpdf generates  lots  of  hyperref
17240         warnings
17241
17242       · #2731:  sphinx.ext.autodoc  does  not  access  propertymethods  which
17243         raises any exceptions
17244
17245       · #2666: C++, properly look up nested names involving constructors.
17246
17247       · #2579: Could not refer a label including both spaces and  colons  via
17248         sphinx.ext.intersphinx
17249
17250       · #2718: Sphinx crashes if the document file is not readable
17251
17252       · #2699: hyperlinks in help HTMLs are broken if html_file_suffix is set
17253
17254       · #2723: extra spaces in latex pdf output from multirow cell
17255
17256       · #2735:  latexpdf  Underfull \hbox (badness 10000) warnings from title
17257         page
17258
17259       · #2667: latex crashes if resized images appeared in section title
17260
17261       · #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
17265   Release 1.4.4 (released Jun 12, 2016)
17266   Bugs fixed
17267       · #2630: Latex sphinx.sty Notice Enviroment formatting problem
17268
17269       · #2632: Warning directives fail in quote environment latex build
17270
17271       · #2633: Sphinx crashes with old styled indices
17272
17273       · Fix a \begin{\minipage} typo in sphinx.sty from 1.4.2 (ref: 68becb1)
17274
17275       · #2622: Latex produces empty pages after title and table of contents
17276
17277       · #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
17278
17279       · Let LaTeX use straight quotes also in inline code (ref #2627)
17280
17281       · #2351: latex crashes if enumerated lists are placed on footnotes
17282
17283       · #2646: latex crashes if math contains twice empty lines
17284
17285       · #2480: sphinx.ext.autodoc: memory addresses were shown
17286
17287       · latex: allow code-blocks appearing inside lists and quotes at maximal
17288         nesting depth (ref #777, #2624, #2651)
17289
17290       · #2635:  Latex  code  directives  produce inconsistent frames based on
17291         viewing resolution
17292
17293       · #2639: Sphinx now bundles iftex.sty
17294
17295       · Failed to build PDF with framed.sty 0.95
17296
17297       · Sphinx now bundles needspace.sty
17298
17299   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
17304       · width option of figure directive does not work if align option speci‐
17305         fied at same time (ref: #2595)
17306
17307       · #2590: The inputenc package breaks compiling under lualatex and xela‐
17308         tex
17309
17310       · #2540: date on latex front page use different font
17311
17312       · Suppress “document isn’t included in any toctree” warning if the doc‐
17313         ument is included (ref: #2603)
17314
17315       · #2614: Some tables in PDF output will end up shifted if user sets non
17316         zero parindent in preamble
17317
17318       · #2602:   URL   redirection   breaks   the   hyperlinks  generated  by
17319         sphinx.ext.intersphinx
17320
17321       · #2613: Show warnings if merged extensions are loaded
17322
17323       · #2619: make sure amstext LaTeX package always loaded  (ref:  d657225,
17324         488ee52, 9d82cad and #2615)
17325
17326       · #2593: latex crashes if any figures in the table
17327
17328   Release 1.4.2 (released May 29, 2016)
17329   Features added
17330       · Now  suppress_warnings  accepts following configurations (ref: #2451,
17331         #2466):
17332
17333         · app.add_node
17334
17335         · app.add_directive
17336
17337         · app.add_role
17338
17339         · app.add_generic_role
17340
17341         · app.add_source_parser
17342
17343         · image.data_uri
17344
17345         · image.nonlocal_uri
17346
17347       · #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
17353       · #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
17357       · #2343: the long source lines in code-blocks are wrapped (without mod‐
17358         ifying the line numbering) in LaTeX output (ref #1534, #2304).
17359
17360   Bugs fixed
17361       · #2370: the equations are slightly misaligned in LaTeX writer
17362
17363       · #1817,   #2077:  suppress  pep8  warnings  on  conf.py  generated  by
17364         sphinx-quickstart
17365
17366       · #2407: building docs crash if document includes large data image URIs
17367
17368       · #2436: Sphinx does not  check  version  by  needs_sphinx  if  loading
17369         extensions failed
17370
17371       · #2397: Setup shorthandoff for turkish documents
17372
17373       · #2447: VerbatimBorderColor wrongly used also for captions of PDF
17374
17375       · #2456:  C++,  fix crash related to document merging (e.g., singlehtml
17376         and Latex builders).
17377
17378       · #2446: latex(pdf) sets local tables of contents  (or  more  generally
17379         topic nodes) in unbreakable boxes, causes overflow at bottom
17380
17381       · #2476: Omit MathJax markers if :nowrap: is given
17382
17383       · #2465:  latex  builder fails in case no caption option is provided to
17384         toctree directive
17385
17386       · Sphinx crashes if self referenced toctree found
17387
17388       · #2481: spelling mistake for mecab search splitter.  Thanks  to  Naoki
17389         Sato.
17390
17391       · #2309: Fix could not refer “indirect hyperlink targets” by ref-role
17392
17393       · intersphinx fails if mapping URL contains any port
17394
17395       · #2088: intersphinx crashes if the mapping URL requires basic auth
17396
17397       · #2304: auto line breaks in latexpdf codeblocks
17398
17399       · #1534: Word wrap long lines in Latex verbatim blocks
17400
17401       · #2460: too much white space on top of captioned literal blocks in PDF
17402         output
17403
17404       · Show error reason when multiple  math  extensions  are  loaded  (ref:
17405         #2499)
17406
17407       · #2483:  any  figure  number was not assigned if figure title contains
17408         only non text objects
17409
17410       · #2501: Unicode subscript numbers are normalized in LaTeX
17411
17412       · #2492:  Figure  directive   with   :figwidth:   generates   incorrect
17413         Latex-code
17414
17415       · The  caption  of  figure  is always put on center even if :align: was
17416         specified
17417
17418       · #2526: LaTeX writer crashes if the section having only images
17419
17420       · #2522: Sphinx touches mo files under installed directory that  caused
17421         permission error.
17422
17423       · #2536:  C++,  fix crash when an immediately nested scope has the same
17424         name as the current scope.
17425
17426       · #2555: Fix crash on any-references with unicode.
17427
17428       · #2517: wrong bookmark encoding in PDF if using LuaLaTeX
17429
17430       · #2521: generated Makefile causes BSD make crashed if sphinx-build not
17431         found
17432
17433       · #2470: typing backport package causes autodoc errors with python 2.7
17434
17435       · sphinx.ext.intersphinx crashes if non-string value is used for key of
17436         intersphinx_mapping
17437
17438       · #2518: intersphinx_mapping disallows non alphanumeric keys
17439
17440       · #2558: unpack error on devhelp builder
17441
17442       · #2561: Info builder crashes when a footnote contains a link
17443
17444       · #2565: The descriptions of objects generated  by  sphinx.ext.autosum‐
17445         mary overflow lines at LaTeX writer
17446
17447       · Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
17448
17449       · #2445: rst_prolog and rst_epilog affect to non reST sources
17450
17451       · #2576: sphinx.ext.imgmath crashes if subprocess raises error
17452
17453       · #2577: sphinx.ext.imgmath: Invalid argument are passed to dvisvgm
17454
17455       · #2556: Xapian search does not work with Python 3
17456
17457       · #2581: The search doesn’t work if language=”es” (spanish)
17458
17459       · #2382:  Adjust spacing after abbreviations on figure numbers in LaTeX
17460         writer
17461
17462       · #2383: The generated footnote by latex_show_urls overflows lines
17463
17464       · #2497, #2552: The label of search button does not fit for the  button
17465         itself
17466
17467   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
17473   Translations
17474       · Added Welsh translation, thanks to Geraint Palmer.
17475
17476       · Added Greek translation, thanks to Stelios Vitalis.
17477
17478       · Added Esperanto translation, thanks to Dinu Gherman.
17479
17480       · Added Hindi translation, thanks to Purnank H. Ghumalia.
17481
17482       · Added Romanian translation, thanks to Razvan Stefanescu.
17483
17484   Bugs fixed
17485       · C++, added support for extern and thread_local.
17486
17487       · C++, type declarations are now using the prefixes typedef, using, and
17488         type, depending on the style of declaration.
17489
17490       · #2413: C++, fix crash on duplicate declarations
17491
17492       · #2394: Sphinx crashes when html_last_updated_fmt is invalid
17493
17494       · #2408: dummy builder not available in Makefile and make.bat
17495
17496       · #2412: hyperlink targets are broken in LaTeX builder
17497
17498       · figure directive crashes if non paragraph item is given as caption
17499
17500       · #2418: time formats no longer allowed in today_fmt
17501
17502       · #2395: Sphinx crashes if unicode character in image filename
17503
17504       · #2396: “too many values to unpack” in genindex-single
17505
17506       · #2405: numref link in PDF jumps to the wrong location
17507
17508       · #2414: missing number in PDF hyperlinks to code listings
17509
17510       · #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
17511
17512   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
17517       · sphinx_rtd_theme  has  become  optional.  Please install it manually.
17518         Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
17519
17520       · #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
17523       · #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
17526       · #2027, #2208: The html_title accepts string values only. And The None
17527         value cannot be accepted.
17528
17529       · sphinx.ext.graphviz: show graph image in inline by default
17530
17531       · #2060,  #2224:  The manpage role now generate sphinx.addnodes.manpage
17532         node instead of sphinx.addnodes.literal_emphasis node.
17533
17534       · #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
17538       · #2300: enhance  autoclass::  to  use  the  docstring  of  __new__  if
17539         __init__ method’s is missing of empty
17540
17541       · #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
17548       · 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
17554       · 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
17559       · #2327: latex_use_parts is deprecated now. Use latex_toplevel_section‐
17560         ing instead.
17561
17562       · #2337: Use  \url{URL}  macro  instead  of  \href{URL}{URL}  in  LaTeX
17563         writer.
17564
17565       · #1498:  manpage  writer:  don’t make whole of item in definition list
17566         bold if it includes strong node.
17567
17568       · #582: Remove hint message from quick search box for html output.
17569
17570       · #2378: Sphinx now bundles newfloat.sty
17571
17572   Features added
17573       · #2092: add todo directive support in napoleon package.
17574
17575       · #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
17579       · #1909: Add “doc” references to Intersphinx inventories.
17580
17581       · C++ type alias support (e.g., .. type:: T = int).
17582
17583       · C++ template support for classes, functions, type aliases, and  vari‐
17584         ables (#1729, #1314).
17585
17586       · C++,  added new scope management directives namespace-push and names‐
17587         pace-pop.
17588
17589       · #1970: Keyboard shortcuts to navigate Next and Previous topics
17590
17591       · Intersphinx: Added support for fetching Intersphinx inventories  with
17592         URLs using HTTP basic auth.
17593
17594       · C++,  added  support  for  template  parameter in function info field
17595         lists.
17596
17597       · C++, added support for pointers to member (function).
17598
17599       · #2113: Allow :class: option to code-block directive.
17600
17601       · #2192: Imgmath (pngmath with svg support).
17602
17603       · #2200: Support XeTeX and LuaTeX for the LaTeX builder.
17604
17605       · #1906: Use xcolor over color for fcolorbox where available for  LaTeX
17606         output.
17607
17608       · #2216: Texinputs makefile improvements.
17609
17610       · #2170: Support for Chinese language search index.
17611
17612       · #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
17613
17614       · #1030: Make page reference names for latex_show_pagerefs translatable
17615
17616       · #2162:   Add  Sphinx.add_source_parser()  to  add  source_suffix  and
17617         source_parsers from extension
17618
17619       · #2207: Add sphinx.parsers.Parser class; a base class for new parsers
17620
17621       · #656: Add graphviz_dot option to graphviz directives  to  switch  the
17622         dot command
17623
17624       · #1939: Added the dummy builder: syntax check without output.
17625
17626       · #2230:  Add  math_number_all  option  to number all displayed math in
17627         math extensions
17628
17629       · #2235: needs_sphinx supports micro version comparison
17630
17631       · #2282: Add “language” attribute to html tag in the “basic” theme
17632
17633       · #1779: Add EPUB 3 builder
17634
17635       · #1751: Add todo_link_only to avoid file path and line  indication  on
17636         todolist. Thanks to Francesco Montesano.
17637
17638       · #2199: Use imagesize package to obtain size of images.
17639
17640       · #1099:  Add  configurable retries to the linkcheck builder. Thanks to
17641         Alex Gaynor.  Also don’t check anchors starting with !.
17642
17643       · #2300: enhance  autoclass::  to  use  the  docstring  of  __new__  if
17644         __init__ method’s is missing of empty
17645
17646       · #1858:  Add  Sphinx.add_enumerable_node() to add enumerable nodes for
17647         numfig feature
17648
17649       · #1286, #2099: Add sphinx.ext.autosectionlabel extension to allow ref‐
17650         erence sections using its title. Thanks to Tadhg O’Higgins.
17651
17652       · #1854: Allow to choose Janome for Japanese splitter.
17653
17654       · #1853:  support  custom  text  splitter  on  html  search  with  lan‐
17655         guage='ja'.
17656
17657       · #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
17661       · #2308: Define \tablecontinued macro to redefine the style of  contin‐
17662         ued label for longtables.
17663
17664       · Select  an  image  by similarity if multiple images are globbed by ..
17665         image:: filename.*
17666
17667       · #1921: Support  figure  substitutions  by  language  and  figure_lan‐
17668         guage_filename
17669
17670       · #2245:  Add  latex_elements["passoptionstopackages"]  option  to call
17671         PassOptionsToPackages in early stage of preambles.
17672
17673       · #2340: Math extension: support alignment of  multiple  equations  for
17674         MathJAX.
17675
17676       · #2338:  Define  \titleref macro to redefine the style of title-refer‐
17677         ence roles.
17678
17679       · Define \menuselection and \accelerator macros to redefine  the  style
17680         of menuselection roles.
17681
17682       · Define \crossref macro to redefine the style of references
17683
17684       · #2301: Texts in the classic html theme should be hyphenated.
17685
17686       · #2355: Define \termref macro to redefine the style of term roles.
17687
17688       · Add  suppress_warnings to suppress arbitrary warning message (experi‐
17689         mental)
17690
17691       · #2229: Fix no warning is given for unknown options
17692
17693       · #2327: Add latex_toplevel_sectioning to switch the top level section‐
17694         ing of LaTeX document.
17695
17696   Bugs fixed
17697       · #1913:  C++,  fix  assert  bug  for enumerators in next-to-global and
17698         global scope.
17699
17700       · C++, fix parsing of ‘signed char’ and ‘unsigned char’ as types.
17701
17702       · C++, add missing support for ‘friend’ functions.
17703
17704       · C++, add missing support for virtual base classes (thanks to Rapptz).
17705
17706       · C++, add support for final classes.
17707
17708       · C++, fix parsing of types prefixed with ‘enum’.
17709
17710       · #2023: Dutch search support uses Danish stemming info.
17711
17712       · C++, add support for user-defined literals.
17713
17714       · #1804: Now html output wraps overflowed long-line-text in  the  side‐
17715         bar. Thanks to Hassen ben tanfous.
17716
17717       · #2183: Fix porterstemmer causes make json to fail.
17718
17719       · #1899: Ensure list is sent to OptParse.
17720
17721       · #2164:  Fix  wrong  check  for pdftex inside sphinx.sty (for graphicx
17722         package option).
17723
17724       · #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
17725
17726       · Fix broken LaTeX code is generated if unknown language is given
17727
17728       · #1944: Fix rst_prolog breaks file-wide metadata
17729
17730       · #2074: make gettext should use canonical  relative  paths  for  .pot.
17731         Thanks to anatoly techtonik.
17732
17733       · #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
17734
17735       · #2251:  Line  breaks in .rst files are transferred to .pot files in a
17736         wrong way.
17737
17738       · #794: Fix date formatting in latex output is not localized
17739
17740       · Remove image/gif from supported_image_types of LaTeX writer (#2272)
17741
17742       · Fix ValueError is raised if LANGUAGE is empty string
17743
17744       · Fix unpack warning  is  shown  when  the  directives  generated  from
17745         Sphinx.add_crossref_type is used
17746
17747       · 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
17752       · #2329: Refresh environment forcely if source directory has changed.
17753
17754       · #2331: Fix code-blocks are filled by  block  in  dvi;  remove  xcdraw
17755         option from xcolor package
17756
17757       · Fix  the  confval  type checker emits warnings if unicode is given to
17758         confvals which expects string value
17759
17760       · #2360: Fix numref in LaTeX output is broken
17761
17762       · #2361: Fix additional paragraphs inside the “compound” directive  are
17763         indented
17764
17765       · #2364:  Fix  KeyError  ‘rootSymbol’ on Sphinx upgrade from older ver‐
17766         sion.
17767
17768       · #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
17769
17770       · #2368: Ignore emacs lock files like .#foo.rst by default.
17771
17772       · #2262: literal_block and its caption has been separated by  pagebreak
17773         in LaTeX output.
17774
17775       · #2319:  Fix  table  counter  is  overrided  by code-block’s in LaTeX.
17776         Thanks to jfbu.
17777
17778       · Fix unpack warning if combinated with 3rd party domain extensions.
17779
17780       · #1153: Fix figures in sidebar causes latex build error.
17781
17782       · #2358: Fix user-preamble could not override the tocdepth definition.
17783
17784       · #2358: Redece tocdepth if part or chapter is  used  for  top_section‐
17785         level.
17786
17787       · #2351: Fix footnote spacing
17788
17789       · #2363:  Fix  toctree() in templates generates broken links in Single‐
17790         HTMLBuilder.
17791
17792       · #2366: Fix empty hyperref is generated on toctree in HTML builder.
17793
17794   Documentation
17795       · #1757: Fix for usage of html_last_updated_fmt. Thanks  to  Ralf  Hem‐
17796         mecke.
17797
17798   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
17804   Bugs fixed
17805       · #2265: Fix babel is used in spite of disabling it on latex_elements
17806
17807       · #2295:  Avoid mutating dictionary errors while enumerating members in
17808         autodoc with Python 3
17809
17810       · #2291: Fix pdflatex “Counter too large” error from  footnotes  inside
17811         tables of contents
17812
17813       · #2292: Fix some footnotes disappear from LaTeX output
17814
17815       · #2287:  sphinx.transforms.Locale  always uses rst parser. Sphinx i18n
17816         feature should support parsers that specified source_parsers.
17817
17818       · #2290: Fix sphinx.ext.mathbase use of amsfonts may break user  choice
17819         of math fonts
17820
17821       · #2324:  Print  a  hint how to increase the recursion limit when it is
17822         hit.
17823
17824       · #1565, #2229: Revert new warning; the new warning will  be  triggered
17825         from version 1.4 on.
17826
17827       · #2329: Refresh environment forcely if source directory has changed.
17828
17829       · #2019: Fix the domain objects in search result are not escaped
17830
17831   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
17836       · Fix filenames were not shown on warnings of citations
17837
17838       · Fix line numbers was not shown  on  warnings  in  LaTeX  and  texinfo
17839         builders
17840
17841       · Fix line numbers was not shown on warnings of indices
17842
17843       · #2026:  Fix  LaTeX  builder  raises  error if parsed-literal includes
17844         links
17845
17846       · #2243: Ignore strange docstring types for classes, do not crash
17847
17848       · #2247: Fix #2205 breaks make html for definition  list  with  classi‐
17849         fiers that contains regular-expression like string
17850
17851       · #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
17854       · #2211: Fix paragraphs in table cell doesn’t work in Latex output
17855
17856       · #2253: :pyobject: option of  literalinclude  directive  can’t  detect
17857         indented  body  block  when  the  block  starts with blank or comment
17858         lines.
17859
17860       · Fix TOC is not shown when no :maxdepth: for toctrees (ref: #771)
17861
17862       · Fix warning message for :numref: if target is in orphaned  doc  (ref:
17863         #2244)
17864
17865   Release 1.3.4 (released Jan 12, 2016)
17866   Bugs fixed
17867       · #2134: Fix figure caption with reference causes latex build error
17868
17869       · #2094: Fix rubric with reference not working in Latex
17870
17871       · #2147: Fix literalinclude code in latex does not break in pages
17872
17873       · #1833:  Fix email addresses is showed again if latex_show_urls is not
17874         None
17875
17876       · #2176: sphinx.ext.graphviz: use <object> instead of  <img>  to  embed
17877         svg
17878
17879       · #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
17880
17881       · #1237: Fix footnotes not working in definition list in LaTeX
17882
17883       · #2168: Fix raw directive does not work for text writer
17884
17885       · #2171: Fix cannot linkcheck url with unicode
17886
17887       · #2182: LaTeX: support image file names with more than 1 dots
17888
17889       · #2189:  Fix previous sibling link for first file in subdirectory uses
17890         last file, not intended previous from root toctree
17891
17892       · #2003: Fix decode error under python2 (only) when make  linkcheck  is
17893         run
17894
17895       · #2186: Fix LaTeX output of mathbb in math
17896
17897       · #1480, #2188: LaTeX: Support math in section titles
17898
17899       · #2071: Fix same footnote in more than two section titles => LaTeX/PDF
17900         Bug
17901
17902       · #2040: Fix UnicodeDecodeError in sphinx-apidoc when  author  contains
17903         non-ascii characters
17904
17905       · #2193:  Fix  shutil.SameFileError if source directory and destination
17906         directory are same
17907
17908       · #2178: Fix unparseable C++ cross-reference when referencing  a  func‐
17909         tion with :cpp:any:
17910
17911       · #2206: Fix Sphinx latex doc build failed due to a footnotes
17912
17913       · #2201: Fix wrong table caption for tables with over 30 rows
17914
17915       · #2213: Set <blockquote> in the classic theme to fit with <p>
17916
17917       · #1815:  Fix  linkcheck does not raise an exception if warniserror set
17918         to true and link is broken
17919
17920       · #2197: Fix slightly cryptic error message for missing index.rst file
17921
17922       · #1894: Unlisted phony targets in quickstart Makefile
17923
17924       · #2125: Fix unifies behavior of  collapsed  fields  (GroupedField  and
17925         TypedField)
17926
17927       · #1408: Check latex_logo validity before copying
17928
17929       · #771: Fix latex output doesn’t set tocdepth
17930
17931       · #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
17934       · #2072: Fix footnotes in chapter-titles do not appear in PDF output
17935
17936       · #1580: Fix paragraphs in longtable don’t work in Latex output
17937
17938       · #1366: Fix centered image not centered in latex
17939
17940       · #1860: Fix man page using :samp: with braces - font doesn’t reset
17941
17942       · #1610: Sphinx crashes in japanese indexing in some systems
17943
17944       · Fix Sphinx crashes if mecab initialization failed
17945
17946       · #2160: Fix broken TOC of PDFs if section includes an image
17947
17948       · #2172: Fix dysfunctional admonition py@lightbox in sphinx.sty. Thanks
17949         to jfbu.
17950
17951       · #2198,#2205: make gettext generate broken msgid for definition lists.
17952
17953       · #2062:  Escape  characters  in  doctests are treated incorrectly with
17954         Python 2.
17955
17956       · #2225: Fix if the option does not begin with  dash,  linking  is  not
17957         performed
17958
17959       · #2226:  Fix  math is not HTML-encoded when :nowrap: is given (jsmath,
17960         mathjax)
17961
17962       · #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
17967       · #2229: Fix no warning is given for unknown options
17968
17969   Release 1.3.3 (released Dec 2, 2015)
17970   Bugs fixed
17971       · #2177: Fix parallel hangs
17972
17973       · #2012: Fix exception occurred if numfig_format is invalid
17974
17975       · #2142:   Provide  non-minified  JS  code  in  sphinx/search/non-mini‐
17976         fied-js/*.js for source distribution on PyPI.
17977
17978       · #2148: Error while building devhelp target with non-ASCII document.
17979
17980   Release 1.3.2 (released Nov 29, 2015)
17981   Features added
17982       · #1935: Make “numfig_format” overridable in latex_elements.
17983
17984   Bugs fixed
17985       · #1976: Avoid “2.0” version of Babel because it doesn’t work with Win‐
17986         dows environment.
17987
17988       · Add a “default.css” stylesheet (which imports “classic.css”) for com‐
17989         patibility.
17990
17991       · #1788: graphviz extension raises exception  when  caption  option  is
17992         present.
17993
17994       · #1789: :pyobject: option of literalinclude directive includes follow‐
17995         ing lines after class definitions
17996
17997       · #1790: literalinclude strips empty lines at the head and tail
17998
17999       · #1802: load plugin themes automatically when  theme.conf  use  it  as
18000         ‘inherit’. Thanks to Takayuki Hirai.
18001
18002       · #1794: custom theme extended from alabaster or sphinx_rtd_theme can’t
18003         find base theme.
18004
18005       · #1834:  compatibility  for  docutils-0.13:  handle_io_errors  keyword
18006         argument for docutils.io.FileInput cause TypeError.
18007
18008       · #1823:  ‘.’  as  <module_path>  for sphinx-apidoc cause an unfriendly
18009         error. Now ‘.’ is converted to absolute path automatically.
18010
18011       · Fix a crash when setting up extensions which do not support metadata.
18012
18013       · #1784:  Provide  non-minified  JS  code  in   sphinx/search/non-mini‐
18014         fied-js/*.js
18015
18016       · #1822,  #1892:  Fix  regression for #1061. autosummary can’t generate
18017         doc for imported members since sphinx-1.3b3. Thanks to Eric Larson.
18018
18019       · #1793, #1819: “see also” misses a linebreak in text output. Thanks to
18020         Takayuki Hirai.
18021
18022       · #1780,  #1866:  “make  text”  shows  “class” keyword twice. Thanks to
18023         Takayuki Hirai.
18024
18025       · #1871: Fix for LaTeX output of tables with one column and multirows.
18026
18027       · Work around the lack of the HTMLParserError exception in Python 3.5.
18028
18029       · #1949: Use safe_getattr in the coverage  builder  to  avoid  aborting
18030         with descriptors that have custom behavior.
18031
18032       · #1915: Do not generate smart quotes in doc field type annotations.
18033
18034       · #1796: On py3, automated .mo building caused UnicodeDecodeError.
18035
18036       · #1923:  Use  babel  features  only  if  the  babel  latex  element is
18037         nonempty.
18038
18039       · #1942: Fix a KeyError in websupport.
18040
18041       · #1903: Fix strange id generation for glossary terms.
18042
18043       · make text will crush if a definition list item has more than 1  clas‐
18044         sifiers as: term : classifier1 : classifier2.
18045
18046       · #1855:  make  gettext  generates  broken po file for definition lists
18047         with classifier.
18048
18049       · #1869: Fix problems when  dealing  with  files  containing  non-ASCII
18050         characters. Thanks to Marvin Schmidt.
18051
18052       · #1798: Fix building LaTeX with references in titles.
18053
18054       · #1725:  On  py2  environment, doctest with using non-ASCII characters
18055         causes 'ascii' codec can't decode byte exception.
18056
18057       · #1540: Fix RuntimeError with circular referenced toctree
18058
18059       · #1983: i18n translation feature breaks references which uses  section
18060         name.
18061
18062       · #1990: Use caption of toctree to title of tableofcontents in LaTeX
18063
18064       · #1987:  Fix ampersand is ignored in :menuselection: and :guilabel: on
18065         LaTeX builder
18066
18067       · #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
18071       · #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
18075       · On Py2 environment, conf.py that is  generated  by  sphinx-quickstart
18076         should have u prefixed config value for ‘version’ and ‘release’.
18077
18078       · #2102: On Windows + Py3, using |today| and non-ASCII date format will
18079         raise UnicodeEncodeError.
18080
18081       · #1974: UnboundLocalError: local variable ‘domain’  referenced  before
18082         assignment  when  using  any  role and sphinx.ext.intersphinx in same
18083         time.
18084
18085       · #2121: multiple words search doesn’t find pages when words across  on
18086         the page title and the page content.
18087
18088       · #1884,  #1885:  plug-in  html  themes  cannot inherit another plug-in
18089         theme. Thanks to Suzumizaki.
18090
18091       · #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
18096       · #2140: Fix footnotes in table has broken in LaTeX
18097
18098       · #2127:  MecabBinder  for  html  searching  feature  doesn’t work with
18099         Python 3.  Thanks to Tomoko Uchida.
18100
18101   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
18107       · #1773: sphinx-quickstart doesn’t  accept  non-ASCII  character  as  a
18108         option argument.
18109
18110       · #1766: the message “least Python 2.6 to run” is at best misleading.
18111
18112       · #1772:  cross  reference  in  docstrings  like  :param .write: breaks
18113         building.
18114
18115       · #1770, #1774: literalinclude with empty file occurs exception. Thanks
18116         to Takayuki Hirai.
18117
18118       · #1777: Sphinx 1.3 can’t load extra theme. Thanks to tell-k.
18119
18120       · #1776:  source_suffix = ['.rst'] cause unfriendly error on prior ver‐
18121         sion.
18122
18123       · #1771: automated .mo building doesn’t work properly.
18124
18125       · #1783: Autodoc: Python2 Allow unicode string in __all__.   Thanks  to
18126         Jens Hedegaard Nielsen.
18127
18128       · #1781:  Setting  html_domain_indices  to  a  list raises a type check
18129         warnings.
18130
18131   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
18136       · Role numref uses %s as special character to indicate position of fig‐
18137         ure numbers instead # symbol.
18138
18139   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
18145       · The  source_suffix  config  value  can now be a list of multiple suf‐
18146         fixes.
18147
18148       · Add the ability to specify source parsers by source suffix  with  the
18149         source_parsers config value.
18150
18151       · #1675:  A  new  builder, AppleHelpBuilder, has been added that builds
18152         Apple Help Books.
18153
18154   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
18158       · #1745:  latex  builder  cause maximum recursion depth exceeded when a
18159         footnote has a footnote mark itself.
18160
18161       · #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6.
18162
18163       · #1658, #1750: No link created (and warning given) if option does  not
18164         begin with -, / or +. Thanks to Takayuki Hirai.
18165
18166       · #1753: C++, added missing support for more complex declarations.
18167
18168       · #1700: Add :caption: option for toctree.
18169
18170       · #1742: :name: option is provided for toctree, code-block and literal‐
18171         include dirctives.
18172
18173       · #1756: Incorrect section titles in search that  was  introduced  from
18174         1.3b3.
18175
18176       · #1746: C++, fixed name lookup procedure, and added missing lookups in
18177         declarations.
18178
18179       · #1765: C++, fix old id generation to use fully qualified names.
18180
18181   Documentation
18182       · #1651: Add vartype field descritpion for python domain.
18183
18184   Release 1.3b3 (released Feb 24, 2015)
18185   Incompatible changes
18186       · Dependency requirement updates: docutils 0.11, Pygments 2.0
18187
18188       · The gettext_enables config value has been  renamed  to  gettext_addi‐
18189         tional_targets.
18190
18191       · #1735: Use https://docs.python.org/ instead of http protocol.  It was
18192         used for sphinx.ext.intersphinx and some documentation.
18193
18194   Features added
18195       · #1346: Add new default theme;
18196
18197         · Add ‘alabaster’ theme.
18198
18199         · Add ‘sphinx_rtd_theme’ theme.
18200
18201         · 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
18205       · Added highlight_options configuration value.
18206
18207       · The language config value is now available in the HTML templates.
18208
18209       · 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
18212       · #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
18216       · Add todo_include_todos config option to quickstart conf file, handled
18217         as described in documentation.
18218
18219       · HTML breadcrumb items tag has class “nav-item” and “nav-item-N” (like
18220         nav-item-0, 1, 2…).
18221
18222       · New  option sphinx-quickstart --use-make-mode for generating Makefile
18223         that use sphinx-build make-mode.
18224
18225       · #1235: i18n: several node can be translated if  it  is  set  to  get‐
18226         text_additional_targets in conf.py. Supported nodes are:
18227
18228         · ‘literal-block’
18229
18230         · ‘doctest-block’
18231
18232         · ‘raw’
18233
18234         · ‘image’
18235
18236       · #1227:  Add  html_scaled_image_link config option to conf.py, to con‐
18237         trol scaled image link.
18238
18239   Bugs fixed
18240       · LaTeX writer now generates correct markup for cells spanning multiple
18241         rows.
18242
18243       · #1674: Do not crash if a module’s __all__ is not a list of strings.
18244
18245       · #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
18246
18247       · On  windows,  make-mode  didn’t  work on Win32 platform if sphinx was
18248         invoked as python sphinx-build.py.
18249
18250       · #1687: linkcheck now treats 401 Unauthorized responses as “working”.
18251
18252       · #1690: toctrees with glob option now can  also  contain  entries  for
18253         single documents with explicit title.
18254
18255       · #1591: html search results for C++ elements now has correct interpage
18256         links.
18257
18258       · bizstyle theme: nested long title pages  make  long  breadcrumb  that
18259         breaks page layout.
18260
18261       · bizstyle  theme:  all  breadcrumb  items  become ‘Top’ on some mobile
18262         browser (iPhone5s safari).
18263
18264       · #1722: restore toctree() template function behavior that was  changed
18265         at 1.3b1.
18266
18267       · #1732: i18n: localized table caption raises exception.
18268
18269       · #1718: :numref: does not work with capital letters in the label
18270
18271       · #1630:  resolve  CSS  conflicts, div.container css target for literal
18272         block wrapper now renamed to div.literal-block-wrapper.
18273
18274       · sphinx.util.pycompat has been restored in  its  backwards-compatibil‐
18275         ity; slated for removal in Sphinx 1.4.
18276
18277       · #1719: LaTeX writer does not respect numref_format option in captions
18278
18279   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
18284   Features added
18285       · #1597:  Added  possibility  to  return  a  new  template  name   from
18286         html-page-context.
18287
18288       · 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
18292   Bugs fixed
18293       · PR#311: sphinx-quickstart does not work on python 3.4.
18294
18295       · Fix  autodoc_docstring_signature not working with signatures in class
18296         docstrings.
18297
18298       · Rebuilding cause crash unexpectedly when source files were added.
18299
18300       · #1607: Fix a crash when building latexpdf with “howto” class
18301
18302       · #1251: Fix again. Sections which  depth  are  lower  than  :tocdepth:
18303         should not be shown on localtoc sidebar.
18304
18305       · make-mode  didn’t  work  on Win32 platform if sphinx was installed by
18306         wheel package.
18307
18308   Release 1.3b1 (released Oct 10, 2014)
18309   Incompatible changes
18310       · Dropped support for Python 2.5, 3.1 and 3.2.
18311
18312       · Dropped support for docutils versions up to 0.9.
18313
18314       · Removed the sphinx.ext.oldcmarkup extension.
18315
18316       · The deprecated  config  values  exclude_trees,  exclude_dirnames  and
18317         unused_docs have been removed.
18318
18319       · 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
18323       · 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
18327       · #1543:  templates_path  is automatically added to exclude_patterns to
18328         avoid reading autosummary rst templates in the templates directory.
18329
18330       · Custom  domains  should  implement  the  new  Domain.resolve_any_xref
18331         method to make the any role work properly.
18332
18333       · 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
18338       · gettext builder: disable extracting/apply ‘index’  node  by  default.
18339         Please  set  ‘index’  to  gettext_enables  to enable extracting index
18340         entries.
18341
18342       · PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya.
18343
18344   Features added
18345       · Add support for Python 3.4.
18346
18347       · Add support for docutils 0.12
18348
18349       · Added sphinx.ext.napoleon extension for NumPy and Google  style  doc‐
18350         string support.
18351
18352       · 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
18357       · 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
18361       · Exception logs now contain the last 10 messages emitted by Sphinx.
18362
18363       · 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
18368       · Changing  the  default  role  within a document with the default-role
18369         directive is now supported.
18370
18371       · 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
18374       · 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
18379       · PR#202: Allow “.” and “~” prefixed references in :param:  doc  fields
18380         for Python.
18381
18382       · PR#184:  Add autodoc_mock_imports, allowing to mock imports of exter‐
18383         nal modules that need not be present when autodocumenting.
18384
18385       · #925: Allow list-typed config values to be provided  on  the  command
18386         line, like -D key=val1,val2.
18387
18388       · #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
18392       · 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
18396       · Prompt for the document language in sphinx-quickstart.
18397
18398       · PR#217: Added config values to suppress UUID and location information
18399         in generated gettext catalogs.
18400
18401       · PR#236, #1456: apidoc: Add a -M option to  put  module  documentation
18402         before submodule documentation. Thanks to Wes Turner and Luc Saffre.
18403
18404       · #1434:  Provide non-minified JS files for jquery.js and underscore.js
18405         to clarify the source of the minified files.
18406
18407       · PR#252, #1291: Windows color console support. Thanks to meu31.
18408
18409       · 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
18413       · PR#229: Allow registration of other translators.  Thanks  to  Russell
18414         Sim.
18415
18416       · Add  app.set_translator()  API  to  register  or  override a Docutils
18417         translator class like html_translator_class.
18418
18419       · PR#267, #1134: add ‘diff’  parameter  to  literalinclude.  Thanks  to
18420         Richard Wall and WAKAYAMA shirou.
18421
18422       · PR#272: Added ‘bizstyle’ theme. Thanks to Shoji KUMAGAI.
18423
18424       · Automatically   compile   *.mo   files  from  *.po  files  when  get‐
18425         text_auto_build is True (default) and *.po is newer than *.mo file.
18426
18427       · #623: sphinx.ext.viewcode supports imported function/class aliases.
18428
18429       · PR#275:  sphinx.ext.intersphinx  supports  multiple  target  for  the
18430         inventory. Thanks to Brigitta Sipocz.
18431
18432       · 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
18436       · #1284: Program options documented with option can now start with +.
18437
18438       · PR#291:  The  caption  of  code-block is recognised as a title of ref
18439         target. Thanks to Takeshi Komiya.
18440
18441       · PR#298: Add new API: add_latex_package().  Thanks to Takeshi Komiya.
18442
18443       · #1344: add gettext_enables to enable extracting  ‘index’  to  gettext
18444         catalog output / applying translation catalog to generated documenta‐
18445         tion.
18446
18447       · 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
18451       · PR#299: add various options to sphinx-quickstart. Quiet  mode  option
18452         --quiet will skips wizard mode. Thanks to WAKAYAMA shirou.
18453
18454       · #1623:  Return types specified with :rtype: are now turned into links
18455         if possible.
18456
18457   Bugs fixed
18458       · #1438: Updated jQuery version from 1.8.3 to 1.11.1.
18459
18460       · #1568: Fix a crash when a “centered” directive contains a reference.
18461
18462       · Now sphinx.ext.autodoc works with python-2.5 again.
18463
18464       · #1563: add_search_language() raises AssertionError for  correct  type
18465         of argument. Thanks to rikoman.
18466
18467       · #1174:  Fix  smart  quotes being applied inside roles like program or
18468         makevar.
18469
18470       · PR#235: comment db schema  of  websupport  lacked  a  length  of  the
18471         node_id field.  Thanks to solos.
18472
18473       · #1466,PR#241:  Fix  failure  of  the  cpp domain parser to parse C+11
18474         “variadic templates” declarations. Thanks to Victor Zverovich.
18475
18476       · #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
18479       · PR#157:  autodoc  remove spurious signatures from @property decorated
18480         attributes. Thanks to David Ham.
18481
18482       · PR#159: Add coverage targets to  quickstart  generated  Makefile  and
18483         make.bat.  Thanks to Matthias Troffaes.
18484
18485       · #1251: When specifying toctree :numbered: option and :tocdepth: meta‐
18486         data, sub section number that is  larger  depth  than  :tocdepth:  is
18487         shrunk.
18488
18489       · PR#260: Encode underscore in citation labels for latex export. Thanks
18490         to Lennart Fricke.
18491
18492       · PR#264: Fix could not  resolve  xref  for  figure  node  with  :name:
18493         option.  Thanks to Takeshi Komiya.
18494
18495       · PR#265:  Fix  could  not  capture  caption  of graphviz node by xref.
18496         Thanks to Takeshi Komiya.
18497
18498       · PR#263, #1013, #1103: Rewrite of C++ domain. Thanks  to  Jakob  Lykke
18499         Andersen.
18500
18501         · Hyperlinks  to  all  found  nested  names  and  template  arguments
18502           (#1103).
18503
18504         · Support  for  function  types  everywhere,  e.g.,   in   std::func‐
18505           tion<bool(int, int)> (#1013).
18506
18507         · Support for virtual functions.
18508
18509         · 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
18513         · Updated tests.
18514
18515         · 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
18519         · 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
18523       · PR#258,  #939:  Add  dedent option for code-block and literalinclude.
18524         Thanks to Zafar Siddiqui.
18525
18526       · 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
18530       · PR#273, #1536:  Fix  RuntimeError  with  numbered  circular  toctree.
18531         Thanks to Takeshi Komiya.
18532
18533       · PR#274:  Set  its URL as a default title value if URL appears in toc‐
18534         tree.  Thanks to Takeshi Komiya.
18535
18536       · PR#276, #1381: rfc and pep roles support custom link text. Thanks  to
18537         Takeshi Komiya.
18538
18539       · PR#277,  #1513:  highlights for function pointers in argument list of
18540         c:function. Thanks to Takeshi Komiya.
18541
18542       · PR#278: Fix section entries were shown twice if toctree has been  put
18543         under only directive. Thanks to Takeshi Komiya.
18544
18545       · #1547:  pgen2  tokenizer  doesn’t recognize ... literal (Ellipsis for
18546         py3).
18547
18548       · 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
18552       · PR#295, #1520: make.bat latexpdf mechanism to cd back to the  current
18553         directory. Thanks to Peter Suter.
18554
18555       · PR#297,  #1571:  Add imgpath property to all builders. It make easier
18556         to develop builder extensions. Thanks to Takeshi Komiya.
18557
18558       · #1584: Point to master doc in HTML “top” link.
18559
18560       · #1585: Autosummary of modules broken in Sphinx-1.2.3.
18561
18562       · #1610: Sphinx  cause  AttributeError  when  MeCab  search  option  is
18563         enabled and python-mecab is not installed.
18564
18565       · #1674: Do not crash if a module’s __all__ is not a list of strings.
18566
18567       · #1673: Fix crashes with nitpick_ignore and :doc: references.
18568
18569       · #1686: ifconfig directive doesn’t care about default config values.
18570
18571       · #1642: Fix only one search result appearing in Chrome.
18572
18573   Documentation
18574       · Add clarification about the syntax of tags. (doc/markup/misc.rst)
18575
18576   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
18581       · New locales: Hebrew, European Portuguese, Vietnamese.
18582
18583   Bugs fixed
18584       · #636: Keep straight single quotes in  literal  blocks  in  the  LaTeX
18585         build.
18586
18587       · #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
18591       · #1363:  Fix  i18n: missing python domain’s cross-references with cur‐
18592         rentmodule directive or currentclass directive.
18593
18594       · #1444: autosummary does not create the  description  from  attributes
18595         docstring.
18596
18597       · #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
18601       · #1467:  Exception  on  Python3  if nonexistent method is specified by
18602         automethod
18603
18604       · #1441: autosummary can’t handle nested classes correctly.
18605
18606       · #1499: With non-callable setup in a conf.py, now sphinx-build emits a
18607         user-friendly error message.
18608
18609       · #1502: In autodoc, fix display of parameter defaults containing back‐
18610         slashes.
18611
18612       · #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
18616       · #1503: py:function  directive  generate  incorrectly  signature  when
18617         specifying a default parameter with an empty list []. Thanks to Geert
18618         Jansen.
18619
18620       · #1508: Non-ASCII filename raise exception on make singlehtml,  latex,
18621         man, texinfo and changes.
18622
18623       · #1531:  On Python3 environment, docutils.conf with ‘source_link=true’
18624         in the general section cause type error.
18625
18626       · PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses
18627         with inheritance-diagram directive. Thanks to WAKAYAMA shirou.
18628
18629       · PR#281, PR#282, #1509: TODO extension not compatible with websupport.
18630         Thanks to Takeshi Komiya.
18631
18632       · #1477: gettext does not extract nodes.line in a table or list.
18633
18634       · #1544: make text generates wrong table when it has empty table cells.
18635
18636       · #1522: Footnotes from table get displayed twice in LaTeX. This  prob‐
18637         lem has been appeared from Sphinx-1.2.1 by #949.
18638
18639       · #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
18643   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
18648       · PR#212: Fix traceback with autodoc and __init__ methods without  doc‐
18649         string.
18650
18651       · PR#213: Fix a missing import in the setup command.
18652
18653       · #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
18656       · #1358: Fix handling of image paths outside of  the  source  directory
18657         when using the “wildcard” style reference.
18658
18659       · #1374:  Fix for autosummary generating overly-long summaries if first
18660         line doesn’t end with a period.
18661
18662       · #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
18663
18664       · #1391: Actually prevent using “pngmath” and “mathjax”  extensions  at
18665         the same time in sphinx-quickstart.
18666
18667       · #1386:  Fix  bug  preventing  more  than one theme being added by the
18668         entry point mechanism.
18669
18670       · #1370: Ignore “toctree” nodes in text writer, instead of raising.
18671
18672       · #1364: Fix ‘make gettext’ fails when the ‘.. todolist::’ directive is
18673         present.
18674
18675       · #1367:   Fix   a   change   of   PR#96  that  break  sphinx.util.doc‐
18676         fields.Field.make_field interface/behavior for item argument usage.
18677
18678   Documentation
18679       · Extended the documentation about building extensions.
18680
18681   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
18687       · #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
18691       · #1340: Can’t search alphabetical words on the HTML quick search  gen‐
18692         erated with language=’ja’.
18693
18694       · #1319: Do not crash if the html_logo file does not exist.
18695
18696       · #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
18700       · #751:  Allow  production  lists  longer than a page in LaTeX by using
18701         longtable.
18702
18703       · #764: Always look for stopwords lowercased in JS search.
18704
18705       · #814: autodoc: Guard against strange type  objects  that  don’t  have
18706         __bases__.
18707
18708       · #932: autodoc: Do not crash if __doc__ is not a string.
18709
18710       · #933:  Do  not crash if an option value is malformed (contains spaces
18711         but no option name).
18712
18713       · #908: On Python 3, handle error messages from LaTeX correctly in  the
18714         pngmath extension.
18715
18716       · #943:  In  autosummary,  recognize “first sentences” to pull from the
18717         docstring if they contain uppercase letters.
18718
18719       · #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
18723       · #901: Emit a warning when using docutils’ new “math” markup without a
18724         Sphinx math extension active.
18725
18726       · #845:  In  code  blocks,  when the selected lexer fails, display line
18727         numbers nevertheless if configured.
18728
18729       · #929: Support parsed-literal blocks in LaTeX output correctly.
18730
18731       · #949: Update the tabulary.sty packed with Sphinx.
18732
18733       · #1050: Add anonymous labels into objects.inv  to  be  referenced  via
18734         intersphinx.
18735
18736       · #1095:  Fix  print-media  stylesheet  being  included  always  in the
18737         “scrolls” theme.
18738
18739       · #1085: Fix current classname not getting set if class description has
18740         :noindex: set.
18741
18742       · #1181: Report option errors in autodoc directives more gracefully.
18743
18744       · #1155:  Fix autodocumenting C-defined methods as attributes in Python
18745         3.
18746
18747       · #1233: Allow finding both Python  classes  and  exceptions  with  the
18748         “class” and “exc” roles in intersphinx.
18749
18750       · #1198:  Allow  “image” for the “figwidth” option of the figure direc‐
18751         tive as documented by docutils.
18752
18753       · #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
18757       · #1017: Be helpful and tell the user when the argument to option  does
18758         not match the required format.
18759
18760       · #1345: Fix two bugs with nitpick_ignore; now you don’t have to remove
18761         the store environment for changes to have effect.
18762
18763       · #1072: In the JS search, fix issues searching for  upper-cased  words
18764         by lowercasing words before stemming.
18765
18766       · #1299:  Make behavior of the math directive more consistent and avoid
18767         producing empty environments in LaTeX output.
18768
18769       · #1308: Strip HTML tags from the content of “raw” nodes before feeding
18770         it to the search indexer.
18771
18772       · #1249: Fix duplicate LaTeX page numbering for manual documents.
18773
18774       · #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
18778       · #1285:  Avoid  name  clashes  between  C  domain  objects and section
18779         titles.
18780
18781       · #848: Always take the newest code in incremental  rebuilds  with  the
18782         sphinx.ext.viewcode extension.
18783
18784       · #979, #1266: Fix exclude handling in sphinx-apidoc.
18785
18786       · #1302:  Fix  regression  in sphinx.ext.inheritance_diagram when docu‐
18787         menting classes that can’t be pickled.
18788
18789       · #1316: Remove hard-coded font-face resources from epub theme.
18790
18791       · #1329: Fix traceback with empty translation msgstr in .po files.
18792
18793       · #1300: Fix references not working in  translated  documents  in  some
18794         instances.
18795
18796       · #1283:  Fix a bug in the detection of changed files that would try to
18797         access doctrees of deleted documents.
18798
18799       · #1330: Fix  exclude_patterns  behavior  with  subdirectories  in  the
18800         html_static_path.
18801
18802       · #1323:  Fix emitting empty <ul> tags in the HTML writer, which is not
18803         valid HTML.
18804
18805       · #1147: Don’t emit a sidebar search box in the “singlehtml” builder.
18806
18807   Documentation
18808       · #1325: Added a “Intersphinx” tutorial section. (doc/tutorial.rst)
18809
18810   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
18815   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
18819   Bugs fixed
18820       · Restore versionmodified CSS class for versionadded/changed and depre‐
18821         cated directives.
18822
18823       · 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
18827       · #1296:  Fix  invalid  charset  in  HTML help generated HTML files for
18828         default locale.
18829
18830       · PR#190: Fix gettext does not extract figure caption and rubric  title
18831         inside other blocks. Thanks to Michael Schlenker.
18832
18833       · PR#176: Make sure setup_command test can always import Sphinx. Thanks
18834         to Dmitry Shachnev.
18835
18836       · #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
18837
18838       · #1269: Fix ResourceWarnings with Python 3.2 or later.
18839
18840       · #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
18844   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
18849   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
18854   Bugs fixed
18855       · #1265:  Fix  i18n:  crash  when  translating  a  section name that is
18856         pointed to from a named target.
18857
18858       · 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
18861       · #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
18865   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
18870       · 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
18874       · 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
18877       · Builders: rebuild i18n target document when catalog updated.
18878
18879       · 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
18883       · 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
18887       · 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
18891       · PR#136:  Autodoc directives now support an imported-members option to
18892         include members imported from different modules.
18893
18894       · New locales: Macedonian, Sinhala, Indonesian.
18895
18896       · Theme package collection by using setuptools plugin mechanism.
18897
18898   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
18903   Bugs fixed
18904       · PR#132: Updated jQuery version to 1.8.3.
18905
18906       · PR#141, #982: Avoid crash when  writing  PNG  file  using  Python  3.
18907         Thanks to Marcin Wojdyr.
18908
18909       · PR#145:  In  parallel  builds,  sphinx  drops second document file to
18910         write.  Thanks to tychoish.
18911
18912       · PR#151: Some styling updates to tables in LaTeX.
18913
18914       · PR#153: The “extensions” config value can now be overridden.
18915
18916       · PR#155: Added support for some C++11 function qualifiers.
18917
18918       · Fix: ‘make gettext’ caused UnicodeDecodeError when templates  contain
18919         utf-8 encoded strings.
18920
18921       · #828:  use  inspect.getfullargspec() to be able to document functions
18922         with keyword-only arguments on Python 3.
18923
18924       · #1090: Fix i18n: multiple cross references (term, ref,  doc)  in  the
18925         same line return the same link.
18926
18927       · #1157:  Combination  of  ‘globaltoc.html’  and  hidden toctree caused
18928         exception.
18929
18930       · #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
18934       · #1160: Citation target missing caused an AssertionError.
18935
18936       · #1162, PR#139: singlehtml builder didn’t copy images to _images/.
18937
18938       · #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
18942       · #1185: Don’t crash when a Python module has a wrong  or  no  encoding
18943         declared, and non-ASCII characters are included.
18944
18945       · #1188:  sphinx-quickstart  raises UnicodeEncodeError if “Project ver‐
18946         sion” includes non-ASCII characters.
18947
18948       · #1189: “Title underline is too short” WARNING  is  given  when  using
18949         fullwidth characters to “Project name” on quickstart.
18950
18951       · #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
18955       · #1192: Fix escaping problem for hyperlinks in the manpage writer.
18956
18957       · #1193: Fix i18n: multiple link references in the same line return the
18958         same link.
18959
18960       · #1176: Fix i18n: footnote reference number missing for auto  numbered
18961         named footnote and auto symbol footnote.
18962
18963       · PR#146,#1172:  Fix  ZeroDivisionError  in  parallel builds. Thanks to
18964         tychoish.
18965
18966       · #1204: Fix wrong generation of links to local intersphinx targets.
18967
18968       · #1206: Fix i18n: gettext did  not  translate  admonition  directive’s
18969         title.
18970
18971       · #1232: Sphinx generated broken ePub files on Windows.
18972
18973       · #1259:  Guard  the debug output call when emitting events; to prevent
18974         the repr() implementation of arbitrary objects  causing  build  fail‐
18975         ures.
18976
18977       · #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X.
18978
18979       · #1234: Ignoring the string consists only of white-space characters.
18980
18981   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
18986       · PR#122: the files given in latex_additional_files  now  override  TeX
18987         files included by Sphinx, such as sphinx.sty.
18988
18989       · 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
18994       · PR#99: the seealso directive now generates admonition  nodes  instead
18995         of the custom seealso node.
18996
18997   Features added
18998       · Markup
18999
19000         · 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
19005         · 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
19010       · HTML builder
19011
19012         · #783:  Create  a link to full size image if it is scaled with width
19013           or height.
19014
19015         · #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
19020         · #1053:  The  “rightsidebar”  and  “collapsiblesidebar”  HTML  theme
19021           options now work together.
19022
19023         · Update to jQuery 1.7.1 and Underscore.js 1.3.1.
19024
19025       · Texinfo builder
19026
19027         · An “Index” node is no longer added when there are no entries.
19028
19029         · “deffn” categories are no longer capitalized if they contain  capi‐
19030           tal letters.
19031
19032         · desc_annotation nodes are now rendered.
19033
19034         · 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
19039         · Field lists formatting has been tweaked  to  better  display  “Info
19040           field lists”.
19041
19042         · system_message and problematic nodes are now formatted in a similar
19043           fashion as done by the text builder.
19044
19045         · “en-dash” and “em-dash” conversion of hyphens  is  no  longer  per‐
19046           formed in option directive signatures.
19047
19048         · @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
19052         · The @finalout command has been added for better TeX output.
19053
19054         · transition  nodes are now formatted using underscores (“_”) instead
19055           of asterisks (“*”).
19056
19057         · The default value for the paragraphindent has been changed  from  2
19058           to 0 meaning that paragraphs are no longer indented by default.
19059
19060         · #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
19064         · Detailed menus are no longer created except for the “Top” node.
19065
19066         · Fixed  an  issue  where  duplicate  domain  indices would result in
19067           invalid output.
19068
19069       · LaTeX builder:
19070
19071         · PR#115: Add 'transition' item in latex_elements for customizing how
19072           transitions are displayed. Thanks to Jeff Klukas.
19073
19074         · 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
19078         · The  'fontpkg'  item  in latex_elements now defaults to '' when the
19079           language uses the Cyrillic script.  Suggested by Dmitry Shachnev.
19080
19081         · 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
19086       · Internationalization:
19087
19088         · 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
19093         · PR#61,#703: Add support for non-ASCII filename handling.
19094
19095       · Other builders:
19096
19097         · Added the Docutils-native XML and pseudo-XML  builders.   See  XML‐
19098           Builder and PseudoXMLBuilder.
19099
19100         · PR#45: The linkcheck builder now checks #anchors for existence.
19101
19102         · 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
19105         · 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
19109         · PR#112: Add epub_show_urls configuration value.
19110
19111       · Extensions:
19112
19113         · PR#52: special_members flag to autodoc now behaves like members.
19114
19115         · PR#47: Added sphinx.ext.linkcode extension.
19116
19117         · PR#25: In inheritance diagrams, the first line of  the  class  doc‐
19118           string is now the tooltip for the class.
19119
19120       · Command-line interfaces:
19121
19122         · PR#75: Added --follow-links option to sphinx-apidoc.
19123
19124         · #869:  sphinx-build  now  has  the  option -T for printing the full
19125           traceback after an unhandled exception.
19126
19127         · sphinx-build  now  supports  the  standard  --help  and   --version
19128           options.
19129
19130         · sphinx-build  now provides more specific error messages when called
19131           with invalid options or arguments.
19132
19133         · 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
19138       · Locales:
19139
19140         · PR#74: Fix some Russian translation.
19141
19142         · PR#54: Added Norwegian bokmaal translation.
19143
19144         · PR#35: Added Slovak translation.
19145
19146         · PR#28: Added Hungarian translation.
19147
19148         · #1113: Add Hebrew locale.
19149
19150         · #1097: Add Basque locale.
19151
19152         · #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
19153
19154         · #1012: Update Estonian translation.
19155
19156       · Optimizations:
19157
19158         · 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
19162         · PR#108:  Add  experimental support for parallel building with a new
19163           sphinx-build -j option.
19164
19165   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
19169       · Added a detailed “Installing Sphinx” document (doc/install.rst).
19170
19171   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
19176       · PR#111:  Respect add_autodoc_attrgetter() even when inherited-members
19177         is set.  Thanks to A. Jesse Jiryu Davis.
19178
19179       · PR#97: Fix footnote handling in translated documents.
19180
19181       · Fix text writer not handling visit_legend for figure  directive  con‐
19182         tents.
19183
19184       · Fix  text  builder  not  respecting  wide/fullwidth characters: title
19185         underline width, table layout width and text wrap width.
19186
19187       · Fix leading space in LaTeX table header cells.
19188
19189       · #1132: Fix LaTeX table output for multi-row cells in the  first  col‐
19190         umn.
19191
19192       · #1128:  Fix  Unicode errors when trying to format time strings with a
19193         non-standard locale.
19194
19195       · #1127: Fix traceback when autodoc  tries  to  tokenize  a  non-Python
19196         file.
19197
19198       · #1126:  Fix  double-hyphen to en-dash conversion in wrong places such
19199         as command-line option names in LaTeX.
19200
19201       · #1123: Allow whitespaces in filenames given to literalinclude.
19202
19203       · #1120: Added improvements about i18n for themes “basic”, “haiku”  and
19204         “scrolls” that Sphinx built-in. Thanks to Leonardo J. Caballero G.
19205
19206       · #1118:  Updated  Spanish translation. Thanks to Leonardo J. Caballero
19207         G.
19208
19209       · #1117: Handle .pyx files in sphinx-apidoc.
19210
19211       · #1112: Avoid duplicate download files when referenced from  documents
19212         in different ways (absolute/relative).
19213
19214       · #1111:   Fix   failure   to  find  uppercase  words  in  search  when
19215         html_search_language is ‘ja’. Thanks to Tomo Saito.
19216
19217       · #1108: The text writer now correctly numbers  enumerated  lists  with
19218         non-default start values (based on patch by Ewan Edwards).
19219
19220       · #1102: Support multi-context “with” statements in autodoc.
19221
19222       · #1090: Fix gettext not extracting glossary terms.
19223
19224       · #1074:  Add environment version info to the generated search index to
19225         avoid compatibility issues with old builds.
19226
19227       · #1070: Avoid un-pickling issues when running Python 3 and  the  saved
19228         environment was created under Python 2.
19229
19230       · #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
19234       · #1062:  sphinx.ext.autodoc  use  __init__  method signature for class
19235         signature.
19236
19237       · #1055: Fix web support with relative path to source directory.
19238
19239       · #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
19243       · #1041: Fix failure of the cpp domain parser to  parse  a  const  type
19244         with a modifier.
19245
19246       · #1038:  Fix  failure  of  the cpp domain parser to parse C+11 “static
19247         constexpr” declarations.  Thanks to Jakub Wilk.
19248
19249       · #1029: Fix intersphinx_mapping values not being stable if the mapping
19250         has plural key/value set with Python 3.3.
19251
19252       · #1028: Fix line block output in the text builder.
19253
19254       · #1024:  Improve  Makefile/make.bat  error  message  if  Sphinx is not
19255         found. Thanks to Anatoly Techtonik.
19256
19257       · #1018: Fix “container” directive handling in the text builder.
19258
19259       · #1015: Stop overriding jQuery contains() in the JavaScript.
19260
19261       · #1010: Make pngmath images transparent by default; IE7+ should handle
19262         it.
19263
19264       · #1008: Fix test failures with Python 3.3.
19265
19266       · #995:  Fix table-of-contents and page numbering for the LaTeX “howto”
19267         class.
19268
19269       · #976: Fix gettext does not extract index entries.
19270
19271       · PR#72: #975: Fix gettext not extracting definition terms before docu‐
19272         tils 0.10.
19273
19274       · #961: Fix LaTeX output for triple quotes in code snippets.
19275
19276       · #958: Do not preserve environment.pickle after a failed build.
19277
19278       · #955: Fix i18n transformation.
19279
19280       · #940: Fix gettext does not extract figure caption.
19281
19282       · #920:  Fix  PIL  packaging issue that allowed to import Image without
19283         PIL namespace.  Thanks to Marc Schlaich.
19284
19285       · #723: Fix  the  search  function  on  local  files  in  WebKit  based
19286         browsers.
19287
19288       · #440: Fix coarse timestamp resolution in some filesystem generating a
19289         wrong list of outdated files.
19290
19291   Release 1.1.3 (Mar 10, 2012)
19292       · PR#40: Fix safe_repr function to decode  bytestrings  with  non-ASCII
19293         characters correctly.
19294
19295       · PR#37: Allow configuring sphinx-apidoc via SPHINX_APIDOC_OPTIONS.
19296
19297       · PR#34: Restore Python 2.4 compatibility.
19298
19299       · PR#36: Make the “bibliography to TOC” fix in LaTeX output specific to
19300         the document class.
19301
19302       · #695: When the highlight language “python” is  specified  explicitly,
19303         do not try to parse the code to recognize non-Python snippets.
19304
19305       · #859:  Fix  exception  under  certain  circumstances when not finding
19306         appropriate objects to link to.
19307
19308       · #860: Do not crash when encountering invalid doctest  examples,  just
19309         emit a warning.
19310
19311       · #864: Fix crash with some settings of modindex_common_prefix.
19312
19313       · #862: Fix handling of -D and -A options on Python 3.
19314
19315       · #851:  Recognize and warn about circular toctrees, instead of running
19316         into recursion errors.
19317
19318       · #853: Restore compatibility with docutils trunk.
19319
19320       · #852: Fix HtmlHelp index entry links again.
19321
19322       · #854: Fix inheritance_diagram raising attribute errors on builtins.
19323
19324       · #832: Fix crashes when putting comments or lone terms in a glossary.
19325
19326       · #834, #818: Fix HTML help language/encoding mapping  for  all  Sphinx
19327         supported languages.
19328
19329       · #844:  Fix crashes when dealing with Unicode output in doctest exten‐
19330         sion.
19331
19332       · #831: Provide --project flag in setup_command as advertised.
19333
19334       · #875: Fix reading config files under Python 3.
19335
19336       · #876: Fix quickstart test under Python 3.
19337
19338       · #870: Fix spurious KeyErrors when removing documents.
19339
19340       · #892: Fix single-HTML builder misbehaving with the master document in
19341         a subdirectory.
19342
19343       · #873: Fix assertion errors with empty only directives.
19344
19345       · #816: Fix encoding issues in the Qt help builder.
19346
19347   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
19350   Release 1.1.1 (Nov 1, 2011)
19351       · #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
19352
19353       · #792: Include “sphinx-apidoc” in the source distribution.
19354
19355       · #797: Don’t crash on a misformatted glossary.
19356
19357       · #801: Make intersphinx work properly without SSL support.
19358
19359       · #805: Make the Sphinx.add_index_to_domain method work correctly.
19360
19361       · #780: Fix Python 2.5 compatibility.
19362
19363   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
19369       · Removed support for old dependency versions; requirements are now:
19370
19371         · Pygments >= 1.2
19372
19373         · Docutils >= 0.7
19374
19375         · Jinja2   >= 2.3
19376
19377   Features added
19378       · Added Python 3.x support.
19379
19380       · New builders and subsystems:
19381
19382         · Added a Texinfo builder.
19383
19384         · Added i18n support for content, a gettext builder and related util‐
19385           ities.
19386
19387         · Added the websupport library and builder.
19388
19389         · #98: Added a sphinx-apidoc script that autogenerates a hierarchy of
19390           source  files containing autodoc directives to document modules and
19391           packages.
19392
19393         · #273: Add an API for adding full-text search support for  languages
19394           other than English.  Add support for Japanese.
19395
19396       · Markup:
19397
19398         · #138: Added an index role, to make inline index entries.
19399
19400         · #454:  Added  more  index  markup capabilities: marking see/seealso
19401           entries, and main entries for a given key.
19402
19403         · #460: Allowed limiting the depth of section numbers for HTML  using
19404           the toctree’s numbered option.
19405
19406         · #586:  Implemented  improved  glossary markup which allows multiple
19407           terms per definition.
19408
19409         · #478: Added py:decorator directive to describe decorators.
19410
19411         · C++ domain now supports array definitions.
19412
19413         · C++ domain now supports doc fields (:param x: inside directives).
19414
19415         · Section headings in only directives are now correctly handled.
19416
19417         · Added emphasize-lines option to source code directives.
19418
19419         · #678: C++ domain now supports superclasses.
19420
19421       · HTML builder:
19422
19423         · Added pyramid theme.
19424
19425         · #559: html_add_permalinks is now a string giving the text  to  dis‐
19426           play in permalinks.
19427
19428         · #259:  HTML  table  rows  now  have  even/odd CSS classes to enable
19429           “Zebra styling”.
19430
19431         · #554: Add theme option sidebarwidth to the basic theme.
19432
19433       · Other builders:
19434
19435         · #516: Added new value of the latex_show_urls  option  to  show  the
19436           URLs in footnotes.
19437
19438         · #209: Added text_newlines and text_sectionchars config values.
19439
19440         · Added man_show_urls config value.
19441
19442         · #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
19446         · #521: Added linkcheck_ignore config value.
19447
19448         · #28: Support row/colspans in tables in the LaTeX builder.
19449
19450       · Configuration and extensibility:
19451
19452         · #537: Added nitpick_ignore.
19453
19454         · #306: Added env-get-outdated event.
19455
19456         · Application.add_stylesheet() now accepts full URIs.
19457
19458       · Autodoc:
19459
19460         · #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
19464         · #176: Provide private-members option for autodoc directives.
19465
19466         · #520: Provide special-members option for autodoc directives.
19467
19468         · #431: Doc comments for attributes can now be given on the same line
19469           as the assignment.
19470
19471         · #437: autodoc now shows values of class data attributes.
19472
19473         · autodoc now supports documenting the signatures  of  functools.par‐
19474           tial objects.
19475
19476       · Other extensions:
19477
19478         · Added the sphinx.ext.mathjax extension.
19479
19480         · #443: Allow referencing external graphviz files.
19481
19482         · Added  inline  option to graphviz directives, and fixed the default
19483           (block-style) in LaTeX output.
19484
19485         · #590: Added caption option to graphviz directives.
19486
19487         · #553: Added testcleanup blocks in the doctest extension.
19488
19489         · #594: trim_doctest_flags now also removes <BLANKLINE> indicators.
19490
19491         · #367: Added automatic exclusion of hidden  members  in  inheritance
19492           diagrams, and an option to selectively enable it.
19493
19494         · Added pngmath_add_tooltips.
19495
19496         · 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
19500       · New locales:
19501
19502         · #221: Added Swedish locale.
19503
19504         · #526: Added Iranian locale.
19505
19506         · #694: Added Latvian locale.
19507
19508         · Added Nepali locale.
19509
19510         · #714: Added Korean locale.
19511
19512         · #766: Added Estonian locale.
19513
19514       · Bugs fixed:
19515
19516         · #778: Fix “hide search matches” link on pages linked by search.
19517
19518         · Fix the source positions referenced by the “viewcode” extension.
19519
19520   Release 1.0.8 (Sep 23, 2011)
19521       · #627: Fix tracebacks for AttributeErrors in autosummary generation.
19522
19523       · Fix the abbr role when the abbreviation has newlines in it.
19524
19525       · #727: Fix the links to search results with custom object types.
19526
19527       · #648:  Fix  line  numbers reported in warnings about undefined refer‐
19528         ences.
19529
19530       · #696, #666: Fix C++ array definitions and template arguments that are
19531         not type names.
19532
19533       · #633: Allow footnotes in section headers in LaTeX output.
19534
19535       · #616: Allow keywords to be linked via intersphinx.
19536
19537       · #613: Allow Unicode characters in production list token names.
19538
19539       · #720: Add dummy visitors for graphviz nodes for text and man.
19540
19541       · #704: Fix image file duplication bug.
19542
19543       · #677: Fix parsing of multiple signatures in C++ domain.
19544
19545       · #637: Ignore Emacs lock files when looking for source files.
19546
19547       · #544: Allow .pyw extension for importable modules in autodoc.
19548
19549       · #700: Use $(MAKE) in quickstart-generated Makefiles.
19550
19551       · #734: Make sidebar search box width consistent in browsers.
19552
19553       · #644: Fix spacing of centered figures in HTML output.
19554
19555       · #767:  Safely  encode  SphinxError  messages  when  printing  them to
19556         sys.stderr.
19557
19558       · #611: Fix LaTeX output error with a document with no sections  but  a
19559         link target.
19560
19561       · Correctly treat built-in method descriptors as methods in autodoc.
19562
19563       · #706: Stop monkeypatching the Python textwrap module.
19564
19565       · #657:  viewcode  now  works  correctly  with  source  files that have
19566         non-ASCII encoding.
19567
19568       · #669: Respect the noindex flag option in py:module directives.
19569
19570       · #675: Fix IndexErrors when including nonexisting lines with  literal‐
19571         include.
19572
19573       · #676: Respect custom function/method parameter separator strings.
19574
19575       · #682: Fix JS incompatibility with jQuery >= 1.5.
19576
19577       · #693: Fix double encoding done when writing HTMLHelp .hhk files.
19578
19579       · #647: Do not apply SmartyPants in parsed-literal blocks.
19580
19581       · C++ domain now supports array definitions.
19582
19583   Release 1.0.7 (Jan 15, 2011)
19584       · #347:  Fix  wrong generation of directives of static methods in auto‐
19585         summary.
19586
19587       · #599: Import PIL as from PIL import Image.
19588
19589       · #558: Fix longtables with captions in LaTeX output.
19590
19591       · Make token references work as hyperlinks again in LaTeX output.
19592
19593       · #572: Show warnings by default when reference labels cannot be found.
19594
19595       · #536: Include line number when complaining  about  missing  reference
19596         targets in nitpicky mode.
19597
19598       · #590: Fix inline display of graphviz diagrams in LaTeX output.
19599
19600       · #589: Build using app.build() in setup command.
19601
19602       · Fix  a  bug  in  the  inheritance  diagram exception that caused base
19603         classes to be skipped if one of them is a builtin.
19604
19605       · Fix general index links for C++ domain objects.
19606
19607       · #332: Make admonition boundaries in LaTeX output visible.
19608
19609       · #573: Fix KeyErrors occurring on rebuild after removing a file.
19610
19611       · Fix a traceback when removing files with globbed toctrees.
19612
19613       · If an autodoc object cannot be imported, always re-read the  document
19614         containing the directive on next build.
19615
19616       · If  an  autodoc object cannot be imported, show the full traceback of
19617         the import error.
19618
19619       · Fix a bug where the removal  of  download  files  and  images  wasn’t
19620         noticed.
19621
19622       · #571: Implement ~ cross-reference prefix for the C domain.
19623
19624       · Fix regression of LaTeX output with the fix of #556.
19625
19626       · #568:  Fix  lookup of class attribute documentation on descriptors so
19627         that comment documentation now works.
19628
19629       · Fix traceback with only directives preceded by targets.
19630
19631       · Fix tracebacks occurring for duplicate C++ domain objects.
19632
19633       · Fix JavaScript domain links to objects with $ in their name.
19634
19635   Release 1.0.6 (Jan 04, 2011)
19636       · #581: Fix traceback in Python domain for empty  cross-reference  tar‐
19637         gets.
19638
19639       · #283: Fix literal block display issues on Chrome browsers.
19640
19641       · #383, #148: Support sorting a limited range of accented characters in
19642         the general index and the glossary.
19643
19644       · #570: Try decoding -D and -A command-line arguments with the locale’s
19645         preferred encoding.
19646
19647       · #528: Observe locale_dirs when looking for the JS translations file.
19648
19649       · #574:  Add  special  code for better support of Japanese documents in
19650         the LaTeX builder.
19651
19652       · Regression of #77: If there is only one parameter given with  :param:
19653         markup, the bullet list is now suppressed again.
19654
19655       · #556:  Fix missing paragraph breaks in LaTeX output in certain situa‐
19656         tions.
19657
19658       · #567: Emit the autodoc-process-docstring event even for objects with‐
19659         out a docstring so that it can add content.
19660
19661       · #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
19664       · #515: Fix tracebacks in the viewcode  extension  for  Python  objects
19665         that do not have a valid signature.
19666
19667       · Fix  strange  reports  of  line  numbers  for warnings generated from
19668         autodoc-included docstrings, due to different behavior  depending  on
19669         docutils version.
19670
19671       · Several fixes to the C++ domain.
19672
19673   Release 1.0.5 (Nov 12, 2010)
19674       · #557:  Add CSS styles required by docutils 0.7 for aligned images and
19675         figures.
19676
19677       · In the Makefile generated by LaTeX output, do not delete pdf files on
19678         clean; they might be required images.
19679
19680       · #535: Fix LaTeX output generated for line blocks.
19681
19682       · #544: Allow .pyw as a source file extension.
19683
19684   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
19688       · #513: Allow giving non-local URIs for JavaScript files, e.g.  in  the
19689         JSMath extension.
19690
19691       · #512: Fix traceback when intersphinx_mapping is empty.
19692
19693   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
19697       · #494: Fix the maxdepth option for  the  toctree()  template  callable
19698         when used with collapse=True.
19699
19700       · #507:  Fix crash parsing Python argument lists containing brackets in
19701         string literals.
19702
19703       · #501: Fix regression when building LaTeX docs with figures that don’t
19704         have captions.
19705
19706       · #510: Fix inheritance diagrams for classes that are not picklable.
19707
19708       · #497:  Introduce  separate  background color for the sidebar collapse
19709         button, making it easier to see.
19710
19711       · #502, #503, #496: Fix small layout bugs in several builtin themes.
19712
19713   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
19717       · Fix handling of doc field types for different directive types.
19718
19719       · Allow breaking long signatures, continuing with backlash-escaped new‐
19720         lines.
19721
19722       · Fix unwanted styling of C domain references (because of  a  namespace
19723         clash with Pygments styles).
19724
19725       · Allow references to PEPs and RFCs with explicit anchors.
19726
19727       · #471: Fix LaTeX references to figures.
19728
19729       · #482:  When  doing  a  non-exact search, match only the given type of
19730         object.
19731
19732       · #481: Apply non-exact search for Python reference targets with  .name
19733         for modules too.
19734
19735       · #484: Fix crash when duplicating a parameter in an info field list.
19736
19737       · #487:  Fix setting the default role to one provided by the oldcmarkup
19738         extension.
19739
19740       · #488: Fix crash when json-py is installed, which provides a json mod‐
19741         ule but is incompatible to simplejson.
19742
19743       · #480: Fix handling of target naming in intersphinx.
19744
19745       · #486: Fix removal of ! for all cross-reference roles.
19746
19747   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
19751       · #266: Add Bengali language.
19752
19753       · #473: Fix a bug in parsing JavaScript object names.
19754
19755       · #474: Fix building with SingleHTMLBuilder when there is no toctree.
19756
19757       · Fix display names for objects linked to by intersphinx with  explicit
19758         targets.
19759
19760       · Fix building with the JSON builder.
19761
19762       · Fix hyperrefs in object descriptions for LaTeX.
19763
19764   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
19771         · Python
19772
19773         · C
19774
19775         · C++
19776
19777         · JavaScript
19778
19779         · reStructuredText
19780
19781       · 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
19786       · Removed support for old dependency versions; requirements are now:
19787
19788         · docutils >= 0.5
19789
19790         · Jinja2   >= 2.2
19791
19792       · Removed deprecated elements:
19793
19794         · exclude_dirs config value
19795
19796         · sphinx.builder module
19797
19798   Features added
19799       · General:
19800
19801         · 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
19805         · Added latexpdf target in quickstart Makefile.
19806
19807       · Markup:
19808
19809         · The menuselection and guilabel roles now support ampersand acceler‐
19810           ators.
19811
19812         · New more compact doc field syntax is now  recognized:  :param  type
19813           name: description.
19814
19815         · Added tab-width option to literalinclude directive.
19816
19817         · Added titlesonly option to toctree directive.
19818
19819         · Added  the  prepend and append options to the literalinclude direc‐
19820           tive.
19821
19822         · #284: All docinfo metadata is now put into the  document  metadata,
19823           not just the author.
19824
19825         · The ref role can now also reference tables by caption.
19826
19827         · The include directive now supports absolute paths, which are inter‐
19828           preted as relative to the source directory.
19829
19830         · In the Python domain, references like :func:`.name`  now  look  for
19831           matching names with any prefix if no direct match is found.
19832
19833       · Configuration:
19834
19835         · Added rst_prolog config value.
19836
19837         · Added html_secnumber_suffix config value to control section number‐
19838           ing format.
19839
19840         · Added html_compact_lists config value to control docutils’  compact
19841           lists feature.
19842
19843         · 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
19848         · html_static_path can now contain single file entries.
19849
19850         · The new universal  config  value  exclude_patterns  makes  the  old
19851           unused_docs, exclude_trees and exclude_dirnames obsolete.
19852
19853         · Added html_output_encoding config value.
19854
19855         · Added  the latex_docclass config value and made the “twoside” docu‐
19856           mentclass option overridable by “oneside”.
19857
19858         · Added  the  trim_doctest_flags  config  value,  which  is  true  by
19859           default.
19860
19861         · Added html_show_copyright config value.
19862
19863         · Added latex_show_pagerefs and latex_show_urls config values.
19864
19865         · 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
19869       · New builders:
19870
19871         · Added a builder for the Epub format.
19872
19873         · Added a builder for manual pages.
19874
19875         · Added a single-file HTML builder.
19876
19877       · HTML output:
19878
19879         · 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
19883         · References  now  get the class internal if they are internal to the
19884           whole project, as opposed to internal to the current page.
19885
19886         · External references can be styled differently with the  new  exter‐
19887           nalrefs theme option for the default theme.
19888
19889         · In  the  default  theme, the sidebar can experimentally now be made
19890           collapsible using the new collapsiblesidebar theme option.
19891
19892         · #129: Toctrees are now  wrapped  in  a  div  tag  with  class  toc‐
19893           tree-wrapper in HTML output.
19894
19895         · The  toctree callable in templates now has a maxdepth keyword argu‐
19896           ment to control the depth of the generated tree.
19897
19898         · The toctree callable in templates now accepts a titles_only keyword
19899           argument.
19900
19901         · Added htmltitle block in layout template.
19902
19903         · In  the JavaScript search, allow searching for object names includ‐
19904           ing the module name, like sys.argv.
19905
19906         · Added new theme haiku, inspired by the Haiku OS user guide.
19907
19908         · Added new theme nature.
19909
19910         · Added new theme agogo, created by Andi Albrecht.
19911
19912         · Added new theme scrolls, created by Armin Ronacher.
19913
19914         · #193: Added a visitedlinkcolor theme option to the default theme.
19915
19916         · #322: Improved responsiveness of the search  page  by  loading  the
19917           search index asynchronously.
19918
19919       · Extension API:
19920
19921         · Added html-collect-pages.
19922
19923         · Added  needs_sphinx  config  value and require_sphinx() application
19924           API method.
19925
19926         · #200: Added add_stylesheet() application API method.
19927
19928       · Extensions:
19929
19930         · Added the viewcode extension.
19931
19932         · Added the extlinks extension.
19933
19934         · Added support for source  ordering  of  members  in  autodoc,  with
19935           autodoc_member_order = 'bysource'.
19936
19937         · Added  autodoc_default_flags  config  value,  which  can be used to
19938           select default flags for all autodoc directives.
19939
19940         · 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
19943         · #280:  Autodoc  can  now  document  instance attributes assigned in
19944           __init__ methods.
19945
19946         · Many improvements and fixes to the autosummary extension, thanks to
19947           Pauli Virtanen.
19948
19949         · #309:  The  graphviz  extension  can  now output SVG instead of PNG
19950           images, controlled by the graphviz_output_format config value.
19951
19952         · Added alt option to graphviz extension directives.
19953
19954         · Added exclude argument to autodoc.between().
19955
19956       · Translations:
19957
19958         · Added Croatian translation, thanks to Bojan Mihelač.
19959
19960         · Added Turkish translation, thanks to Firat Ozgul.
19961
19962         · Added Catalan translation, thanks to Pau Fernández.
19963
19964         · Added simplified Chinese translation.
19965
19966         · Added Danish translation, thanks to Hjorth Larsen.
19967
19968         · Added Lithuanian translation, thanks to Dalius Dobravolskas.
19969
19970       · Bugs fixed:
19971
19972         · #445: Fix links to result pages when using the search  function  of
19973           HTML built with the dirhtml builder.
19974
19975         · #444:  In  templates,  properly  re-escape  values treated with the
19976           “striptags” Jinja filter.
19977
19978   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

PROJECTS USING SPHINX

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
19987       I’ve grouped the list into sections to make it easier to find interest‐
19988       ing examples.
19989
19990   Documentation using the alabaster theme
19991       · Alabaster: https://alabaster.readthedocs.io/
19992
19993       · Blinker: https://pythonhosted.org/blinker/
19994
19995       · Calibre: https://manual.calibre-ebook.com/
19996
19997       · Click: http://click.pocoo.org/ (customized)
19998
19999       · coala: https://docs.coala.io/ (customized)
20000
20001       · CodePy: https://documen.tician.de/codepy/
20002
20003       · Fabric: http://docs.fabfile.org/
20004
20005       · Fityk: http://fityk.nieto.pl/
20006
20007       · Flask: http://flask.pocoo.org/docs/
20008
20009       · Flask-OpenID: https://pythonhosted.org/Flask-OpenID/
20010
20011       · Invoke: http://docs.pyinvoke.org/
20012
20013       · Jinja: http://jinja.pocoo.org/docs/
20014
20015       · Lino: http://www.lino-framework.org/ (customized)
20016
20017       · marbl: https://getmarbl.readthedocs.io/
20018
20019       · MDAnalysis: http://www.mdanalysis.org/docs/ (customized)
20020
20021       · MeshPy: https://documen.tician.de/meshpy/
20022
20023       · PyCUDA: https://documen.tician.de/pycuda/
20024
20025       · PyOpenCL: https://documen.tician.de/pyopencl/
20026
20027       · PyLangAcq: http://pylangacq.org/
20028
20029       · pytest: https://docs.pytest.org/ (customized)
20030
20031       · python-apt: https://apt.alioth.debian.org/python-apt-doc/
20032
20033       · PyVisfile: https://documen.tician.de/pyvisfile/
20034
20035       · Requests: http://www.python-requests.org/
20036
20037       · searx: https://asciimoo.github.io/searx/
20038
20039       · Tablib: http://docs.python-tablib.org/
20040
20041       · urllib3: https://urllib3.readthedocs.io/ (customized)
20042
20043       · Werkzeug: http://werkzeug.pocoo.org/docs/ (customized)
20044
20045   Documentation using the classic theme
20046       · Advanced                       Generic                       Widgets:
20047         http://xoomer.virgilio.it/infinity77/AGW_Docs/ (customized)
20048
20049       · Apache CouchDB: http://docs.couchdb.org/ (customized)
20050
20051       · APSW: https://rogerbinns.github.io/apsw/
20052
20053       · Arb: http://arblib.org/
20054
20055       · Bazaar: http://doc.bazaar.canonical.com/ (customized)
20056
20057       · Beautiful                                                       Soup:
20058         https://www.crummy.com/software/BeautifulSoup/bs4/doc/
20059
20060       · Blender: https://docs.blender.org/api/current/
20061
20062       · Bugzilla: https://bugzilla.readthedocs.io/
20063
20064       · Buildbot: https://docs.buildbot.net/latest/
20065
20066       · CMake: https://cmake.org/documentation/ (customized)
20067
20068       · Chaco: http://docs.enthought.com/chaco/ (customized)
20069
20070       · Cormoran: http://cormoran.nhopkg.org/docs/
20071
20072       · DEAP: https://deap.readthedocs.io/ (customized)
20073
20074       · Director: https://pythonhosted.org/director/
20075
20076       · EZ-Draw:
20077         https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html
20078         (customized)
20079
20080       · F2py: http://f2py.sourceforge.net/docs/
20081
20082       · Generic Mapping Tools (GMT):  http://gmt.soest.hawaii.edu/doc/latest/
20083         (customized)
20084
20085       · Genomedata:
20086         https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/
20087
20088       · GetFEM++: http://getfem.org/ (customized)
20089
20090       · Glasgow                       Haskell                       Compiler:
20091         https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/
20092         (customized)
20093
20094       · Grok: http://grok.zope.org/doc/current/ (customized)
20095
20096       · GROMACS: http://manual.gromacs.org/documentation/
20097
20098       · GSL Shell: http://www.nongnu.org/gsl-shell/
20099
20100       · Hands-on                       Python                       Tutorial:
20101         http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
20102
20103       · Kaa: http://api.freevo.org/kaa-base/ (customized)
20104
20105       · Leo: http://leoeditor.com/
20106
20107       · LEPL: http://www.acooke.org/lepl/ (customized)
20108
20109       · Mayavi: http://docs.enthought.com/mayavi/mayavi/ (customized)
20110
20111       · MediaGoblin: https://mediagoblin.readthedocs.io/ (customized)
20112
20113       · mpmath: http://mpmath.org/doc/current/
20114
20115       · OpenCV: http://docs.opencv.org/ (customized)
20116
20117       · OpenEXR: http://excamera.com/articles/26/doc/index.html
20118
20119       · OpenGDA: http://www.opengda.org/gdadoc/html/
20120
20121       · Peach^3: https://peach3.nl/doc/latest/userdoc/ (customized)
20122
20123       · Plone: https://docs.plone.org/ (customized)
20124
20125       · PyEMD: https://pyemd.readthedocs.io/
20126
20127       · Pyevolve: http://pyevolve.sourceforge.net/
20128
20129       · Pygame: https://www.pygame.org/docs/ (customized)
20130
20131       · PyMQI: https://pythonhosted.org/pymqi/
20132
20133       · PyQt4: http://pyqt.sourceforge.net/Docs/PyQt4/ (customized)
20134
20135       · PyQt5: http://pyqt.sourceforge.net/Docs/PyQt5/ (customized)
20136
20137       · Python 2: https://docs.python.org/2/
20138
20139       · Python 3: https://docs.python.org/3/ (customized)
20140
20141       · Python Packaging Authority: https://www.pypa.io/ (customized)
20142
20143       · Ring   programming   language:  http://ring-lang.sourceforge.net/doc/
20144         (customized)
20145
20146       · SageMath: https://doc.sagemath.org/ (customized)
20147
20148       · Segway:
20149         http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
20150
20151       · simuPOP:
20152         http://simupop.sourceforge.net/manual_release/build/userGuide.html
20153         (customized)
20154
20155       · Sprox: http://sprox.org/ (customized)
20156
20157       · SymPy: http://docs.sympy.org/
20158
20159       · TurboGears: https://turbogears.readthedocs.io/ (customized)
20160
20161       · tvtk: http://docs.enthought.com/mayavi/tvtk/
20162
20163       · Varnish:  https://www.varnish-cache.org/docs/  (customized, alabaster
20164         for index)
20165
20166       · Waf: https://waf.io/apidocs/
20167
20168       · wxPython  Phoenix:   https://wxpython.org/Phoenix/docs/html/main.html
20169         (customized)
20170
20171       · z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
20172
20173       · zc.async: https://pythonhosted.org/zc.async/ (customized)
20174
20175       · Zope: https://docs.zope.org/zope2/ (customized)
20176
20177   Documentation using the sphinxdoc theme
20178       · cartopy: http://scitools.org.uk/cartopy/docs/latest/
20179
20180       · Jython: http://www.jython.org/docs/
20181
20182       · Matplotlib: https://matplotlib.org/
20183
20184       · MDAnalysis Tutorial: http://www.mdanalysis.org/MDAnalysisTutorial/
20185
20186       · NetworkX: https://networkx.github.io/
20187
20188       · PyCantonese: http://pycantonese.org/
20189
20190       · Pyre: http://docs.danse.us/pyre/sphinx/
20191
20192       · pySPACE: https://pyspace.github.io/pyspace/
20193
20194       · Pysparse: http://pysparse.sourceforge.net/
20195
20196       · PyTango:
20197         http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/
20198
20199       · Python  Wild  Magic: https://vmlaker.github.io/pythonwildmagic/ (cus‐
20200         tomized)
20201
20202       · Reteisi: http://www.reteisi.org/contents.html (customized)
20203
20204       · Sqlkit: http://sqlkit.argolinux.org/ (customized)
20205
20206       · Turbulenz: http://docs.turbulenz.com/
20207
20208   Documentation using the nature theme
20209       · Alembic: http://alembic.zzzcomputing.com/
20210
20211       · Cython: http://docs.cython.org/
20212
20213       · easybuild: https://easybuild.readthedocs.io/
20214
20215       · jsFiddle: http://doc.jsfiddle.net/
20216
20217       · libLAS: https://www.liblas.org/ (customized)
20218
20219       · Lmod: https://lmod.readthedocs.io/
20220
20221       · MapServer: http://mapserver.org/ (customized)
20222
20223       · Pandas: https://pandas.pydata.org/pandas-docs/stable/
20224
20225       · pyglet: https://pyglet.readthedocs.io/ (customized)
20226
20227       · Setuptools: https://setuptools.readthedocs.io/
20228
20229       · Spring                                                        Python:
20230         https://docs.spring.io/spring-python/1.2.x/sphinx/html/
20231
20232       · StatsModels: http://www.statsmodels.org/ (customized)
20233
20234       · Sylli: http://sylli.sourceforge.net/
20235
20236   Documentation using another builtin theme
20237       · Breathe: https://breathe.readthedocs.io/ (haiku)
20238
20239       · MPipe: https://vmlaker.github.io/mpipe/ (sphinx13)
20240
20241       · NLTK: http://www.nltk.org/ (agogo)
20242
20243       · Programmieren       mit      PyGTK      und      Glade      (German):
20244         http://www.florian-diesch.de/doc/python-und-glade/online/     (agogo,
20245         customized)
20246
20247       · PyPubSub: https://pypubsub.readthedocs.io/ (bizstyle)
20248
20249       · Pylons:   http://docs.pylonsproject.org/projects/pylons-webframework/
20250         (pyramid)
20251
20252       · Pyramid                        web                         framework:
20253         https://docs.pylonsproject.org/projects/pyramid/ (pyramid)
20254
20255       · Sphinx: http://www.sphinx-doc.org/ (sphinx13) :-)
20256
20257       · Valence: http://docs.valence.desire2learn.com/ (haiku, customized)
20258
20259   Documentation using sphinx_rtd_theme
20260       · Annotator: http://docs.annotatorjs.org/
20261
20262       · Ansible: https://docs.ansible.com/ (customized)
20263
20264       · Arcade: http://arcade.academy/
20265
20266       · aria2: https://aria2.github.io/manual/en/html/
20267
20268       · ASE: https://wiki.fysik.dtu.dk/ase/
20269
20270       · Autofac: http://docs.autofac.org/
20271
20272       · BigchainDB: https://docs.bigchaindb.com/
20273
20274       · Blocks: https://blocks.readthedocs.io/
20275
20276       · bootstrap-datepicker: https://bootstrap-datepicker.readthedocs.io/
20277
20278       · Certbot: https://letsencrypt.readthedocs.io/
20279
20280       · Chainer: https://docs.chainer.org/ (customized)
20281
20282       · CherryPy: http://docs.cherrypy.org/
20283
20284       · Chainer: https://docs.chainer.org/
20285
20286       · CodeIgniter: https://www.codeigniter.com/user_guide/
20287
20288       · Conda: https://conda.io/docs/
20289
20290       · Corda: https://docs.corda.net/
20291
20292       · Dask: https://dask.pydata.org/
20293
20294       · Databricks: https://docs.databricks.com/ (customized)
20295
20296       · Dataiku DSS: https://doc.dataiku.com/
20297
20298       · edX: http://docs.edx.org/
20299
20300       · Electrum: http://docs.electrum.org/
20301
20302       · Elemental: http://libelemental.org/documentation/dev/
20303
20304       · ESWP3: https://eswp3.readthedocs.io/
20305
20306       · Ethereum Homestead: http://www.ethdocs.org/
20307
20308       · Fidimag: https://fidimag.readthedocs.io/
20309
20310       · Flake8: http://flake8.pycqa.org/
20311
20312       · GeoNode: http://docs.geonode.org/
20313
20314       · Godot: https://godot.readthedocs.io/
20315
20316       · Graylog: http://docs.graylog.org/
20317
20318       · GPAW: https://wiki.fysik.dtu.dk/gpaw/ (customized)
20319
20320       · HDF5 for Python (h5py): http://docs.h5py.org/
20321
20322       · Hyperledger Fabric: https://hyperledger-fabric.readthedocs.io/
20323
20324       · Hyperledger Sawtooth: https://intelledger.github.io/
20325
20326       · IdentityServer: http://docs.identityserver.io/
20327
20328       · Idris: http://docs.idris-lang.org/
20329
20330       · javasphinx: https://bronto-javasphinx.readthedocs.io/
20331
20332       · Julia: https://julia.readthedocs.io/
20333
20334       · Jupyter Notebook: https://jupyter-notebook.readthedocs.io/
20335
20336       · Lasagne: https://lasagne.readthedocs.io/
20337
20338       · Linguistica: https://linguistica-uchicago.github.io/lxa5/
20339
20340       · Linux kernel: https://www.kernel.org/doc/html/latest/index.html
20341
20342       · MathJax: https://docs.mathjax.org/
20343
20344       · MDTraj: http://mdtraj.org/latest/ (customized)
20345
20346       · MICrobial Community Analysis (micca): http://micca.org/docs/latest/
20347
20348       · MicroPython: https://docs.micropython.org/
20349
20350       · Minds: https://www.minds.org/docs/ (customized)
20351
20352       · Mink: http://mink.behat.org/
20353
20354       · Mockery: http://docs.mockery.io/
20355
20356       · mod_wsgi: https://modwsgi.readthedocs.io/
20357
20358       · MoinMoin: https://moin-20.readthedocs.io/
20359
20360       · Mopidy: https://docs.mopidy.com/
20361
20362       · MyHDL: http://docs.myhdl.org/
20363
20364       · Nextflow: https://www.nextflow.io/docs/latest/index.html
20365
20366       · NICOS: https://forge.frm2.tum.de/nicos/doc/nicos-master/ (customized)
20367
20368       · Pelican: http://docs.getpelican.com/
20369
20370       · picamera: https://picamera.readthedocs.io/
20371
20372       · Pillow: https://pillow.readthedocs.io/
20373
20374       · pip: https://pip.pypa.io/
20375
20376       · Paver: https://paver.readthedocs.io/
20377
20378       · peewee: http://docs.peewee-orm.com/
20379
20380       · Phinx: http://docs.phinx.org/
20381
20382       · phpMyAdmin: https://docs.phpmyadmin.net/
20383
20384       · PROS: https://pros.cs.purdue.edu/v5/ (customized)
20385
20386       · Pweave: http://mpastell.com/pweave/
20387
20388       · PyPy: http://doc.pypy.org/
20389
20390       · python-sqlparse: https://sqlparse.readthedocs.io/
20391
20392       · PyVISA: https://pyvisa.readthedocs.io/
20393
20394       · Read The Docs: https://docs.readthedocs.io/
20395
20396       · Free     your     information     from    their    silos    (French):
20397         http://redaction-technique.org/ (customized)
20398
20399       · Releases Sphinx extension: https://releases.readthedocs.io/
20400
20401       · Qtile: http://docs.qtile.org/
20402
20403       · Quex: http://quex.sourceforge.net/doc/html/main.html
20404
20405       · Satchmo: http://docs.satchmoproject.com/
20406
20407       · Scapy: https://scapy.readthedocs.io/
20408
20409       · SimPy: http://simpy.readthedocs.io/
20410
20411       · SlamData: http://docs.slamdata.com/
20412
20413       · Solidity: https://solidity.readthedocs.io/
20414
20415       · Sonos Controller (SoCo): http://docs.python-soco.com/
20416
20417       · Sphinx AutoAPI: https://sphinx-autoapi.readthedocs.io/
20418
20419       · sphinx-argparse: https://sphinx-argparse.readthedocs.io/
20420
20421       · Sphinx-Gallery: https://sphinx-gallery.readthedocs.io/ (customized)
20422
20423       · StarUML: http://docs.staruml.io/
20424
20425       · Sublime Text Unofficial Documentation: http://docs.sublimetext.info/
20426
20427       · SunPy: http://docs.sunpy.org/
20428
20429       · Sylius: http://docs.sylius.org/
20430
20431       · Tango Controls: https://tango-controls.readthedocs.io/ (customized)
20432
20433       · Topshelf: http://docs.topshelf-project.com/
20434
20435       · Theano: http://www.deeplearning.net/software/theano/
20436
20437       · ThreatConnect: https://docs.threatconnect.com/
20438
20439       · Tuleap: https://tuleap.net/doc/en/
20440
20441       · TYPO3: https://docs.typo3.org/ (customized)
20442
20443       · uWSGI: https://uwsgi-docs.readthedocs.io/
20444
20445       · Wagtail: http://docs.wagtail.io/
20446
20447       · Web    Application    Attack    and    Audit    Framework     (w3af):
20448         http://docs.w3af.org/
20449
20450       · Weblate: https://docs.weblate.org/
20451
20452       · x265: https://x265.readthedocs.io/
20453
20454       · ZeroNet: https://zeronet.readthedocs.io/
20455
20456   Documentation using sphinx_bootstrap_theme
20457       · Bootstrap                                                      Theme:
20458         https://ryan-roemer.github.io/sphinx-bootstrap-theme/
20459
20460       · C/C++ Software Development with Eclipse: http://eclipsebook.in/
20461
20462       · Dataverse: http://guides.dataverse.org/
20463
20464       · e-cidadania: https://e-cidadania.readthedocs.io/
20465
20466       · Hangfire: http://docs.hangfire.io/
20467
20468       · Hedge: https://documen.tician.de/hedge/
20469
20470       · ObsPy: https://docs.obspy.org/
20471
20472       · Open Dylan: https://opendylan.org/documentation/
20473
20474       · Pootle: http://docs.translatehouse.org/projects/pootle/
20475
20476       · PyUblas: https://documen.tician.de/pyublas/
20477
20478       · seaborn: https://seaborn.pydata.org/
20479
20480   Documentation using a custom theme or integrated in a website
20481       · Apache Cassandra: https://cassandra.apache.org/doc/
20482
20483       · Astropy: http://docs.astropy.org/
20484
20485       · Bokeh: https://bokeh.pydata.org/
20486
20487       · Boto 3: https://boto3.readthedocs.io/
20488
20489       · CakePHP: https://book.cakephp.org/
20490
20491       · CasperJS: http://docs.casperjs.org/
20492
20493       · Ceph: http://docs.ceph.com/docs/master/
20494
20495       · Chef: https://docs.chef.io/
20496
20497       · CKAN: http://docs.ckan.org/
20498
20499       · Confluent Platform: http://docs.confluent.io/
20500
20501       · Django: https://docs.djangoproject.com/
20502
20503       · Doctrine: http://docs.doctrine-project.org/
20504
20505       · Enterprise        Toolkit        for        Acrobat         products:
20506         https://www.adobe.com/devnet-docs/acrobatetk/
20507
20508       · Gameduino: http://excamera.com/sphinx/gameduino/
20509
20510       · gensim: https://radimrehurek.com/gensim/
20511
20512       · GeoServer: http://docs.geoserver.org/
20513
20514       · gevent: http://www.gevent.org/
20515
20516       · GHC           -           Glasgow          Haskell          Compiler:
20517         http://downloads.haskell.org/~ghc/master/users-guide/
20518
20519       · Guzzle: http://docs.guzzlephp.org/en/stable/
20520
20521       · H2O.ai: http://docs.h2o.ai/
20522
20523       · Istihza      (Turkish      Python       documentation       project):
20524         https://belgeler.yazbel.com/python-istihza/
20525
20526       · Kombu: http://docs.kombu.me/
20527
20528       · Lasso: http://lassoguide.com/
20529
20530       · Mako: http://docs.makotemplates.org/
20531
20532       · MirrorBrain: http://mirrorbrain.org/docs/
20533
20534       · MongoDB: https://docs.mongodb.com/
20535
20536       · Music21: http://web.mit.edu/music21/doc/
20537
20538       · MyHDL: http://docs.myhdl.org/en/latest/
20539
20540       · nose: https://nose.readthedocs.io/
20541
20542       · ns-3: https://www.nsnam.org/documentation/
20543
20544       · NumPy: https://docs.scipy.org/doc/numpy/reference/
20545
20546       · ObjectListView: http://objectlistview.sourceforge.net/python/
20547
20548       · OpenERP: https://doc.odoo.com/
20549
20550       · OpenCV: http://docs.opencv.org/
20551
20552       · OpenLayers: http://docs.openlayers.org/
20553
20554       · OpenTURNS: http://openturns.github.io/openturns/master/
20555
20556       · Open vSwitch: http://docs.openvswitch.org/
20557
20558       · PlatformIO: http://docs.platformio.org/
20559
20560       · PyEphem: http://rhodesmill.org/pyephem/
20561
20562       · Pygments: http://pygments.org/docs/
20563
20564       · Plone               User               Manual               (German):
20565         https://www.hasecke.com/plone-benutzerhandbuch/4.0/
20566
20567       · PSI4: http://www.psicode.org/psi4manual/master/index.html
20568
20569       · PyMOTW: https://pymotw.com/2/
20570
20571       · python-aspectlib:     https://python-aspectlib.readthedocs.io/     (‐
20572         sphinx_py3doc_enhanced_theme)
20573
20574       · QGIS: https://qgis.org/en/docs/index.html
20575
20576       · qooxdoo: http://www.qooxdoo.org/current/
20577
20578       · Roundup: http://www.roundup-tracker.org/
20579
20580       · SaltStack: https://docs.saltstack.com/
20581
20582       · scikit-learn: http://scikit-learn.org/stable/
20583
20584       · SciPy: https://docs.scipy.org/doc/scipy/refrence/
20585
20586       · Scrapy: https://doc.scrapy.org/
20587
20588       · Seaborn: https://seaborn.pydata.org/
20589
20590       · Selenium: http://docs.seleniumhq.org/docs/
20591
20592       · Self: http://www.selflanguage.org/
20593
20594       · Substance D: https://docs.pylonsproject.org/projects/substanced/
20595
20596       · Sulu: http://docs.sulu.io/
20597
20598       · SQLAlchemy: https://docs.sqlalchemy.org/
20599
20600       · tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
20601
20602       · Twisted: http://twistedmatrix.com/documents/current/
20603
20604       · Ubuntu Packaging Guide: http://packaging.ubuntu.com/html/
20605
20606       · WebFaction: https://docs.webfaction.com/
20607
20608       · WTForms: https://wtforms.readthedocs.io/
20609
20610   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
20616       · Benoit Boissinot: https://bboissin.appspot.com/ (classic, customized)
20617
20618       · Computer  Networks,  Parallelization,   and   Simulation   Laboratory
20619         (CNPSLab): https://lab.miletic.net/ (sphinx_rtd_theme)
20620
20621       · Deep    Learning   Tutorials:   http://www.deeplearning.net/tutorial/
20622         (sphinxdoc)
20623
20624       · Loyola University Chicago COMP 339-439  Distributed  Systems  course:
20625         http://books.cs.luc.edu/distributedsystems/ (sphinx_bootstrap_theme)
20626
20627       · Pylearn2:  http://www.deeplearning.net/software/pylearn2/ (sphinxdoc,
20628         customized)
20629
20630       · SciPy        Cookbook:         https://scipy-cookbook.readthedocs.io/
20631         (sphinx_rtd_theme)
20632
20633       · The   Wine   Cellar  Book:  https://www.thewinecellarbook.com/doc/en/
20634         (sphinxdoc)
20635
20636       · Thomas Cokelaer’s  Python,  Sphinx  and  reStructuredText  tutorials:
20637         http://thomas-cokelaer.info/tutorials/ (standard)
20638
20639       · UC    Berkeley    ME233   Advanced   Control   Systems   II   course:
20640         https://berkeley-me233.github.io/ (sphinxdoc)
20641
20642   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
20646       · “Expert                     Python                      Programming”:
20647         https://www.packtpub.com/application-development/expert-python-programming
20648
20649       · “Expert     Python     Programming”      (Japanese      translation):
20650         https://www.amazon.co.jp/dp/4048686291/
20651
20652       · “LassoGuide”: http://www.lassosoft.com/Lasso-Documentation
20653
20654       · “Learning              Sphinx”             (in             Japanese):
20655         https://www.oreilly.co.jp/books/9784873116488/
20656
20657       · “Mercurial:    the    definitive     guide     (Second     edition)”:
20658         https://book.mercurial-scm.org/
20659
20660       · “Pioneers and Prominent Men of Utah”: http://pioneers.rstebbing.com/
20661
20662       · “Pomodoro     Technique    Illustrated”    (Japanese    translation):
20663         https://www.amazon.co.jp/dp/4048689525/
20664
20665       · “Python      Professional      Programming”      (in       Japanese):
20666         http://www.amazon.co.jp/dp/4798032948/
20667
20668       · “The        repoze.bfg        Web       Application       Framework”:
20669         https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
20670
20671       · “Simple  and Steady Way of Learning for Software Engineering” (in Ja‐
20672         panese): https://www.amazon.co.jp/dp/477414259X/
20673
20674       · “Software-Dokumentation                 mit                  Sphinx”:
20675         https://www.amazon.de/dp/1497448689/
20676
20677       · “Theoretical Physics Reference”: http://www.theoretical-physics.net/
20678
20679       · “The                          Varnish                          Book”:
20680         https://info.varnish-software.com/the-varnish-book
20681
20682   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
20687       · “Content  Conditioning  and Distribution for Dynamic Virtual Worlds”:
20688         https://www.cs.princeton.edu/research/techreps/TR-941-12
20689
20690       · “The Sphinx Thesis Resource”: https://jterrace.github.io/sphinxtr/
20691

SPHINX AUTHORS

20693       Sphinx is written and maintained by Georg Brandl <georg@python.org>.
20694
20695       Substantial parts of the templates were written by  Armin  Ronacher  <‐
20696       armin.ronacher@active-4.com>.
20697
20698       Other co-maintainers:
20699
20700       · Takayuki Shimizukawa <shimizukawa@gmail.com>
20701
20702       · Daniel Neuhäuser <@DasIch>
20703
20704       · Jon Waltman <@jonwaltman>
20705
20706       · Rob Ruana <@RobRuana>
20707
20708       · Robert Lehmann <@lehmannro>
20709
20710       · Roland Meister <@rolmei>
20711
20712       · Takeshi Komiya <@tk0miya>
20713
20714       · Jean-François Burnol <@jfbu>
20715
20716       · Yoshiki Shibukawa <@shibu_jp>
20717
20718       Other contributors, listed alphabetically, are:
20719
20720       · Alastair Houghton – Apple Help builder
20721
20722       · Alexander Todorov – inheritance_diagram tests and improvements
20723
20724       · Andi Albrecht – agogo theme
20725
20726       · Jakob Lykke Andersen – Rewritten C++ domain
20727
20728       · Henrique Bastos – SVG support for graphviz extension
20729
20730       · Daniel Bültmann – todo extension
20731
20732       · Marco Buttu – doctest extension (pyversion option)
20733
20734       · Etienne Desautels – apidoc module
20735
20736       · Michael Droettboom – inheritance_diagram extension
20737
20738       · Charles Duffy – original graphviz extension
20739
20740       · Kevin Dunn – MathJax extension
20741
20742       · Josip Dzolonga – coverage builder
20743
20744       · Buck Evan – dummy builder
20745
20746       · Matthew Fernandez – todo extension fix
20747
20748       · Hernan Grecco – search improvements
20749
20750       · Horst Gutmann – internationalization support
20751
20752       · Martin Hans – autodoc improvements
20753
20754       · Zac Hatfield-Dodds – doctest reporting improvements
20755
20756       · Doug Hellmann – graphviz improvements
20757
20758       · Tim Hoffmann – theme improvements
20759
20760       · Timotheus Kampik - JS theme & search enhancements
20761
20762       · Dave Kuhlman – original LaTeX writer
20763
20764       · Blaise Laflamme – pyramid theme
20765
20766       · Thomas Lamb – linkcheck builder
20767
20768       · Łukasz Langa – partial support for autodoc
20769
20770       · Ian Lee – quickstart improvements
20771
20772       · Robert Lehmann – gettext builder (GSOC project)
20773
20774       · Dan MacKinlay – metadata fixes
20775
20776       · Martin Mahner – nature theme
20777
20778       · Will Maier – directory HTML builder
20779
20780       · Jacob Mason – websupport library (GSOC project)
20781
20782       · Glenn Matthews – python domain signature improvements
20783
20784       · Roland Meister – epub builder
20785
20786       · Ezio Melotti – collapsible sidebar JavaScript
20787
20788       · Bruce Mitchener – Minor epub improvement
20789
20790       · Daniel Neuhäuser – JavaScript domain, Python 3 support (GSOC)
20791
20792       · Christopher Perkins – autosummary integration
20793
20794       · Benjamin Peterson – unittests
20795
20796       · T. Powers – HTML output improvements
20797
20798       · Jeppe Pihl – literalinclude improvements
20799
20800       · Rob Ruana – napoleon extension
20801
20802       · Stefan Seefeld – toctree improvements
20803
20804       · Gregory Szorc – performance improvements
20805
20806       · Taku Shimizu – epub3 builder
20807
20808       · Antonio Valentino – qthelp builder, docstring inheritance
20809
20810       · Filip Vavera – napoleon todo directive
20811
20812       · Pauli Virtanen – autodoc improvements, autosummary extension
20813
20814       · Stefan van der Walt – autosummary extension
20815
20816       · Thomas Waldmann – apidoc module fixes
20817
20818       · John Waltman – Texinfo builder
20819
20820       · Barry Warsaw – setup command improvements
20821
20822       · Sebastian Wiesner – image handling, distutils support
20823
20824       · Michael Wilson – Intersphinx HTTP basic auth support
20825
20826       · Matthew Woodcraft – text output improvements
20827
20828       · Joel Wurtz – cellspanning support in LaTeX
20829
20830       · Hong Xu – svg support in imgmath extension and various bug fixes
20831
20832       · Stephen Finucane – setup command improvements and documentation
20833
20834       · Daniel Pizetta – inheritance diagram improvements
20835
20836       Many thanks for all contributions!
20837
20838       There  are  also  a  few  modules  or functions incorporated from other
20839       authors and projects:
20840
20841       · sphinx.util.jsdump uses  the  basestring  encoding  from  simplejson,
20842         written by Bob Ippolito, released under the MIT license
20843
20844       · sphinx.util.stemmer was written by Vivake Gupta, placed in the Public
20845         Domain
20846
20847       · modindex
20848
20849       · glossary
20850

AUTHOR

20852       Georg Brandl
20853
20855       2007-2018, Georg Brandl and the Sphinx team
20856
20857
20858
20859
208601.7.6                            Aug 02, 2018                    SPHINX-ALL(1)
Impressum