[Python-checkins] r63585 - in doctools/trunk: CHANGES doc/config.rst doc/ext/appapi.rst sphinx/application.py sphinx/builder.py sphinx/config.py sphinx/htmlhelp.py sphinx/quickstart.py sphinx/templates/layout.html
georg.brandl
python-checkins at python.org
Sat May 24 20:03:56 CEST 2008
Author: georg.brandl
Date: Sat May 24 20:03:56 2008
New Revision: 63585
Log:
Add html_short_title and html_show_sphinx config values.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/config.rst
doctools/trunk/doc/ext/appapi.rst
doctools/trunk/sphinx/application.py
doctools/trunk/sphinx/builder.py
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/htmlhelp.py
doctools/trunk/sphinx/quickstart.py
doctools/trunk/sphinx/templates/layout.html
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sat May 24 20:03:56 2008
@@ -19,6 +19,15 @@
* The directories in the `html_static_path` can now contain subdirectories.
+* The new config value `html_short_title` can be used to set a shorter
+ title for the documentation which is then used in the navigation bar.
+
+* The new config value `html_show_sphinx` can be used to control whether
+ a link to Sphinx is added to the HTML footer.
+
+* Defaults for configuration values can now be callables, which allows
+ dynamic defaults.
+
Bugs fixed
----------
@@ -40,7 +49,7 @@
* Fix behavior of references to functions/methods with an explicit title.
-* Support citation nodes in LaTeX writer.
+* Support citation nodes in LaTeX writer.M v7
Release 0.3 (May 6, 2008)
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Sat May 24 20:03:56 2008
@@ -182,6 +182,14 @@
v{<revision>} documentation'`, where the placeholders are replaced by the
config values of the same name.
+.. confval:: html_short_title
+
+ A shorter "title" for the HTML docs. This is used in for links in the header
+ and in the HTML Help docs. If not given, it defaults to the value of
+ :confval:`html_title`.
+
+ .. versionadded:: 0.4
+
.. confval:: html_style
The style sheet to use for HTML pages. A file of that name must exist either
@@ -293,6 +301,13 @@
to translate document trees to HTML. Default is ``None`` (use the builtin
translator).
+.. confval:: html_show_sphinx
+
+ If true, "Created using Sphinx" is shown in the HTML footer. Default is
+ ``True``.
+
+ .. versionadded:: 0.4
+
.. confval:: htmlhelp_basename
Output file base name for HTML help builder. Default is ``'pydoc'``.
Modified: doctools/trunk/doc/ext/appapi.rst
==============================================================================
--- doctools/trunk/doc/ext/appapi.rst (original)
+++ doctools/trunk/doc/ext/appapi.rst Sat May 24 20:03:56 2008
@@ -24,6 +24,11 @@
in the setting only takes effect when a document is parsed -- this means that
the whole environment must be rebuilt.
+ .. versionchanged:: 0.4
+ If the *default* value is a callable, it will be called with the config
+ object as its argument in order to get the default value. This can be
+ used to implement config values whose default depends on other values.
+
.. method:: Sphinx.add_event(name)
Register an event called *name*.
@@ -43,7 +48,7 @@
documentation.
.. XXX once we target docutils 0.5, update this
-
+
.. method:: Sphinx.add_role(name, role)
Register a Docutils role. *name* must be the role name that occurs in the
Modified: doctools/trunk/sphinx/application.py
==============================================================================
--- doctools/trunk/sphinx/application.py (original)
+++ doctools/trunk/sphinx/application.py Sat May 24 20:03:56 2008
@@ -79,16 +79,12 @@
setattr(self.config, key, val)
# load all extension modules
- for extension in getattr(self.config, 'extensions', ()):
+ for extension in self.config.extensions:
self.setup_extension(extension)
# the config file itself can be an extension
- if hasattr(self.config, 'setup'):
+ if self.config.setup:
self.config.setup(self)
- # this must happen after loading extension modules, since they
- # can add custom config values
- self.config.init_defaults()
-
if buildername is None:
print >>status, 'No builder selected, using default: html'
buildername = 'html'
@@ -179,9 +175,10 @@
self.builderclasses[builder.name] = builder
def add_config_value(self, name, default, rebuild_env):
- if name in self.config.values:
+ if name in self.config.valuenames:
raise ExtensionError('Config value %r already present' % name)
- self.config.values[name] = (default, rebuild_env)
+ self.config.valuenames.add(name)
+ self.config.__class__.config_values[name] = (default, rebuild_env)
def add_event(self, name):
if name in self._events:
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py (original)
+++ doctools/trunk/sphinx/builder.py Sat May 24 20:03:56 2008
@@ -320,9 +320,6 @@
else:
self.last_updated = None
- docstitle = self.config.html_title or \
- '%s v%s documentation' % (self.config.project,
- self.config.release)
logo = self.config.html_logo and \
path.basename(self.config.html_logo) or ''
@@ -339,7 +336,9 @@
use_modindex = self.config.html_use_modindex,
use_index = self.config.html_use_index,
use_opensearch = self.config.html_use_opensearch,
- docstitle = docstitle,
+ docstitle = self.config.html_title,
+ shorttitle = self.config.html_short_title,
+ show_sphinx = self.config.html_show_sphinx,
builder = self.name,
parents = [],
titles = {},
@@ -913,17 +912,15 @@
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,
+ 'docstitle': self.config.html_title,
+ 'shorttitle': self.config.html_short_title,
'libchanges': sorted(libchanges.iteritems()),
'apichanges': sorted(apichanges),
'otherchanges': sorted(otherchanges.iteritems()),
+ 'show_sphinx': self.config.html_show_sphinx,
}
f = open(path.join(self.outdir, 'index.html'), 'w')
try:
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Sat May 24 20:03:56 2008
@@ -47,7 +47,10 @@
template_bridge = (None, False),
# HTML options
- html_title = (None, False),
+ html_title = (lambda self: '%s v%s documentation' %
+ (self.project, self.release),
+ False),
+ html_short_title = (lambda self: self.html_title, False),
html_style = ('default.css', False),
html_logo = (None, False),
html_static_path = ([], False),
@@ -61,6 +64,7 @@
html_copy_source = (True, False),
html_use_opensearch = ('', False),
html_file_suffix = (None, False),
+ html_show_sphinx = (True, False),
# HTML help only options
htmlhelp_basename = ('pydoc', False),
@@ -77,7 +81,7 @@
)
def __init__(self, dirname, filename):
- self.values = self.config_values.copy()
+ self.valuenames = set(self.config_values.keys())
config = {'__file__': path.join(dirname, filename)}
olddir = os.getcwd()
try:
@@ -85,12 +89,20 @@
execfile(config['__file__'], config)
finally:
os.chdir(olddir)
- self.__dict__.update(config)
-
- def init_defaults(self):
- for val in self.values:
- if val not in self.__dict__:
- self.__dict__[val] = self.values[val][0]
+ for name in config:
+ if name in self.valuenames:
+ self.__dict__[name] = config[name]
+ self.setup = config.get('setup', None)
+
+ def __getattr__(self, name):
+ if name.startswith('_'):
+ raise AttributeError(name)
+ if name not in self.valuenames:
+ raise AttributeError('No such config value: %s' % name)
+ default = self.config_values[name][0]
+ if callable(default):
+ return default(self)
+ return default
def __getitem__(self, name):
return getattr(self, name)
@@ -102,4 +114,4 @@
delattr(self, name)
def __contains__(self, name):
- return hasattr(self, name)
+ return name in self.valuenames
Modified: doctools/trunk/sphinx/htmlhelp.py
==============================================================================
--- doctools/trunk/sphinx/htmlhelp.py (original)
+++ doctools/trunk/sphinx/htmlhelp.py Sat May 24 20:03:56 2008
@@ -129,9 +129,8 @@
builder.info('writing project file...')
f = open(path.join(outdir, outname+'.hhp'), 'w')
try:
- title = builder.config.html_title or \
- '%s v%s documentation' % (builder.config.project, builder.config.release)
- f.write(project_template % {'outname': outname, 'title': title,
+ f.write(project_template % {'outname': outname,
+ 'title': builder.config.html_title,
'version': builder.config.version,
'project': builder.config.project})
if not outdir.endswith(os.sep):
@@ -150,7 +149,8 @@
try:
f.write(contents_header)
# special books
- f.write('<LI> ' + object_sitemap % ('Main page', 'index.html'))
+ f.write('<LI> ' + object_sitemap % (builder.config.html_short_title,
+ 'index.html'))
if builder.config.html_use_modindex:
f.write('<LI> ' + object_sitemap % ('Global Module Index', 'modindex.html'))
# the TOC
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py (original)
+++ doctools/trunk/sphinx/quickstart.py Sat May 24 20:03:56 2008
@@ -105,6 +105,9 @@
# "<project> v<release> documentation".
#html_title = None
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
# The name of an image file (within the static path) to place at the top of
# the sidebar.
#html_logo = None
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html (original)
+++ doctools/trunk/sphinx/templates/layout.html Sat May 24 20:03:56 2008
@@ -25,7 +25,7 @@
title="Customize your viewing settings" accesskey="S">settings</a> |</li>
{%- endif %}
{%- block rootrellink %}
- <li><a href="{{ pathto('index') }}">{{ docstitle }}</a>{{ reldelim1 }}</li>
+ <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
{%- endblock %}
{%- for parent in parents %}
<li><a href="{{ parent.link|e }}" accesskey="U">{{ parent.title }}</a>{{ reldelim1 }}</li>
@@ -185,6 +185,9 @@
{%- if last_updated %}
Last updated on {{ last_updated }}.
{%- endif %}
+ {%- if show_sphinx %}
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
+ {%- endif %}
</div>
{%- endblock %}
</body>
More information about the Python-checkins
mailing list