[Python-checkins] r62406 - in doctools/trunk: CHANGES doc/_templates/index.html doc/concepts.rst doc/conf.py doc/config.rst sphinx/builder.py sphinx/config.py sphinx/quickstart.py sphinx/templates/changes/frameset.html sphinx/templates/changes/rstsource.html sphinx/templates/changes/versionchanges.html sphinx/templates/defindex.html sphinx/templates/index.html sphinx/templates/layout.html sphinx/templates/search.html
georg.brandl
python-checkins at python.org
Sat Apr 19 23:28:25 CEST 2008
Author: georg.brandl
Date: Sat Apr 19 23:28:24 2008
New Revision: 62406
Log:
* Use a customizable title for the docs.
* Fix up the clumsy index template handling.
Added:
doctools/trunk/sphinx/templates/defindex.html
Removed:
doctools/trunk/sphinx/templates/index.html
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/_templates/index.html
doctools/trunk/doc/concepts.rst
doctools/trunk/doc/conf.py
doctools/trunk/doc/config.rst
doctools/trunk/sphinx/builder.py
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/quickstart.py
doctools/trunk/sphinx/templates/changes/frameset.html
doctools/trunk/sphinx/templates/changes/rstsource.html
doctools/trunk/sphinx/templates/changes/versionchanges.html
doctools/trunk/sphinx/templates/layout.html
doctools/trunk/sphinx/templates/search.html
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sat Apr 19 23:28:24 2008
@@ -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 @@
- 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
Modified: doctools/trunk/doc/_templates/index.html
==============================================================================
--- doctools/trunk/doc/_templates/index.html (original)
+++ doctools/trunk/doc/_templates/index.html Sat Apr 19 23:28:24 2008
@@ -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>
Modified: doctools/trunk/doc/concepts.rst
==============================================================================
--- doctools/trunk/doc/concepts.rst (original)
+++ doctools/trunk/doc/concepts.rst Sat Apr 19 23:28:24 2008
@@ -109,6 +109,3 @@
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.
Modified: doctools/trunk/doc/conf.py
==============================================================================
--- doctools/trunk/doc/conf.py (original)
+++ doctools/trunk/doc/conf.py Sat Apr 19 23:28:24 2008
@@ -95,7 +95,7 @@
# 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
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Sat Apr 19 23:28:24 2008
@@ -149,6 +149,14 @@
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 @@
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 @@
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``.
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py (original)
+++ doctools/trunk/sphinx/builder.py Sat Apr 19 23:28:24 2008
@@ -317,12 +317,17 @@
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 @@
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 @@
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()),
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Sat Apr 19 23:28:24 2008
@@ -45,12 +45,12 @@
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),
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py (original)
+++ doctools/trunk/sphinx/quickstart.py Sat Apr 19 23:28:24 2008
@@ -96,6 +96,10 @@
# 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 @@
# 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 = {}
Modified: doctools/trunk/sphinx/templates/changes/frameset.html
==============================================================================
--- doctools/trunk/sphinx/templates/changes/frameset.html (original)
+++ doctools/trunk/sphinx/templates/changes/frameset.html Sat Apr 19 23:28:24 2008
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/html4/frameset.dtd">
<html>
<head>
- <title>Changes in Version {{ version }} — {{ project }} Documentation</title>
+ <title>Changes in Version {{ version }} — {{ docstitle }}</title>
</head>
<frameset cols="45%,*">
<frame name="main" src="changes.html">
Modified: doctools/trunk/sphinx/templates/changes/rstsource.html
==============================================================================
--- doctools/trunk/sphinx/templates/changes/rstsource.html (original)
+++ doctools/trunk/sphinx/templates/changes/rstsource.html Sat Apr 19 23:28:24 2008
@@ -2,7 +2,7 @@
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
- <title>{{ filename }} — {{ project }} Documentation</title>
+ <title>{{ filename }} — {{ docstitle }}</title>
<style type="text/css">
.hl { background-color: yellow }
</style>
Modified: doctools/trunk/sphinx/templates/changes/versionchanges.html
==============================================================================
--- doctools/trunk/sphinx/templates/changes/versionchanges.html (original)
+++ doctools/trunk/sphinx/templates/changes/versionchanges.html Sat Apr 19 23:28:24 2008
@@ -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 }} — {{ project }} Documentation</title>
+ <title>Changes in Version {{ version }} — {{ docstitle }}</title>
</head>
<body>
<div class="document">
Added: doctools/trunk/sphinx/templates/defindex.html
==============================================================================
--- (empty file)
+++ doctools/trunk/sphinx/templates/defindex.html Sat Apr 19 23:28:24 2008
@@ -0,0 +1,30 @@
+{% 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 %}
Deleted: doctools/trunk/sphinx/templates/index.html
==============================================================================
--- doctools/trunk/sphinx/templates/index.html Sat Apr 19 23:28:24 2008
+++ (empty file)
@@ -1,30 +0,0 @@
-{% 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 %}
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html (original)
+++ doctools/trunk/sphinx/templates/layout.html Sat Apr 19 23:28:24 2008
@@ -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> »</li>
+ <li><a href="{{ pathto('index') }}">{{ docstitle }}</a> »</li>
{%- endblock %}
{%- for parent in parents %}
<li><a href="{{ parent.link|e }}" accesskey="U">{{ parent.title }}</a> »</li>
@@ -36,7 +36,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
{%- if builder != 'htmlhelp' %}
- {%- set titlesuffix = " — " + project + " Documentation" %}
+ {%- set titlesuffix = " — " + 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 %}
Modified: doctools/trunk/sphinx/templates/search.html
==============================================================================
--- doctools/trunk/sphinx/templates/search.html (original)
+++ doctools/trunk/sphinx/templates/search.html Sat Apr 19 23:28:24 2008
@@ -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.
More information about the Python-checkins
mailing list