1. Georg Brandl
  2. sphinx

Commits

georg.brandl  committed 8b762e4

* Use a customizable title for the docs.
* Fix up the clumsy index template handling.

  • Participants
  • Parent commits d870241
  • Branches default

Comments (0)

Files changed (15)

File CHANGES

View file
 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
 ------------------
 
   - 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

File doc/_templates/index.html

View file
 {% 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>

File doc/concepts.rst

View file
   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.

File doc/conf.py

View file
 
 # 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

File doc/config.rst

View file
 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
    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
    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``.

File sphinx/builder.py

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

File sphinx/config.py

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

File sphinx/quickstart.py

View file
 # 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".
 # 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 = {}
 

File sphinx/templates/changes/frameset.html

View file
   "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">

File sphinx/templates/changes/rstsource.html

View file
   "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>

File sphinx/templates/changes/versionchanges.html

View file
   <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">

File sphinx/templates/defindex.html

View file
+{% extends "layout.html" %}
+{% set title = 'Overview' %}
+{% block body %}
+  <h1>{{ docstitle }}</h1>
+  <p>
+    Welcome! This is
+    {% block description %}the documentation for {{ project }}
+    {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}{% endblock %}.
+  </p>
+  {% block beforetables %}
+  {% endblock %}
+  {% block tables %}
+  <p><strong>Indices and tables:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br>
+         <span class="linkdescr">lists all sections and subsections</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
+         <span class="linkdescr">search this documentation</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Global Module Index</a><br>
+         <span class="linkdescr">quick access to all modules</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br>
+         <span class="linkdescr">all functions, classes, terms</span></p>
+    </td></tr>
+  </table>
+  {% endblock %}
+  {% block aftertables %}
+  {% endblock %}
+{% endblock %}

File sphinx/templates/index.html

-{% extends "layout.html" %}
-{% set title = 'Overview' %}
-{% set page_links = [
-  (pathto('@rss/recent'), 'application/rss+xml', 'Recent Comments')
-] %}
-{% block body %}
-  <h1>{{ project }} Documentation</h1>
-  <p>
-    Welcome! This is the documentation for {{ project }}
-    {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}.
-  </p>
-  {% if indextemplate %}
-  {{ rendertemplate(indextemplate) }}
-  {% else %}
-  <p><strong>Indices and tables:</strong></p>
-  <table class="contentstable" align="center"><tr>
-    <td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br>
-         <span class="linkdescr">lists all sections and subsections</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
-         <span class="linkdescr">search this documentation</span></p>
-    </td><td width="50%">
-      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Global Module Index</a><br>
-         <span class="linkdescr">quick access to all modules</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br>
-         <span class="linkdescr">all functions, classes, terms</span></p>
-    </td></tr>
-  </table>
-  {% endif %}
-{% endblock %}

File sphinx/templates/layout.html

View file
                                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>
   <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' %}
     {%- 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 %}

File sphinx/templates/search.html

View file
 {% 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.