Sphinx 0.2

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 blocks 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’s 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.