Release 0.5 (in development)
============================
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 ```` tags via the docutils ``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
- 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 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
----------
* Fix a problem with module links not being generated in LaTeX output.
* Fix the handling of images in different directories.
* 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.
* Properly escape quotes in HTML help attribute values.
* Fix LaTeX build for some description environments with ``:noindex:``.
* Don't crash on weird 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.
Release 0.4.3 (Oct 8, 2008)
===========================
* 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.
Release 0.4.2 (Jul 29, 2008)
============================
* 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.
Release 0.4.1 (Jul 5, 2008)
===========================
* 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.
Release 0.4 (Jun 23, 2008)
==========================
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.
Release 0.3 (May 6, 2008)
=========================
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.
Release 0.2 (Apr 27, 2008)
==========================
Incompatible changes
--------------------
* Jinja, the template engine used for the default HTML templates, is now
no longer shipped with Sphinx. If it is not installed automatically for
you (it is now listed as a dependency in ``setup.py``), install it manually
from PyPI. This will also be needed if you're using Sphinx from a SVN
checkout; in that case please also remove the ``sphinx/jinja`` directory
that may be left over from old revisions.
* The clumsy handling of the ``index.html`` template was removed. The config
value ``html_index`` is gone, and ``html_additional_pages`` should be used
instead. If you need it, the old ``index.html`` template is still there,
called ``defindex.html``, and you can port your html_index template, using
Jinja inheritance, by changing your template::
{% extends "defindex.html" %}
{% block tables %}
... old html_index template content ...
{% endblock %}
and putting ``'index': name of your template`` in ``html_additional_pages``.
* In the layout template, redundant ``block``\s were removed; you should use
Jinja's standard ``{{ super() }}`` mechanism instead, as explained in the
(newly written) templating docs.
New features added
------------------
* Extension API (Application object):
- Support a new method, ``add_crossref_type``. It works like
``add_description_unit`` but the directive will only create a target
and no output.
- Support a new method, ``add_transform``. It takes a standard docutils
``Transform`` subclass which is then applied by Sphinx' reader on
parsing reST document trees.
- Add support for other template engines than Jinja, by adding an
abstraction called a "template bridge". This class handles rendering
of templates and can be changed using the new configuration value
"template_bridge".
- The config file itself can be an extension (if it provides a ``setup()``
function).
* Markup:
- New directive, ``currentmodule``. It can be used to indicate the module
name of the following documented things without creating index entries.
- Allow giving a different title to documents in the toctree.
- Allow giving multiple options in a ``cmdoption`` directive.
- Fix display of class members without explicit class name given.
* Templates (HTML output):
- ``index.html`` renamed to ``defindex.html``, see above.
- There's a new config value, ``html_title``, that controls the overall
"title" of the set of Sphinx docs. It is used instead everywhere instead of
"Projectname vX.Y documentation" now.
- All references to "documentation" in the templates have been removed, so
that it is now easier to use Sphinx for non-documentation documents with
the default templates.
- Templates now have an XHTML doctype, to be consistent with docutils'
HTML output.
- You can now create an OpenSearch description file with the
``html_use_opensearch`` config value.
- You can now quickly include a logo in the sidebar, using the ``html_logo``
config value.
- There are new blocks in the sidebar, so that you can easily insert content
into the sidebar.
* LaTeX output:
- The ``sphinx.sty`` package was cleaned of unused stuff.
- You can include a logo in the title page with the ``latex_logo`` config
value.
- You can define the link colors and a border and background color for
verbatim environments.
Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian
Wiesner for suggestions.
Bugs fixed
----------
* sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given
members. Remove "self" in class constructor argument list.
* sphinx.htmlwriter: Don't use os.path for joining image HREFs.
* sphinx.htmlwriter: Don't use SmartyPants for HTML attribute values.
* sphinx.latexwriter: Implement option lists. Also, some other changes
were made to ``sphinx.sty`` in order to enhance compatibility and
remove old unused stuff. Thanks to Gael Varoquaux for that!
* sphinx.roles: Fix referencing glossary terms with explicit targets.
* sphinx.environment: Don't swallow TOC entries when resolving subtrees.
* sphinx.quickstart: Create a sensible default latex_documents setting.
* sphinx.builder, sphinx.environment: Gracefully handle some user error
cases.
* sphinx.util: Follow symbolic links when searching for documents.
Release 0.1.61950 (Mar 26, 2008)
================================
* sphinx.quickstart: Fix format string for Makefile.
Release 0.1.61945 (Mar 26, 2008)
================================
* sphinx.htmlwriter, sphinx.latexwriter: Support the ``.. image::``
directive by copying image files to the output directory.
* sphinx.builder: Consistently name "special" HTML output directories
with a leading underscore; this means ``_sources`` and ``_static``.
* sphinx.environment: Take dependent files into account when collecting
the set of outdated sources.
* sphinx.directives: Record files included with ``.. literalinclude::``
as dependencies.
* sphinx.ext.autodoc: Record files from which docstrings are included
as dependencies.
* sphinx.builder: Rebuild all HTML files in case of a template change.
* sphinx.builder: Handle unavailability of TOC relations (previous/
next chapter) more gracefully in the HTML builder.
* sphinx.latexwriter: Include fncychap.sty which doesn't seem to be
very common in TeX distributions. Add a ``clean`` target in the
latex Makefile. Really pass the correct paper and size options
to the LaTeX document class.
* setup: On Python 2.4, don't egg-depend on docutils if a docutils is
already installed -- else it will be overwritten.
Release 0.1.61843 (Mar 24, 2008)
================================
* sphinx.quickstart: Really don't create a makefile if the user
doesn't want one.
* setup: Don't install scripts twice, via setuptools entry points
and distutils scripts. Only install via entry points.
* sphinx.builder: Don't recognize the HTML builder's copied source
files (under ``_sources``) as input files if the source suffix is
``.txt``.
* sphinx.highlighting: Generate correct markup for LaTeX Verbatim
environment escapes even if Pygments is not installed.
* sphinx.builder: The WebHTMLBuilder is now called PickleHTMLBuilder.
* sphinx.htmlwriter: Make parsed-literal blocks work as expected,
not highlighting them via Pygments.
* sphinx.environment: Don't error out on reading an empty source file.
Release 0.1.61798 (Mar 23, 2008)
================================
* sphinx: Work with docutils SVN snapshots as well as 0.4.
* sphinx.ext.doctest: Make the group in which doctest blocks are
placed selectable, and default to ``'default'``.
* sphinx.ext.doctest: Replace ```` in doctest blocks by
real blank lines for presentation output, and remove doctest
options given inline.
* sphinx.environment: Move doctest_blocks out of block_quotes to
support indented doctest blocks.
* sphinx.ext.autodoc: Render ``.. automodule::`` docstrings in a
section node, so that module docstrings can contain proper
sectioning.
* sphinx.ext.autodoc: Use the module's encoding for decoding
docstrings, rather than requiring ASCII.
Release 0.1.61611 (Mar 21, 2008)
================================
* First public release.