Merge branch 'master' into HEAD

.gitignore

@@ -1,6 +1,7 @@
 *.pyc
 *.egg
 *.so
+*.swp
 
 .dir-locals.el
 .ropeproject/

.travis.yml

@@ -1,16 +1,36 @@
 language: python
 sudo: false
+cache:
+  directories:
+    - $HOME/.cache/pip
 python:
   - "2.6"
   - "2.7"
   - "3.3"
   - "3.4"
+  - "3.5"
+  - "3.5-dev"
   - "pypy"
 env:
-  - DOCUTILS=0.11
+  global:
-  - DOCUTILS=0.12
+    - TEST='-v --with-timer --timer-top-n 25'
+  matrix:
+    - DOCUTILS=0.11
+    - DOCUTILS=0.12
+addons:
+  apt:
+    packages:
+    - graphviz
+    - texlive-latex-recommended
+    - texlive-latex-extra
+    - texlive-fonts-recommended
+    - texlive-fonts-extra
 install:
+  - pip install -U pip setuptools
   - pip install docutils==$DOCUTILS
   - pip install -r test-reqs.txt
-before_script: flake8
+before_script:
-script: make test
+  -  if [[ $TRAVIS_PYTHON_VERSION != '2.6' ]]; then flake8; fi
+script:
+  -  if [[ $TRAVIS_PYTHON_VERSION == '3.5' ]]; then make style-check test-async; fi
+  -  if [[ $TRAVIS_PYTHON_VERSION != '3.5' ]]; then make test; fi

AUTHORS

@@ -24,10 +24,12 @@ Other contributors, listed alphabetically, are:
 * Charles Duffy -- original graphviz extension
 * Kevin Dunn -- MathJax extension
 * Josip Dzolonga -- coverage builder
+* Buck Evan -- dummy builder
 * Hernan Grecco -- search improvements
 * Horst Gutmann -- internationalization support
 * Martin Hans -- autodoc improvements
 * Doug Hellmann -- graphviz improvements
+* Timotheus Kampik - JS theme & search enhancements
 * Takeshi Komiya -- numref feature
 * Dave Kuhlman -- original LaTeX writer
 * Blaise Laflamme -- pyramid theme
@@ -39,6 +41,7 @@ Other contributors, listed alphabetically, are:
 * Martin Mahner -- nature theme
 * Will Maier -- directory HTML builder
 * Jacob Mason -- websupport library (GSOC project)
+* Glenn Matthews -- python domain signature improvements
 * Roland Meister -- epub builder
 * Ezio Melotti -- collapsible sidebar JavaScript
 * Daniel Neuhäuser -- JavaScript domain, Python 3 support (GSOC)
@@ -50,14 +53,18 @@ Other contributors, listed alphabetically, are:
 * Stefan Seefeld -- toctree improvements
 * Gregory Szorc -- performance improvements
 * Shibukawa Yoshiki -- pluggable search API and Japanese search
+* Taku Shimizu -- epub3 builder
 * Antonio Valentino -- qthelp builder
+* Filip Vavera -- napoleon todo directive
 * Pauli Virtanen -- autodoc improvements, autosummary extension
 * Stefan van der Walt -- autosummary extension
 * Thomas Waldmann -- apidoc module fixes
 * John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
+* Michael Wilson -- Intersphinx HTTP basic auth support
 * Joel Wurtz -- cellspanning support in LaTeX
+* Hong Xu -- svg support in imgmath extension and various bug fixes
 
 Many thanks for all contributions!
 

CHANGES

@@ -1,12 +1,102 @@
-Release 1.4 (in development)
+Release 1.5 (in development)
 ============================
 
 Incompatible changes
 --------------------
 
+* latex, package fancybox is not longer a dependency of sphinx.sty
+* Use ``'locales'`` as a default value of `locale_dirs`
+* latex, package ifthen is not any longer a dependency of sphinx.sty
+* latex, style file does not modify fancyvrb's Verbatim (also available as
+  OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper.
+* latex, package newfloat is no longer a dependency of sphinx.sty (ref #2660;
+  it was shipped with Sphinx since 1.3.4).
+* latex, literal blocks in tables do not use OriginalVerbatim but
+  sphinxVerbatimintable which handles captions and wraps lines(ref #2704).
+* latex, replace ``pt`` by TeX equivalent ``bp`` if found in ``width`` or
+  ``height`` attribute of an image.
+* latex, if ``width`` or ``height`` attribute of an image is given with no unit,
+  use ``px`` rather than ignore it.
+* latex: Separate stylesheets of pygments to independent .sty file
+* #2454: The filename of sourcelink is now changed.  The value of
+  `html_sourcelink_suffix` will be appended to the original filename (like
+  ``index.rst.txt``).
+* ``sphinx.util.copy_static_entry()`` is now deprecated.
+  Use ``sphinx.util.fileutil.copy_asset()`` instead.
+* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been changed
+  (ref: #2510, #2753)
+* Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
+  because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773)
+* QtHelpBuilder doens't generate search page (ref: #2352)
+* QtHelpBuilder uses ``nonav`` theme instead of default one
+  to improve readability.
+* latex: To provide good default settings to Japanese docs, Sphinx uses ``jsbooks``
+  as a docclass by default if the ``language`` is ``ja``.
+* latex: To provide good default settings to Japanese docs, Sphinx uses
+  ``jreport`` and ``jsbooks`` as a docclass by default if the ``language`` is
+  ``ja``.
+* ``sphinx-quickstart`` now allows a project version is empty
+* Fix :download: role on epub/qthelp builder. They ignore the role because they don't support it.
+* ``sphinx.ext.viewcode`` doesn't work on epub building by default. ``viewcode_enable_epub`` option
+* ``sphinx.ext.viewcode`` disabled on singlehtml builder.
+* Use make-mode of ``sphinx-quickstart`` by default.  To disable this, use
+  ``-M`` option
+* Fix ``genindex.html`` to satisfy xhtml standard.
+
 Features added
 --------------
 
+* Add ``:caption:`` option for sphinx.ext.inheritance_diagram.
+* #2471: Add config variable for default doctest flags.
+* Convert linkcheck builder to requests for better encoding handling
+* #2463, #2516: Add keywords of "meta" directive to search index
+* ``:maxdepth:`` option of toctree affects ``secnumdepth`` (ref: #2547)
+* #2575: Now ``sphinx.ext.graphviz`` allows ``:align:`` option
+* Show warnings if unknown key is specified to `latex_elements`
+* Show warnings if no domains match with `primary_domain` (ref: #2001)
+* C++, show warnings when the kind of role is misleading for the kind
+  of target it refers to (e.g., using the `class` role for a function).
+* latex, writer abstracts more of text styling into customizable macros, e.g.
+  the ``visit_emphasis`` will output ``\sphinxstyleemphasis`` rather than
+  ``\emph`` (which may be in use elsewhere or in an added LaTeX package). See
+  list at end of ``sphinx.sty`` (ref: #2686)
+* latex, public names for environments and parameters used by note, warning,
+  and other admonition types, allowing full customizability from the
+  ``'preamble'`` key or an input file (ref: feature request #2674, #2685)
+* latex, better computes column widths of some tables (as a result, there will
+  be slight changes as tables now correctly fill the line width; ref: #2708)
+* latex, sphinxVerbatim environment is more easily customizable (ref: #2704).
+  In addition to already existing VerbatimColor and VerbatimBorderColor:
+
+  - two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``,
+  - booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``.
+
+* latex, captions for literal blocks inside tables are handled, and long code
+  lines wrapped to fit table cell (ref: #2704)
+* #2597: Show warning messages as darkred
+* latex, allow image dimensions using px unit (default is 96px=1in)
+* Show warnings if invalid dimension units found
+* #2650: Add ``--pdb`` option to setup.py command
+* latex, make the use of ``\small`` for code listings customizable (ref #2721)
+* #2663: Add ``--warning-is-error`` option to setup.py command
+* Show warnings if deprecated latex options are used
+* Add sphinx.config.ENUM to check the config values is in candidates
+* math: Add hyperlink marker to each equations in HTML output
+* Add new theme ``nonav`` that doesn't include any navigation links.
+  This is for any help generator like qthelp.
+* #2680: `sphinx.ext.todo` now emits warnings if `todo_emit_warnings` enabled.
+  Also, it emits an additional event named `todo-defined` to handle the TODO
+  entries in 3rd party extensions.
+* Python domain signature parser now uses the xref mixin for 'exceptions',
+  allowing exception classes to be autolinked.
+* #2513: Add `latex_engine` to switch the LaTeX engine by conf.py
+* #2682: C++, basic support for attributes (C++11 style and GNU style).
+  The new configuration variables 'cpp_id_attributes' and 'cpp_paren_attributes'
+  can be used to introduce custom attributes.
+* #1958: C++, add configuration variable 'cpp_index_common_prefix' for removing
+  prefixes from the index text of C++ objects.
+* C++, added concept directive. Thanks to mickk-on-cpp.
+* C++, added support for template introduction syntax. Thanks to mickk-on-cpp.
 * apidoc now avoids invalidating cached files by not writing to files whose
   content doesn't change. This can lead to significant performance wins if
   apidoc is run frequently.
@@ -14,15 +104,616 @@ Features added
 Bugs fixed
 ----------
 
-* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes following
+* #2707: (latex) the column width is badly computed for tabular
-  lines after class definitions
+* #2799: Sphinx installs roles and directives automatically on importing sphinx
-* #1790: ``literalinclude`` strips empty lines at the head and tail
+  module.  Now Sphinx installs them on running application.
-* #1913: C++, fix assert bug for enumerators in next-to-global and global scope.
+* `sphinx.ext.autodoc` crashes if target code imports * from mock modules
+  by `autodoc_mock_imports`.
+* #1953: ``Sphinx.add_node`` does not add handlers the translator installed by
+  `html_translator_class`
+* #1797: text builder inserts blank line on top
 
 Documentation
 -------------
 
 
+Release 1.4.6 (in development)
+==============================
+
+Bugs fixed
+----------
+
+
+Release 1.4.6 (released Aug 20, 2016)
+=====================================
+
+Incompatible changes
+--------------------
+
+* #2867: linkcheck builder crashes with six-1.4.  Now Sphinx depends on six-1.5 or
+  later
+
+Bugs fixed
+----------
+
+* applehelp: Sphinx crashes if ``hiutil`` or ``codesign`` commands not found
+* Fix ``make clean`` abort issue when build dir contains regular files like ``DS_Store``.
+* Reduce epubcheck warnings/errors:
+
+  * Fix DOCTYPE to html5
+  * Change extension from .html to .xhtml.
+  * Disable search page on epub results
+
+* #2778: Fix autodoc crashes if obj.__dict__ is a property method and raises exception
+* Fix duplicated toc in epub3 output.
+* #2775: Fix failing linkcheck with servers not supporting identidy encoding
+* #2833: Fix formatting instance annotations in ext.autodoc.
+* #1911: ``-D`` option of ``sphinx-build`` does not override the ``extensions`` variable
+* #2789: `sphinx.ext.intersphinx` generates wrong hyperlinks if the inventory is given
+* parsing errors for caption of code-blocks are displayed in document (ref: #2845)
+* #2846: ``singlehtml`` builder does not include figure numbers
+* #2816: Fix data from builds cluttering the ``Domain.initial_data`` class attributes
+
+Release 1.4.5 (released Jul 13, 2016)
+=====================================
+
+Incompatible changes
+--------------------
+
+* latex, inclusion of non-inline images from image directive resulted in
+  non-coherent whitespaces depending on original image width; new behaviour
+  by necessity differs from earlier one in some cases. (ref: #2672)
+* latex, use of ``\includegraphics`` to refer to Sphinx custom variant is
+  deprecated; in future it will revert to original LaTeX macro, custom one
+  already has alternative name ``\sphinxincludegraphics``.
+
+Features added
+--------------
+
+* new config option ``latex_keep_old_macro_names``, defaults to True. If False,
+  lets macros (for text styling) be defined only with ``\sphinx``-prefixed names.
+* latex writer allows user customization of "shadowed" boxes (topics), via
+  three length variables.
+* woff-format web font files now supported by the epub builder.
+
+Bugs fixed
+----------
+
+* jsdump fix for python 3: fixes the HTML search on python > 3
+* #2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4
+* #2629: memoir class crashes LaTeX. Fixed ``by latex_keep_old_macro_names=False`` (ref 2675)
+* #2684: `sphinx.ext.intersphinx` crashes with six-1.4.1
+* #2679: ``float`` package needed for ``'figure_align': 'H'`` latex option
+* #2671: image directive may lead to inconsistent spacing in pdf
+* #2705: ``toctree`` generates empty bullet_list if ``:titlesonly:`` specified
+* #2479: `sphinx.ext.viewcode` uses python2 highlighter by default
+* #2700: HtmlHelp builder has hard coded index.html
+* latex, since 1.4.4 inline literal text is followed by spurious space
+* #2722: C++, fix id generation for var/member declarations to include namespaces.
+* latex, images (from image directive) in lists or quoted blocks did not obey
+  indentation (fixed together with #2671)
+* #2733: since Sphinx-1.4.4 ``make latexpdf`` generates lots of hyperref warnings
+* #2731: `sphinx.ext.autodoc` does not access propertymethods which raises any
+  exceptions
+* #2666: C++, properly look up nested names involving constructors.
+* #2579: Could not refer a label including both spaces and colons via
+  `sphinx.ext.intersphinx`
+* #2718: Sphinx crashes if the document file is not readable
+* #2699: hyperlinks in help HTMLs are broken if `html_file_suffix` is set
+* #2723: extra spaces in latex pdf output from multirow cell
+* #2735: latexpdf ``Underfull \hbox (badness 10000)`` warnings from title page
+* #2667: latex crashes if resized images appeared in section title
+* #2763: (html) Provide default value for required ``alt`` attribute for image
+  tags of SVG source, required to validate and now consistent w/ other formats.
+
+
+Release 1.4.4 (released Jun 12, 2016)
+=====================================
+
+Bugs fixed
+----------
+
+* #2630: Latex sphinx.sty Notice Enviroment formatting problem
+* #2632: Warning directives fail in quote environment latex build
+* #2633: Sphinx crashes with old styled indices
+* Fix a ``\begin{\minipage}`` typo in sphinx.sty from 1.4.2 (ref: 68becb1)
+* #2622: Latex produces empty pages after title and table of contents
+* #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
+* Let LaTeX use straight quotes also in inline code (ref #2627)
+* #2351: latex crashes if enumerated lists are placed on footnotes
+* #2646: latex crashes if math contains twice empty lines
+* #2480: `sphinx.ext.autodoc`: memory addresses were shown
+* latex: allow code-blocks appearing inside lists and quotes at maximal nesting
+  depth (ref #777, #2624, #2651)
+* #2635: Latex code directives produce inconsistent frames based on viewing
+  resolution
+* #2639: Sphinx now bundles iftex.sty
+* Failed to build PDF with framed.sty 0.95
+* Sphinx now bundles needspace.sty
+
+
+Release 1.4.3 (released Jun 5, 2016)
+====================================
+
+Bugs fixed
+----------
+
+* #2530: got "Counter too large" error on building PDF if large numbered
+  footnotes existed in admonitions
+* ``width`` option of figure directive does not work if ``align`` option specified at same time (ref: #2595)
+* #2590: The ``inputenc`` package breaks compiling under lualatex and xelatex
+* #2540: date on latex front page use different font
+* Suppress "document isn't included in any toctree" warning if the document is included (ref: #2603)
+* #2614: Some tables in PDF output will end up shifted if user sets non zero
+  \parindent in preamble
+* #2602: URL redirection breaks the hyperlinks generated by `sphinx.ext.intersphinx`
+* #2613: Show warnings if merged extensions are loaded
+* #2619: make sure amstext LaTeX package always loaded (ref: d657225, 488ee52,
+  9d82cad and #2615)
+* #2593: latex crashes if any figures in the table
+
+
+Release 1.4.2 (released May 29, 2016)
+=====================================
+
+Features added
+--------------
+
+* Now :confval:`suppress_warnings` accepts following configurations (ref: #2451, #2466):
+
+  - ``app.add_node``
+  - ``app.add_directive``
+  - ``app.add_role``
+  - ``app.add_generic_role``
+  - ``app.add_source_parser``
+  - ``image.data_uri``
+  - ``image.nonlocal_uri``
+
+* #2453: LaTeX writer allows page breaks in topic contents; and their
+  horizontal extent now fits in the line width (with shadow in margin). Also
+  warning-type admonitions allow page breaks and their vertical spacing has
+  been made more coherent with the one for hint-type notices (ref #2446).
+
+* #2459: the framing of literal code-blocks in LaTeX output (and not only the
+  code lines themselves) obey the indentation in lists or quoted blocks.
+
+* #2343: the long source lines in code-blocks are wrapped (without modifying
+  the line numbering) in LaTeX output (ref #1534, #2304).
+
+Bugs fixed
+----------
+
+* #2370: the equations are slightly misaligned in LaTeX writer
+* #1817, #2077: suppress pep8 warnings on conf.py generated by sphinx-quickstart
+* #2407: building docs crash if document includes large data image URIs
+* #2436: Sphinx does not check version by :confval:`needs_sphinx` if loading extensions failed
+* #2397: Setup shorthandoff for turkish documents
+* #2447: VerbatimBorderColor wrongly used also for captions of PDF
+* #2456: C++, fix crash related to document merging (e.g., singlehtml and Latex builders).
+* #2446: latex(pdf) sets local tables of contents (or more generally topic
+  nodes) in unbreakable boxes, causes overflow at bottom
+* #2476: Omit MathJax markers if :nowrap: is given
+* #2465: latex builder fails in case no caption option is provided to toctree directive
+* Sphinx crashes if self referenced toctree found
+* #2481: spelling mistake for mecab search splitter. Thanks to Naoki Sato.
+* #2309: Fix could not refer "indirect hyperlink targets" by ref-role
+* intersphinx fails if mapping URL contains any port
+* #2088: intersphinx crashes if the mapping URL requires basic auth
+* #2304: auto line breaks in latexpdf codeblocks
+* #1534: Word wrap long lines in Latex verbatim blocks
+* #2460: too much white space on top of captioned literal blocks in PDF output
+* Show error reason when multiple math extensions are loaded (ref: #2499)
+* #2483: any figure number was not assigned if figure title contains only non text objects
+* #2501: Unicode subscript numbers are normalized in LaTeX
+* #2492: Figure directive with :figwidth: generates incorrect Latex-code
+* The caption of figure is always put on center even if ``:align:`` was specified
+* #2526: LaTeX writer crashes if the section having only images
+* #2522: Sphinx touches mo files under installed directory that caused permission error.
+* #2536: C++, fix crash when an immediately nested scope has the same name as the current scope.
+* #2555: Fix crash on any-references with unicode.
+* #2517: wrong bookmark encoding in PDF if using LuaLaTeX
+* #2521: generated Makefile causes BSD make crashed if sphinx-build not found
+* #2470: ``typing`` backport package causes autodoc errors with python 2.7
+* ``sphinx.ext.intersphinx`` crashes if non-string value is used for key of `intersphinx_mapping`
+* #2518: `intersphinx_mapping` disallows non alphanumeric keys
+* #2558: unpack error on devhelp builder
+* #2561: Info builder crashes when a footnote contains a link
+* #2565: The descriptions of objects generated by ``sphinx.ext.autosummary`` overflow lines at LaTeX writer
+* Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
+* #2445: `rst_prolog` and `rst_epilog` affect to non reST sources
+* #2576: ``sphinx.ext.imgmath`` crashes if subprocess raises error
+* #2577: ``sphinx.ext.imgmath``: Invalid argument are passed to dvisvgm
+* #2556: Xapian search does not work with Python 3
+* #2581: The search doesn't work if language="es" (spanish)
+* #2382: Adjust spacing after abbreviations on figure numbers in LaTeX writer
+* #2383: The generated footnote by `latex_show_urls` overflows lines
+* #2497, #2552: The label of search button does not fit for the button itself
+
+
+Release 1.4.1 (released Apr 12, 2016)
+=====================================
+
+Incompatible changes
+--------------------
+
+* The default format of `today_fmt` and `html_last_updated_fmt` is back to
+  strftime format again.  Locale Date Markup Language is also supported for
+  backward compatibility until Sphinx-1.5.
+
+Translations
+------------
+
+* Added Welsh translation, thanks to Geraint Palmer.
+* Added Greek translation, thanks to Stelios Vitalis.
+* Added Esperanto translation, thanks to Dinu Gherman.
+* Added Hindi translation, thanks to Purnank H. Ghumalia.
+* Added Romanian translation, thanks to Razvan Stefanescu.
+
+Bugs fixed
+----------
+
+* C++, added support for ``extern`` and ``thread_local``.
+* C++, type declarations are now using the prefixes ``typedef``, ``using``, and ``type``,
+  depending on the style of declaration.
+* #2413: C++, fix crash on duplicate declarations
+* #2394: Sphinx crashes when html_last_updated_fmt is invalid
+* #2408: dummy builder not available in Makefile and make.bat
+* #2412: hyperlink targets are broken in LaTeX builder
+* figure directive crashes if non paragraph item is given as caption
+* #2418: time formats no longer allowed in today_fmt
+* #2395: Sphinx crashes if unicode character in image filename
+* #2396: "too many values to unpack" in genindex-single
+* #2405: numref link in PDF jumps to the wrong location
+* #2414: missing number in PDF hyperlinks to code listings
+* #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
+
+
+Release 1.4 (released Mar 28, 2016)
+===================================
+
+Incompatible changes
+--------------------
+* Drop ``PorterStemmer`` package support. Use ``PyStemmer`` instead of ``PorterStemmer``
+  to accelerate stemming.
+* sphinx_rtd_theme has become optional. Please install it manually.
+  Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
+* #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take
+  title of roles as an argument of custom macros.
+* #2022: 'Thumbs.db' and '.DS_Store' are added to `exclude_patterns` default values in
+  conf.py that will be provided on sphinx-quickstart.
+* #2027, #2208: The ``html_title`` accepts string values only. And The None value cannot be
+  accepted.
+* ``sphinx.ext.graphviz``: show graph image in inline by default
+* #2060, #2224: The ``manpage`` role now generate ``sphinx.addnodes.manpage`` node instead
+  of ``sphinx.addnodes.literal_emphasis`` node.
+* #2022: :confval:`html_extra_path` also copies dotfiles in the extra directory, and
+  refers to :confval:`exclude_patterns` to exclude extra files and directories.
+* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing
+  of empty
+* #2251: Previously, under glossary directives, multiple terms for one definition are
+  converted into single ``term`` node and the each terms in the term node are separated
+  by ``termsep`` node. In new implementation, each terms are converted into individual
+  ``term`` nodes and ``termsep`` node is removed.
+  By this change, output layout of every builders are changed a bit.
+* The default highlight language is now Python 3.  This means that source code
+  is highlighted as Python 3 (which is mostly a superset of Python 2), and no
+  parsing is attempted to distinguish valid code.  To get the old behavior back,
+  add ``highlight_language = "python"`` to conf.py.
+* `Locale Date Markup Language
+  <http://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns>`_ like
+  ``"MMMM dd, YYYY"`` is default format for `today_fmt` and `html_last_updated_fmt`.
+  However strftime format like ``"%B %d, %Y"`` is also supported for backward
+  compatibility until Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
+* #2327: `latex_use_parts` is deprecated now. Use `latex_toplevel_sectioning` instead.
+* #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer.
+* #1498: manpage writer: don't make whole of item in definition list bold if it includes strong node.
+* #582: Remove hint message from quick search box for html output.
+* #2378: Sphinx now bundles newfloat.sty
+
+Features added
+--------------
+* #2092: add todo directive support in napoleon package.
+* #1962: when adding directives, roles or nodes from an extension, warn if such
+  an element is already present (built-in or added by another extension).
+* #1909: Add "doc" references to Intersphinx inventories.
+* C++ type alias support (e.g., ``.. type:: T = int``).
+* C++ template support for classes, functions, type aliases, and variables (#1729, #1314).
+* C++, added new scope management directives ``namespace-push`` and ``namespace-pop``.
+* #1970: Keyboard shortcuts to navigate Next and Previous topics
+* Intersphinx: Added support for fetching Intersphinx inventories with URLs
+  using HTTP basic auth.
+* C++, added support for template parameter in function info field lists.
+* C++, added support for pointers to member (function).
+* #2113: Allow ``:class:`` option to code-block directive.
+* #2192: Imgmath (pngmath with svg support).
+* #2200: Support XeTeX and LuaTeX for the LaTeX builder.
+* #1906: Use xcolor over color for \fcolorbox where available for LaTeX output.
+* #2216: Texinputs makefile improvements.
+* #2170: Support for Chinese language search index.
+* #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
+* #1030: Make page reference names for latex_show_pagerefs translatable
+* #2162: Add Sphinx.add_source_parser() to add source_suffix and source_parsers from extension
+* #2207: Add sphinx.parsers.Parser class; a base class for new parsers
+* #656: Add ``graphviz_dot`` option to graphviz directives to switch the ``dot`` command
+* #1939: Added the ``dummy`` builder: syntax check without output.
+* #2230: Add ``math_number_all`` option to number all displayed math in math extensions
+* #2235: ``needs_sphinx`` supports micro version comparison
+* #2282: Add "language" attribute to html tag in the "basic" theme
+* #1779: Add EPUB 3 builder
+* #1751: Add :confval:`todo_link_only` to avoid file path and line indication on
+  :rst:dir:`todolist`. Thanks to Francesco Montesano.
+* #2199: Use ``imagesize`` package to obtain size of images.
+* #1099: Add configurable retries to the linkcheck builder. Thanks to Alex Gaynor.
+  Also don't check anchors starting with ``!``.
+* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing
+  of empty
+* #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature
+* #1286, #2099: Add ``sphinx.ext.autosectionlabel`` extension to allow reference
+  sections using its title. Thanks to Tadhg O'Higgins.
+* #1854: Allow to choose Janome for Japanese splitter.
+* #1853: support custom text splitter on html search with ``language='ja'``.
+* #2320: classifier of glossary terms can be used for index entries grouping key.
+  The classifier also be used for translation. See also :ref:`glossary-directive`.
+* #2308: Define ``\tablecontinued`` macro to redefine the style of continued label for
+  longtables.
+* Select an image by similarity if multiple images are globbed by ``.. image:: filename.*``
+* #1921: Support figure substitutions by :confval:`language` and :confval:`figure_language_filename`
+* #2245: Add ``latex_elements["passoptionstopackages"]`` option to call PassOptionsToPackages
+  in early stage of preambles.
+* #2340: Math extension: support alignment of multiple equations for MathJAX.
+* #2338: Define ``\titleref`` macro to redefine the style of ``title-reference`` roles.
+* Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of `menuselection` roles.
+* Define ``\crossref`` macro to redefine the style of references
+* #2301: Texts in the classic html theme should be hyphenated.
+* #2355: Define ``\termref`` macro to redefine the style of ``term`` roles.
+* Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental)
+* #2229: Fix no warning is given for unknown options
+* #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of LaTeX document.
+
+Bugs fixed
+----------
+* #1913: C++, fix assert bug for enumerators in next-to-global and global scope.
+* C++, fix parsing of 'signed char' and 'unsigned char' as types.
+* C++, add missing support for 'friend' functions.
+* C++, add missing support for virtual base classes (thanks to Rapptz).
+* C++, add support for final classes.
+* C++, fix parsing of types prefixed with 'enum'.
+* #2023: Dutch search support uses Danish stemming info.
+* C++, add support for user-defined literals.
+* #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks to
+  Hassen ben tanfous.
+* #2183: Fix porterstemmer causes ``make json`` to fail.
+* #1899: Ensure list is sent to OptParse.
+* #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package option).
+* #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
+* Fix broken LaTeX code is generated if unknown language is given
+* #1944: Fix rst_prolog breaks file-wide metadata
+* #2074: make gettext should use canonical relative paths for .pot. Thanks to
+  anatoly techtonik.
+* #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
+* #2251: Line breaks in .rst files are transferred to .pot files in a wrong way.
+* #794: Fix date formatting in latex output is not localized
+* Remove ``image/gif`` from supported_image_types of LaTeX writer (#2272)
+* Fix ValueError is raised if LANGUAGE is empty string
+* Fix unpack warning is shown when the directives generated from ``Sphinx.add_crossref_type`` is used
+* The default highlight language is now ``default``.  This means that source code
+  is highlighted as Python 3 (which is mostly a superset of Python 2) if possible.
+  To get the old behavior back, add ``highlight_language = "python"`` to conf.py.
+* #2329: Refresh environment forcely if source directory has changed.
+* #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option from
+  xcolor package
+* Fix the confval type checker emits warnings if unicode is given to confvals which expects string value
+* #2360: Fix numref in LaTeX output is broken
+* #2361: Fix additional paragraphs inside the "compound" directive are indented
+* #2364: Fix KeyError 'rootSymbol' on Sphinx upgrade from older version.
+* #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
+* #2368: Ignore emacs lock files like ``.#foo.rst`` by default.
+* #2262: literal_block and its caption has been separated by pagebreak in LaTeX output.
+* #2319: Fix table counter is overrided by code-block's in LaTeX.  Thanks to jfbu.
+* Fix unpack warning if combinated with 3rd party domain extensions.
+* #1153: Fix figures in sidebar causes latex build error.
+* #2358: Fix user-preamble could not override the tocdepth definition.
+* #2358: Redece tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel.
+* #2351: Fix footnote spacing
+* #2363: Fix ``toctree()`` in templates generates broken links in SingleHTMLBuilder.
+* #2366: Fix empty hyperref is generated on toctree in HTML builder.
+
+Documentation
+-------------
+
+* #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf Hemmecke.
+
+
+Release 1.3.6 (released Feb 29, 2016)
+=====================================
+
+Features added
+--------------
+
+* #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This should be
+  introduced with :confval:`source_parsers` feature. Thanks for Eric Holscher.
+
+
+Bugs fixed
+----------
+
+* #2265: Fix babel is used in spite of disabling it on ``latex_elements``
+* #2295: Avoid mutating dictionary errors while enumerating members in autodoc
+  with Python 3
+* #2291: Fix pdflatex "Counter too large" error from footnotes inside tables of contents
+* #2292: Fix some footnotes disappear from LaTeX output
+* #2287: ``sphinx.transforms.Locale`` always uses rst parser. Sphinx i18n feature should
+  support parsers that specified source_parsers.
+* #2290: Fix ``sphinx.ext.mathbase`` use of amsfonts may break user choice of math fonts
+* #2324: Print a hint how to increase the recursion limit when it is hit.
+* #1565, #2229: Revert new warning; the new warning will be triggered from version 1.4 on.
+* #2329: Refresh environment forcely if source directory has changed.
+* #2019: Fix the domain objects in search result are not escaped
+
+Release 1.3.5 (released Jan 24, 2016)
+=====================================
+
+Bugs fixed
+----------
+
+* Fix line numbers was not shown on warnings in LaTeX and texinfo builders
+* Fix filenames were not shown on warnings of citations
+* Fix line numbers was not shown on warnings in LaTeX and texinfo builders
+* Fix line numbers was not shown on warnings of indices
+* #2026: Fix LaTeX builder raises error if parsed-literal includes links
+* #2243: Ignore strange docstring types for classes, do not crash
+* #2247: Fix #2205 breaks make html for definition list with classifiers
+  that contains regular-expression like string
+* #1565: Sphinx will now emit a warning that highlighting was skipped if the syntax
+  is incorrect for `code-block`, `literalinclude` and so on.
+* #2211: Fix paragraphs in table cell doesn't work in Latex output
+* #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect indented
+  body block when the block starts with blank or comment lines.
+* Fix TOC is not shown when no ``:maxdepth:`` for toctrees (ref: #771)
+* Fix warning message for ``:numref:`` if target is in orphaned doc (ref: #2244)
+
+Release 1.3.4 (released Jan 12, 2016)
+=====================================
+
+Bugs fixed
+----------
+
+* #2134: Fix figure caption with reference causes latex build error
+* #2094: Fix rubric with reference not working in Latex
+* #2147: Fix literalinclude code in latex does not break in pages
+* #1833: Fix email addresses is showed again if latex_show_urls is not None
+* #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed svg
+* #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
+* #1237: Fix footnotes not working in definition list in LaTeX
+* #2168: Fix raw directive does not work for text writer
+* #2171: Fix cannot linkcheck url with unicode
+* #2182: LaTeX: support image file names with more than 1 dots
+* #2189: Fix previous sibling link for first file in subdirectory uses last file, not
+  intended previous from root toctree
+* #2003: Fix decode error under python2 (only) when ``make linkcheck`` is run
+* #2186: Fix LaTeX output of \mathbb in math
+* #1480, #2188: LaTeX: Support math in section titles
+* #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug
+* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii characters
+* #2193: Fix shutil.SameFileError if source directory and destination directory are same
+* #2178: Fix unparseable C++ cross-reference when referencing a function with :cpp:any:
+* #2206: Fix Sphinx latex doc build failed due to a footnotes
+* #2201: Fix wrong table caption for tables with over 30 rows
+* #2213: Set <blockquote> in the classic theme to fit with <p>
+* #1815: Fix linkcheck does not raise an exception if warniserror set to true and link is
+  broken
+* #2197: Fix slightly cryptic error message for missing index.rst file
+* #1894: Unlisted phony targets in quickstart Makefile
+* #2125: Fix unifies behavior of collapsed fields (``GroupedField`` and ``TypedField``)
+* #1408: Check latex_logo validity before copying
+* #771: Fix latex output doesn't set tocdepth
+* #1820: On Windows, console coloring is broken with colorama version 0.3.3.
+  Now sphinx use colorama>=0.3.5 to avoid this problem.
+* #2072: Fix footnotes in chapter-titles do not appear in PDF output
+* #1580: Fix paragraphs in longtable don't work in Latex output
+* #1366: Fix centered image not centered in latex
+* #1860: Fix man page using ``:samp:`` with braces - font doesn't reset
+* #1610: Sphinx crashes in japanese indexing in some systems
+* Fix Sphinx crashes if mecab initialization failed
+* #2160: Fix broken TOC of PDFs if section includes an image
+* #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty. Thanks to jfbu.
+* #2198,#2205: ``make gettext`` generate broken msgid for definition lists.
+* #2062: Escape characters in doctests are treated incorrectly with Python 2.
+* #2225: Fix if the option does not begin with dash, linking is not performed
+* #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax)
+* #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions doesn't
+  support resolve_any_xref and resolve_xref returns problematic node instead of None.
+  sphinxcontrib-httpdomain is one of them.
+* #2229: Fix no warning is given for unknown options
+
+Release 1.3.3 (released Dec 2, 2015)
+====================================
+
+Bugs fixed
+----------
+
+* #2177: Fix parallel hangs
+* #2012: Fix exception occurred if ``numfig_format`` is invalid
+* #2142: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` for
+  source distribution on PyPI.
+* #2148: Error while building devhelp target with non-ASCII document.
+
+
+Release 1.3.2 (released Nov 29, 2015)
+=====================================
+
+Features added
+--------------
+
+* #1935: Make "numfig_format" overridable in latex_elements.
+
+Bugs fixed
+----------
+
+* #1976: Avoid "2.0" version of Babel because it doesn't work with Windows environment.
+* Add a "default.css" stylesheet (which imports "classic.css") for compatibility.
+* #1788: graphviz extension raises exception when caption option is present.
+* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes following
+  lines after class definitions
+* #1790: ``literalinclude`` strips empty lines at the head and tail
+* #1802: load plugin themes automatically when theme.conf use it as 'inherit'. Thanks to
+  Takayuki Hirai.
+* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find base theme.
+* #1834: compatibility for docutils-0.13: handle_io_errors keyword argument for
+  docutils.io.FileInput cause TypeError.
+* #1823: '.' as <module_path> for sphinx-apidoc cause an unfriendly error. Now '.'
+  is converted to absolute path automatically.
+* Fix a crash when setting up extensions which do not support metadata.
+* #1784: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js``
+* #1822, #1892: Fix regression for #1061. autosummary can't generate doc for imported
+  members since sphinx-1.3b3. Thanks to Eric Larson.
+* #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki Hirai.
+* #1780, #1866: "make text" shows "class" keyword twice. Thanks to Takayuki
+  Hirai.
+* #1871: Fix for LaTeX output of tables with one column and multirows.
+* Work around the lack of the HTMLParserError exception in Python 3.5.
+* #1949: Use ``safe_getattr`` in the coverage builder to avoid aborting with
+  descriptors that have custom behavior.
+* #1915: Do not generate smart quotes in doc field type annotations.
+* #1796: On py3, automated .mo building caused UnicodeDecodeError.
+* #1923: Use babel features only if the babel latex element is nonempty.
+* #1942: Fix a KeyError in websupport.
+* #1903: Fix strange id generation for glossary terms.
+* ``make text`` will crush if a definition list item has more than 1 classifiers as:
+  ``term : classifier1 : classifier2``.
+* #1855: make gettext generates broken po file for definition lists with classifier.
+* #1869: Fix problems when dealing with files containing non-ASCII characters. Thanks to
+  Marvin Schmidt.
+* #1798: Fix building LaTeX with references in titles.
+* #1725: On py2 environment, doctest with using non-ASCII characters causes
+  ``'ascii' codec can't decode byte`` exception.
+* #1540: Fix RuntimeError with circular referenced toctree
+* #1983: i18n translation feature breaks references which uses section name.
+* #1990: Use caption of toctree to title of \tableofcontents in LaTeX
+* #1987: Fix ampersand is ignored in ``:menuselection:`` and ``:guilabel:`` on LaTeX builder
+* #1994: More supporting non-standard parser (like recommonmark parser) for Translation and
+  WebSupport feature. Now node.rawsource is fall backed to node.astext() during docutils
+  transforming.
+* #1989: "make blahblah" on Windows indicate help messages for sphinx-build every time.
+  It was caused by wrong make.bat that generated by Sphinx-1.3.0/1.3.1.
+* On Py2 environment, conf.py that is generated by sphinx-quickstart should have u prefixed
+  config value for 'version' and 'release'.
+* #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will raise
+  UnicodeEncodeError.
+* #1974: UnboundLocalError: local variable 'domain' referenced before assignment when
+  using `any` role and `sphinx.ext.intersphinx` in same time.
+* #2121: multiple words search doesn't find pages when words across on the page title and
+  the page content.
+* #1884, #1885: plug-in html themes cannot inherit another plug-in theme. Thanks to
+  Suzumizaki.
+* #1818: `sphinx.ext.todo` directive generates broken html class attribute as
+  'admonition-' when :confval:`language` is specified with non-ASCII linguistic area like
+  'ru' or 'ja'. To fix this, now ``todo`` directive can use ``:class:`` option.
+* #2140: Fix footnotes in table has broken in LaTeX
+* #2127: MecabBinder for html searching feature doesn't work with Python 3.
+  Thanks to Tomoko Uchida.
+
+
 Release 1.3.1 (released Mar 17, 2015)
 =====================================
 
@@ -43,6 +734,7 @@ Bugs fixed
   Thanks to Jens Hedegaard Nielsen.
 * #1781: Setting `html_domain_indices` to a list raises a type check warnings.
 
+
 Release 1.3 (released Mar 10, 2015)
 ===================================
 
@@ -91,6 +783,7 @@ Documentation
 
 * #1651: Add ``vartype`` field descritpion for python domain.
 
+
 Release 1.3b3 (released Feb 24, 2015)
 =====================================
 
@@ -100,7 +793,7 @@ Incompatible changes
 * Dependency requirement updates: docutils 0.11, Pygments 2.0
 * The ``gettext_enables`` config value has been renamed to
   `gettext_additional_targets`.
-* #1735: Use https://doc.python.org/ instead of ``http`` protocol.
+* #1735: Use https://docs.python.org/ instead of ``http`` protocol.
   It was used for `sphinx.ext.intersphinx` and some documentation.
 
 Features added
@@ -495,7 +1188,7 @@ Bugs fixed
   if they contain uppercase letters.
 * #923: Take the entire LaTeX document into account when caching
   pngmath-generated images.  This rebuilds them correctly when
-  `pngmath_latex_preamble` changes.
+  ``pngmath_latex_preamble`` changes.
 * #901: Emit a warning when using docutils' new "math" markup without a Sphinx
   math extension active.
 * #845: In code blocks, when the selected lexer fails, display line numbers
@@ -824,13 +1517,12 @@ Features added
 * Command-line interfaces:
 
   - PR#75: Added ``--follow-links`` option to sphinx-apidoc.
-  - #869: sphinx-build now has the option :option:`-T` for printing the full
+  - #869: sphinx-build now has the option ``-T`` for printing the full
     traceback after an unhandled exception.
-  - sphinx-build now supports the standard :option:`--help` and
+  - sphinx-build now supports the standard ``--help`` and ``--version`` options.
-    :option:`--version` options.
   - sphinx-build now provides more specific error messages when called with
     invalid options or arguments.
-  - sphinx-build now has a verbose option :option:`-v` which can be repeated for
+  - sphinx-build now has a verbose option ``-v`` which can be repeated for
     greater effect.  A single occurrence provides a slightly more verbose output
     than normal.  Two or more occurrences of this option provides more detailed
     output which may be useful for debugging.
@@ -852,7 +1544,7 @@ Features added
     stemming routines.  Saves about 20 seconds when building the Python
     documentation.
   - PR#108: Add experimental support for parallel building with a new
-    :option:`-j` option.
+    :option:`sphinx-build -j` option.
 
 Documentation
 -------------
@@ -1114,7 +1806,7 @@ Features added
     indicators.
   - #367: Added automatic exclusion of hidden members in inheritance
     diagrams, and an option to selectively enable it.
-  - Added `pngmath_add_tooltips`.
+  - Added ``pngmath_add_tooltips``.
   - The math extension displaymath directives now support ``name`` in
     addition to ``label`` for giving the equation label, for compatibility
     with Docutils.
@@ -1442,7 +2134,7 @@ Features added
 * General:
 
   - Added a "nitpicky" mode that emits warnings for all missing
-    references.  It is activated by the :option:`-n` command-line switch
+    references.  It is activated by the :option:`sphinx-build -n` command-line switch
     or the `nitpicky` config value.
   - Added ``latexpdf`` target in quickstart Makefile.
 

EXAMPLES

@@ -4,22 +4,27 @@ Projects using Sphinx
 This is an (incomplete) alphabetic list of projects that use Sphinx or
 are experimenting with using it for their documentation.  If you like to
 be included, please mail to `the Google group
-<https://groups.google.com/group/sphinx-users>`_.
+<https://groups.google.com/forum/#!forum/sphinx-users>`_.
 
 I've grouped the list into sections to make it easier to find
 interesting examples.
 
-Documentation using the default theme
+Documentation using the alabaster theme
+---------------------------------------
+
+* PyLangAcq: http://pylangacq.org/
+
+Documentation using the classic theme
 -------------------------------------
 
 * APSW: http://apidoc.apsw.googlecode.com/hg/index.html
 * ASE: https://wiki.fysik.dtu.dk/ase/
 * Calibre: http://manual.calibre-ebook.com/
-* CodePy: http://documen.tician.de/codepy/
+* CodePy: https://documen.tician.de/codepy/
 * Cython: http://docs.cython.org/
 * Cormoran: http://cormoran.nhopkg.org/docs/
 * Director: http://pythonhosted.org/director/
-* Dirigible: http://www.projectdirigible.com/documentation/
+* Dirigible: http://www.projectdirigible.com/
 * F2py: http://f2py.sourceforge.net/docs/
 * GeoDjango: https://docs.djangoproject.com/en/dev/ref/contrib/gis/
 * Genomedata:
@@ -31,10 +36,10 @@ Documentation using the default theme
 * Heapkeeper: http://heapkeeper.org/
 * Hands-on Python Tutorial:
   http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
-* Hedge: http://documen.tician.de/hedge/
+* Hedge: https://documen.tician.de/hedge/
 * Leo: http://leoeditor.com/
-* Lino: http://lino.saffre-rumma.net/
+* Lino: http://www.lino-framework.org/
-* MeshPy: http://documen.tician.de/meshpy/
+* MeshPy: https://documen.tician.de/meshpy/
 * mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
 * OpenEXR: http://excamera.com/articles/26/doc/index.html
 * OpenGDA: http://www.opengda.org/gdadoc/html/
@@ -42,19 +47,21 @@ Documentation using the default theme
 * Paste: http://pythonpaste.org/script/
 * Paver: http://paver.github.io/paver/
 * Pioneers and Prominent Men of Utah: http://pioneers.rstebbing.com/
-* PyCantonese: http://pycantonese.github.io/
+* PyCantonese: http://pycantonese.org/
 * Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
-* PyCuda: http://documen.tician.de/pycuda/
+* PyCuda: https://documen.tician.de/pycuda/
 * Pyevolve: http://pyevolve.sourceforge.net/
-* Pylo: http://documen.tician.de/pylo/
+* Pylo: https://documen.tician.de/pylo/
 * PyMQI: http://pythonhosted.org/pymqi/
 * PyPubSub: http://pubsub.sourceforge.net/
 * pySPACE: http://pyspace.github.io/pyspace/
-* Python: https://docs.python.org/
+* Python: https://docs.python.org/3/
 * python-apt: http://apt.alioth.debian.org/python-apt-doc/
-* PyUblas: http://documen.tician.de/pyublas/
+* PyUblas: https://documen.tician.de/pyublas/
 * Quex: http://quex.sourceforge.net/doc/html/main.html
+* Ring programming language: http://ring-lang.sourceforge.net/doc/index.html
 * Scapy: http://www.secdev.org/projects/scapy/doc/
+* Seaborn: https://stanford.edu/~mwaskom/software/seaborn/
 * Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
 * SimPy: http://simpy.readthedocs.org/en/latest/
 * SymPy: http://docs.sympy.org/
@@ -62,11 +69,12 @@ Documentation using the default theme
 * z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
 
 
-Documentation using a customized version of the default theme
+Documentation using a customized version of the classic theme
 -------------------------------------------------------------
 
 * Advanced Generic Widgets:
   http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
+* Arb: http://fredrikj.net/arb/
 * Bazaar: http://doc.bazaar.canonical.com/en/
 * CakePHP: http://book.cakephp.org/2.0/en/index.html
 * Chaco: http://docs.enthought.com/chaco/
@@ -78,7 +86,6 @@ Documentation using a customized version of the default theme
   https://or-tools.googlecode.com/svn/trunk/documentation/user_manual/index.html
 * GPAW: https://wiki.fysik.dtu.dk/gpaw/
 * Grok: http://grok.zope.org/doc/current/
-* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
 * Kaa: http://api.freevo.org/kaa-base/
 * LEPL: http://www.acooke.org/lepl/
 * Mayavi: http://docs.enthought.com/mayavi/mayavi/
@@ -87,11 +94,11 @@ Documentation using a customized version of the default theme
 * NumPy: http://docs.scipy.org/doc/numpy/reference/
 * OpenCV: http://docs.opencv.org/
 * Peach^3: http://peach3.nl/doc/latest/userdoc/
-* Sage: http://sagemath.org/doc/
+* Sage: http://www.sagemath.org/doc/
 * SciPy: http://docs.scipy.org/doc/scipy/reference/
 * simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html
 * Sprox: http://sprox.org/
-* TurboGears: http://turbogears.org/2.0/docs/
+* TurboGears: http://turbogears.readthedocs.org/en/latest/
 * Varnish: https://www.varnish-cache.org/docs/
 * Zentyal: http://doc.zentyal.org/
 * Zope: http://docs.zope.org/zope2/index.html
@@ -114,18 +121,19 @@ Documentation using the sphinxdoc theme
 * Python Wild Magic: http://vmlaker.github.io/pythonwildmagic/
 * Reteisi: http://www.reteisi.org/contents.html
 * Sqlkit: http://sqlkit.argolinux.org/
-* Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
 * Turbulenz: http://docs.turbulenz.com/
-* WebFaction: http://docs.webfaction.com/
+* WebFaction: https://docs.webfaction.com/
 
 
 Documentation using another builtin theme
 -----------------------------------------
 
 * C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
+* ESWP3 (http://eswp3.org) (sphinx_rtd_theme)
 * Jinja: http://jinja.pocoo.org/ (scrolls)
 * jsFiddle: http://doc.jsfiddle.net/ (nature)
 * libLAS: http://www.liblas.org/ (nature)
+* Linguistica: http://linguistica-uchicago.github.io/lxa5/ (sphinx_rtd_theme)
 * MPipe: http://vmlaker.github.io/mpipe/ (sphinx13)
 * pip: https://pip.pypa.io/en/latest/ (sphinx_rtd_theme)
 * Pyramid web framework:
@@ -145,12 +153,12 @@ Documentation using another builtin theme
 Documentation using a custom theme/integrated in a site
 -------------------------------------------------------
 
-* Blender: http://www.blender.org/documentation/250PythonDoc/
+* Blender: https://www.blender.org/api/250PythonDoc/
 * Blinker: http://discorporate.us/projects/Blinker/docs/
-* Ceph: http://ceph.com/docs/master/
+* Ceph: http://docs.ceph.com/docs/master/
 * Classy: http://www.pocoo.org/projects/classy/
 * DEAP: http://deap.gel.ulaval.ca/doc/0.8/index.html
-* Django: http://docs.djangoproject.com/
+* Django: https://docs.djangoproject.com/
 * Elemental: http://libelemental.org/documentation/dev/index.html
 * Enterprise Toolkit for Acrobat products:
   http://www.adobe.com/devnet-docs/acrobatetk/
@@ -159,34 +167,33 @@ Documentation using a custom theme/integrated in a site
 * Flask-OpenID: http://pythonhosted.org/Flask-OpenID/
 * Gameduino: http://excamera.com/sphinx/gameduino/
 * GeoServer: http://docs.geoserver.org/
+* GHC - Glasgow Haskell Compiler: http://downloads.haskell.org/~ghc/master/users-guide/
 * Glashammer: http://glashammer.org/
-* Istihza (Turkish Python documentation project):
+* Istihza (Turkish Python documentation project): http://belgeler.istihza.com/py2/
-  http://www.istihza.com/py2/icindekiler_python.html
 * Lasso: http://lassoguide.com/
 * Manage documentation such as source code (fr): http://redaction-technique.org/
 * MathJax: http://docs.mathjax.org/en/latest/
 * MirrorBrain: http://mirrorbrain.org/docs/
 * MyHDL: http://docs.myhdl.org/en/latest/
 * nose: http://nose.readthedocs.org/en/latest/
-* NoTex: https://notex.ch/overview/
+* NoTex: https://www.notex.ch/overview/
 * ObjectListView: http://objectlistview.sourceforge.net/python/
-* Open ERP: http://doc.openerp.com/
+* Open ERP: https://doc.odoo.com/
 * OpenCV: http://docs.opencv.org/
-* Open Dylan: http://opendylan.org/documentation/ and also provides a
+* Open Dylan: http://opendylan.org/documentation/
-  `dylan domain <https://github.com/dylan-lang/sphinx-extensions/blob/master/dylandomain/reference.rst>`__
 * OpenLayers: http://docs.openlayers.org/
 * PyEphem: http://rhodesmill.org/pyephem/
 * German Plone user manual: http://www.hasecke.com/plone-benutzerhandbuch/
-* PSI4: http://sirius.chem.vt.edu/psi4manual/latest/index.html
+* PSI4: http://www.psicode.org/psi4manual/master/index.html
 * Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/
-* PyMOTW: http://pymotw.com/2/
+* PyMOTW: https://pymotw.com/2/
 * python-aspectlib: http://python-aspectlib.readthedocs.org/en/latest/
   (`sphinx-py3doc-enhanced-theme`_)
 * QGIS: http://qgis.org/en/docs/index.html
 * qooxdoo: http://manual.qooxdoo.org/current/
 * Roundup: http://www.roundup-tracker.org/
 * Selenium: http://docs.seleniumhq.org/docs/
-* Self: http://selflanguage.org/
+* Self: http://www.selflanguage.org/
 * Substance D: http://docs.pylonsproject.org/projects/substanced/en/latest/
 * Tablib: http://tablib.org/
 * SQLAlchemy: http://www.sqlalchemy.org/docs/
@@ -201,14 +208,12 @@ Documentation using a custom theme/integrated in a site
 Homepages and other non-documentation sites
 -------------------------------------------
 
-* Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
 * A personal page: http://www.dehlia.in/
 * Benoit Boissinot: http://bboissin.appspot.com/
 * lunarsite: http://lunaryorn.de/
-* Red Hot Chili Python: http://redhotchilipython.com/
 * The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
 * UC Berkeley Advanced Control Systems course:
-  http://www.me.berkeley.edu/ME233/sp14/
+  http://msc.berkeley.edu/tomizuka/me233spring13/
 * VOR: http://www.vor-cycling.be/
 
 
@@ -217,11 +222,11 @@ Books produced using Sphinx
 
 * "The ``repoze.bfg`` Web Application Framework":
   http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
-* A Theoretical Physics Reference book: http://theoretical-physics.net/
+* A Theoretical Physics Reference book: http://www.theoretical-physics.net/
 * "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
   http://www.amazon.co.jp/dp/477414259X/
 * "Expert Python Programming":
-  http://www.packtpub.com/expert-python-programming/book
+  https://www.packtpub.com/application-development/expert-python-programming
 * "Expert Python Programming" (Japanese translation):
   http://www.amazon.co.jp/dp/4048686291/
 * "Pomodoro Technique Illustrated" (Japanese translation):
@@ -231,7 +236,7 @@ Books produced using Sphinx
 * "Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski":
   http://www.hasecke.eu/Dekalog/
 * The "Varnish Book":
-  https://www.varnish-software.com/static/book/
+  http://book.varnish-software.com/4.0/
 * "Learning Sphinx" (in Japanese):
   http://www.oreilly.co.jp/books/9784873116488/
 * "LassoGuide":

LICENSE

@@ -1,7 +1,7 @@
 License for Sphinx
 ==================
 
-Copyright (c) 2007-2015 by the Sphinx team (see AUTHORS file).
+Copyright (c) 2007-2016 by the Sphinx team (see AUTHORS file).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

MANIFEST.in

@@ -13,14 +13,15 @@ include sphinx-build.py
 include sphinx-quickstart.py
 include sphinx-apidoc.py
 
+recursive-include sphinx/templates *
 recursive-include sphinx/texinputs *
 recursive-include sphinx/themes *
 recursive-include sphinx/locale *
+recursive-include sphinx/search/non-minified-js *.js
 recursive-include sphinx/ext/autosummary/templates *
 recursive-include tests *
 recursive-include utils *
-include sphinx/pycode/Grammar-py2.txt
+include sphinx/pycode/Grammar-py*
-include sphinx/pycode/Grammar-py3.txt
 
 recursive-include doc *
 prune doc/_build

Makefile

@@ -1,12 +1,17 @@
 PYTHON ?= python
 
-.PHONY: all check clean clean-pyc clean-patchfiles clean-backupfiles \
+.PHONY: all style-check clean clean-pyc clean-patchfiles clean-backupfiles \
-        clean-generated pylint reindent test covertest build convert-utils
+        clean-generated pylint reindent test covertest build
 
 DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \
              -i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \
              -i .ropeproject -i doc/_build -i tests/path.py \
-             -i tests/coverage.py -i env -i utils/convert.py \
+             -i tests/coverage.py -i utils/convert.py \
+             -i tests/typing_test_data.py \
+             -i tests/test_autodoc_py35.py \
+             -i tests/roots/test-warnings/undecodable.rst \
+             -i tests/build \
+             -i tests/roots/test-warnings/undecodable.rst \
              -i sphinx/search/da.py \
              -i sphinx/search/de.py \
              -i sphinx/search/en.py \
@@ -23,24 +28,22 @@ DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \
              -i sphinx/search/ru.py \
              -i sphinx/search/sv.py \
              -i sphinx/search/tr.py \
-             -i utils/reindent3.py -i utils/check_sources3.py -i .tox
+             -i .tox
 
-all: clean-pyc clean-backupfiles check test
+all: clean-pyc clean-backupfiles style-check test
 
-ifeq ($(PYTHON), python3)
+style-check:
-check: convert-utils
-	@$(PYTHON) utils/check_sources3.py $(DONT_CHECK) .
-else
-check:
 	@$(PYTHON) utils/check_sources.py $(DONT_CHECK) .
-endif
 
-clean: clean-pyc clean-patchfiles clean-backupfiles clean-generated
+clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles
 
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 
+clean-pycache:
+	find . -name __pycache__ -exec rm -rf {} +
+
 clean-patchfiles:
 	find . -name '*.orig' -exec rm -f {} +
 	find . -name '*.rej' -exec rm -f {} +
@@ -52,18 +55,20 @@ clean-backupfiles:
 clean-generated:
 	rm -f utils/*3.py*
 
+clean-testfiles:
+	rm -rf tests/build
+	rm -rf .tox/
+
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx
 
-ifeq ($(PYTHON), python3)
-reindent: convert-utils
-	@$(PYTHON) utils/reindent3.py -r -n .
-else
 reindent:
 	@$(PYTHON) utils/reindent.py -r -n .
-endif
 
 test:
+	@cd tests; $(PYTHON) run.py -I py35 -d -m '^[tT]est' $(TEST)
+
+test-async:
 	@cd tests; $(PYTHON) run.py -d -m '^[tT]est' $(TEST)
 
 covertest:
@@ -72,8 +77,3 @@ covertest:
 
 build:
 	@$(PYTHON) setup.py build
-
-ifeq ($(PYTHON), python3)
-convert-utils:
-	@python3 utils/convert.py -i utils/convert.py utils/
-endif

README.rst

@@ -33,6 +33,12 @@ Install from cloned source as editable::
    pip install -e .
 
 
+Release signatures
+==================
+
+Releases are signed with `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_
+
+
 Reading the docs
 ================
 

doc/_templates/index.html

@@ -5,17 +5,16 @@
 
   <div class="quotebar">
     <p><em>{%trans%}What users say:{%endtrans%}</em></p>
-    <p>{%trans%}&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
+    <p>{%trans%}&#8220;Cheers for a great tool that actually makes programmers <b>want</b>
-      to write documentation!&rdquo;{%endtrans%}</p>
+      to write documentation!&#8220;{%endtrans%}</p>
   </div>
 
   <p>{%trans%}
     Sphinx is a tool that makes it easy to create intelligent and beautiful
     documentation, written by Georg Brandl and licensed under the BSD license.{%endtrans%}</p>
   <p>{%trans%}It was originally created for <a href="https://docs.python.org/">the
-    new Python documentation</a>, and it has excellent facilities for the
+    Python documentation</a>, and it has excellent facilities for the
-    documentation of Python projects, but C/C++ is already supported as well,
+    documentation of software projects in a range of languages.  Of
-    and it is planned to add special support for other languages as well.  Of
     course, this site is also created from reStructuredText sources using
     Sphinx!  The following features should be highlighted:{%endtrans%}
   </p>
@@ -39,10 +38,10 @@
       in a second repository; most of them installable from PyPI{%endtrans%}</li>
   </ul>
   <p>{%trans%}
-    Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
+    Sphinx uses <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
     as its markup language, and many of its strengths come from the power and
     straightforwardness of reStructuredText and its parsing and translating
-    suite, the <a href="http://docutils.sf.net/">Docutils</a>.{%endtrans%}
+    suite, the <a href="http://docutils.sourceforge.net/">Docutils</a>.{%endtrans%}
   </p>
 
   <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
@@ -62,11 +61,11 @@
   </table>
 
   <p>{%trans%}
-    You can also download PDF versions of the Sphinx documentation:
+    You can also download PDF/EPUB versions of the Sphinx documentation:
-    a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from
+    a <a href="http://readthedocs.org/projects/sphinx/downloads/pdf/stable/">PDF version</a> generated from
     the LaTeX Sphinx produces, and
-    a <a href="http://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated
+    a <a href="http://readthedocs.org/projects/sphinx/downloads/epub/stable/">EPUB version</a>.
-    by rst2pdf.{%endtrans%}
+   {%endtrans%}
   </p>
 
   <h2>{%trans%}Examples{%endtrans%}</h2>

doc/_templates/indexsidebar.html

@@ -14,20 +14,12 @@
 <p>{%trans%}Current version: <b>{{ version }}</b>{%endtrans%}</p>
 <p>{%trans%}Get Sphinx from the <a href="https://pypi.python.org/pypi/Sphinx">Python Package
 Index</a>, or install it with:{%endtrans%}</p>
-{% if version.split('b')|length > 1 %}
-<pre>pip install Sphinx=={{ version }}</pre>
-<p>{%trans%}<a href="http://sphinx-doc.org/">Stable version docs</a>
-are also available.{%endtrans%}</p>
-{% else %}
 <pre>pip install -U Sphinx</pre>
-<p>{%trans%}Latest <a href="http://sphinx-doc.org/latest/">development version docs</a>
-are also available.{%endtrans%}</p>
-{% endif %}
 {% endif %}
 
 <h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3>
 
-<p>{%trans%}Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:{%endtrans%}</p>
+<p>{%trans%}Join the <a href="http://groups.google.com/group/sphinx-users">sphinx-users</a> mailing list on Google Groups:{%endtrans%}</p>
 <form action="http://groups.google.com/group/sphinx-users/boxsubscribe"
       style="padding-left: 0.5em">
   <input type="text" name="email" value="your@email" style="font-size: 90%; width: 120px"

doc/_themes/sphinx13/layout.html

@@ -4,7 +4,7 @@
 
     Sphinx layout template for the sphinxdoc theme.
 
-    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
 {%- extends "basic/layout.html" %}
@@ -57,8 +57,8 @@
 {% endblock %}
 
 {% block rootrellink %}
-        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|</li>
+        <li><a href="{{ pathto('index') }}">Sphinx home</a>&#160;|</li>
-        <li><a href="{{ pathto('contents') }}">Documentation</a> &raquo;</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a> &#187;</li>
 {% endblock %}
 
 {% block header %}

doc/_themes/sphinx13/static/sphinx13.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- sphinx13 theme.
  *
- * :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

doc/builders.rst

@@ -23,6 +23,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
 .. class:: DirectoryHTMLBuilder
@@ -36,6 +38,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 0.6
@@ -48,6 +52,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.0
@@ -61,6 +67,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
 .. module:: sphinx.builders.qthelp
@@ -72,9 +80,11 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
-   .. _Qt help: http://qt-project.org/doc/qt-4.8/qthelp-framework.html
+   .. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html
 
 .. module:: sphinx.builders.applehelp
 .. class:: AppleHelpBuilder
@@ -96,6 +106,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.3
@@ -109,6 +121,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
 .. module:: sphinx.builders.epub
@@ -117,13 +131,35 @@ The builder's "name" must be given to the **-b** command-line option of
    This builder produces the same output as the standalone HTML builder, but
    also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
    details about it.  For definition of the epub format, have a look at
-   `<http://idpf.org/epub>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
+   `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
    The builder creates *EPUB 2* files.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
+.. module:: sphinx.builders.epub3
+.. class:: Epub3Builder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
+   details about it.  For definition of the epub format, have a look at
+   `<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
+   The builder creates *EPUB 3* files.
+
+   This builder is still *experimental* because it can't generate valid EPUB 3
+   files.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: format
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.4
+
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
@@ -145,10 +181,12 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
 Note that a direct PDF builder using ReportLab is available in `rst2pdf
-<http://rst2pdf.googlecode.com>`_ version 0.12 or greater.  You need to add
+<https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or greater.  You need to add
 ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
 ``pdf``.  Refer to the `rst2pdf manual <http://ralsina.me/static/manual.pdf>`_
 for details.
@@ -162,6 +200,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 0.4
@@ -175,6 +215,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.0
@@ -196,6 +238,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.1
@@ -261,6 +305,8 @@ for details.
 
       The old name ``web`` still works as well.
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    The file suffix is ``.fpickle``.  The global context is called
@@ -276,6 +322,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    The file suffix is ``.fjson``.  The global context is called
@@ -293,6 +341,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.1
@@ -307,8 +357,22 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
+.. module:: sphinx.builders.dummy
+.. class:: DummyBuilder
+
+   This builder produces no output.  The input is only parsed and checked for
+   consistency.  This is useful for linting purposes.
+
+   .. autoattribute:: name
+
+   .. autoattribute:: supported_image_types
+
+   .. versionadded:: 1.4
+
 .. module:: sphinx.builders.linkcheck
 .. class:: CheckExternalLinksBuilder
 
@@ -318,6 +382,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
 .. module:: sphinx.builders.xml
@@ -329,6 +395,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.2
@@ -343,6 +411,8 @@ for details.
 
    .. autoattribute:: name
 
+   .. autoattribute:: format
+
    .. autoattribute:: supported_image_types
 
    .. versionadded:: 1.2

doc/conf.py

@@ -15,7 +15,7 @@ templates_path = ['_templates']
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2015, Georg Brandl and the Sphinx team'
+copyright = '2007-2016, Georg Brandl and the Sphinx team'
 version = sphinx.__released__
 release = version
 show_authors = True
@@ -36,9 +36,9 @@ epub_author = 'Georg Brandl'
 epub_publisher = 'http://sphinx-doc.org/'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
-epub_pre_files = [('index.html', 'Welcome')]
+epub_pre_files = [('index.xhtml', 'Welcome')]
-epub_post_files = [('install.html', 'Installing Sphinx'),
+epub_post_files = [('install.xhtml', 'Installing Sphinx'),
-                   ('develop.html', 'Sphinx development')]
+                   ('develop.xhtml', 'Sphinx development')]
 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
                       '_static/jquery.js', '_static/searchtools.js',
                       '_static/underscore.js', '_static/basic.css',
@@ -47,7 +47,8 @@ epub_fix_images = False
 epub_max_image_width = 0
 epub_show_urls = 'inline'
 epub_use_index = False
-epub_guide = (('toc', 'contents.html', u'Table of Contents'),)
+epub_guide = (('toc', 'contents.xhtml', u'Table of Contents'),)
+epub3_description = 'Sphinx documentation generator system manual'
 
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]

doc/config.rst

@@ -56,7 +56,7 @@ General configuration
 
 .. confval:: extensions
 
-   A list of strings that are module names of Sphinx extensions.  These can be
+   A list of strings that are module names of :ref:`extensions`. These can be
    extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
 
    Note that you can extend :data:`sys.path` within the conf file if your
@@ -96,8 +96,11 @@ General configuration
 
    If given, a dictionary of parser classes for different source suffices.  The
    keys are the suffix, the values can be either a class or a string giving a
-   fully-qualified name of a parser class.  Files with a suffix that is not in
+   fully-qualified name of a parser class.  The parser class can be either
-   the dictionary will be parsed with the default reStructuredText parser.
+   ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`.  Files with a
+   suffix that is not in the dictionary will be parsed with the default
+   reStructuredText parser.
+
 
    For example::
 
@@ -128,7 +131,7 @@ General configuration
      :confval:`exclude_dirnames`)
 
    :confval:`exclude_patterns` is also consulted when looking for static files
-   in :confval:`html_static_path`.
+   in :confval:`html_static_path` and :confval:`html_extra_path`.
 
    .. versionadded:: 1.0
 
@@ -209,6 +212,33 @@ General configuration
 
    .. versionadded:: 0.5
 
+.. confval:: suppress_warnings
+
+   A list of warning types to suppress arbitrary warning messages.
+
+   Sphinx supports following warning types:
+
+   * app.add_node
+   * app.add_directive
+   * app.add_role
+   * app.add_generic_role
+   * app.add_source_parser
+   * image.data_uri
+   * image.nonlocal_uri
+   * ref.term
+   * ref.ref
+   * ref.numref
+   * ref.keyword
+   * ref.option
+   * ref.citation
+   * ref.doc
+
+   You can choose from these types.
+
+   Now, this option should be considered *experimental*.
+
+   .. versionadded:: 1.4
+
 .. confval:: needs_sphinx
 
    If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@@ -217,6 +247,9 @@ General configuration
 
    .. versionadded:: 1.0
 
+   .. versionchanged:: 1.4
+      also accepts micro version string
+
 .. confval:: needs_extensions
 
    This value can be a dictionary specifying version requirements for extensions
@@ -234,7 +267,7 @@ General configuration
 
    If true, Sphinx will warn about *all* references where the target cannot be
    found.  Default is ``False``.  You can activate this mode temporarily using
-   the :option:`-n` command-line switch.
+   the :option:`-n <sphinx-build -n>` command-line switch.
 
    .. versionadded:: 1.0
 
@@ -250,7 +283,12 @@ General configuration
 .. confval:: numfig
 
    If true, figures, tables and code-blocks are automatically numbered if they
-   has caption. For now, it works only with the HTML builder. Default is ``False``.
+   have a caption.  At same time, the `numref` role is enabled.  For now, it
+   works only with the HTML builder and LaTeX builder. Default is ``False``.
+
+   .. note::
+
+      LaTeX builder always assign numbers whether this option is enabled or not.
 
    .. versionadded:: 1.3
 
@@ -309,16 +347,35 @@ Project information
 
    The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
    %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
-   %format for the selected locale).
+   format for the selected locale).
+
+   .. versionchanged:: 1.4
+
+      Format specification was changed from strftime to Locale Data Markup
+      Language. strftime format is also supported for backward compatibility
+      until Sphinx-1.5.
+
+   .. versionchanged:: 1.4.1
+
+      Format specification was changed again from Locale Data Markup Language
+      to strftime.  LDML format is also supported for backward compatibility
+      until Sphinx-1.5.
 
 .. confval:: highlight_language
 
    The default language to highlight source code in.  The default is
-   ``'python'``.  The value should be a valid Pygments lexer name, see
+   ``'python3'``.  The value should be a valid Pygments lexer name, see
    :ref:`code-examples` for more details.
 
    .. versionadded:: 0.5
 
+   .. versionchanged:: 1.4
+      The default is now ``'default'``. It is similar to ``'python3'``;
+      it is mostly a superset of ``'python'``. but it fallbacks to
+      ``'none'`` without warning if failed.  ``'python3'`` and other
+      languages will emit warning if failed.  If you prefer Python 2
+      only highlighting, you can set it back to ``'python'``.
+
 .. confval:: highlight_options
 
    A dictionary of options that modify how the lexer specified by
@@ -397,12 +454,18 @@ documentation on :ref:`intl` for details.
    The code for the language the docs are written in.  Any text automatically
    generated by Sphinx will be in that language.  Also, Sphinx will try to
    substitute individual paragraphs from your documents with the translation
-   sets obtained from :confval:`locale_dirs`.  In the LaTeX builder, a suitable
+   sets obtained from :confval:`locale_dirs`.  Sphinx will search
-   language will be selected as an option for the *Babel* package.  Default is
+   language-specific figures named by `figure_language_filename` and substitute
-   ``None``, which means that no translation will be done.
+   them for original figures.  In the LaTeX builder, a suitable language will
+   be selected as an option for the *Babel* package.  Default is ``None``,
+   which means that no translation will be done.
 
    .. versionadded:: 0.5
 
+   .. versionchanged:: 1.4
+
+      Support figure substitution
+
    Currently supported languages by Sphinx are:
 
    * ``bn`` -- Bengali
@@ -453,12 +516,15 @@ documentation on :ref:`intl` for details.
    this path are searched by the standard :mod:`gettext` module.
 
    Internal messages are fetched from a text domain of ``sphinx``; so if you
-   add the directory :file:`./locale` to this settting, the message catalogs
+   add the directory :file:`./locale` to this setting, the message catalogs
    (compiled from ``.po`` format using :program:`msgfmt`) must be in
    :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
    individual documents depends on :confval:`gettext_compact`.
 
-   The default is ``[]``.
+   The default is ``['locales']``.
+
+   .. versionchanged:: 1.5
+      Use ``locales`` directory as a default value
 
 .. confval:: gettext_compact
 
@@ -521,6 +587,14 @@ documentation on :ref:`intl` for details.
 
    .. versionadded:: 1.3
 
+.. confval:: figure_language_filename
+
+   The filename format for language-specific figures.  The default value is
+   ``{root}.{language}{ext}``.  It will be expanded to
+   ``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``.
+
+   .. versionadded:: 1.4
+
 .. _html-options:
 
 Options for HTML output
@@ -565,8 +639,7 @@ that use Sphinx's HTMLWriter class.
    The "title" for HTML documentation generated with Sphinx's own templates.
    This is appended to the ``<title>`` tag of individual pages, and used in the
    navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
-   v{<revision>} documentation'` (with the values coming from the config
+   v{<revision>} documentation'`.
-   values).
 
 .. confval:: html_short_title
 
@@ -580,7 +653,7 @@ that use Sphinx's HTMLWriter class.
 
    A dictionary of values to pass into the template engine's context for all
    pages.  Single values can also be put in this dictionary using the
-   :option:`-A` command-line option of ``sphinx-build``.
+   :option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``.
 
    .. versionadded:: 0.5
 
@@ -635,11 +708,30 @@ that use Sphinx's HTMLWriter class.
 
    .. versionadded:: 1.2
 
+   .. versionchanged:: 1.4
+      The dotfiles in the extra directory will be copied to the output directory.
+      And it refers :confval:`exclude_patterns` on copying extra files and
+      directories, and ignores if path matches to patterns.
+
 .. confval:: html_last_updated_fmt
 
-   If this is not the empty string, a 'Last updated on:' timestamp is inserted
+   If this is not None, a 'Last updated on:' timestamp is inserted
-   at every page bottom, using the given :func:`strftime` format.  Default is
+   at every page bottom, using the given :func:`strftime` format.
-   ``'%b %d, %Y'`` (or a locale-dependent equivalent).
+   The empty string is equivalent to ``'%b %d, %Y'`` (or a
+   locale-dependent equivalent).
+
+   .. versionchanged:: 1.4
+
+      Format specification was changed from strftime to Locale Data Markup
+      Language. strftime format is also supported for backward compatibility
+      until Sphinx-1.5.
+
+   .. versionchanged:: 1.4.1
+
+      Format specification was changed again from Locale Data Markup Language
+      to strftime.  LDML format is also supported for backward compatibility
+      until Sphinx-1.5.
+
 
 .. confval:: html_use_smartypants
 
@@ -778,9 +870,16 @@ that use Sphinx's HTMLWriter class.
 
    .. versionadded:: 0.6
 
+.. confval:: html_sourcelink_suffix
+
+   Suffix to be appended to source links (see :confval:`html_show_sourcelink`),
+   unless they have this suffix already.  Default is ``'.txt'``.
+
+   .. versionadded:: 1.5
+
 .. confval:: html_use_opensearch
 
-   If nonempty, an `OpenSearch <http://opensearch.org>`_ description file will be
+   If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description file will be
    output, and all pages will contain a ``<link>`` tag referring to it.  Since
    OpenSearch doesn't support relative URLs for its search page location, the
    value of this option must be the base URL from which these documents are
@@ -867,12 +966,13 @@ that use Sphinx's HTMLWriter class.
    * ``it`` -- Italian
    * ``ja`` -- Japanese
    * ``no`` -- Norwegian
-   * ``pr`` -- Portuguese
+   * ``pt`` -- Portuguese
    * ``ro`` -- Romanian
    * ``ru`` -- Russian
    * ``es`` -- Spanish
    * ``sv`` -- Swedish
    * ``tr`` -- Turkish
+   * ``zh`` -- Chinese
 
    .. admonition:: Accelerating build speed
 
@@ -898,15 +998,65 @@ that use Sphinx's HTMLWriter class.
 
    The Japanese support has these options:
 
-   * ``type`` -- ``'mecab'`` or ``'default'`` (selects either MeCab or
+   :type:
-     TinySegmenter word splitter algorithm)
+      _`type` is dotted module path string to specify Splitter implementation which
-   * ``dic_enc`` -- the encoding for the MeCab algorithm
+      should be derived from :class:`sphinx.search.ja.BaseSplitter`.
-   * ``dict`` -- the dictionary to use for the MeCab algorithm
+      If not specified or None is specified, ``'sphinx.search.ja.DefaultSplitter'`` will
-   * ``lib`` -- the library name for finding the MeCab library via ctypes if the
+      be used.
-     Python binding is not installed
+
+      You can choose from these modules:
+
+      :'sphinx.search.ja.DefaultSplitter':
+         TinySegmenter algorithm. This is default splitter.
+      :'sphinx.search.ja.MeCabSplitter':
+         MeCab binding. To use this splitter, 'mecab' python binding or dynamic link
+         library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
+      :'sphinx.search.ja.JanomeSplitter':
+         Janome binding. To use this splitter,
+         `Janome <https://pypi.python.org/pypi/Janome>`_ is required.
+
+      To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are also
+      acceptable. However it will be deprecated in Sphinx-1.6.
+
+
+   Other option values depend on splitter value which you choose.
+
+   Options for ``'mecab'``:
+      :dic_enc:
+         _`dic_enc option` is the encoding for the MeCab algorithm.
+      :dict:
+         _`dict option` is the dictionary to use for the MeCab algorithm.
+      :lib:
+         _`lib option` is the library name for finding the MeCab library via ctypes if
+         the Python binding is not installed.
+
+      For example::
+
+          html_search_options = {
+              'type': 'mecab',
+              'dic_enc': 'utf-8',
+              'dict': '/path/to/mecab.dic',
+              'lib': '/path/to/libmecab.so',
+          }
+
+   Options for ``'janome'``:
+      :user_dic: _`user_dic option` is the user dictionary file path for Janome.
+      :user_dic_enc:
+         _`user_dic_enc option` is the encoding for the user dictionary file specified by
+         ``user_dic`` option. Default is 'utf8'.
 
    .. versionadded:: 1.1
 
+   .. versionchanged:: 1.4
+      html_search_options for Japanese is re-organized and any custom splitter can be
+      used by `type`_ settings.
+
+
+   The Chinese support has these options:
+
+   * ``dict``  -- the ``jieba`` dictionary path if want to use
+     custom dictionary.
+
 .. confval:: html_search_scorer
 
    The name of a JavaScript file (relative to the configuration directory) that
@@ -1127,11 +1277,25 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    The title of the document.  It defaults to the :confval:`html_title` option
    but can be set independently for epub creation.
 
+.. confval:: epub3_description
+
+   The description of the document. The default value is ``''``.
+
+   .. versionadded:: 1.4
+
 .. confval:: epub_author
 
    The author of the document.  This is put in the Dublin Core metadata.  The
    default value is ``'unknown'``.
 
+.. confval:: epub3_contributor
+
+   The name of a person, organization, etc. that played a secondary role in
+   the creation of the content of an EPUB Publication. The default value is
+   ``'unknown'``.
+
+   .. versionadded:: 1.4
+
 .. confval:: epub_language
 
    The language of the document.  This is put in the Dublin Core metadata.  The
@@ -1234,6 +1398,10 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    a chapter, but can be confusing because it mixes entries of different
    depth in one list.  The default value is ``True``.
 
+   .. note::
+
+      ``epub3`` builder ignores ``epub_tocdup`` option(always ``False``)
+
 .. confval:: epub_tocscope
 
    This setting control the scope of the epub table of contents.  The setting
@@ -1287,12 +1455,33 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
    .. versionadded:: 1.2
 
+.. confval:: epub3_page_progression_direction
+
+   The global direction in which the content flows.
+   Allowed values are ``'ltr'`` (left-to-right), ``'rtl'`` (right-to-left) and
+   ``'default'``. The default value is ``'ltr'``.
+
+   When the ``'default'`` value is specified, the Author is expressing no
+   preference and the Reading System may chose the rendering direction.
+
+   .. versionadded:: 1.4
+
 .. _latex-options:
 
 Options for LaTeX output
 ------------------------
 
-These options influence LaTeX output.
+These options influence LaTeX output. See further :doc:`latex`.
+
+.. confval:: latex_engine
+
+   The LaTeX engine to build the docs.  The setting can have the following
+   values:
+
+   * pdflatex -- PDFLaTeX (default)
+   * xelatex -- XeLaTeX
+   * lualatex -- LuaLaTeX
+   * platex -- pLaTeX (default if `language` is 'ja')
 
 .. confval:: latex_documents
 
@@ -1337,6 +1526,15 @@ These options influence LaTeX output.
    configuration directory) that is the logo of the docs.  It is placed at the
    top of the title page.  Default: ``None``.
 
+.. confval:: latex_toplevel_sectioning
+
+   This value determines the topmost sectioning unit. It should be chosen from
+   ``part``, ``chapter`` or ``section``. The default is ``None``; the topmost
+   sectioning unit is switched by documentclass. ``section`` is used if
+   documentclass will be ``howto``, otherwise ``chapter`` will be used.
+
+   .. versionadded:: 1.4
+
 .. confval:: latex_use_parts
 
    If true, the topmost sectioning unit is parts, else it is chapters.  Default:
@@ -1344,6 +1542,9 @@ These options influence LaTeX output.
 
    .. versionadded:: 0.3
 
+   .. deprecated:: 1.4
+      Use :confval:`latex_toplevel_sectioning`.
+
 .. confval:: latex_appendices
 
    A list of document names to append as an appendix to all manuals.
@@ -1388,6 +1589,21 @@ These options influence LaTeX output.
       value selected the ``'inline'`` display.  For backwards compatibility,
       ``True`` is still accepted.
 
+.. confval:: latex_keep_old_macro_names
+
+   If ``True`` (default) the ``\strong``, ``\code``, ``\bfcode``, ``\email``,
+   ``\tablecontinued``, ``\titleref``, ``\menuselection``, ``\accelerator``,
+   ``\crossref``, ``\termref``, and ``\optional`` text styling macros are
+   pre-defined by Sphinx and may be user-customized by some
+   ``\renewcommand``'s inserted either via ``'preamble'`` key or :dudir:`raw
+   <raw-data-pass-through>` directive. If ``False``, only ``\sphinxstrong``,
+   etc... macros are defined (and may be redefined by user). Setting to
+   ``False`` may help solve macro name conflicts caused by user-added latex
+   packages.
+
+   .. versionadded:: 1.4.5
+
+
 .. confval:: latex_elements
 
    .. versionadded:: 0.5
@@ -1406,6 +1622,15 @@ These options influence LaTeX output.
      ``'pointsize'``
         Point size option of the document class (``'10pt'``, ``'11pt'`` or
         ``'12pt'``), default ``'10pt'``.
+     ``'pxunit'``
+        the value of the ``px`` when used in image attributes ``width`` and
+        ``height``. The default value is ``'49336sp'`` which achieves
+        ``96px=1in`` (``1in = 72.27*65536 = 4736286.72sp``, and all dimensions
+        in TeX are internally integer multiples of ``sp``). To obtain for
+        example ``100px=1in``, one can use ``'0.01in'`` but it is more precise
+        to use ``'47363sp'``. To obtain ``72px=1in``, use ``'1bp'``.
+
+        .. versionadded:: 1.5
      ``'babel'``
         "babel" package inclusion, default ``'\\usepackage{babel}'``.
      ``'fontpkg'``
@@ -1423,22 +1648,33 @@ These options influence LaTeX output.
         the "Bjarne" style uses numbers spelled out in English).  Other
         "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and
         "Rejne".  You can also set this to ``''`` to disable fncychap.
+     ``'passoptionstopackages'``
+        "PassOptionsToPackage" call, default empty.
+
+        .. versionadded:: 1.4
      ``'preamble'``
-        Additional preamble content, default empty.
+        Additional preamble content, default empty. See :doc:`latex`.
      ``'figure_align'``
         Latex figure float alignment, default 'htbp' (here, top, bottom, page).
         Whenever an image doesn't fit into the current page, it will be
         'floated' into the next page but may be preceded by any other text.
         If you don't like this behavior, use 'H' which will disable floating
         and position figures strictly in the order they appear in the source.
+
+        .. versionadded:: 1.3
      ``'footer'``
         Additional footer content (before the indices), default empty.
 
    * Keys that don't need be overridden unless in special cases are:
 
      ``'inputenc'``
-        "inputenc" package inclusion, default
+        "inputenc" package inclusion, defaults to
-        ``'\\usepackage[utf8]{inputenc}'``.
+        ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
+        Otherwise unset.
+
+        .. versionchanged:: 1.4.3
+           Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+           compilers.
      ``'cmappkg'``
         "cmap" package inclusion, default ``'\\usepackage{cmap}'``.
 
@@ -1448,6 +1684,9 @@ These options influence LaTeX output.
      ``'maketitle'``
         "maketitle" call, default ``'\\maketitle'``.  Override if you want to
         generate a differently-styled title page.
+     ``'releasename'``
+        value that prefixes ``'release'`` element on title page, default
+        ``'Release'``.
      ``'tableofcontents'``
         "tableofcontents" call, default ``'\\tableofcontents'``.  Override if
         you want to generate a different table of contents or put content
@@ -1473,7 +1712,6 @@ These options influence LaTeX output.
      ``'release'``
      ``'author'``
      ``'logo'``
-     ``'releasename'``
      ``'makeindex'``
      ``'shorthandoff'``
 
@@ -1485,6 +1723,11 @@ These options influence LaTeX output.
 
    .. versionadded:: 1.0
 
+   .. versionchanged:: 1.5
+
+      In Japanese docs(`language` is ``ja``), ``'jreport'`` is used for
+      ``'howto'`` and ``'jsbooks'`` is used for ``'manual'`` by default.
+
 .. confval:: latex_additional_files
 
    A list of file names, relative to the configuration directory, to copy to the
@@ -1713,6 +1956,13 @@ Options for the linkcheck builder
 
    .. versionadded:: 1.1
 
+.. confval:: linkcheck_retries
+
+   The number of times the linkcheck builder will attempt to check a URL before
+   declaring it broken. Defaults to 1 attempt.
+
+   .. versionadded:: 1.4
+
 .. confval:: linkcheck_timeout
 
    A timeout value, in seconds, for the linkcheck builder.  **Only works in
@@ -1753,3 +2003,33 @@ Options for the XML builder
        constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
        these all don't match slashes.  A double star ``**`` can be used to match
        any sequence of characters *including* slashes.
+
+
+.. _cpp-config:
+
+Options for the C++ domain
+--------------------------
+
+.. confval:: cpp_index_common_prefix
+
+   A list of prefixes that will be ignored when sorting C++ objects in the global index.
+   For example ``['awesome_lib::']``.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_id_attributes
+
+   A list of strings that the parser additionally should accept as attributes.
+   This can for example be used when attributes have been ``#define`` d for portability.
+
+   .. versionadded:: 1.5
+
+.. confval:: cpp_paren_attributes
+
+   A list of strings that the parser additionally should accept as attributes with one argument.
+   That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute
+   for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``).
+   This can for example be used when attributes have been ``#define`` d for portability.
+
+   .. versionadded:: 1.5
+

doc/contents.rst

@@ -1,3 +1,4 @@
+
 .. _contents:
 
 Sphinx documentation contents
@@ -17,6 +18,7 @@ Sphinx documentation contents
    intl
    theming
    templating
+   latex
    extensions
    extdev/index
    websupport

doc/develop.rst

@@ -10,7 +10,7 @@ Sphinx is a maintained by a group of volunteers.  We value every contribution!
 * Issues and feature requests should be raised in the `tracker
   <https://github.com/sphinx-doc/sphinx/issues>`_.
 * The mailing list for development is at `Google Groups
-  <https://groups.google.com/group/sphinx-dev/>`_.
+  <https://groups.google.com/forum/#!forum/sphinx-dev>`_.
 * There is also the #sphinx-doc IRC channel on `freenode
   <http://freenode.net/>`_.
 
@@ -21,7 +21,7 @@ Extensions
 
 To learn how to write your own extension, see :ref:`dev-extensions`.
 
-The `sphinx-contrib <http://bitbucket.org/birkenfeld/sphinx-contrib/>`_
+The `sphinx-contrib <https://bitbucket.org/birkenfeld/sphinx-contrib/>`_
 repository contains many contributed extensions.  Some of them have their own
 releases on PyPI, others you can install from a checkout.
 
@@ -96,14 +96,14 @@ own extensions.
 
 .. _aafigure: https://launchpad.net/aafigure
 .. _gnuplot: http://www.gnuplot.info/
-.. _paver: http://www.blueskyonmars.com/projects/paver/
+.. _paver: http://paver.github.io/paver/
 .. _Sword: http://www.crosswire.org/sword/
 .. _Lilypond: http://lilypond.org/
 .. _sdedit: http://sdedit.sourceforge.net/
 .. _Trac: http://trac.edgewall.org
 .. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
 .. _OmegaT: http://www.omegat.org/
-.. _PlantUML: http://plantuml.sourceforge.net/
+.. _PlantUML: http://plantuml.com/
 .. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
 .. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home
 .. _blockdiag: http://blockdiag.com/en/
@@ -112,24 +112,24 @@ own extensions.
 .. _nwdiag: http://blockdiag.com/en/
 .. _Google Analytics: http://www.google.com/analytics/
 .. _Google Chart: https://developers.google.com/chart/
-.. _Google Maps: https://maps.google.com/
+.. _Google Maps: https://www.google.com/maps
 .. _Google style: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
 .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
-.. _hyphenator: http://code.google.com/p/hyphenator/
+.. _hyphenator: https://github.com/mnater/hyphenator
 .. _exceltable: http://pythonhosted.org/sphinxcontrib-exceltable/
 .. _YouTube: http://www.youtube.com/
 .. _ClearQuest: http://www-03.ibm.com/software/products/en/clearquest
 .. _Zope interfaces: http://docs.zope.org/zope.interface/README.html
 .. _slideshare: http://www.slideshare.net/
-.. _TikZ/PGF LaTeX package: http://sourceforge.net/projects/pgf/
+.. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
 .. _MATLAB: http://www.mathworks.com/products/matlab/
-.. _swf: http://bitbucket.org/klorenz/sphinxcontrib-swf
+.. _swf: https://bitbucket.org/klorenz/sphinxcontrib-swf
-.. _findanything: http://bitbucket.org/klorenz/sphinxcontrib-findanything
+.. _findanything: https://bitbucket.org/klorenz/sphinxcontrib-findanything
-.. _cmakedomain: http://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
+.. _cmakedomain: https://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
 .. _GNU Make: http://www.gnu.org/software/make/
-.. _makedomain: http://bitbucket.org/klorenz/sphinxcontrib-makedomain
+.. _makedomain: https://bitbucket.org/klorenz/sphinxcontrib-makedomain
 .. _inlinesyntaxhighlight: http://sphinxcontrib-inlinesyntaxhighlight.readthedocs.org
-.. _CMake: http://cmake.org
+.. _CMake: https://cmake.org
-.. _domaintools: http://bitbucket.org/klorenz/sphinxcontrib-domaintools
+.. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
 .. _restbuilder: https://pypi.python.org/pypi/sphinxcontrib-restbuilder
 .. _Lasso: http://www.lassosoft.com/

doc/devguide.rst

@@ -111,7 +111,7 @@ These are the basic steps needed to start developing on Sphinx.
 
    * Run the unit tests::
 
-       pip install nose mock
+       pip install -r test-reqs.txt
        make test
 
    * Build the documentation and check the output for different builders::

doc/domains.rst

@@ -359,6 +359,18 @@ single word, like this::
    :param int priority: The priority of the message, can be a number 1-5
 
 
+.. versionadded:: 1.5
+
+Container types such as lists and dictionaries can be linked automatically
+using the following syntax::
+
+   :type priorities: list(int)
+   :type priorities: list[int]
+   :type mapping: dict(str, int)
+   :type mapping: dict[str, int]
+   :type point: tuple(float, float)
+   :type point: tuple[float, float]
+
 .. _python-roles:
 
 Cross-referencing Python objects
@@ -528,60 +540,128 @@ a visibility statement (``public``, ``private`` or ``protected``).
 
    Describe a class/struct, possibly with specification of inheritance, e.g.,::
 
-      .. cpp:class:: SomeName::SomeClass : public MyBase, MyOtherBase
+      .. cpp:class:: MyClass : public MyBase, MyOtherBase
 
-.. rst:directive:: .. cpp:function:: (member-)function prototype
+   The class can be directly declared inside a nested scope, e.g.,::
+
+      .. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
+
+   A template class can be declared::
+
+      .. cpp:class:: template<typename T, std::size_t N> std::array
+
+   or with a line break::
+
+      .. cpp:class:: template<typename T, std::size_t N> \
+                     std::array
+
+   Full and partial template specialisations can be declared::
+
+      .. cpp:class:: template<> \
+                      std::array<bool, 256>
+
+      .. cpp:class:: template<typename T> \
+                      std::array<T, 42>
+
+
+.. rst:directive:: .. cpp:function:: (member) function prototype
 
    Describe a function or member function, e.g.,::
 
-      .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
+      .. cpp:function:: bool myMethod(int arg1, std::string arg2)
 
-         Describes a method with parameters and types.
+         A function with parameters and types.
 
-      .. cpp:function:: bool namespaced::theclass::method(T1, T2)
+      .. cpp:function:: bool myMethod(int, double)
 
-         Describes a method with unnamed parameters.
+         A function with unnamed parameters.
 
-      .. cpp:function:: const T &array<T>::operator[]() const
+      .. cpp:function:: const T &MyClass::operator[](std::size_t i) const
 
-         Describes the constant indexing operator of a templated array.
+         An overload for the indexing operator.
 
       .. cpp:function:: operator bool() const
 
-         Describe a casting operator here.
+         A casting operator.
 
       .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
 
-         Describe a constexpr function here.
+         A constexpr function.
 
       .. cpp:function:: MyClass::MyClass(const MyClass&) = default
 
-         Describe a copy constructor with default implementation.
+         A copy constructor with default implementation.
 
-.. rst:directive:: .. cpp:member:: (member-)variable declaration
+   Function templates can also be described::
-                   .. cpp:var:: (member-)variable declaration
 
-   Describe a varible or member variable, e.g.,::
+      .. cpp:function:: template<typename U> \
+                        void print(U &&u)
 
-      .. cpp:member:: std::string theclass::name
+   and function template specialisations::
 
-      .. cpp:member:: std::string theclass::name[N][M]
+      .. cpp:function:: template<> \
+                        void print(int i)
+
+
+.. rst:directive:: .. cpp:member:: (member) variable declaration
+                   .. cpp:var:: (member) variable declaration
+
+   Describe a variable or member variable, e.g.,::
+
+      .. cpp:member:: std::string MyClass::myMember
+
+      .. cpp:var:: std::string MyClass::myOtherMember[N][M]
 
       .. cpp:member:: int a = 42
 
-.. rst:directive:: .. cpp:type:: typedef-like declaration
+   Variable templates can also be described::
-                   .. cpp:type:: name
 
-   Describe a type as in a typedef declaration, or the name of a type with unspecified type, e.g.,::
+      .. cpp:member:: template<class T> \
+                      constexpr T pi = T(3.1415926535897932385)
+
+
+.. rst:directive:: .. cpp:type:: typedef declaration
+                   .. cpp:type:: name
+                   .. cpp:type:: type alias declaration
+
+   Describe a type as in a typedef declaration, a type alias declaration,
+   or simply the name of a type with unspecified type, e.g.,::
 
       .. cpp:type:: std::vector<int> MyList
 
          A typedef-like declaration of a type.
 
-      .. cpp:type:: theclass::const_iterator
+      .. cpp:type:: MyContainer::const_iterator
 
          Declaration of a type alias with unspecified type.
 
+      .. cpp:type:: MyType = std::unordered_map<int, std::string>
+
+         Declaration of a type alias.
+
+   A type alias can also be templated::
+
+      .. cpp:type:: template<typename T> \
+                    MyContainer = std::vector<T>
+
+   The example are rendered as follows.
+
+   .. cpp:type:: std::vector<int> MyList
+
+      A typedef-like declaration of a type.
+
+   .. cpp:type:: MyContainer::const_iterator
+
+      Declaration of a type alias with unspecified type.
+
+   .. cpp:type:: MyType = std::unordered_map<int, std::string>
+
+      Declaration of a type alias.
+
+   .. cpp:type:: template<typename T> \
+                 MyContainer = std::vector<T>
+
+
 .. rst:directive:: .. cpp:enum:: unscoped enum declaration
                    .. cpp:enum-struct:: scoped enum declaration
                    .. cpp:enum-class:: scoped enum declaration
@@ -610,25 +690,194 @@ a visibility statement (``public``, ``private`` or ``protected``).
 .. rst:directive:: .. cpp:enumerator:: name
                    .. cpp:enumerator:: name = constant
 
-   Describe an enumerator, optionally with its value defined.
+   Describe an enumerator, optionally with its value defined, e.g.,::
 
-.. rst:directive:: .. cpp:namespace:: namespace
+      .. cpp:enumerator:: MyEnum::myEnumerator
 
-   Select the current namespace for the subsequent objects. Note that the namespace
+      .. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
-   does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,::
+
+
+.. rst:directive:: .. cpp:concept:: template-parameter-list name
+                   .. cpp:concept:: template-parameter-list name()
+
+   .. warning:: The support for concepts is experimental. It is based on the
+      Concepts Technical Specification, and the features may change as the TS evolves.
+
+   Describe a variable concept or a function concept. Both must have exactly 1
+   template parameter list. The name may be a nested name. Examples::
+
+      .. cpp:concept:: template<typename It> std::Iterator
+
+         Proxy to an element of a notional sequence that can be compared,
+         indirected, or incremented.
+
+      .. cpp:concept:: template<typename Cont> std::Container()
+
+         Holder of elements, to which it can provide access via
+         :cpp:concept:`Iterator` s.
+
+   They will render as follows:
+
+   .. cpp:concept:: template<typename It> std::Iterator
+
+      Proxy to an element of a notional sequence that can be compared,
+      indirected, or incremented.
+
+   .. cpp:concept:: template<typename Cont> std::Container()
+
+      Holder of elements, to which it can provide access via
+      :cpp:concept:`Iterator` s.
+
+Constrained Templates
+~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: The support for constrained templates is experimental. It is based on the
+  Concepts Technical Specification, and the features may change as the TS evolves.
+
+.. note:: Sphinx does not currently support ``requires`` clauses.
+
+Placeholders
+............
+
+Declarations may use the name of a concept to introduce constrained template
+parameters, or the keyword ``auto`` to introduce unconstrained template parameters::
+
+   .. cpp:function:: void f(auto &&arg)
+
+      A function template with a single unconstrained template parameter.
+
+   .. cpp:function:: void f(std::Iterator it)
+
+      A function template with a single template parameter, constrained by the
+      Iterator concept.
+
+Template Introductions
+......................
+
+Simple constrained function or class templates can be declared with a
+`template introduction` instead of a template parameter list::
+
+   .. cpp:function:: std::Iterator{It} void advance(It &it)
+
+       A function template with a template parameter constrained to be an Iterator.
+
+   .. cpp:class:: std::LessThanComparable{T} MySortedContainer
+
+       A class template with a template parameter constrained to be LessThanComparable.
+
+They are rendered as follows.
+
+.. cpp:function:: std::Iterator{It} void advance(It &it)
+
+   A function template with a template parameter constrained to be an Iterator.
+
+.. cpp:class:: std::LessThanComparable{T} MySortedContainer
+
+   A class template with a template parameter constrained to be LessThanComparable.
+
+Note however that no checking is performed with respect to parameter
+compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
+even though it would not be valid C++.
+
+
+Namespacing
+~~~~~~~~~~~~~~~~~
+
+Declarations in the C++ domain are as default placed in global scope.
+The current scope can be changed using three namespace directives.
+They manage a stack declarations where ``cpp:namespace`` resets the stack and
+changes a given scope.
+The ``cpp:namespace-push`` directive changes the scope to a given inner scope
+of the current one.
+The ``cpp:namespace-pop`` directive undos the most recent ``cpp:namespace-push``
+directive.
+
+.. rst:directive:: .. cpp:namespace:: scope specification
+
+   Changes the current scope for the subsequent objects to the given scope,
+   and resets the namespace directive stack.
+   Note that the namespace does not need to correspond to C++ namespaces,
+   but can end in names of classes, e.g.,::
 
       .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
 
-   All subsequent objects will be defined as if their name were declared with the namespace
+   All subsequent objects will be defined as if their name were declared with the scope
-   prepended. The subsequent cross-references will be searched for by both their specified name
+   prepended. The subsequent cross-references will be searched for starting in the current scope.
-   and with the namespace prepended.
 
-   Using ``NULL``, ``0``, or ``nullptr`` as the namespace will reset it to the global namespace.
+   Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global scope.
+
+   A namespace declaration can also be templated, e.g.,::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+      .. cpp:namespace:: template<typename T> std::vector
+
+      .. cpp:function:: std::size_t size() const
+
+   declares ``size`` as a member function of the template class ``std::vector``.
+   Equivalently this could have been declared using::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+         .. cpp:function:: std::size_t size() const
+
+   or:::
+
+      .. cpp:class:: template<typename T> \
+                     std::vector
+
+
+.. rst:directive:: .. cpp:namespace-push:: scope specification
+
+   Change the scope relatively to the current scope. For example, after::
+
+      .. cpp:namespace:: A::B
+
+      .. cpp:namespace-push:: C::D
+
+   the current scope will be ``A::B::C::D``.
+
+.. rst:directive:: .. cpp:namespace-pop::
+
+   Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope).
+   For example, after::
+
+      .. cpp:namespace:: A::B
+
+      .. cpp:namespace-push:: C::D
+
+      .. cpp:namespace-pop::
+
+   the current scope will be ``A::B`` (*not* ``A::B::C``).
+
+   If no previous ``cpp:namespace-push`` directive has been used, but only a ``cpp:namespace``
+   directive, then the current scope will be reset to global scope.
+   That is, ``.. cpp:namespace:: A::B`` is equivalent to::
+
+      .. cpp:namespace:: nullptr
+
+      .. cpp:namespace-push:: A::B
+
+
+Info field lists
+~~~~~~~~~~~~~~~~~
+
+The C++ directives support the following info fields (see also :ref:`info-field-lists`):
+
+* `param`, `parameter`, `arg`, `argument`: Description of a parameter.
+* `tparam`: Description of a template parameter.
+* `returns`, `return`: Description of a return value.
+* `throws`, `throw`, `exception`: Description of a possibly thrown exception.
 
 
 .. _cpp-roles:
 
-These roles link to the given object types:
+Cross-referencing
+~~~~~~~~~~~~~~~~~
+
+These roles link to the given declaration types:
 
 .. rst:role:: cpp:any
               cpp:class
@@ -636,22 +885,23 @@ These roles link to the given object types:
               cpp:member
               cpp:var
               cpp:type
+              cpp:concept
               cpp:enum
               cpp:enumerator
 
-   Reference a C++ object by name. The name must be properly qualified relative to the
+   Reference a C++ declaration by name (see below for details).
-   position of the link.
+   The name must be properly qualified relative to the position of the link.
 
-   .. note::
+.. admonition:: Note on References with Templates Parameters/Arguments
 
-      Sphinx's syntax to give references a custom title can interfere with
+   Sphinx's syntax to give references a custom title can interfere with
-      linking to template classes, if nothing follows the closing angle
+   linking to template classes, if nothing follows the closing angle
-      bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<T>```.
+   bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<int>```.
-      This is interpreted as a link to ``T`` with a title of ``MyClass``.
+   This is interpreted as a link to ``int`` with a title of ``MyClass``.
-      In this case, please escape the opening angle bracket with a backslash,
+   In this case, please escape the opening angle bracket with a backslash,
-      like this: ``:cpp:class:`MyClass\<T>```.
+   like this: ``:cpp:class:`MyClass\<int>```.
 
-.. admonition:: Note on References
+.. admonition:: Note on References to Overloaded Functions
 
    It is currently impossible to link to a specific version of an
    overloaded method.  Currently the C++ domain is the first domain
@@ -660,11 +910,84 @@ These roles link to the given object types:
    specific overload.  Currently Sphinx will link to the first overloaded
    version of the method / function.
 
-.. admonition:: Note on Template Delcarations
+Declarations without template parameters and template arguments
+.................................................................
 
-   The C++ domain currently does not support template classes/functions/aliases/variables
+For linking to non-templated declarations the name must be a nested name,
-   (e.g., ``template<typename T> MyClass``), only template instantiations
+e.g., ``f`` or ``MyClass::f``.
-   (e.g., ``MyClass<T>``).
+
+Templated declarations
+......................
+
+Assume the following declarations.
+
+.. cpp:class:: Wrapper
+
+   .. cpp:class:: template<typename TOuter> \
+                  Outer
+
+      .. cpp:class:: template<typename TInner> \
+                     Inner
+
+In general the reference must include the template paraemter declarations, e.g.,
+``template\<typename TOuter> Wrapper::Outer`` (:cpp:class:`template\<typename TOuter> Wrapper::Outer`).
+Currently the lookup only succeed if the template parameter identifiers are equal strings. That is,
+``template\<typename UOuter> Wrapper::Outer`` will not work.
+
+The inner template class can not be directly referenced, unless the current namespace
+is changed or the following shorthand is used.
+If a template parameter list is omitted, then the lookup will assume either a template or a non-template,
+but not a partial template specialisation.
+This means the following references work.
+
+- ``Wrapper::Outer`` (:cpp:class:`Wrapper::Outer`)
+- ``Wrapper::Outer::Inner`` (:cpp:class:`Wrapper::Outer::Inner`)
+- ``template\<typename TInner> Wrapper::Outer::Inner`` (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
+
+(Full) Template Specialisations
+................................
+
+Assume the following declarations.
+
+.. cpp:class:: template<typename TOuter> \
+               Outer
+
+  .. cpp:class:: template<typename TInner> \
+                 Inner
+
+.. cpp:class:: template<> \
+               Outer<int>
+
+  .. cpp:class:: template<typename TInner> \
+                 Inner
+
+  .. cpp:class:: template<> \
+                 Inner<bool>
+
+In general the reference must include a template parameter list for each template argument list.
+The full specialisation above can therefore be referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<> Outer\<int>`)
+and ``template\<> template\<> Outer\<int>::Inner\<bool>`` (:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`).
+As a shorthand the empty template parameter list can be omitted, e.g., ``Outer\<int>`` (:cpp:class:`Outer\<int>`)
+and ``Outer\<int>::Inner\<bool>`` (:cpp:class:`Outer\<int>::Inner\<bool>`).
+
+
+Partial Template Specialisations
+.................................
+
+Assume the following declaration.
+
+.. cpp:class:: template<typename T> \
+               Outer<T*>
+
+References to partial specialisations must always include the template parameter lists, e.g.,
+``template\<typename T> Outer\<T*>`` (:cpp:class:`template\<typename T> Outer\<T*>`).
+Currently the lookup only succeed if the template parameter identifiers are equal strings.
+
+
+Configuration Variables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`cpp-config`.
 
 
 The Standard Domain
@@ -696,6 +1019,8 @@ There is a set of directives allowing documenting command-line programs:
    referencable by :rst:role:`option` (in the example case, you'd use something
    like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
 
+   ``cmdoption`` directive is a deprecated alias for the ``option`` directive.
+
 .. rst:directive:: .. envvar:: name
 
    Describes an environment variable that the documented code or program uses or
@@ -875,13 +1200,14 @@ More domains
 
 The sphinx-contrib_ repository contains more domains available as extensions;
 currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_
-domains. Also available are domains for `Common Lisp`_, dqn_, Go_, Jinja_,
+domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_,
-Operation_, and Scala_.
+Jinja_, Operation_, and Scala_.
 
 
 .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
 
 .. _Ada: https://pypi.python.org/pypi/sphinxcontrib-adadomain
+.. _Chapel: https://pypi.python.org/pypi/sphinxcontrib-chapeldomain
 .. _CoffeeScript: https://pypi.python.org/pypi/sphinxcontrib-coffee
 .. _Common Lisp: https://pypi.python.org/pypi/sphinxcontrib-cldomain
 .. _dqn: https://pypi.python.org/pypi/sphinxcontrib-dqndomain

doc/ext/autodoc.rst

@@ -41,7 +41,7 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
 docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 
 .. _Google:
-   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
+   https://google.github.io/styleguide/pyguide.html#Comments
 .. _NumPy:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
@@ -314,6 +314,12 @@ There are also new config values that you can set:
 
    .. versionadded:: 0.3
 
+   If the class has no ``__init__`` method or if the ``__init__`` method's
+   docstring is empty, but the class has a ``__new__`` method's docstring,
+   it is used instead.
+
+   .. versionadded:: 1.4
+
 .. confval:: autodoc_member_order
 
    This value selects if automatically documented members are sorted

doc/ext/autosectionlabel.rst

@@ -0,0 +1,25 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
+==============================================================================
+
+.. module:: sphinx.ext.autosectionlabel
+   :synopsis: Allow reference section its title.
+
+.. versionadded:: 1.4
+
+This extension allows you to refer sections its title.  This affects to the
+reference role (:rst:role:`ref`).
+
+For example::
+
+    A Plain Title
+    -------------
+
+    This is the text of the section.
+
+    It refers to the section title, see :ref:`A Plain Title`.
+
+
+Internally, this extension generates the labels for each section.  If same
+section names are used in whole of document, any one is used for a target.

doc/ext/doctest.rst

@@ -33,11 +33,14 @@ There are two kinds of test blocks:
 * *code-output-style* blocks consist of an ordinary piece of Python code, and
   optionally, a piece of output for that code.
 
-The doctest extension provides four directives.  The *group* argument is
+
-interpreted as follows: if it is empty, the block is assigned to the group named
+Directives
-``default``.  If it is ``*``, the block is assigned to all groups (including the
+----------
-``default`` group).  Otherwise, it must be a comma-separated list of group
+
-names.
+The *group* argument below is interpreted as follows: if it is empty, the block
+is assigned to the group named ``default``.  If it is ``*``, the block is
+assigned to all groups (including the ``default`` group).  Otherwise, it must be
+a comma-separated list of group names.
 
 .. rst:directive:: .. testsetup:: [group]
 
@@ -56,12 +59,9 @@ names.
 .. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
-   controlling how actual output is compared with what you give as output.  By
+   controlling how actual output is compared with what you give as output.  The
-   default, these options are enabled: ``ELLIPSIS`` (allowing you to put
+   default set of flags is specified by the :confval:`doctest_default_flags`
-   ellipses in the expected output that match anything in the actual output),
+   configuration variable.
-   ``IGNORE_EXCEPTION_DETAIL`` (not comparing tracebacks),
-   ``DONT_ACCEPT_TRUE_FOR_1`` (by default, doctest accepts "True" in the output
-   where "1" is given -- this is a relic of pre-Python 2.2 times).
 
    This directive supports two options:
 
@@ -174,7 +174,24 @@ The following is an example for the usage of the directives.  The test via
       This parrot wouldn't voom if you put 3000 volts through it!
 
 
-There are also these config values for customizing the doctest extension:
+Configuration
+-------------
+
+The doctest extension uses the following configuration values:
+
+.. confval:: doctest_default_flags
+
+   By default, these options are enabled:
+
+   - ``ELLIPSIS``, allowing you to put ellipses in the expected output that
+     match anything in the actual output;
+   - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost
+     colon and any module information in the exception name to be ignored;
+   - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is
+     given -- the default behavior of accepting this substitution is a relic of
+     pre-Python 2.2 times.
+
+   .. versionadded:: 1.5
 
 .. confval:: doctest_path
 

doc/ext/example_google.py

@@ -6,30 +6,74 @@ Style Guide`_. Docstrings may extend over multiple lines. Sections are created
 with a section header and a colon followed by a block of indented text.
 
 Example:
-  Examples can be given using either the ``Example`` or ``Examples``
+    Examples can be given using either the ``Example`` or ``Examples``
-  sections. Sections support any reStructuredText formatting, including
+    sections. Sections support any reStructuredText formatting, including
-  literal blocks::
+    literal blocks::
 
-      $ python example_google.py
+        $ python example_google.py
 
-Section breaks are created by simply resuming unindented text. Section breaks
+Section breaks are created by resuming unindented text. Section breaks
 are also implicitly created anytime a new section starts.
 
 Attributes:
-  module_level_variable (int): Module level variables may be documented in
+    module_level_variable1 (int): Module level variables may be documented in
-    either the ``Attributes`` section of the module docstring, or in an
+        either the ``Attributes`` section of the module docstring, or in an
-    inline docstring immediately following the variable.
+        inline docstring immediately following the variable.
 
-    Either form is acceptable, but the two should not be mixed. Choose
+        Either form is acceptable, but the two should not be mixed. Choose
-    one convention to document module level variables and be consistent
+        one convention to document module level variables and be consistent
-    with it.
+        with it.
+
+Todo:
+    * For module TODOs
+    * You have to also use ``sphinx.ext.todo`` extension
 
 .. _Google Python Style Guide:
-   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+   http://google.github.io/styleguide/pyguide.html
 
 """
 
-module_level_variable = 12345
+module_level_variable1 = 12345
+
+module_level_variable2 = 98765
+"""int: Module level variable documented inline.
+
+The docstring may span multiple lines. The type may optionally be specified
+on the first line, separated by a colon.
+"""
+
+
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Args:
+        param1 (int): The first parameter.
+        param2 (str): The second parameter.
+
+    Returns:
+        bool: The return value. True for success, False otherwise.
+
+    .. _PEP 484:
+        https://www.python.org/dev/peps/pep-0484/
+
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    Args:
+        param1: The first parameter.
+        param2: The second parameter.
+
+    Returns:
+        The return value. True for success, False otherwise.
+
+    """
 
 
 def module_level_function(param1, param2=None, *args, **kwargs):
@@ -39,47 +83,46 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     of each parameter is required. The type and description of each parameter
     is optional, but should be included if not obvious.
 
-    If the parameter itself is optional, it should be noted by adding
+    If \*args or \*\*kwargs are accepted,
-    ", optional" to the type. If \*args or \*\*kwargs are accepted, they
+    they should be listed as ``*args`` and ``**kwargs``.
-    should be listed as \*args and \*\*kwargs.
 
     The format for a parameter is::
 
         name (type): description
-          The description may span multiple lines. Following
+            The description may span multiple lines. Following
-          lines should be indented.
+            lines should be indented. The "(type)" is optional.
 
-          Multiple paragraphs are supported in parameter
+            Multiple paragraphs are supported in parameter
-          descriptions.
+            descriptions.
 
     Args:
-      param1 (int): The first parameter.
+        param1 (int): The first parameter.
-      param2 (str, optional): The second parameter. Defaults to None.
+        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
-        Second line of description should be indented.
+            Second line of description should be indented.
-      *args: Variable length argument list.
+        *args: Variable length argument list.
-      **kwargs: Arbitrary keyword arguments.
+        **kwargs: Arbitrary keyword arguments.
 
     Returns:
-      bool: True if successful, False otherwise.
+        bool: True if successful, False otherwise.
 
-      The return type is optional and may be specified at the beginning of
+        The return type is optional and may be specified at the beginning of
-      the ``Returns`` section followed by a colon.
+        the ``Returns`` section followed by a colon.
 
-      The ``Returns`` section may span multiple lines and paragraphs.
+        The ``Returns`` section may span multiple lines and paragraphs.
-      Following lines should be indented to match the first line.
+        Following lines should be indented to match the first line.
 
-      The ``Returns`` section supports any reStructuredText formatting,
+        The ``Returns`` section supports any reStructuredText formatting,
-      including literal blocks::
+        including literal blocks::
 
-          {
+            {
-              'param1': param1,
+                'param1': param1,
-              'param2': param2
+                'param2': param2
-          }
+            }
 
     Raises:
-      AttributeError: The ``Raises`` section is a list of all exceptions
+        AttributeError: The ``Raises`` section is a list of all exceptions
-        that are relevant to the interface.
+            that are relevant to the interface.
-      ValueError: If `param2` is equal to `param1`.
+        ValueError: If `param2` is equal to `param1`.
 
     """
     if param1 == param2:
@@ -91,17 +134,17 @@ def example_generator(n):
     """Generators have a ``Yields`` section instead of a ``Returns`` section.
 
     Args:
-      n (int): The upper limit of the range to generate, from 0 to `n` - 1
+        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
 
     Yields:
-      int: The next number in the range of 0 to `n` - 1
+        int: The next number in the range of 0 to `n` - 1.
 
     Examples:
-      Examples should be written in doctest format, and should illustrate how
+        Examples should be written in doctest format, and should illustrate how
-      to use the function.
+        to use the function.
 
-      >>> print [i for i in example_generator(4)]
+        >>> print([i for i in example_generator(4)])
-      [0, 1, 2, 3]
+        [0, 1, 2, 3]
 
     """
     for i in range(n):
@@ -118,18 +161,19 @@ class ExampleError(Exception):
     convention to document the __init__ method and be consistent with it.
 
     Note:
-      Do not include the `self` parameter in the ``Args`` section.
+        Do not include the `self` parameter in the ``Args`` section.
 
     Args:
-      msg (str): Human readable string describing the exception.
+        msg (str): Human readable string describing the exception.
-      code (int, optional): Error code, defaults to 2.
+        code (:obj:`int`, optional): Error code.
 
     Attributes:
-      msg (str): Human readable string describing the exception.
+        msg (str): Human readable string describing the exception.
-      code (int): Exception error code.
+        code (int): Exception error code.
 
     """
-    def __init__(self, msg, code=2):
+
+    def __init__(self, msg, code):
         self.msg = msg
         self.code = code
 
@@ -137,17 +181,21 @@ class ExampleError(Exception):
 class ExampleClass(object):
     """The summary line for a class docstring should fit on one line.
 
-    If the class has public attributes, they should be documented here
+    If the class has public attributes, they may be documented here
     in an ``Attributes`` section and follow the same formatting as a
-    function's ``Args`` section.
+    function's ``Args`` section. Alternatively, attributes may be documented
+    inline with the attribute's declaration (see __init__ method below).
+
+    Properties created with the ``@property`` decorator should be documented
+    in the property's getter method.
 
     Attributes:
-      attr1 (str): Description of `attr1`.
+        attr1 (str): Description of `attr1`.
-      attr2 (list of str): Description of `attr2`.
+        attr2 (:obj:`int`, optional): Description of `attr2`.
-      attr3 (int): Description of `attr3`.
 
     """
-    def __init__(self, param1, param2, param3=0):
+
+    def __init__(self, param1, param2, param3):
         """Example of docstring on the __init__ method.
 
         The __init__ method may be documented in either the class level
@@ -157,46 +205,72 @@ class ExampleClass(object):
         convention to document the __init__ method and be consistent with it.
 
         Note:
-          Do not include the `self` parameter in the ``Args`` section.
+            Do not include the `self` parameter in the ``Args`` section.
 
         Args:
-          param1 (str): Description of `param1`.
+            param1 (str): Description of `param1`.
-          param2 (list of str): Description of `param2`. Multiple
+            param2 (:obj:`int`, optional): Description of `param2`. Multiple
-            lines are supported.
+                lines are supported.
-          param3 (int, optional): Description of `param3`, defaults to 0.
+            param3 (list(str)): Description of `param3`.
 
         """
         self.attr1 = param1
         self.attr2 = param2
-        self.attr3 = param3
+        self.attr3 = param3  #: Doc comment *inline* with attribute
+
+        #: list(str): Doc comment *before* attribute, with type specified
+        self.attr4 = ['attr4']
+
+        self.attr5 = None
+        """str: Docstring *after* attribute, with type specified."""
+
+    @property
+    def readonly_property(self):
+        """str: Properties should be documented in their getter method."""
+        return 'readonly_property'
+
+    @property
+    def readwrite_property(self):
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
+
+        If the setter method contains notable behavior, it should be
+        mentioned here.
+        """
+        return ['readwrite_property']
+
+    @readwrite_property.setter
+    def readwrite_property(self, value):
+        value
 
     def example_method(self, param1, param2):
         """Class methods are similar to regular functions.
 
         Note:
-          Do not include the `self` parameter in the ``Args`` section.
+            Do not include the `self` parameter in the ``Args`` section.
 
         Args:
-          param1: The first parameter.
+            param1: The first parameter.
-          param2: The second parameter.
+            param2: The second parameter.
 
         Returns:
-          True if successful, False otherwise.
+            True if successful, False otherwise.
 
         """
         return True
 
     def __special__(self):
-        """By default special members with docstrings are included.
+        """By default special members with docstrings are not included.
 
         Special members are any methods or attributes that start with and
         end with a double underscore. Any special member with a docstring
-        will be included in the output.
+        will be included in the output, if
+        ``napoleon_include_special_with_doc`` is set to True.
 
-        This behavior can be disabled by changing the following setting in
+        This behavior can be enabled by changing the following setting in
         Sphinx's conf.py::
 
-            napoleon_include_special_with_doc = False
+            napoleon_include_special_with_doc = True
 
         """
         pass

doc/ext/example_google.rst

@@ -9,7 +9,9 @@ Example Google Style Python Docstrings
 
    :ref:`example_numpy`
 
-Download: :download:`example_google.py <example_google.py>`
+.. only:: builder_html
+
+   Download: :download:`example_google.py <example_google.py>`
 
 .. literalinclude:: example_google.py
    :language: python

doc/ext/example_numpy.py

@@ -23,12 +23,12 @@ Notes
     This is an example of an indented section. It's like any other section,
     but the body is indented to help it stand out from surrounding text.
 
-If a section is indented, then a section break is created simply by
+If a section is indented, then a section break is created by
 resuming unindented text.
 
 Attributes
 ----------
-module_level_variable : int
+module_level_variable1 : int
     Module level variables may be documented in either the ``Attributes``
     section of the module docstring, or in an inline docstring immediately
     following the variable.
@@ -37,12 +37,66 @@ module_level_variable : int
     one convention to document module level variables and be consistent
     with it.
 
+
 .. _NumPy Documentation HOWTO:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
 """
 
-module_level_variable = 12345
+module_level_variable1 = 12345
+
+module_level_variable2 = 98765
+"""int: Module level variable documented inline.
+
+The docstring may span multiple lines. The type may optionally be specified
+on the first line, separated by a colon.
+"""
+
+
+def function_with_types_in_docstring(param1, param2):
+    """Example function with types documented in the docstring.
+
+    `PEP 484`_ type annotations are supported. If attribute, parameter, and
+    return types are annotated according to `PEP 484`_, they do not need to be
+    included in the docstring:
+
+    Parameters
+    ----------
+    param1 : int
+        The first parameter.
+    param2 : str
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+    .. _PEP 484:
+        https://www.python.org/dev/peps/pep-0484/
+
+    """
+
+
+def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
+    """Example function with PEP 484 type annotations.
+
+    The return type must be duplicated in the docstring to comply
+    with the NumPy docstring style.
+
+    Parameters
+    ----------
+    param1
+        The first parameter.
+    param2
+        The second parameter.
+
+    Returns
+    -------
+    bool
+        True if successful, False otherwise.
+
+    """
 
 
 def module_level_function(param1, param2=None, *args, **kwargs):
@@ -52,9 +106,8 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     The name of each parameter is required. The type and description of each
     parameter is optional, but should be included if not obvious.
 
-    If the parameter itself is optional, it should be noted by adding
+    If \*args or \*\*kwargs are accepted,
-    ", optional" to the type. If \*args or \*\*kwargs are accepted, they
+    they should be listed as ``*args`` and ``**kwargs``.
-    should be listed as \*args and \*\*kwargs.
 
     The format for a parameter is::
 
@@ -63,6 +116,7 @@ def module_level_function(param1, param2=None, *args, **kwargs):
 
             The description may span multiple lines. Following lines
             should be indented to match the first line of the description.
+            The ": type" is optional.
 
             Multiple paragraphs are supported in parameter
             descriptions.
@@ -71,8 +125,8 @@ def module_level_function(param1, param2=None, *args, **kwargs):
     ----------
     param1 : int
         The first parameter.
-    param2 : str, optional
+    param2 : :obj:`str`, optional
-        The second parameter, defaults to None.
+        The second parameter.
     *args
         Variable length argument list.
     **kwargs
@@ -115,19 +169,19 @@ def example_generator(n):
     Parameters
     ----------
     n : int
-        The upper limit of the range to generate, from 0 to `n` - 1
+        The upper limit of the range to generate, from 0 to `n` - 1.
 
     Yields
     ------
     int
-        The next number in the range of 0 to `n` - 1
+        The next number in the range of 0 to `n` - 1.
 
     Examples
     --------
     Examples should be written in doctest format, and should illustrate how
     to use the function.
 
-    >>> print [i for i in example_generator(4)]
+    >>> print([i for i in example_generator(4)])
     [0, 1, 2, 3]
 
     """
@@ -152,18 +206,19 @@ class ExampleError(Exception):
     ----------
     msg : str
         Human readable string describing the exception.
-    code : int, optional
+    code : :obj:`int`, optional
-        Error code, defaults to 2.
+        Numeric error code.
 
     Attributes
     ----------
     msg : str
         Human readable string describing the exception.
     code : int
-        Exception error code.
+        Numeric error code.
 
     """
-    def __init__(self, msg, code=2):
+
+    def __init__(self, msg, code):
         self.msg = msg
         self.code = code
 
@@ -171,21 +226,24 @@ class ExampleError(Exception):
 class ExampleClass(object):
     """The summary line for a class docstring should fit on one line.
 
-    If the class has public attributes, they should be documented here
+    If the class has public attributes, they may be documented here
     in an ``Attributes`` section and follow the same formatting as a
-    function's ``Parameters`` section.
+    function's ``Args`` section. Alternatively, attributes may be documented
+    inline with the attribute's declaration (see __init__ method below).
+
+    Properties created with the ``@property`` decorator should be documented
+    in the property's getter method.
 
     Attributes
     ----------
     attr1 : str
         Description of `attr1`.
-    attr2 : list of str
+    attr2 : :obj:`int`, optional
         Description of `attr2`.
-    attr3 : int
-        Description of `attr3`.
 
     """
-    def __init__(self, param1, param2, param3=0):
+
+    def __init__(self, param1, param2, param3):
         """Example of docstring on the __init__ method.
 
         The __init__ method may be documented in either the class level
@@ -202,16 +260,41 @@ class ExampleClass(object):
         ----------
         param1 : str
             Description of `param1`.
-        param2 : list of str
+        param2 : list(str)
             Description of `param2`. Multiple
             lines are supported.
-        param3 : int, optional
+        param3 : :obj:`int`, optional
-            Description of `param3`, defaults to 0.
+            Description of `param3`.
 
         """
         self.attr1 = param1
         self.attr2 = param2
-        self.attr3 = param3
+        self.attr3 = param3  #: Doc comment *inline* with attribute
+
+        #: list(str): Doc comment *before* attribute, with type specified
+        self.attr4 = ["attr4"]
+
+        self.attr5 = None
+        """str: Docstring *after* attribute, with type specified."""
+
+    @property
+    def readonly_property(self):
+        """str: Properties should be documented in their getter method."""
+        return "readonly_property"
+
+    @property
+    def readwrite_property(self):
+        """list(str): Properties with both a getter and setter
+        should only be documented in their getter method.
+
+        If the setter method contains notable behavior, it should be
+        mentioned here.
+        """
+        return ["readwrite_property"]
+
+    @readwrite_property.setter
+    def readwrite_property(self, value):
+        value
 
     def example_method(self, param1, param2):
         """Class methods are similar to regular functions.
@@ -236,16 +319,17 @@ class ExampleClass(object):
         return True
 
     def __special__(self):
-        """By default special members with docstrings are included.
+        """By default special members with docstrings are not included.
 
         Special members are any methods or attributes that start with and
         end with a double underscore. Any special member with a docstring
-        will be included in the output.
+        will be included in the output, if
+        ``napoleon_include_special_with_doc`` is set to True.
 
-        This behavior can be disabled by changing the following setting in
+        This behavior can be enabled by changing the following setting in
         Sphinx's conf.py::
 
-            napoleon_include_special_with_doc = False
+            napoleon_include_special_with_doc = True
 
         """
         pass

doc/ext/example_numpy.rst

@@ -9,7 +9,9 @@ Example NumPy Style Python Docstrings
 
    :ref:`example_google`
 
-Download: :download:`example_numpy.py <example_numpy.py>`
+.. only:: builder_html
+
+   Download: :download:`example_numpy.py <example_numpy.py>`
 
 .. literalinclude:: example_numpy.py
    :language: python

doc/ext/githubpages.rst

@@ -0,0 +1,12 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
+==================================================================
+
+.. module:: sphinx.ext.githubpages
+   :synopsis: Publish HTML docs in GitHub Pages
+
+.. versionadded:: 1.4
+
+This extension creates ``.nojekyll`` file on generated HTML directory to publish
+the document on GitHub Pages.

doc/ext/graphviz.rst

@@ -53,6 +53,10 @@ It adds these directives:
 
          "bar" -- "baz";
 
+   .. note:: The graph name is passed unchanged to Graphviz.  If it contains
+      non-alphanumeric characters (e.g. a dash), you will have to double-quote
+      it.
+
 
 .. rst:directive:: digraph
 
@@ -83,6 +87,19 @@ It adds these directives:
    caption to the diagram.  Naturally, diagrams marked as "inline" cannot have a
    caption.
 
+.. deprecated:: 1.4
+   ``inline`` option is deprecated.
+   All three directives generate inline node by default. If ``caption`` is given,
+   these generate block node instead.
+
+.. versionchanged:: 1.4
+   All three directives support a ``graphviz_dot`` option that can be switch the
+   ``dot`` command within the directive.
+
+.. versionadded:: 1.5
+   All three directives support a ``align`` option to align the graph horizontal.
+   The values "left", "center", "right" are allowed.
+
 There are also these new config values:
 
 .. confval:: graphviz_dot
@@ -93,8 +110,8 @@ There are also these new config values:
 
    Since this setting is not portable from system to system, it is normally not
    useful to set it in ``conf.py``; rather, giving it on the
-   :program:`sphinx-build` command line via the :option:`-D` option should be
+   :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
-   preferable, like this::
+   option should be preferable, like this::
 
       sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
 
@@ -107,7 +124,18 @@ There are also these new config values:
 .. confval:: graphviz_output_format
 
    The output format for Graphviz when building HTML files.  This must be either
-   ``'png'`` or ``'svg'``; the default is ``'png'``.
+   ``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in
+   order to make the URL links work properly, an appropriate ``target``
+   attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the
+   link in the following graph should work in the svg output: ::
+
+       .. graphviz::
+
+            digraph example {
+                a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
+                b [label="other"];
+                a -> b;
+            }
 
    .. versionadded:: 1.0
       Previously, output always was PNG.

doc/ext/ifconfig.rst

@@ -26,8 +26,8 @@ This extension is quite simple, and features only one directive:
    :file:`conf.py`, e.g.::
 
       def setup(app):
-          app.add_config_value('releaselevel', '', True)
+          app.add_config_value('releaselevel', '', 'env')
 
-   The second argument is the default value, the third should always be ``True``
+   The second argument is the default value, the third should always be ``'env'``
    for such values (it selects if Sphinx re-reads the documents if the value
    changes).

doc/ext/inheritance.rst

@@ -33,10 +33,15 @@ It adds this directive:
    It also supports a ``private-bases`` flag option; if given, private base
    classes (those whose name starts with ``_``) will be included.
 
+   You can use ``caption`` option to give a caption to the diagram.
+
    .. versionchanged:: 1.1
       Added ``private-bases`` option; previously, all bases were always
       included.
 
+   .. versionchanged:: 1.5
+      Added ``caption`` option
+
 
 New config values are:
 

doc/ext/math.rst

@@ -4,7 +4,7 @@ Math support in Sphinx
 ======================
 
 .. module:: sphinx.ext.mathbase
-   :synopsis: Common math support for pngmath and mathjax / jsmath.
+   :synopsis: Common math support for imgmath and mathjax / jsmath.
 
 .. versionadded:: 0.5
 
@@ -17,7 +17,7 @@ support extensions should, if possible, reuse that support too.
 .. note::
 
    :mod:`.mathbase` is not meant to be added to the :confval:`extensions` config
-   value, instead, use either :mod:`sphinx.ext.pngmath` or
+   value, instead, use either :mod:`sphinx.ext.imgmath` or
    :mod:`sphinx.ext.mathjax` as described below.
 
 The input language for mathematics is LaTeX markup.  This is the de-facto
@@ -28,6 +28,13 @@ Keep in mind that when you put math markup in **Python docstrings** read by
 :mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
 or use Python raw strings (``r"raw"``).
 
+:mod:`.mathbase` provides the following config values:
+
+.. confval:: math_number_all
+
+   Set this option to ``True`` if you want all displayed math to be numbered.
+   The default is ``False``.
+
 :mod:`.mathbase` defines these new markup elements:
 
 .. rst:role:: math
@@ -96,20 +103,27 @@ or use Python raw strings (``r"raw"``).
       beautiful mathematical formulas.
 
 
-:mod:`sphinx.ext.pngmath` -- Render math as PNG images
+:mod:`sphinx.ext.imgmath` -- Render math as images
-------------------------------------------------------
+--------------------------------------------------
 
-.. module:: sphinx.ext.pngmath
+.. module:: sphinx.ext.imgmath
-   :synopsis: Render math as PNG images.
+   :synopsis: Render math as PNG or SVG images.
 
-This extension renders math via LaTeX and dvipng_ into PNG images.  This of
+.. versionadded:: 1.4
-course means that the computer where the docs are built must have both programs
+
-available.
+This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG
+images. This of course means that the computer where the docs are built must
+have both programs available.
 
 There are various config values you can set to influence how the images are
 built:
 
-.. confval:: pngmath_latex
+.. confval:: imgmath_image_format
+
+   The output image format. The default is ``'png'``.  It should be either
+   ``'png'`` or ``'svg'``.
+
+.. confval:: imgmath_latex
 
    The command name with which to invoke LaTeX.  The default is ``'latex'``; you
    may need to set this to a full path if ``latex`` is not in the executable
@@ -117,45 +131,54 @@ built:
 
    Since this setting is not portable from system to system, it is normally not
    useful to set it in ``conf.py``; rather, giving it on the
-   :program:`sphinx-build` command line via the :option:`-D` option should be
+   :program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
-   preferable, like this::
+   option should be preferable, like this::
 
-      sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
+      sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
 
-   .. versionchanged:: 0.5.1
+   This value should only contain the path to the latex executable, not further
-      This value should only contain the path to the latex executable, not
+   arguments; use :confval:`imgmath_latex_args` for that purpose.
-      further arguments; use :confval:`pngmath_latex_args` for that purpose.
 
-.. confval:: pngmath_dvipng
+.. confval:: imgmath_dvipng
 
    The command name with which to invoke ``dvipng``.  The default is
    ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
-   the executable search path.
+   the executable search path. This option is only used when
+   ``imgmath_image_format`` is set to ``'png'``.
 
-.. confval:: pngmath_latex_args
+.. confval:: imgmath_dvisvgm
+
+   The command name with which to invoke ``dvisvgm``.  The default is
+   ``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
+   in the executable search path.  This option is only used when
+   ``imgmath_image_format`` is ``'svg'``.
+
+.. confval:: imgmath_latex_args
 
    Additional arguments to give to latex, as a list.  The default is an empty
    list.
 
-   .. versionadded:: 0.5.1
+.. confval:: imgmath_latex_preamble
-
-.. confval:: pngmath_latex_preamble
 
    Additional LaTeX code to put into the preamble of the short LaTeX files that
    are used to translate the math snippets.  This is empty by default.  Use it
    e.g. to add more packages whose commands you want to use in the math.
 
-.. confval:: pngmath_dvipng_args
+.. confval:: imgmath_dvipng_args
 
    Additional arguments to give to dvipng, as a list.  The default value is
    ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
    image a bit darker and larger then it is by default, and produces PNGs with a
-   transparent background.
+   transparent background.  This option is used only when
+   ``imgmath_image_format`` is ``'png'``.
 
-   .. versionchanged:: 1.2
+.. confval:: imgmath_dvisvgm_args
-      Now includes ``-bg Transparent`` by default.
 
-.. confval:: pngmath_use_preview
+   Additional arguments to give to dvisvgm, as a list.  The default value is
+   ``['--no-fonts']``.  This option is used only when ``imgmath_image_format``
+   is ``'svg'``.
+
+.. confval:: imgmath_use_preview
 
    ``dvipng`` has the ability to determine the "depth" of the rendered text: for
    example, when typesetting a fraction inline, the baseline of surrounding text
@@ -165,14 +188,20 @@ built:
    ``vertical-align`` style that correctly aligns the baselines.
 
    Unfortunately, this only works when the `preview-latex package`_ is
-   installed.  Therefore, the default for this option is ``False``.
+   installed. Therefore, the default for this option is ``False``.
 
-.. confval:: pngmath_add_tooltips
+   Currently this option is only used when ``imgmath_image_format`` is
+   ``'png'``.
+
+.. confval:: imgmath_add_tooltips
 
    Default: ``True``.  If false, do not add the LaTeX code as an "alt" attribute
    for math images.
 
-   .. versionadded:: 1.1
+.. confval:: imgmath_font_size
+
+   The font size (in ``pt``) of the displayed math.  The default value is
+   ``12``.  It must be a positive integer.
 
 
 :mod:`sphinx.ext.mathjax` -- Render math via JavaScript
@@ -235,7 +264,8 @@ package jsMath_.  It provides this config value:
 
 
 .. _dvipng: http://savannah.nongnu.org/projects/dvipng/
-.. _MathJax: http://www.mathjax.org/
+.. _dvisvgm: http://dvisvgm.bplaced.net/
+.. _MathJax: https://www.mathjax.org/
 .. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
 .. _preview-latex package: http://www.gnu.org/software/auctex/preview-latex.html
 .. _AmSMath LaTeX package: http://www.ams.org/publications/authors/tex/amslatex

doc/ext/napoleon.rst

@@ -11,6 +11,8 @@
 Napoleon - *Marching toward legible docstrings*
 ===============================================
 
+.. highlight:: text
+
 Are you tired of writing docstrings that look like this::
 
     :param path: The path of the file to wrap
@@ -48,11 +50,11 @@ the documentation, so it doesn't modify any of the docstrings in your actual
 source code files.
 
 .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
-.. _docstrings: http://www.python.org/dev/peps/pep-0287/
+.. _docstrings: https://www.python.org/dev/peps/pep-0287/
 .. _Google Python Style Guide:
-   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
+   http://google.github.io/styleguide/pyguide.html
 .. _Google:
-   http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
+   http://google.github.io/styleguide/pyguide.html#Comments
 .. _NumPy:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 .. _Khan Academy:
@@ -110,9 +112,11 @@ All of the following section headers are supported:
     * ``Raises``
     * ``References``
     * ``See Also``
+    * ``Todo``
     * ``Warning``
     * ``Warnings`` *(alias of Warning)*
     * ``Warns``
+    * ``Yield`` *(alias of Yields)*
     * ``Yields``
 
 Google vs NumPy
@@ -122,7 +126,9 @@ Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
 main difference between the two styles is that Google uses indention to
 separate sections, whereas NumPy uses underlines.
 
-Google style::
+Google style:
+
+.. code-block:: python3
 
     def func(arg1, arg2):
         """Summary line.
@@ -139,7 +145,9 @@ Google style::
         """
         return True
 
-NumPy style::
+NumPy style:
+
+.. code-block:: python3
 
     def func(arg1, arg2):
         """Summary line.
@@ -179,6 +187,60 @@ not be mixed. Choose one style for your project and be consistent with it.
    * :ref:`example_numpy`
 
 
+Type Annotations
+----------------
+
+`PEP 484`_ introduced a standard way to express types in Python code.
+This is an alternative to expressing types directly in docstrings.
+One benefit of expressing types according to `PEP 484`_ is that
+type checkers and IDEs can take advantage of them for static code
+analysis.
+
+Google style with Python 3 type annotations::
+
+    def func(arg1: int, arg2: str) -> bool:
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1: Description of arg1
+            arg2: Description of arg2
+
+        Returns:
+            Description of return value
+
+        """
+        return True
+
+Google style with types in docstrings::
+
+    def func(arg1, arg2):
+        """Summary line.
+
+        Extended description of function.
+
+        Args:
+            arg1 (int): Description of arg1
+            arg2 (str): Description of arg2
+
+        Returns:
+            bool: Description of return value
+
+        """
+        return True
+
+.. Note::
+   `Python 2/3 compatible annotations`_ aren't currently
+   supported by Sphinx and won't show up in the docs.
+
+.. _PEP 484:
+   https://www.python.org/dev/peps/pep-0484/
+
+.. _Python 2/3 compatible annotations:
+   https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+
+
 Configuration
 =============
 
@@ -195,6 +257,7 @@ enabled in `conf.py`::
     # Napoleon settings
     napoleon_google_docstring = True
     napoleon_numpy_docstring = True
+    napoleon_include_init_with_doc = False
     napoleon_include_private_with_doc = False
     napoleon_include_special_with_doc = True
     napoleon_use_admonition_for_examples = False
@@ -221,6 +284,23 @@ enabled in `conf.py`::
    True to parse `NumPy style`_ docstrings. False to disable support
    for NumPy style docstrings. *Defaults to True.*
 
+.. confval:: napoleon_include_init_with_doc
+
+   True to list ``__init___`` docstrings separately from the class
+   docstring. False to fall back to Sphinx's default behavior, which
+   considers the ``__init___`` docstring as part of the class
+   documentation. *Defaults to False.*
+
+   **If True**::
+
+       def __init__(self):
+           \"\"\"
+           This will be included in the docs because it has a docstring
+           \"\"\"
+
+       def __init__(self):
+           # This will NOT be included in the docs
+
 .. confval:: napoleon_include_private_with_doc
 
    True to include private members (like ``_membername``) with docstrings
@@ -358,6 +438,22 @@ enabled in `conf.py`::
                     * **arg2** (*int, optional*) --
                       Description of `arg2`, defaults to 0
 
+.. confval:: napoleon_use_keyword
+
+   True to use a ``:keyword:`` role for each function keyword argument.
+   False to use a single ``:keyword arguments:`` role for all the
+   keywords.
+   *Defaults to True.*
+
+   This behaves similarly to  :attr:`napoleon_use_param`. Note unlike docutils,
+   ``:keyword:`` and ``:param:`` will not be treated the same way - there will
+   be a separate "Keyword Arguments" section, rendered in the same fashion as
+   "Parameters" section (type links created if possible)
+
+   .. seealso::
+
+      :attr:`napoleon_use_param`
+
 .. confval:: napoleon_use_rtype
 
    True to use the ``:rtype:`` role for the return type. False to output

doc/ext/todo.rst

@@ -16,6 +16,10 @@ There are two additional directives when using this extension:
    It will only show up in the output if :confval:`todo_include_todos` is
    ``True``.
 
+   .. versionadded:: 1.3.2
+      This directive supports an ``class`` option that determines the class attribute
+      for HTML output.  If not given, the class defaults to ``admonition-todo``.
+
 
 .. rst:directive:: todolist
 
@@ -29,3 +33,26 @@ There is also an additional config value:
 
    If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
    else they produce nothing.  The default is ``False``.
+
+.. confval:: todo_emit_warnings
+
+   If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries.
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
+.. confval:: todo_link_only
+
+   If this is ``True``, :rst:dir:`todolist` produce output without file path and line,
+   The default is ``False``.
+
+   .. versionadded:: 1.4
+
+autodoc provides the following an additional event:
+
+.. event:: todo-defined (app, node)
+
+   .. versionadded:: 1.5
+
+   Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node``
+   node.

doc/ext/viewcode.rst

@@ -15,11 +15,12 @@ a highlighted version of the source code, and a link will be added to all object
 descriptions that leads to the source code of the described object.  A link back
 from the source to the description will also be inserted.
 
-There are currently no configuration values for this extension; you just need to
+This extension works only on HTML related builders like ``html``,
-add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to
+``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
-work.
+``singlehtml``. By default ``epub`` builder doesn't
+support this extension (see :confval:`viewcode_enable_epub`).
 
-There is also an additional config value:
+There is an additional config value:
 
 .. confval:: viewcode_import
 
@@ -38,3 +39,26 @@ There is also an additional config value:
       main routine is protected by a ``if __name__ == '__main__'`` condition.
 
    .. versionadded:: 1.3
+
+.. confval:: viewcode_enable_epub
+
+   If this is ``True``, viewcode extension is also enabled even if you use
+   epub builders. This extension generates pages outside toctree, but this
+   is not preferred as epub format.
+
+   Until 1.4.x, this extension is always enabled. If you want to generate
+   epub as same as 1.4.x, you should set ``True``, but epub format checker's
+   score becomes worse.
+
+   The default is ``False``.
+
+   .. versionadded:: 1.5
+
+   .. warning::
+
+      Not all epub readers support pages generated by viewcode extension.
+      These readers ignore links to pages are not under toctree.
+
+      Some reader's rendering result are corrupted and
+      `epubcheck <https://github.com/IDPF/epubcheck>`_'s score
+      becomes worse even if the reader supports.

doc/extdev/appapi.rst

@@ -125,6 +125,28 @@ package.
    .. versionchanged:: 0.5
       Added the support for keyword arguments giving visit functions.
 
+.. method:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
+
+   Register a Docutils node class as a numfig target.  Sphinx numbers the node
+   automatically. And then the users can refer it using :rst:role:`numref`.
+
+   *figtype* is a type of enumerable nodes.  Each figtypes have individual
+   numbering sequences.  As a system figtypes, ``figure``, ``table`` and
+   ``code-block`` are defined.  It is able to add custom nodes to these
+   default figtypes.  It is also able to define new custom figtype if new
+   figtype is given.
+
+   *title_getter* is a getter function to obtain the title of node.  It takes
+   an instance of the enumerable node, and it must return its title as string.
+   The title is used to the default title of references for :rst:role:`ref`.
+   By default, Sphinx searches ``docutils.nodes.caption`` or
+   ``docutils.nodes.title`` from the node as a title.
+
+   Other keyword arguments are used for node visitor functions. See the
+   :meth:`Sphinx.add_node` for details.
+
+   .. versionadded:: 1.4
+
 .. method:: Sphinx.add_directive(name, func, content, arguments, **options)
             Sphinx.add_directive(name, directiveclass)
 
@@ -155,7 +177,7 @@ package.
       add_directive('literalinclude', literalinclude_directive,
                     content = 0, arguments = (1, 0, 0),
                     linenos = directives.flag,
-                    language = direcitves.unchanged,
+                    language = directives.unchanged,
                     encoding = directives.encoding)
 
    .. versionchanged:: 0.6
@@ -336,6 +358,12 @@ package.
 
    .. versionadded:: 1.1
 
+.. method:: Sphinx.add_source_parser(suffix, parser)
+
+   Register a parser class for specified *suffix*.
+
+   .. versionadded:: 1.4
+
 .. method:: Sphinx.require_sphinx(version)
 
    Compare *version* (which must be a ``major.minor`` version string,

doc/extdev/envapi.rst

@@ -17,7 +17,11 @@ Build environment API
 
    .. attribute:: srcdir
 
-      Source directory (the directory containing ``conf.py``).
+      Source directory.
+
+   .. attribute:: confdir
+
+      Directory containing ``conf.py``.
 
    .. attribute:: doctreedir
 

doc/extdev/index.rst

@@ -52,4 +52,5 @@ APIs used for writing extensions
    builderapi
    markupapi
    domainapi
+   parserapi
    nodes

doc/extdev/markupapi.rst

@@ -135,5 +135,5 @@ return ``node.children`` from the Directive.
 
 .. seealso::
 
-   `Creating directives <http://docutils.sf.net/docs/howto/rst-directives.html>`_
+   `Creating directives <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
       HOWTO of the Docutils documentation

doc/extdev/parserapi.rst

@@ -0,0 +1,8 @@
+.. _parser-api:
+
+Parser API
+==========
+
+.. module:: sphinx.parsers
+
+.. autoclass:: Parser

doc/extdev/tutorial.rst

@@ -149,7 +149,7 @@ The new elements are added in the extension's setup function.  Let us create a
 new Python module called :file:`todo.py` and add the setup function::
 
    def setup(app):
-       app.add_config_value('todo_include_todos', False, False)
+       app.add_config_value('todo_include_todos', False, 'html')
 
        app.add_node(todolist)
        app.add_node(todo,
@@ -171,7 +171,7 @@ the individual calls do is the following:
   new *config value* ``todo_include_todos``, whose default value should be
   ``False`` (this also tells Sphinx that it is a boolean value).
 
-  If the third argument was ``True``, all documents would be re-read if the
+  If the third argument was ``'html'``, HTML documents would be full rebuild if the
   config value changed its value.  This is needed for config values that
   influence reading (build phase 1).
 

doc/extensions.rst

@@ -19,19 +19,21 @@ These extensions are built in and can be activated by respective entries in the
 .. toctree::
 
    ext/autodoc
+   ext/autosectionlabel
    ext/autosummary
-   ext/doctest
-   ext/intersphinx
-   ext/math
-   ext/graphviz
-   ext/inheritance
-   ext/ifconfig
    ext/coverage
-   ext/todo
+   ext/doctest
    ext/extlinks
-   ext/viewcode
+   ext/githubpages
+   ext/graphviz
+   ext/ifconfig
+   ext/inheritance
+   ext/intersphinx
    ext/linkcode
+   ext/math
    ext/napoleon
+   ext/todo
+   ext/viewcode
 
 
 Third-party extensions
@@ -47,7 +49,7 @@ comprehensive list.
 
 If you write an extension that you think others will find useful or you think
 should be included as a part of Sphinx, please write to the project mailing
-list (`join here <https://groups.google.com/group/sphinx-dev>`_).
+list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
 
 .. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
 

doc/faq.rst

@@ -10,7 +10,7 @@ How do I...
 -----------
 
 ... create PDF files without LaTeX?
-   You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or
+   You can use `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or
    greater which comes with built-in Sphinx integration.  See the
    :ref:`builders` section for details.
 
@@ -82,7 +82,7 @@ GitHub Pages
    Sphinx HTML output properly.
 
 MediaWiki
-   See https://bitbucket.org/kevindunn/sphinx-wiki, a project by Kevin Dunn.
+   See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by Kevin Dunn.
 
 Google Analytics
    You can use a custom ``layout.html`` template, like this:
@@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files:
   are often cut at the right margin.  The default Courier font (or variant) is
   quite wide and you can only display up to 60 characters on a line.  If you
   replace it with a narrower font, you can get more characters on a line.  You
-  may even use `FontForge <http://fontforge.org/>`_ and create
+  may even use `FontForge <http://fontforge.github.io/>`_ and create
   narrow variants of some free font.  In my case I get up to 70 characters on a
   line.
 
@@ -149,7 +149,7 @@ The following list gives some hints for the creation of epub files:
 * Test the created epubs. You can use several alternatives.  The ones I am aware
   of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
   and Bookworm_.  For bookworm you can download the source from
-  http://code.google.com/p/threepress/ and run your own local server.
+  https://code.google.com/archive/p/threepress and run your own local server.
 
 * Large floating divs are not displayed properly.
   If they cover more than one page, the div is only shown on the first page.
@@ -167,10 +167,10 @@ The following list gives some hints for the creation of epub files:
   :confval:`html_static_path` directory and reference it with its full path in
   the :confval:`epub_cover` config option.
 
-.. _Epubcheck: http://code.google.com/p/epubcheck/
+.. _Epubcheck: https://code.google.com/archive/p/epubcheck
 .. _Calibre: http://calibre-ebook.com/
-.. _FBreader: http://fbreader.org/
+.. _FBreader: https://fbreader.org/
-.. _Bookworm: http://oreilly.com/bookworm/index.html
+.. _Bookworm: http://www.oreilly.com/bookworm/index.html
 
 
 .. _texinfo-faq:
@@ -213,7 +213,7 @@ If you want Emacs to display Info files produced by Sphinx using the value
 Info files, try adding the following Emacs Lisp code to your start-up file,
 ``~/.emacs.d/init.el``.
 
-::
+.. code-block:: elisp
 
    (defadvice info-insert-file-contents (after
                                          sphinx-info-insert-file-contents

doc/install.rst

@@ -72,7 +72,7 @@ Install Python
 Most Windows users do not have Python, so we begin with the installation of
 Python itself.  If you have already installed Python, please skip this section.
 
-Go to http://python.org, the main download site for Python. Look at the left
+Go to https://www.python.org/, the main download site for Python. Look at the left
 sidebar and under "Quick Links", click "Windows Installer" to download.
 
 .. image:: pythonorg.png
@@ -114,7 +114,7 @@ as ``sphinx-build`` easily from the Command Prompt.
 
 
 Install the pip command
-^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Python has a very useful :command:`pip` command which can download and install
 3rd-party libraries with a single command. This is provided by the
@@ -135,11 +135,11 @@ install.
 .. note::
 
    ``pip`` has been contained in the Python official installation after version
-    of Python-3.4.0 or Python-2.7.9.
+   of Python-3.4.0 or Python-2.7.9.
 
 
 Installing Sphinx with pip
----------------------------
+--------------------------
 
 If you finished the installation of pip, type this line in the command prompt:
 
@@ -147,7 +147,7 @@ If you finished the installation of pip, type this line in the command prompt:
 
    C:\> pip install sphinx
 
-After installation, type :command:`sphinx-build` on the command prompt.  If
+After installation, type :command:`sphinx-build -h` on the command prompt.  If
 everything worked fine, you will get a Sphinx version number and a list of
 options for this command.
 

doc/intl.rst

@@ -63,7 +63,7 @@ be translated you need to follow these instructions:
         msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
 
 * Set :confval:`locale_dirs` to ``["locale/"]``.
-* Set :confval:`language` to ``es`` (also possible via :option:`-D`).
+* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
 * Run your desired build.
 
 
@@ -88,14 +88,18 @@ This section describe a easy way to translate with sphinx-intl.
    :confval:`gettext_compact` is set to `False` (the Sphinx document is
    already configured as such).
 
-#. Extract document's translatable messages into pot files::
+#. Extract document's translatable messages into pot files:
+
+   .. code-block:: console
 
       $ make gettext
 
    As a result, many pot files are generated under ``_build/locale``
    directory.
 
-#. Setup/Update your `locale_dir`::
+#. Setup/Update your `locale_dir`:
+
+   .. code-block:: console
 
       $ sphinx-intl update -p _build/locale -l de -l ja
 
@@ -106,17 +110,25 @@ This section describe a easy way to translate with sphinx-intl.
 
 #. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
 
-#. Build mo files and make translated document.
+#. make translated document.
 
    You need a :confval:`language` parameter in ``conf.py`` or you may also
-   specify the parameter on the command line::
+   specify the parameter on the command line:
+
+   .. code-block:: console
 
-      $ sphinx-intl build
       $ make -e SPHINXOPTS="-D language='de'" html
 
 Congratulations! You got the translated documentation in the ``_build/html``
 directory.
 
+.. versionadded:: 1.3
+
+   sphinx-build that is invoked by make command will build po files into mo files.
+
+   If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
+   before make command.
+
 
 Translating
 ^^^^^^^^^^^
@@ -157,7 +169,7 @@ and to apply differences to translated po files.
 In order to apply the updating difference of a pot file to po file,
 use the :command:`sphinx-intl update` command.
 
-.. code-block:: bash
+.. code-block:: console
 
    $ sphinx-intl update -p _build/locale
 
@@ -176,7 +188,7 @@ easy to fetch and push translations.
 
    You need :command:`tx` command to upload resources (pot files).
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ pip install transifex-client
 
@@ -200,7 +212,7 @@ easy to fetch and push translations.
    This process will create ``.tx/config`` in the current directory, as well as
    a ``~/.transifexrc`` file that includes auth information.
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ tx init
       Creating .tx folder...
@@ -215,7 +227,7 @@ easy to fetch and push translations.
 
    Register pot files to ``.tx/config`` file:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ cd /your/document/root
       $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
@@ -223,7 +235,7 @@ easy to fetch and push translations.
 
    and upload pot files:
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ tx push -s
       Pushing translations for resource sphinx-document-test_1_0.builders:
@@ -242,7 +254,7 @@ easy to fetch and push translations.
 
    Get translated catalogs and build mo files (ex. for 'de'):
 
-   .. code-block:: bash
+   .. code-block:: console
 
       $ cd /your/document/root
       $ tx pull -l de
@@ -251,9 +263,10 @@ easy to fetch and push translations.
       ...
       Done.
 
-   Build po files into mo and make html::
+   Invoke make html:
+
+   .. code-block:: console
 
-      $ sphinx-intl build
       $ make -e SPHINXOPTS="-D language='de'" html
 
 
@@ -297,5 +310,5 @@ There is `sphinx translation page`_ for Sphinx-1.3 documentation.
 .. _`transifex-client`: https://pypi.python.org/pypi/transifex-client
 .. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
 .. _Transifex: https://www.transifex.com/
-.. _`sphinx translation page`: https://www.transifex.com/projects/p/sphinx-doc-1_3/
+.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc-1_3/
-.. _`Transifex Client v0.8 &mdash; Transifex documentation`: http://help.transifex.com/features/client/index.html
+.. _`Transifex Client v0.8 &mdash; Transifex documentation`: http://docs.transifex.com/developer/client/

doc/intro.rst

@@ -9,12 +9,12 @@ possibly subdirectories of docs in there as well), Sphinx can generate a
 nicely-organized arrangement of HTML files (in some other directory) for easy
 browsing and navigation.  But from the same source, it can also generate a
 LaTeX file that you can compile into a PDF version of the documents, or a
-PDF file directly using `rst2pdf <http://rst2pdf.googlecode.com>`_.
+PDF file directly using `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_.
 
 The focus is on hand-written documentation, rather than auto-generated API docs.
 Though there is support for that kind of docs as well (which is intended to be
 freely mixed with hand-written content), if you need pure API docs have a look
-at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
+at `Epydoc <http://epydoc.sourceforge.net/>`_, which also understands reST.
 
 For a great "introduction" to writing docs in general -- the whys and hows, see
 also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric
@@ -36,12 +36,12 @@ to reStructuredText/Sphinx from other documentation systems.
   code to convert Python-doc-style LaTeX markup to Sphinx reST.
 
 * Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx
-  markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
+  markup; it is at `Google Code <https://github.com/wojdyr/db2rst>`_.
 
 * Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
   to Sphinx: `odt2sphinx <https://pypi.python.org/pypi/odt2sphinx/>`_.
 
-* To convert different markups, `Pandoc <http://johnmacfarlane.net/pandoc/>`_ is
+* To convert different markups, `Pandoc <http://pandoc.org/>`_ is
   a very helpful tool.
 
 
@@ -59,8 +59,8 @@ docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.10
 or some (not broken) SVN trunk snapshot.  If you like to have source code
 highlighting support, you must also install the Pygments_ library.
 
-.. _reStructuredText: http://docutils.sf.net/rst.html
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _docutils: http://docutils.sf.net/
+.. _docutils: http://docutils.sourceforge.net/
 .. _Jinja2: http://jinja.pocoo.org/
 .. _Pygments: http://pygments.org/
 

doc/invocation.rst

@@ -6,7 +6,9 @@ Invocation of sphinx-quickstart
 ===============================
 
 The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
-It is called like this::
+It is called like this:
+
+   .. code-block:: console
 
      $ sphinx-quickstart [options] [projectdir]
 
@@ -100,9 +102,9 @@ Extension options
 
    Enable `sphinx.ext.coverage` extension.
 
-.. option:: --ext-pngmath
+.. option:: --ext-imgmath
 
-   Enable `sphinx.ext.pngmath` extension.
+   Enable `sphinx.ext.imgmath` extension.
 
 .. option:: --ext-mathjax
 
@@ -141,9 +143,11 @@ Invocation of sphinx-build
 ==========================
 
 The :program:`sphinx-build` script builds a Sphinx documentation set.  It is
-called like this::
+called like this:
 
-     $ sphinx-build [options] sourcedir builddir [filenames]
+.. code-block:: console
+
+    $ sphinx-build [options] sourcedir builddir [filenames]
 
 where *sourcedir* is the :term:`source directory`, and *builddir* is the
 directory in which you want to place the built documentation.  Most of the time,
@@ -380,9 +384,11 @@ Invocation of sphinx-apidoc
 ===========================
 
 The :program:`sphinx-apidoc` generates completely automatic API documentation
-for a Python package.  It is called like this::
+for a Python package.  It is called like this:
 
-     $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
+.. code-block:: console
+
+    $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
 
 where *packagedir* is the path to the package to document, and *outputdir* is
 the directory where the generated sources are placed.  Any *pathnames* given

doc/latex.rst

@@ -0,0 +1,151 @@
+.. highlightlang:: python
+
+.. _latex:
+
+LaTeX customization
+===================
+
+.. module:: latex
+   :synopsis: LaTeX specifics.
+
+The *latex* target does not (yet) benefit from pre-prepared themes like the
+*html* target does (see :doc:`theming`).
+
+There are two principal means of setting up customization:
+
+#. usage of the :ref:`latex-options` as described in :doc:`config`, particularly the
+   various keys of :confval:`latex_elements`, to modify the loaded packages,
+   for example::
+
+        'fontpkg':  '\\usepackage{times}',            # can load other font
+        'fncychap': '\\usepackage[Bjarne]{fncychap}', # can use other option
+
+   .. tip::
+
+      It is not mandatory to load *fncychap*. Naturally, without it and in
+      absence of further customizations, the chapter headings will revert to
+      LaTeX's default for the *report* class.
+
+#. usage of LaTeX ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
+   ``\definecolor`` to modify the defaults from package file :file:`sphinx.sty`
+   and class files :file:`sphinxhowto.cls` and :file:`sphinxmanual.cls`. If such
+   definitions are few, they can be located inside the ``'preamble'`` key of
+   :confval:`latex_elements`. In case of many it may prove more convenient to
+   assemble them into a specialized file :file:`customizedmacros.tex` and use::
+
+       'preamble': '\\makeatletter\\input{customizedmacros.tex}\\makeatother',
+
+   More advanced LaTeX users will set up a style file
+   :file:`customizedmacros.sty`, which can then be loaded via::
+
+       'preamble': '\\usepackage{customizedmacros}',
+
+   The :ref:`build configuration file <build-config>` file will then have its variable
+   :confval:`latex_additional_files` appropriately configured, for example::
+
+       latex_additional_files = ["customizedmacros.sty"]
+
+   Such *LaTeX Sphinx theme* files could possibly be contributed in the
+   future by advanced users for wider use.
+
+Let us illustrate here what can be modified by the second method.
+
+- text styling commands (they have one argument): ``\sphinx<foo>`` with
+  ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
+  ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
+  ``optional``. By default and for backwards compatibility the ``\sphinx<foo>``
+  expands to ``\<foo>`` hence the user can choose to customize rather the latter
+  (the non-prefixed macros will be left undefined if option
+  :confval:`latex_keep_old_macro_names` is set to ``False`` in :file:`conf.py`.)
+
+  .. versionchanged:: 1.4.5
+     use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
+     with user added packages. The LaTeX writer uses always the prefixed names.
+- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
+  ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
+  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
+  ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
+  ``abbreviation``, ``literalintitle``.
+
+  .. versionadded:: 1.5
+     earlier, the LaTeX writer used hard-coded ``\texttt``, ``\emph``, etc...
+- parameters for paragraph level environments: with ``<foo>`` one of
+  :dudir:`warning`, :dudir:`caution`, :dudir:`attention`,
+  :dudir:`danger`, :dudir:`error`, the colours
+  *sphinx<foo>bordercolor* and *sphinx<foo>bgcolor* can be
+  re-defined using ``\definecolor`` command. The
+  ``\sphinx<foo>border`` is a command (not a LaTeX length) which
+  specifies the thickness of the frame (default ``1pt``) and can be
+  ``\renewcommand`` 'd. The same applies with ``<foo>`` one of
+  :dudir:`note`, :dudir:`hint`, :dudir:`important`, :dudir:`tip`, but
+  the background colour is not implemented by the default environments
+  and the top and bottom rule thickness default is ``0.5pt``.
+
+  .. versionchanged:: 1.5
+     customizability of the parameters for each type of admonition.
+- paragraph level environments: for each admonition as in the previous item, the
+  used environment is named ``sphinx<foo>``. They may be ``\renewenvironment``
+  'd individually, and must then be defined with one argument (it is the heading
+  of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
+  English is the document language). Their default definitions use either the
+  *sphinxheavybox* (for the first listed directives) or the *sphinxlightbox*
+  environments, configured to use the parameters (colours, border thickness)
+  specific to each type, as mentioned in the previous item.
+
+  .. versionchanged:: 1.5
+     use of public environment names, separate customizability of the parameters.
+- the :dudir:`contents` directive (with ``:local:`` option) and the
+  :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
+  Its default definition obeys three LaTeX lengths (not commands) as parameters:
+  ``\sphinxshadowsep`` (distance from contents), ``\sphinxshadowsize`` (width of
+  lateral shadow), ``\sphinxshadowrule`` (thickness of the frame).
+
+  .. versionchanged:: 1.5
+     use of public names for the three lengths. The environment itself was
+     redefined to allow page breaks at release 1.4.2.
+- the literal blocks (:rst:dir:`code-block` directives, etc ...), are
+  implemented using ``sphinxVerbatim`` environment which is a wrapper of
+  ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
+  of the top caption and the wrapping of long lines, and a frame which allows
+  pagebreaks. The LaTeX lengths (not commands) ``\sphinxverbatimsep`` and
+  ``\sphinxverbatimborder`` customize the framing. Inside tables the used
+  environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
+  allows a caption).
+
+  .. versionchanged:: 1.5
+     ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning
+     which is the one of ``OriginalVerbatim`` too), and custom one is called
+     ``sphinxVerbatim``. Also, earlier version of Sphinx used
+     ``OriginalVerbatim`` inside tables (captions were lost, long code lines
+     were not wrapped), they now use ``sphinxVerbatimintable``.
+  .. versionadded:: 1.5
+     the two customizable lengths, the ``sphinxVerbatimintable``.
+- by default the Sphinx style file ``sphinx.sty`` includes the command
+  ``\fvset{fontsize=\small}`` as part of its configuration of
+  ``fancyvrb.sty``. The user may override this for example via
+  ``\fvset{fontsize=auto}`` which will use for listings the ambient
+  font size. Refer to ``fancyvrb.sty``'s documentation for further keys.
+
+  .. versionadded:: 1.5
+     formerly, the use of ``\small`` for code listings was not customizable.
+- miscellaneous colours: *TitleColor*, *InnerLinkColor*, *OuterLinkColor*,
+  *VerbatimColor* (this is a background colour), *VerbatimBorderColor*.
+- the ``\sphinxAtStartFootnote`` is inserted between footnote numbers and their
+  texts, by default it does ``\mbox{ }``.
+- use ``\sphinxSetHeaderFamily`` to set the font used by headings
+  (default is ``\sffamily\bfseries``).
+
+  .. versionadded:: 1.5
+- the section, subsection, ...  headings are set using  *titlesec*'s
+  ``\titleformat`` command.
+- for the ``'manual'`` class, the chapter headings can be customized using
+  *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. Or, if
+  the loading of this package has been removed from ``'fncychap'`` key, one can
+  use the *titlesec* ``\titleformat`` command.
+
+.. note::
+
+   It is impossible to revert or prevent the loading of a package that results
+   from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
+   file. Sphinx aims at loading as few packages as are really needed for its
+   default design.

doc/markup/code.rst

@@ -21,8 +21,8 @@ an "unused" primary prompt; this is an example of what *not* to do::
    2
    >>>
 
-Syntax highlighting is done with `Pygments <http://pygments.org>`_ (if it's
+Syntax highlighting is done with `Pygments <http://pygments.org>`_ and handled
-installed) and handled in a smart way:
+in a smart way:
 
 * There is a "highlighting language" for each source file.  Per default, this is
   ``'python'`` as the majority of files will have to highlight Python snippets,
@@ -77,7 +77,7 @@ installed) and handled in a smart way:
 Line numbers
 ^^^^^^^^^^^^
 
-If installed, Pygments can generate line numbers for code blocks.  For
+Pygments can generate line numbers for code blocks.  For
 automatically-highlighted blocks (those started by ``::``), line numbers must be
 switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
 option::

doc/markup/inline.rst

@@ -200,6 +200,12 @@ Referencing downloadable files
    The ``example.py`` file will be copied to the output directory, and a
    suitable link generated to it.
 
+   Not to show unavailable download links, you should wrap whole paragraphs that
+   have this role::
+
+      .. only:: builder_html
+
+         See :download:`this example script <../example.py>`.
 
 Cross-referencing figures by figure number
 ------------------------------------------
@@ -242,9 +248,8 @@ objects:
 
 .. rst:role:: option
 
-   A command-line option to an executable program.  The leading hyphen(s) must
+   A command-line option to an executable program.  This generates a link to
-   be included.  This generates a link to a :rst:dir:`option` directive, if it
+   a :rst:dir:`option` directive, if it exists.
-   exists.
 
 
 The following role creates a cross-reference to a term in a

doc/markup/misc.rst

@@ -191,7 +191,7 @@ Including content based on tags
 
    All tags must follow the standard Python identifier syntax as set out in
    the `Identifiers and keywords
-   <https://docs.python.org/reference/lexical_analysis.html#identifiers>`_
+   <https://docs.python.org/2/reference/lexical_analysis.html#identifiers>`_
    documentation.  That is, a tag expression may only consist of tags that
    conform to the syntax of Python variables.  In ASCII, this consists of the
    uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``

doc/markup/para.rst

@@ -183,6 +183,24 @@ Glossary
 
    (When the glossary is sorted, the first term determines the sort order.)
 
+   If you want to specify "grouping key" for general index entries, you can put a "key"
+   as "term : key". For example::
+
+      .. glossary::
+
+         term 1 : A
+         term 2 : B
+            Definition of both terms.
+
+   Note that "key" is used for grouping key as is.
+   The "key" isn't normalized; key "A" and "a" become different groups.
+   The whole characters in "key" is used instead of a first character; it is used for
+   "Combining Character Sequence" and "Surrogate Pairs" grouping key.
+
+   In i18n situation, you can specify "localized term : key" even if original text only
+   have "term" part. In this case, translated "localized term" will be categorized in
+   "key" group.
+
    .. versionadded:: 0.6
       You can now give the glossary directive a ``:sorted:`` flag that will
       automatically sort the entries alphabetically.
@@ -190,6 +208,8 @@ Glossary
    .. versionchanged:: 1.1
       Now supports multiple terms and inline markup in terms.
 
+   .. versionchanged:: 1.4
+      Index key for glossary term should be considered *experimental*.
 
 Grammar production displays
 ---------------------------

doc/markup/toctree.rst

@@ -85,7 +85,7 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Additional options**
 
-   You can use ``caption`` option to provide toctree caption and you can use
+   You can use ``caption`` option to provide a toctree caption and you can use
    ``name`` option to provide implicit target name that can be referenced by
    using :rst:role:`ref`::
 
@@ -223,11 +223,8 @@ The special document names (and pages generated for them) are:
 
 .. rubric:: Footnotes
 
-.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
+.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
-       whole table of contents will always be presented at the begin of the
+       directive in the document.
-       document, and its depth is controlled by the ``tocdepth`` counter, which
-       you can reset in your :confval:`latex_preamble` config value using
-       e.g. ``\setcounter{tocdepth}{2}``.
 
 .. [#] A note on available globbing syntax: you can use the standard shell
        constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that

doc/rest.rst

@@ -196,6 +196,8 @@ Use ```Link text <http://example.com/>`_`` for inline web links.  If the link
 text should be the web address, you don't need special markup at all, the parser
 finds links and mail addresses in ordinary text.
 
+.. important:: There must be a space between the link text and the opening \< for the URL.
+
 You can also separate the link and the target definition (:duref:`ref
 <hyperlink-targets>`), like this::
 
@@ -223,8 +225,10 @@ as long as the text::
    =================
 
 Normally, there are no heading levels assigned to certain characters as the
-structure is determined from the succession of headings.  However, for the
+structure is determined from the succession of headings.  However, this
-Python documentation, this convention is used which you may follow:
+convention is used in `Python's Style Guide for documentating
+<https://docs.python.org/devguide/documenting.html#style-guide>`_ which you may
+follow:
 
 * ``#`` with overline, for parts
 * ``*`` with overline, for chapters
@@ -359,8 +363,9 @@ directory on building (e.g. the ``_static`` directory for HTML output.)
 
 Interpretation of image size options (``width`` and ``height``) is as follows:
 if the size has no unit or the unit is pixels, the given size will only be
-respected for output channels that support pixels (i.e. not in LaTeX output).
+respected for output channels that support pixels. Other units (like ``pt``
-Other units (like ``pt`` for points) will be used for HTML and LaTeX output.
+for points) will be used for HTML and LaTeX output (the latter replaces ``pt``
+by ``bp`` as this is the TeX unit such that ``72bp=1in``).
 
 Sphinx extends the standard docutils behavior by allowing an asterisk for the
 extension::
@@ -382,6 +387,9 @@ Note that image file names should not contain spaces.
 .. versionchanged:: 0.6
    Image paths can now be absolute.
 
+.. versionchanged:: 1.5
+   latex target supports pixels (default is ``96px=1in``).
+
 
 Footnotes
 ---------

doc/templating.rst

@@ -399,3 +399,8 @@ are in HTML form), these variables are also available:
 
    * ``includehidden`` (``False`` by default): if true, the TOC tree will also
      contain hidden entries.
+
+.. data:: page_source_suffix
+
+   The suffix of the file that was rendered. Since we support a list of :confval:`source_suffix`,
+   this will allow you to properly link to the original source file.

doc/theming.rst

@@ -51,7 +51,7 @@ The third form provides your theme path dynamically to Sphinx if the
 called ``sphinx_themes`` in your setup.py file and write a ``get_path`` function
 that has to return the directory with themes in it::
 
-    // in your 'setup.py'
+    # 'setup.py'
 
     setup(
         ...
@@ -63,7 +63,7 @@ that has to return the directory with themes in it::
         ...
     )
 
-    // in 'your_package.py'
+    # 'your_package.py'
 
     from os import path
     package_dir = path.abspath(path.dirname(__file__))
@@ -81,7 +81,7 @@ that has to return the directory with themes in it::
 Builtin themes
 --------------
 
-.. cssclass:: right
+.. cssclass:: longtable
 
 +--------------------+--------------------+
 | **Theme overview** |                    |
@@ -154,9 +154,9 @@ These themes are:
 
   .. _Read the Docs Sphinx Theme: https://pypi.python.org/pypi/sphinx_rtd_theme
 
-* **classic** -- This is the classic theme, which looks like `the Python
+* **classic** -- This is the classic theme, which looks like `the Python 2
-  documentation <https://docs.python.org/>`_.  It can be customized via these
+  documentation <https://docs.python.org/2/>`_.  It can be customized via
-  options:
+  these options:
 
   - **rightsidebar** (true or false): Put the sidebar on the right side.
     Defaults to ``False``.
@@ -242,7 +242,7 @@ These themes are:
   *sidebarwidth*.
 
 * **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
-  <http://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
+  <https://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
   options are supported:
 
   - **full_logo** (true or false, default ``False``): If this is true, the
@@ -275,7 +275,7 @@ These themes are:
 
 .. versionchanged:: 1.3
    The 'default' theme has been renamed to 'classic'. 'default' is still
-   available, however it will emit notice a recommendation that using new
+   available, however it will emit a notice that it is an alias for the new
    'alabaster' theme.
 
 Creating themes

doc/tutorial.rst

@@ -122,8 +122,9 @@ this::
    $ sphinx-build -b html sourcedir builddir
 
 where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation.  The :option:`-b`
+directory in which you want to place the built documentation.
-option selects a builder; in this example Sphinx will build HTML files.
+The :option:`-b <sphinx-build -b>` option selects a builder; in this example
+Sphinx will build HTML files.
 
 |more| See :ref:`invocation` for all options that :program:`sphinx-build`
 supports.
@@ -299,12 +300,17 @@ features of intersphinx.
 More topics to be covered
 -------------------------
 
-- Other extensions (math, viewcode, doctest)
+- :doc:`Other extensions <extensions>`:
+
+  * :doc:`ext/math`,
+  * :doc:`ext/viewcode`,
+  * :doc:`ext/doctest`,
+  * ...
 - Static files
-- Selecting a theme
+- :doc:`Selecting a theme <theming>`
-- Templating
+- :ref:`Templating <templating>`
 - Using extensions
-- Writing extensions
+- :ref:`Writing extensions <dev-extensions>`
 
 
 .. rubric:: Footnotes

doc/web/quickstart.rst

@@ -135,7 +135,7 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
 
 .. note::
 
-   This only works works if your documentation is served from your
+   This only works if your documentation is served from your
    document root. If it is served from another directory, you will
    need to prefix the url route with that directory, and give the `docroot`
    keyword argument when creating the web support object::

ez_setup.py

@@ -1,332 +0,0 @@
-#!/usr/bin/env python
-"""Bootstrap setuptools installation
-
-To use setuptools in your package's setup.py, include this
-file in the same directory and add this to the top of your setup.py::
-
-    from ez_setup import use_setuptools
-    use_setuptools()
-
-To require a specific version of setuptools, set a download
-mirror, or use an alternate download directory, simply supply
-the appropriate options to ``use_setuptools()``.
-
-This file can also be run as a script to install or upgrade setuptools.
-"""
-import os
-import shutil
-import sys
-import tempfile
-import zipfile
-import optparse
-import subprocess
-import platform
-import textwrap
-import contextlib
-
-from distutils import log
-
-try:
-    from urllib.request import urlopen
-except ImportError:
-    from urllib2 import urlopen
-
-try:
-    from site import USER_SITE
-except ImportError:
-    USER_SITE = None
-
-DEFAULT_VERSION = "7.0"
-DEFAULT_URL = "https://pypi.python.org/packages/source/s/setuptools/"
-
-def _python_cmd(*args):
-    """
-    Return True if the command succeeded.
-    """
-    args = (sys.executable,) + args
-    return subprocess.call(args) == 0
-
-
-def _install(archive_filename, install_args=()):
-    with archive_context(archive_filename):
-        # installing
-        log.warn('Installing Setuptools')
-        if not _python_cmd('setup.py', 'install', *install_args):
-            log.warn('Something went wrong during the installation.')
-            log.warn('See the error message above.')
-            # exitcode will be 2
-            return 2
-
-
-def _build_egg(egg, archive_filename, to_dir):
-    with archive_context(archive_filename):
-        # building an egg
-        log.warn('Building a Setuptools egg in %s', to_dir)
-        _python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir)
-    # returning the result
-    log.warn(egg)
-    if not os.path.exists(egg):
-        raise IOError('Could not build the egg.')
-
-
-class ContextualZipFile(zipfile.ZipFile):
-    """
-    Supplement ZipFile class to support context manager for Python 2.6
-    """
-
-    def __enter__(self):
-        return self
-
-    def __exit__(self, type, value, traceback):
-        self.close()
-
-    def __new__(cls, *args, **kwargs):
-        """
-        Construct a ZipFile or ContextualZipFile as appropriate
-        """
-        if hasattr(zipfile.ZipFile, '__exit__'):
-            return zipfile.ZipFile(*args, **kwargs)
-        return super(ContextualZipFile, cls).__new__(cls)
-
-
-@contextlib.contextmanager
-def archive_context(filename):
-    # extracting the archive
-    tmpdir = tempfile.mkdtemp()
-    log.warn('Extracting in %s', tmpdir)
-    old_wd = os.getcwd()
-    try:
-        os.chdir(tmpdir)
-        with ContextualZipFile(filename) as archive:
-            archive.extractall()
-
-        # going in the directory
-        subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
-        os.chdir(subdir)
-        log.warn('Now working in %s', subdir)
-        yield
-
-    finally:
-        os.chdir(old_wd)
-        shutil.rmtree(tmpdir)
-
-
-def _do_download(version, download_base, to_dir, download_delay):
-    egg = os.path.join(to_dir, 'setuptools-%s-py%d.%d.egg'
-                       % (version, sys.version_info[0], sys.version_info[1]))
-    if not os.path.exists(egg):
-        archive = download_setuptools(version, download_base,
-                                      to_dir, download_delay)
-        _build_egg(egg, archive, to_dir)
-    sys.path.insert(0, egg)
-
-    # Remove previously-imported pkg_resources if present (see
-    # https://bitbucket.org/pypa/setuptools/pull-request/7/ for details).
-    if 'pkg_resources' in sys.modules:
-        del sys.modules['pkg_resources']
-
-    import setuptools
-    setuptools.bootstrap_install_from = egg
-
-
-def use_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
-        to_dir=os.curdir, download_delay=15):
-    to_dir = os.path.abspath(to_dir)
-    rep_modules = 'pkg_resources', 'setuptools'
-    imported = set(sys.modules).intersection(rep_modules)
-    try:
-        import pkg_resources
-    except ImportError:
-        return _do_download(version, download_base, to_dir, download_delay)
-    try:
-        pkg_resources.require("setuptools>=" + version)
-        return
-    except pkg_resources.DistributionNotFound:
-        return _do_download(version, download_base, to_dir, download_delay)
-    except pkg_resources.VersionConflict as VC_err:
-        if imported:
-            msg = textwrap.dedent("""
-                The required version of setuptools (>={version}) is not available,
-                and can't be installed while this script is running. Please
-                install a more recent version first, using
-                'easy_install -U setuptools'.
-
-                (Currently using {VC_err.args[0]!r})
-                """).format(VC_err=VC_err, version=version)
-            sys.stderr.write(msg)
-            sys.exit(2)
-
-        # otherwise, reload ok
-        del pkg_resources, sys.modules['pkg_resources']
-        return _do_download(version, download_base, to_dir, download_delay)
-
-def _clean_check(cmd, target):
-    """
-    Run the command to download target. If the command fails, clean up before
-    re-raising the error.
-    """
-    try:
-        subprocess.check_call(cmd)
-    except subprocess.CalledProcessError:
-        if os.access(target, os.F_OK):
-            os.unlink(target)
-        raise
-
-def download_file_powershell(url, target):
-    """
-    Download the file at url to target using Powershell (which will validate
-    trust). Raise an exception if the command cannot complete.
-    """
-    target = os.path.abspath(target)
-    ps_cmd = (
-        "[System.Net.WebRequest]::DefaultWebProxy.Credentials = "
-        "[System.Net.CredentialCache]::DefaultCredentials; "
-        "(new-object System.Net.WebClient).DownloadFile(%(url)r, %(target)r)"
-        % vars()
-    )
-    cmd = [
-        'powershell',
-        '-Command',
-        ps_cmd,
-    ]
-    _clean_check(cmd, target)
-
-def has_powershell():
-    if platform.system() != 'Windows':
-        return False
-    cmd = ['powershell', '-Command', 'echo test']
-    with open(os.path.devnull, 'wb') as devnull:
-        try:
-            subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
-        except Exception:
-            return False
-    return True
-
-download_file_powershell.viable = has_powershell
-
-def download_file_curl(url, target):
-    cmd = ['curl', url, '--silent', '--output', target]
-    _clean_check(cmd, target)
-
-def has_curl():
-    cmd = ['curl', '--version']
-    with open(os.path.devnull, 'wb') as devnull:
-        try:
-            subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
-        except Exception:
-            return False
-    return True
-
-download_file_curl.viable = has_curl
-
-def download_file_wget(url, target):
-    cmd = ['wget', url, '--quiet', '--output-document', target]
-    _clean_check(cmd, target)
-
-def has_wget():
-    cmd = ['wget', '--version']
-    with open(os.path.devnull, 'wb') as devnull:
-        try:
-            subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
-        except Exception:
-            return False
-    return True
-
-download_file_wget.viable = has_wget
-
-def download_file_insecure(url, target):
-    """
-    Use Python to download the file, even though it cannot authenticate the
-    connection.
-    """
-    src = urlopen(url)
-    try:
-        # Read all the data in one block.
-        data = src.read()
-    finally:
-        src.close()
-
-    # Write all the data in one block to avoid creating a partial file.
-    with open(target, "wb") as dst:
-        dst.write(data)
-
-download_file_insecure.viable = lambda: True
-
-def get_best_downloader():
-    downloaders = (
-        download_file_powershell,
-        download_file_curl,
-        download_file_wget,
-        download_file_insecure,
-    )
-    viable_downloaders = (dl for dl in downloaders if dl.viable())
-    return next(viable_downloaders, None)
-
-def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
-        to_dir=os.curdir, delay=15, downloader_factory=get_best_downloader):
-    """
-    Download setuptools from a specified location and return its filename
-
-    `version` should be a valid setuptools version number that is available
-    as an sdist for download under the `download_base` URL (which should end
-    with a '/'). `to_dir` is the directory where the egg will be downloaded.
-    `delay` is the number of seconds to pause before an actual download
-    attempt.
-
-    ``downloader_factory`` should be a function taking no arguments and
-    returning a function for downloading a URL to a target.
-    """
-    # making sure we use the absolute path
-    to_dir = os.path.abspath(to_dir)
-    zip_name = "setuptools-%s.zip" % version
-    url = download_base + zip_name
-    saveto = os.path.join(to_dir, zip_name)
-    if not os.path.exists(saveto):  # Avoid repeated downloads
-        log.warn("Downloading %s", url)
-        downloader = downloader_factory()
-        downloader(url, saveto)
-    return os.path.realpath(saveto)
-
-def _build_install_args(options):
-    """
-    Build the arguments to 'python setup.py install' on the setuptools package
-    """
-    return ['--user'] if options.user_install else []
-
-def _parse_args():
-    """
-    Parse the command line for options
-    """
-    parser = optparse.OptionParser()
-    parser.add_option(
-        '--user', dest='user_install', action='store_true', default=False,
-        help='install in user site package (requires Python 2.6 or later)')
-    parser.add_option(
-        '--download-base', dest='download_base', metavar="URL",
-        default=DEFAULT_URL,
-        help='alternative URL from where to download the setuptools package')
-    parser.add_option(
-        '--insecure', dest='downloader_factory', action='store_const',
-        const=lambda: download_file_insecure, default=get_best_downloader,
-        help='Use internal, non-validating downloader'
-    )
-    parser.add_option(
-        '--version', help="Specify which version to download",
-        default=DEFAULT_VERSION,
-    )
-    options, args = parser.parse_args()
-    # positional arguments are ignored
-    return options
-
-def main():
-    """Install or upgrade setuptools and EasyInstall"""
-    options = _parse_args()
-    archive = download_setuptools(
-        version=options.version,
-        download_base=options.download_base,
-        downloader_factory=options.downloader_factory,
-    )
-    return _install(archive, _build_install_args(options))
-
-if __name__ == '__main__':
-    sys.exit(main())

setup.cfg

@@ -25,5 +25,5 @@ universal = 1
 
 [flake8]
 max-line-length=95
-ignore=E113,E116,E221,E226,E241,E251
+ignore=E113,E116,E221,E226,E241,E251,E901
-exclude=ez_setup.py,utils/*,tests/*,build/*,sphinx/search/*,sphinx/pycode/pgen2/*
+exclude=tests/*,build/*,sphinx/search/*,sphinx/pycode/pgen2/*,doc/ext/example*.py

setup.py

@@ -1,14 +1,10 @@
 # -*- coding: utf-8 -*-
-try:
+from setuptools import setup, find_packages
-    from setuptools import setup, find_packages
-except ImportError:
-    import ez_setup
-    ez_setup.use_setuptools()
-    from setuptools import setup, find_packages
 
 import os
 import sys
 from distutils import log
+from distutils.cmd import Command
 
 import sphinx
 
@@ -46,19 +42,20 @@ if sys.version_info < (2, 6) or (3, 0) <= sys.version_info < (3, 3):
     sys.exit(1)
 
 requires = [
-    'six>=1.4',
+    'six>=1.5',
     'Jinja2>=2.3',
     'Pygments>=2.0',
     'docutils>=0.11',
     'snowballstemmer>=1.1',
-    'babel>=1.3',
+    'babel>=1.3,!=2.0',
     'alabaster>=0.7,<0.8',
-    'sphinx_rtd_theme>=0.1,<0.2',
+    'imagesize',
+    'requests',
 ]
 extras_require = {
     # Environment Marker works for wheel 0.24 or later
     ':sys_platform=="win32"': [
-        'colorama',
+        'colorama>=0.3.5',
     ],
     'websupport': [
         'sqlalchemy>=0.9',
@@ -68,12 +65,13 @@ extras_require = {
         'nose',
         'mock',  # it would be better for 'test:python_version in "2.6,2.7"'
         'simplejson',  # better: 'test:platform_python_implementation=="PyPy"'
+        'html5lib',
     ],
 }
 
 # for sdist installation with pip-1.5.6
 if sys.platform == 'win32':
-    requires.append('colorama')
+    requires.append('colorama>=0.3.5')
 
 # Provide a "compile_catalog" command that also creates the translated
 # JavaScript files if Babel is available.
@@ -102,6 +100,13 @@ else:
         def run(self):
             compile_catalog.run(self)
 
+            if isinstance(self.domain, list):
+                for domain in self.domain:
+                    self._run_domain_js(domain)
+            else:
+                self._run_domain_js(self.domain)
+
+        def _run_domain_js(self, domain):
             po_files = []
             js_files = []
 
@@ -110,20 +115,20 @@ else:
                     po_files.append((self.locale,
                                      os.path.join(self.directory, self.locale,
                                                   'LC_MESSAGES',
-                                                  self.domain + '.po')))
+                                                  domain + '.po')))
                     js_files.append(os.path.join(self.directory, self.locale,
                                                  'LC_MESSAGES',
-                                                 self.domain + '.js'))
+                                                 domain + '.js'))
                 else:
                     for locale in os.listdir(self.directory):
                         po_file = os.path.join(self.directory, locale,
                                                'LC_MESSAGES',
-                                               self.domain + '.po')
+                                               domain + '.po')
                         if os.path.exists(po_file):
                             po_files.append((locale, po_file))
                             js_files.append(os.path.join(self.directory, locale,
                                                          'LC_MESSAGES',
-                                                         self.domain + '.js'))
+                                                         domain + '.js'))
             else:
                 po_files.append((self.locale, self.input_file))
                 if self.output_file:
@@ -131,14 +136,11 @@ else:
                 else:
                     js_files.append(os.path.join(self.directory, self.locale,
                                                  'LC_MESSAGES',
-                                                 self.domain + '.js'))
+                                                 domain + '.js'))
 
             for js_file, (locale, po_file) in zip(js_files, po_files):
-                infile = open(po_file, 'r')
+                with open(po_file, 'r') as infile:
-                try:
                     catalog = read_po(infile, locale)
-                finally:
-                    infile.close()
 
                 if catalog.fuzzy and not self.use_fuzzy:
                     continue
@@ -155,21 +157,43 @@ else:
                             msgid = msgid[0]
                         jscatalog[msgid] = message.string
 
-                outfile = open(js_file, 'wb')
+                with open(js_file, 'wb') as outfile:
-                try:
                     outfile.write('Documentation.addTranslations(')
                     dump(dict(
                         messages=jscatalog,
                         plural_expr=catalog.plural_expr,
                         locale=str(catalog.locale)
-                    ), outfile)
+                    ), outfile, sort_keys=True)
                     outfile.write(');')
-                finally:
-                    outfile.close()
 
     cmdclass['compile_catalog'] = compile_catalog_plusjs
 
 
+class CompileGrammarCommand(Command):
+    description = 'Compile python grammar file for pycode'
+    user_options = []
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        from sphinx.pycode.pgen2.driver import compile_grammar
+
+        compile_grammar('sphinx/pycode/Grammar-py2.txt')
+        print('sphinx/pycode/Grammar-py2.txt ... done')
+
+        compile_grammar('sphinx/pycode/Grammar-py3.txt')
+        print('sphinx/pycode/Grammar-py3.txt ... done')
+
+    def sub_commands(self):
+        pass
+
+cmdclass['compile_grammar'] = CompileGrammarCommand
+
+
 setup(
     name='Sphinx',
     version=sphinx.__version__,

sphinx-apidoc.py

@@ -4,7 +4,7 @@
     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

sphinx-autogen.py

@@ -4,7 +4,7 @@
     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

sphinx-build.py

@@ -4,7 +4,7 @@
     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 

sphinx-quickstart.py

@@ -4,7 +4,7 @@
     Sphinx - Python documentation toolchain
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """