==========================
Incompatible changes
--------------------
* Support for domains has been added. A domain is a collection of
directives and roles that all describe objects belonging together,
e.g. elements of a programming language. A few builtin domains are
provided:
- Python
- C
- C++
- JavaScript
- reStructuredText
* The old markup for defining and linking to C directives is now
deprecated. It will not work anymore in future versions without
activating the ``oldcmarkup`` extension; in Sphinx
1.0, it is activated by default.
* Removed support for old dependency versions; requirements are now:
- Docutils >= 0.5
- Jinja2 >= 2.2
* Removed deprecated elements:
- ``exclude_dirs`` config value
- ``sphinx.builder`` module
Features added
--------------
* General:
- Added a "nitpicky" mode that emits warnings for all missing
references. It is activated by the :option:`sphinx-build -n` command-line
switch or the :confval:`nitpicky` config value.
- Added ``latexpdf`` target in quickstart Makefile.
* Markup:
- The ``menuselection`` and ``guilabel`` roles now
support ampersand accelerators.
- New more compact doc field syntax is now recognized: ``:param type
name: description``.
- Added ``tab-width`` option to ``literalinclude`` directive.
- Added ``titlesonly`` option to :rst:dir:`toctree` directive.
- Added the ``prepend`` and ``append`` options to the
``literalinclude`` directive.
- 284: All docinfo metadata is now put into the document metadata, not
just the author.
- The ``ref`` role can now also reference tables by caption.
- The :dudir:`include` directive now supports absolute paths, which
are interpreted as relative to the source directory.
- In the Python domain, references like ``:func:`.name now look for
matching names with any prefix if no direct match is found.
* Configuration:
- Added ``rst_prolog`` config value.
- Added ``html_secnumber_suffix`` config value to control
section numbering format.
- Added ``html_compact_lists`` config value to control
Docutils' compact lists feature.
- The ``html_sidebars`` config value can now contain patterns
as keys, and the values can be lists that explicitly select which
sidebar templates should be rendered. That means that the builtin
sidebar contents can be included only selectively.
- ``html_static_path`` can now contain single file entries.
- The new universal config value ``exclude_patterns`` makes the
old ``unused_docs``, ``exclude_trees`` and
``exclude_dirnames`` obsolete.
- Added ``html_output_encoding`` config value.
- Added the ``latex_docclass`` config value and made the
"twoside" documentclass option overridable by "oneside".
- Added the ``trim_doctest_flags`` config value, which is true
by default.
- Added ``html_show_copyright`` config value.
- Added ``latex_show_pagerefs and ``latex_show_urls``
config values.
- The behavior of ``html_file_suffix changed slightly: the
empty string now means "no suffix" instead of "default suffix", use
``None`` for "default suffix".
* New builders:
- Added a builder for the Epub format.
- Added a builder for manual pages.
- Added a single-file HTML builder.
* HTML output:
- Inline roles now get a CSS class with their name, allowing styles to
customize their appearance. Domain-specific roles get two classes,
``domain`` and ``domain-rolename``.
- References now get the class ``internal`` if they are internal to
the whole project, as opposed to internal to the current page.
- External references can be styled differently with the new
``externalrefs`` theme option for the default theme.
- In the default theme, the sidebar can experimentally now be made
collapsible using the new ``collapsiblesidebar`` theme option.
- 129: Toctrees are now wrapped in a ``div`` tag with class
``toctree-wrapper`` in HTML output.
- The :data:`toctree` callable in templates now has a ``maxdepth``
keyword argument to control the depth of the generated tree.
- The :data:`toctree` callable in templates now accepts a
``titles_only`` keyword argument.
- Added ``htmltitle`` block in layout template.
- In the JavaScript search, allow searching for object names including
the module name, like ``sys.argv``.
- Added new theme ``haiku``, inspired by the Haiku OS user guide.
- Added new theme ``nature``.
- Added new theme ``agogo``, created by Andi Albrecht.
- Added new theme ``scrolls``, created by Armin Ronacher.
- 193: Added a ``visitedlinkcolor`` theme option to the default
theme.
- 322: Improved responsiveness of the search page by loading the
search index asynchronously.
* Extension API:
- Added :event:`html-collect-pages`.
- Added ``needs_sphinx`` config value and
:meth:`~sphinx.application.Sphinx.require_sphinx` application API
method.
- 200: Added :meth:`!add_stylesheet`
application API method.
* Extensions:
- Added the :mod:`~sphinx.ext.viewcode` extension.
- Added the :mod:`~sphinx.ext.extlinks` extension.
- Added support for source ordering of members in autodoc, with
``autodoc_member_order = 'bysource'``.
- Added ``autodoc_default_flags`` config value, which can be
used to select default flags for all autodoc directives.
- Added a way for intersphinx to refer to named labels in other
projects, and to specify the project you want to link to.
- 280: Autodoc can now document instance attributes assigned in
``__init__`` methods.
- Many improvements and fixes to the :mod:`~sphinx.ext.autosummary`
extension, thanks to Pauli Virtanen.
- 309: The :mod:`~sphinx.ext.graphviz` extension can now output SVG
instead of PNG images, controlled by the
``graphviz_output_format`` config value.
- Added ``alt`` option to :rst:dir:`graphviz` extension directives.
- Added ``exclude`` argument to :func:`.autodoc.between`.
* Translations:
- Added Croatian translation, thanks to Bojan Mihelač.
- Added Turkish translation, thanks to Firat Ozgul.
- Added Catalan translation, thanks to Pau Fernández.
- Added simplified Chinese translation.
- Added Danish translation, thanks to Hjorth Larsen.
- Added Lithuanian translation, thanks to Dalius Dobravolskas.
* Bugs fixed:
- 445: Fix links to result pages when using the search function
of HTML built with the ``dirhtml`` builder.
- 444: In templates, properly re-escape values treated with the
"striptags" Jinja filter.