Sphinx

===============================================

New features added
------------------

* Markup features:

- Citations are now global: all citation defined in any file can be
referenced from any file. Citations are collected in a bibliography
for LaTeX output.

- Footnotes are now properly handled in the LaTeX builder: they appear
at the location of the footnote reference in text, not at the end of
a section. Thanks to Andrew McNamara for the initial patch.

- "System Message" warnings are now automatically removed from the
built documentation, and only written to stderr. If you want the
old behavior, set the new config value ``keep_warnings`` to ``True``.

- Glossary entries are now automatically added to the index.

- Figures with captions can now be referred to like section titles,
using the ``:ref:`` role without an explicit link text.

- Added ``cmember`` role for consistency.

- Lists enumerated by letters or roman numerals are now handled like in
standard reST.

- The ``seealso`` directive can now also be given arguments, as a short
form.

- You can now document several programs and their options with the
new ``program`` directive.

* HTML output and templates:

- Incompatible change: The "root" relation link (top left in the
relbar) now points to the ``master_doc`` by default, no longer to a
document called "index". The old behavior, while useful in some
situations, was somewhat unexpected. Override the "rootrellink"
block in the template to customize where it refers to.

- The JavaScript search now searches for objects before searching in
the full text.

- TOC tree entries now have CSS classes that make it possible to
style them depending on their depth.

- Highlighted code blocks now have CSS classes that make it possible
to style them depending on their language.

- HTML ``<meta>`` tags via the Docutils :dudir:`meta` directive are now
supported.

- ``SerializingHTMLBuilder`` was added as new abstract builder that
can be subclassed to serialize build HTML in a specific format. The
``PickleHTMLBuilder`` is a concrete subclass of it that uses pickle
as serialization implementation.

- ``JSONHTMLBuilder`` was added as another ``SerializingHTMLBuilder``
subclass that dumps the generated HTML into JSON files for further
processing.

- The ``rellinks`` block in the layout template is now called
``linktags`` to avoid confusion with the relbar links.

- The HTML builders have two additional attributes now that can be
used to disable the anchor-link creation after headlines and
definition links.

- Only generate a module index if there are some modules in the
documentation.

* New and changed config values:

- Added support for internationalization in generated text with the
``language`` and ``locale_dirs`` config values. Many thanks to
language contributors:

* Horst Gutmann -- German
* Pavel Kosina -- Czech
* David Larlet -- French
* Michał Kandulski -- Polish
* Yasushi Masuda -- Japanese
* Guillem Borrell -- Spanish
* Luc Saffre and Peter Bertels -- Dutch
* Fred Lin -- Traditional Chinese
* Roger Demetrescu -- Brazilian Portuguese
* Rok Garbas -- Slovenian

- The new config value ``highlight_language`` set a global default for
highlighting. When ``'python3'`` is selected, console output blocks
are recognized like for ``'python'``.

- Exposed Pygments' lexer guessing as a highlight "language" ``guess``.

- The new config value ``latex_elements`` allows to override all LaTeX
snippets that Sphinx puts into the generated .tex file by default.

- Added ``exclude_dirnames`` config value that can be used to exclude
e.g. CVS directories from source file search.

- Added ``source_encoding`` config value to select input encoding.

* Extensions:

- The new extensions ``sphinx.ext.jsmath`` and ``sphinx.ext.pngmath``
provide math support for both HTML and LaTeX builders.

- The new extension ``sphinx.ext.intersphinx`` half-automatically
creates links to Sphinx documentation of Python objects in other
projects.

- The new extension ``sphinx.ext.todo`` allows the insertion of
"To do" directives whose visibility in the output can be toggled.
It also adds a directive to compile a list of all todo items.

- sphinx.ext.autodoc has a new event ``autodoc-process-signature``
that allows tuning function signature introspection.

- sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows
tuning which members are included in the generated content.

- Respect ``__all__`` when autodocumenting module members.

- The ``automodule`` directive now supports the ``synopsis``,
``deprecated`` and ``platform`` options.

* Extension API:

- ``Sphinx.add_node()`` now takes optional visitor methods for the
HTML, LaTeX and text translators; this prevents having to manually
patch the classes.

- Added ``Sphinx.add_javascript()`` that adds scripts to load in the
default HTML template.

- Added new events: ``source-read``, ``env-updated``,
``env-purge-doc``, ``missing-reference``, ``build-finished``.

* Other changes:

- Added a command-line switch ``-Q``: it will suppress warnings.

- Added a command-line switch ``-A``: it can be used to supply
additional values into the HTML templates.

- Added a command-line switch ``-C``: if it is given, no configuration
file ``conf.py`` is required.

- Added a distutils command ``build_sphinx``: When Sphinx is installed,
you can call ``python setup.py build_sphinx`` for projects that have
Sphinx documentation, which will build the docs and place them in
the standard distutils build directory.

- In quickstart, if the selected root path already contains a Sphinx
project, complain and abort.

Bugs fixed
----------

* 51: Escape configuration values placed in HTML templates.

* 44: Fix small problems in HTML help index generation.

* Fix LaTeX output for line blocks in tables.

* 38: Fix "illegal unit" error when using pixel image widths/heights.

* Support table captions in LaTeX output.

* 39: Work around a bug in Jinja that caused "<generator ...>" to be
emitted in HTML output.

* Fix a problem with module links not being generated in LaTeX output.

* Fix the handling of images in different directories.

* 29: Support option lists in the text writer. Make sure that dashes
introducing long option names are not contracted to en-dashes.

* Support the "scale" option for images in HTML output.

* 25: Properly escape quotes in HTML help attribute values.

* Fix LaTeX build for some description environments with ``:noindex:``.

* 24: Don't crash on uncommon casing of role names (like ``:Class:``).

* Only output ANSI colors on color terminals.

* Update to newest fncychap.sty, to fix problems with non-ASCII
characters at the start of chapter titles.

* Fix a problem with index generation in LaTeX output, caused by
hyperref not being included last.

* Don't disregard return annotations for functions without any parameters.

* Don't throw away labels for code blocks.

===========================

* Fix a bug in autodoc with directly given autodoc members.

* Fix a bug in autodoc that would import a module twice, once as
"module", once as "module.".

* Fix a bug in the HTML writer that created duplicate ``id``
attributes for section titles with Docutils 0.5.

* Properly call ``super()`` in overridden blocks in templates.

* Add a fix when using XeTeX.

* Unify handling of LaTeX escaping.

* Rebuild everything when the ``extensions`` config value changes.

* Don't try to remove a nonexisting static directory.

* Fix an indentation problem in production lists.

* Fix encoding handling for literal include files: ``literalinclude``
now has an ``encoding`` option that defaults to UTF-8.

* Fix the handling of non-ASCII characters entered in quickstart.

* Fix a crash with nonexisting image URIs.

============================

* Fix rendering of the ``samp`` role in HTML.

* Fix a bug with LaTeX links to headings leading to a wrong page.

* Reread documents with globbed toctrees when source files are
added or removed.

* Add a missing parameter to PickleHTMLBuilder.handle_page().

* Put inheritance info always on its own line.

* Don't automatically enclose code with whitespace in it in quotes;
only do this for the ``samp`` role.

* autodoc now emits a more precise error message when a module
can't be imported or an attribute can't be found.

* The JavaScript search now uses the correct file name suffix when
referring to found items.

* The automodule directive now accepts the ``inherited-members``
and ``show-inheritance`` options again.

* You can now rebuild the docs normally after relocating the source
and/or doctree directory.

===========================

* Added sub-/superscript node handling to TextBuilder.

* Label names in references are now case-insensitive, since reST
label names are always lowercased.

* Fix linkcheck builder crash for malformed URLs.

* Add compatibility for admonitions and Docutils 0.5.

* Remove the silly restriction on "rubric" in the LaTeX writer: you
can now write arbitrary "rubric" directives, and only those with
a title of "Footnotes" will be ignored.

* Copy the HTML logo to the output ``_static`` directory.

* Fix LaTeX code for modules with underscores in names and platforms.

* Fix a crash with nonlocal image URIs.

* Allow the usage of :noindex: in ``automodule`` directives, as
documented.

* Fix the ``delete()`` docstring processor function in autodoc.

* Fix warning message for nonexisting images.

* Fix JavaScript search in Internet Explorer.

==========================

New features added
------------------

* ``tocdepth`` can be given as a file-wide metadata entry, and
specifies the maximum depth of a TOC of this file.

* The new config value ``default_role`` can be used to select the
default role for all documents.

* Sphinx now interprets field lists with fields like ``:param foo:``
in description units.

* The new ``staticmethod`` directive can be used to mark methods as
static methods.

* HTML output:

- The "previous" and "next" links have a more logical structure, so
that by following "next" links you can traverse the entire TOC
tree.

- The new event ``html-page-context`` can be used to include custom
values into the context used when rendering an HTML template.

- Document metadata is now in the default template context, under
the name ``metadata``.

- The new config value ``html_favicon`` can be used to set a favicon
for the HTML output. Thanks to Sebastian Wiesner.

- The new config value ``html_use_index`` can be used to switch index
generation in HTML documents off.

- The new config value ``html_split_index`` can be used to create
separate index pages for each letter, to be used when the complete
index is too large for one page.

- The new config value ``html_short_title`` can be used to set a
shorter title for the documentation which is then used in the
navigation bar.

- The new config value ``html_show_sphinx`` can be used to control
whether a link to Sphinx is added to the HTML footer.

- The new config value ``html_file_suffix`` can be used to set the
HTML file suffix to e.g. ``.xhtml``.

- The directories in the ``html_static_path`` can now contain
subdirectories.

- The module index now isn't collapsed if the number of submodules
is larger than the number of toplevel modules.

* The image directive now supports specifying the extension as ``.*``,
which makes the builder select the one that matches best. Thanks to
Sebastian Wiesner.

* The new config value ``exclude_trees`` can be used to exclude whole
subtrees from the search for source files.

* Defaults for configuration values can now be callables, which allows
dynamic defaults.

* The new TextBuilder creates plain-text output.

* Python 3-style signatures, giving a return annotation via ``->``,
are now supported.

* Extensions:

- The autodoc extension now offers a much more flexible way to
manipulate docstrings before including them into the output, via
the new ``autodoc-process-docstring`` event.

- The ``autodoc`` extension accepts signatures for functions, methods
and classes now that override the signature got via introspection
from Python code.

- The ``autodoc`` extension now offers a ``show-inheritance`` option
for autoclass that inserts a list of bases after the signature.

- The autodoc directives now support the ``noindex`` flag option.


Bugs fixed
----------

* Correctly report the source location for docstrings included with
autodoc.

* Fix the LaTeX output of description units with multiple signatures.

* Handle the figure directive in LaTeX output.

* Handle raw admonitions in LaTeX output.

* Fix determination of the title in HTML help output.

* Handle project names containing spaces.

* Don't write SSI-like comments in HTML output.

* Rename the "sidebar" class to "sphinxsidebar" in order to stay different
from reST sidebars.

* Use a binary TOC in HTML help generation to fix issues links without
explicit anchors.

* Fix behavior of references to functions/methods with an explicit title.

* Support citation, subscript and superscript nodes in LaTeX writer.

* Provide the standard "class" directive as "cssclass"; else it is
shadowed by the Sphinx-defined directive.

* Fix the handling of explicit module names given to autoclass directives.
They now show up with the correct module name in the generated docs.

* Enable autodoc to process Unicode docstrings.

* The LaTeX writer now translates line blocks with ``\raggedright``,
which plays nicer with tables.

* Fix bug with directories in the HTML builder static path.

=========================

New features added
------------------

* The ``toctree`` directive now supports a ``glob`` option that allows
glob-style entries in the content.

* If the ``pygments_style`` config value contains a dot it's treated as the
import path of a custom Pygments style class.

* A new config value, ``exclude_dirs``, can be used to exclude whole
directories from the search for source files.

* The configuration directory (containing ``conf.py``) can now be set
independently from the source directory. For that, a new command-line
option ``-c`` has been added.

* A new directive ``tabularcolumns`` can be used to give a tabular column
specification for LaTeX output. Tables now use the ``tabulary`` package.
Literal blocks can now be placed in tables, with several caveats.

* A new config value, ``latex_use_parts``, can be used to enable parts in LaTeX
documents.

* Autodoc now skips inherited members for classes, unless you give the
new ``inherited-members`` option.

* A new config value, ``autoclass_content``, selects if the docstring of the
class' ``__init__`` method is added to the directive's body.

* Support for C++ class names (in the style ``Class::Function``) in C function
descriptions.

* Support for a ``toctree_only`` item in items for the ``latex_documents``
config value. This only includes the documents referenced by TOC trees in the
output, not the rest of the file containing the directive.

Bugs fixed
----------

* sphinx.htmlwriter: Correctly write the TOC file for any structure of the
master document. Also encode non-ASCII characters as entities in TOC
and index file. Remove two remaining instances of hard-coded
"documentation".

* sphinx.ext.autodoc: descriptors are detected properly now.

* sphinx.latexwriter: implement all reST admonitions, not just ``note``
and ``warning``.

* Lots of little fixes to the LaTeX output and style.

* Fix OpenSearch template and make template URL absolute. The
``html_use_opensearch`` config value now must give the base URL.

* Some unused files are now stripped from the HTML help file build.