===================================
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
<https://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 forcedly 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 overridden by code-block's in LaTeX. Thanks to
jfbu.
* Fix unpack warning if combined 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: Reduce 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.