Sphinx

# 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 `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’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.