* Use a customizable title for the docs.

* Fix up the clumsy index template handling.

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

doc/_templates/index.html

@@ -1,11 +1,6 @@
 {% extends "layout.html" %}
 {% set title = 'Overview' %}
 {% block body %}
-<!--  <p style="background-color: #fcc; font-size: large; border: 1px solid #f00; padding: 10px;">
-    <b>Attention:</b> this is a preview. Sphinx is not released yet on PyPI,
-    and the contents of this documentation are subject to change.
-  </p> -->
-
   <h1>Welcome</h1>
 
   <p>

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.

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/<name>.
 #html_copy_source = True

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 ``<title>`` 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``.

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()),

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),

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 = {}
 

sphinx/templates/changes/frameset.html

@@ -2,7 +2,7 @@
   "http://www.w3.org/TR/html4/frameset.dtd">
 <html>
   <head>
-    <title>Changes in Version {{ version }} &mdash; {{ project }} Documentation</title>
+    <title>Changes in Version {{ version }} &mdash; {{ docstitle }}</title>
   </head>
   <frameset cols="45%,*">
     <frame name="main" src="changes.html">

sphinx/templates/changes/rstsource.html

@@ -2,7 +2,7 @@
   "http://www.w3.org/TR/html4/loose.dtd">
 <html>
   <head>
-    <title>{{ filename }} &mdash; {{ project }} Documentation</title>
+    <title>{{ filename }} &mdash; {{ docstitle }}</title>
     <style type="text/css">
       .hl { background-color: yellow }
     </style>

sphinx/templates/changes/versionchanges.html

@@ -9,7 +9,7 @@
   <head>
     <link rel="stylesheet" href="default.css">
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-    <title>Changes in Version {{ version }} &mdash; {{ project }} Documentation</title>
+    <title>Changes in Version {{ version }} &mdash; {{ docstitle }}</title>
   </head>
   <body>
     <div class="document">

sphinx/templates/defindex.html

@@ -1,17 +1,15 @@
 {% extends "layout.html" %}
 {% set title = 'Overview' %}
-{% set page_links = [
-  (pathto('@rss/recent'), 'application/rss+xml', 'Recent Comments')
-] %}
 {% block body %}
-  <h1>{{ project }} Documentation</h1>
+  <h1>{{ docstitle }}</h1>
   <p>
-    Welcome! This is the documentation for {{ project }}
+    Welcome! This is
-    {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}.
+    {% block description %}the documentation for {{ project }}
+    {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}{% endblock %}.
   </p>
-  {% if indextemplate %}
+  {% block beforetables %}
-  {{ rendertemplate(indextemplate) }}
+  {% endblock %}
-  {% else %}
+  {% block tables %}
   <p><strong>Indices and tables:</strong></p>
   <table class="contentstable" align="center"><tr>
     <td width="50%">
@@ -26,5 +24,7 @@
          <span class="linkdescr">all functions, classes, terms</span></p>
     </td></tr>
   </table>
-  {% endif %}
+  {% endblock %}
+  {% block aftertables %}
+  {% endblock %}
 {% endblock %}

sphinx/templates/layout.html

@@ -23,7 +23,7 @@
                                title="Customize your viewing settings" accesskey="S">settings</a> |</li>
         {%- endif %}
         {%- block rootrellink %}
-        <li><a href="{{ pathto('index') }}">{{ project }} v{{ release }} documentation</a> &raquo;</li>
+        <li><a href="{{ pathto('index') }}">{{ docstitle }}</a> &raquo;</li>
         {%- endblock %}
         {%- for parent in parents %}
           <li><a href="{{ parent.link|e }}" accesskey="U">{{ parent.title }}</a> &raquo;</li>
@@ -36,7 +36,7 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     {%- if builder != 'htmlhelp' %}
-      {%- set titlesuffix = " &mdash; " + project + " Documentation" %}
+      {%- set titlesuffix = " &mdash; " + docstitle %}
     {%- endif %}
     <title>{{ title|striptags }}{{ titlesuffix }}</title>
     {%- if builder == 'web' %}
@@ -70,7 +70,7 @@
     {%- if hasdoc('copyright') %}
     <link rel="copyright" title="Copyright" href="{{ pathto('copyright') }}">
     {%- endif %}
-    <link rel="top" title="{{ project }} Documentation" href="{{ pathto('index') }}">
+    <link rel="top" title="{{ docstitle }}" href="{{ pathto('index') }}">
     {%- if parents %}
     <link rel="up" title="{{ parents[-1].title|striptags }}" href="{{ parents[-1].link|e }}">
     {%- endif %}

sphinx/templates/search.html

@@ -1,12 +1,12 @@
 {% extends "layout.html" %}
-{% set title = 'Search Documentation' %}
+{% set title = 'Search' %}
 {% block extrahead %}
     <script type="text/javascript" src="{{ pathto('_static/searchtools.js', 1) }}"></script>
 {% endblock %}
 {% block body %}
-  <h1 id="search-documentation">Search Documentation</h1>
+  <h1 id="search-documentation">Search</h1>
   <p>
-    From here you can search the {{ project }} documentation. Enter your search
+    From here you can search these documents. Enter your search
     words into the box below and click "search". Note that the search
     function will automatically search for all of the words. Pages
     containing less words won't appear in the result list.