diff --git a/CHANGES b/CHANGES
index a11d101ae..0e8df6288 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,29 @@
Changes in trunk
================
+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``.
+
New features added
------------------
@@ -27,6 +50,16 @@ New features added
- Allow giving multiple options in a ``cmdoption`` directive.
- Fix display of class members without explicit class name given.
+* Templates:
+
+ - ``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.
+
Thanks to Jacob Kaplan-Moss, Talin and Sebastian Wiesner for suggestions.
Bugs fixed
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index abd2bb96b..411097829 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -1,11 +1,6 @@
{% extends "layout.html" %}
{% set title = 'Overview' %}
{% block body %}
-
-
Welcome
diff --git a/doc/concepts.rst b/doc/concepts.rst
index cbc74d489..7ea23dbfa 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -109,6 +109,3 @@ The special document names (and pages generated for them) are:
Though only few such names are currently used by Sphinx, you should not create
documents or document-containing directories with such names. (Using ``_`` as
a prefix for a custom template directory is fine.)
-
-``index`` is a special name, too, if the :confval:`html_index` config value is
-nonempty.
diff --git a/doc/conf.py b/doc/conf.py
index 74ec3d394..13e666716 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -95,7 +95,7 @@ html_sidebars = {'index': 'indexsidebar.html'}
# Additional templates that should be rendered to pages, maps page names to
# templates.
-#html_additional_pages = {}
+html_additional_pages = {'index': 'index.html'}
# If true, the reST sources are included in the HTML build as _sources/.
#html_copy_source = True
diff --git a/doc/config.rst b/doc/config.rst
index 938af23f9..7378270fb 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -149,6 +149,14 @@ Options for HTML output
These options influence HTML as well as HTML Help output, and other builders
that use Sphinx' HTMLWriter class.
+.. confval:: html_title
+
+ The "title" for HTML documentation generated with Sphinx' own templates.
+ This is appended to the ```` tag of individual pages, and used in the
+ navigation bar as the "topmost" element. It defaults to :samp:`'{<project>}
+ v{<revision>} documentation'`, where the placeholders are replaced by the
+ config values of the same name.
+
.. confval:: html_style
The style sheet to use for HTML pages. A file of that name must exist either
@@ -173,17 +181,6 @@ that use Sphinx' HTMLWriter class.
If true, *SmartyPants* will be used to convert quotes and dashes to
typographically correct entities. Default: ``True``.
-.. confval:: html_index
-
- Content template for the index page, filename relative to this file. If this
- is not the empty string, the "index" document will not be created from a
- reStructuredText file but from the ``index.html`` template. The template you
- specify in this value will be included in the ``index.html``, together with
- a list of tables.
-
- If you want to completely override the resulting ``index`` document, set this
- to some nonempty value and override the ``index.html`` template.
-
.. confval:: html_sidebars
Custom sidebar templates, must be a dictionary that maps document names to
@@ -210,6 +207,19 @@ that use Sphinx' HTMLWriter class.
This will render the template ``customdownload.html`` as the page
``download.html``.
+ .. note::
+
+ Earlier versions of Sphinx had a value called :confval:`html_index` which
+ was a clumsy way of controlling the content of the "index" document. If
+ you used this feature, migrate it by adding an ``'index'`` key to this
+ setting, with your custom template as the value, and in your custom
+ template, use ::
+
+ {% extend "defindex.html" %}
+ {% block tables %}
+ ... old template content ...
+ {% endblock %}
+
.. confval:: html_use_modindex
If true, add a module index to the HTML documents. Default is ``True``.
diff --git a/sphinx/builder.py b/sphinx/builder.py
index 59cf3174b..39be00b65 100644
--- a/sphinx/builder.py
+++ b/sphinx/builder.py
@@ -317,12 +317,17 @@ class StandaloneHTMLBuilder(Builder):
else:
self.last_updated = None
+ docstitle = self.config.html_title or \
+ '%s v%s documentation' % (self.config.project,
+ self.config.release)
+
self.globalcontext = dict(
project = self.config.project,
- copyright = self.config.copyright,
release = self.config.release,
version = self.config.version,
last_updated = self.last_updated,
+ docstitle = docstitle,
+ copyright = self.config.copyright,
style = self.config.html_style,
use_modindex = self.config.html_use_modindex,
builder = self.name,
@@ -463,12 +468,6 @@ class StandaloneHTMLBuilder(Builder):
self.info(' '+pagename, nonl=1)
self.handle_page(pagename, {}, template)
- # the index page
- indextemplate = self.config.html_index
- if indextemplate:
- self.info(' index', nonl=1)
- self.handle_page('index', {'indextemplate': indextemplate}, 'index.html')
-
self.info()
# copy image files
@@ -859,9 +858,14 @@ class ChangesBuilder(Builder):
otherchanges.setdefault((docname, title), []).append(
(entry, docname, lineno))
+ docstitle = self.config.html_title or \
+ '%s v%s documentation' % (self.config.project,
+ self.config.release)
+
ctx = {
'project': self.config.project,
'version': version,
+ 'docstitle': docstitle,
'libchanges': sorted(libchanges.iteritems()),
'apichanges': sorted(apichanges),
'otherchanges': sorted(otherchanges.iteritems()),
diff --git a/sphinx/config.py b/sphinx/config.py
index e4fbddf49..ffb1ab47d 100644
--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -45,12 +45,12 @@ class Config(object):
template_bridge = (None, False),
# HTML options
+ html_title = (None, False),
html_style = ('default.css', False),
html_static_path = ([], False),
html_last_updated_fmt = ('%b %d, %Y', False),
html_use_smartypants = (True, False),
html_translator_class = (None, False),
- html_index = ('', False),
html_sidebars = ({}, False),
html_additional_pages = ({}, False),
html_use_modindex = (True, False),
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index 0bdf10eaf..7e07cde53 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -96,6 +96,10 @@ pygments_style = 'sphinx'
# given in html_static_path.
html_style = 'default.css'
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
@@ -109,9 +113,6 @@ html_last_updated_fmt = '%%b %%d, %%Y'
# typographically correct entities.
#html_use_smartypants = True
-# Content template for the index page.
-#html_index = ''
-
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
diff --git a/sphinx/templates/changes/frameset.html b/sphinx/templates/changes/frameset.html
index f7732ba58..e464f5de4 100644
--- a/sphinx/templates/changes/frameset.html
+++ b/sphinx/templates/changes/frameset.html
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/html4/frameset.dtd">
<html>
<head>
- <title>Changes in Version {{ version }} — {{ project }} Documentation
+ Changes in Version {{ version }} — {{ docstitle }}