==========================
New features added
------------------
* Incompatible changes:
- Templating now requires the Jinja2 library, which is an enhanced
version of the old Jinja1 engine. Since the syntax and semantic
is largely the same, very few fixes should be necessary in
custom templates.
- The "document" div tag has been moved out of the ``layout.html``
template's "document" block, because the closing tag was already
outside. If you overwrite this block, you need to remove your
"document" div tag as well.
- The ``autodoc_skip_member`` event now also gets to decide
whether to skip members whose name starts with underscores.
Previously, these members were always automatically skipped.
Therefore, if you handle this event, add something like this
to your event handler to restore the old behavior::
if name.startswith('_'):
return True
* Theming support, see the new section in the documentation.
* Markup:
- Due to popular demand, added a ``:doc:`` role which directly
links to another document without the need of creating a
label to which a ``:ref:`` could link to.
- 4: Added a ``:download:`` role that marks a non-document file
for inclusion into the HTML output and links to it.
- Added an ``only`` directive that can selectively include text
based on enabled "tags". Tags can be given on the command
line. Also, the current builder output format (e.g. "html" or
"latex") is always a defined tag.
- 10: Added HTML section numbers, enabled by giving a
``:numbered:`` flag to the ``toctree`` directive.
- 114: Added an ``abbr`` role to markup abbreviations and
acronyms.
- The ``literalinclude`` directive now supports several more
options, to include only parts of a file.
- The ``toctree`` directive now supports a ``:hidden:`` flag,
which will prevent links from being generated in place of
the directive -- this allows you to define your document
structure, but place the links yourself.
- 123: The ``glossary`` directive now supports a ``:sorted:``
flag that sorts glossary entries alphabetically.
- Paths to images, literal include files and download files
can now be absolute (like ``/images/foo.png``). They are
treated as relative to the top source directory.
- 52: There is now a ``hlist`` directive, creating a compact
list by placing distributing items into multiple columns.
- 77: If a description environment with info field list only
contains one ``:param:`` entry, no bullet list is generated.
- 6: Don't generate redundant ``<ul>`` for top-level TOC tree
items, which leads to a visual separation of TOC entries.
- 23: Added a ``classmethod`` directive along with ``method``
and ``staticmethod``.
- Scaled images now get a link to the unscaled version.
- SVG images are now supported in HTML (via ``<object>`` and
``<embed>`` tags).
- Added a ``toctree`` callable to the templates, and the ability
to include external links in toctrees. The 'collapse' keyword
argument indicates whether or not to only display subitems of
the current page. (Defaults to ``True``.)
* Configuration:
- The new config value ``rst_epilog`` can contain reST that is
appended to each source file that is read. This is the right
place for global substitutions.
- The new ``html_add_permalinks`` config value can be used to
switch off the generated "paragraph sign" permalinks for each
heading and definition environment.
- The new ``html_show_sourcelink`` config value can be used to
switch off the links to the reST sources in the sidebar.
- The default value for ``htmlhelp_basename`` is now the project
title, cleaned up as a filename.
- The new ``modindex_common_prefix`` config value can be used to
ignore certain package names for module index sorting.
- The new ``trim_footnote_reference_space`` config value mirrors
the Docutils config value of the same name and removes the
space before a footnote reference that is necessary for reST
to recognize the reference.
- The new ``latex_additional_files`` config value can be used to
copy files (that Sphinx doesn't copy automatically, e.g. if they
are referenced in custom LaTeX added in ``latex_elements``) to
the build directory.
* Builders:
- The HTML builder now stores a small file named ``.buildinfo`` in
its output directory. It stores a hash of config values that
can be used to determine if a full rebuild needs to be done (e.g.
after changing ``html_theme``).
- New builder for Qt help collections, by Antonio Valentino.
- The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates
a separate directory for every page, and places the page there
in a file called ``index.html``. Therefore, page URLs and links
don't need to contain ``.html``.
- The new ``html_link_suffix`` config value can be used to select
the suffix of generated links between HTML files.
- 96: The LaTeX builder now supports figures wrapped by text, when
using the ``figwidth`` option and right/left alignment.
* New translations:
- Italian by Sandro Dentella.
- Ukrainian by Petro Sasnyk.
- Finnish by Jukka Inkeri.
- Russian by Alexander Smishlajev.
* Extensions and API:
- New ``graphviz`` extension to embed graphviz graphs.
- New ``inheritance_diagram`` extension to embed... inheritance
diagrams!
- New ``autosummary`` extension that generates summaries of
modules and automatic documentation of modules.
- Autodoc now has a reusable Python API, which can be used to
create custom types of objects to auto-document (e.g. Zope
interfaces). See also ``Sphinx.add_autodocumenter()``.
- Autodoc now handles documented attributes.
- Autodoc now handles inner classes and their methods.
- Autodoc can document classes as functions now if explicitly
marked with ``autofunction``.
- Autodoc can now exclude single members from documentation
via the ``exclude-members`` option.
- Autodoc can now order members either alphabetically (like
previously) or by member type; configurable either with the
config value ``autodoc_member_order`` or a ``member-order``
option per directive.
- The function ``Sphinx.add_directive()`` now also supports
Docutils 0.5-style directive classes. If they inherit from
``sphinx.util.compat.Directive``, they also work with
Docutils 0.4.
- There is now a ``Sphinx.add_lexer()`` method to be able to use
custom Pygments lexers easily.
- There is now ``Sphinx.add_generic_role()`` to mirror the
Docutils' own function.
* Other changes:
- Config overrides for single dict keys can now be given on the
command line.
- There is now a ``doctest_global_setup`` config value that can
be used to give setup code for all doctests in the documentation.
- Source links in HTML are now generated with ``rel="nofollow"``.
- Quickstart can now generate a Windows ``make.bat`` file.
- 62: There is now a ``-w`` option for sphinx-build that writes
warnings to a file, in addition to stderr.
- There is now a ``-W`` option for sphinx-build that turns warnings
into errors.