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:
Configuration:
Builders:
New translations:
Extensions and API:
Other 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.
Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian Wiesner for suggestions.