[Python-checkins] r63833 - in doctools/trunk: CHANGES doc/conf.py doc/ext/appapi.rst sphinx sphinx/application.py sphinx/builder.py sphinx/templates/layout.html sphinx/templates/web/settings.html
georg.brandl
python-checkins at python.org
Sat May 31 18:14:36 CEST 2008
Author: georg.brandl
Date: Sat May 31 18:14:36 2008
New Revision: 63833
Log:
Add html-page-context event for customizing the template context.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/conf.py
doctools/trunk/doc/ext/appapi.rst
doctools/trunk/sphinx/ (props changed)
doctools/trunk/sphinx/application.py
doctools/trunk/sphinx/builder.py
doctools/trunk/sphinx/templates/layout.html
doctools/trunk/sphinx/templates/web/settings.html
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sat May 31 18:14:36 2008
@@ -28,6 +28,11 @@
* Defaults for configuration values can now be callables, which allows
dynamic defaults.
+* The new ``html-page-context`` event can be used to include custom values
+ into the context used when rendering an HTML template.
+
+* Add document metadata to the values in the default template context.
+
Bugs fixed
----------
Modified: doctools/trunk/doc/conf.py
==============================================================================
--- doctools/trunk/doc/conf.py (original)
+++ doctools/trunk/doc/conf.py Sat May 31 18:14:36 2008
@@ -162,7 +162,25 @@
return sig
+event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
+
+def parse_event(env, sig, signode):
+ m = event_sig_re.match(sig)
+ if not m:
+ signode += addnodes.desc_name(sig, sig)
+ return sig
+ name, args = m.groups()
+ signode += addnodes.desc_name(name, name)
+ plist = addnodes.desc_parameterlist()
+ for arg in args.split(','):
+ arg = arg.strip()
+ plist += addnodes.desc_parameter(arg, arg)
+ signode += plist
+ return name
+
+
def setup(app):
app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive)
app.add_description_unit('role', 'role', 'pair: %s; role', parse_role)
app.add_description_unit('confval', 'confval', 'pair: %s; configuration value')
+ app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)
Modified: doctools/trunk/doc/ext/appapi.rst
==============================================================================
--- doctools/trunk/doc/ext/appapi.rst (original)
+++ doctools/trunk/doc/ext/appapi.rst Sat May 31 18:14:36 2008
@@ -162,22 +162,43 @@
Sphinx core events
------------------
-These events are known to the core:
+These events are known to the core. The arguments showed are given to the
+registered event handlers.
-.. tabularcolumns:: |l|L|L|
+.. event:: builder-inited ()
+
+ Emitted the builder object has been created.
+
+.. event:: doctree-read (doctree)
+
+ Emitted when a doctree has been parsed and read by the environment, and is
+ about to be pickled.
+
+.. event:: doctree-resolved (doctree, docname)
+
+ Emitted when a doctree has been "resolved" by the environment, that is, all
+ references and TOCs have been inserted.
+
+.. event:: page-context (pagename, templatename, context, doctree)
+
+ Emitted when the HTML builder has created a context dictionary to render a
+ template with -- this can be used to add custom elements to the context.
+
+ The *pagename* argument is the canonical name of the page being rendered,
+ that is, without ``.html`` suffix and using slashes as path separators. The
+ *templatename* is the name of the template to render, this will be
+ ``'page.html'`` for all pages from reST documents.
+
+ The *context* argument is a dictionary of values that are given to the
+ template engine to render the page and can be modified to include custom
+ values. Keys must be strings.
+
+ The *doctree* argument will be a doctree when the page is created from a reST
+ documents; it will be ``None`` when the page is created from an HTML template
+ alone.
+
+ .. versionadded:: 0.4
-====================== =================================== =========
-Event name Emitted when Arguments
-====================== =================================== =========
-``'builder-inited'`` the builder object has been created -none-
-``'doctree-read'`` a doctree has been parsed and read *doctree*
- by the environment, and is about to
- be pickled
-``'doctree-resolved'`` a doctree has been "resolved" by *doctree*, *docname*
- the environment, that is, all
- references and TOCs have been
- inserted
-====================== =================================== =========
.. _template-bridge:
Modified: doctools/trunk/sphinx/application.py
==============================================================================
--- doctools/trunk/sphinx/application.py (original)
+++ doctools/trunk/sphinx/application.py Sat May 31 18:14:36 2008
@@ -49,7 +49,8 @@
events = {
'builder-inited': '',
'doctree-read' : 'the doctree before being pickled',
- 'doctree-resolved' : 'the doctree, the docname',
+ 'doctree-resolved' : 'doctree, docname',
+ 'html-page-context': 'pagename, context, doctree or None',
}
class Sphinx(object):
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py (original)
+++ doctools/trunk/sphinx/builder.py Sat May 31 18:14:36 2008
@@ -341,19 +341,13 @@
show_sphinx = self.config.html_show_sphinx,
builder = self.name,
parents = [],
- titles = {},
logo = logo,
len = len, # the built-in
)
- def write_doc(self, docname, doctree):
- destination = StringOutput(encoding='utf-8')
- doctree.settings = self.docsettings
-
- self.imgpath = relative_uri(self.get_target_uri(docname), '_images')
- self.docwriter.write(doctree, destination)
- self.docwriter.assemble_parts()
-
+ def get_doc_context(self, docname, body):
+ """Collect items for the template context of a page."""
+ # find out relations
prev = next = None
parents = []
related = self.env.toctree_relations.get(docname)
@@ -383,27 +377,40 @@
# "back to index" link already
parents.reverse()
+ # title rendered as HTML
title = titles.get(docname)
- if title:
- title = self.render_partial(title)['title']
- else:
- title = ''
- self.globalcontext['titles'][docname] = title
+ title = title and self.render_partial(title)['title'] or ''
+ # the name for the copied source
sourcename = self.config.html_copy_source and docname + '.txt' or ''
- ctx = dict(
+
+ # metadata for the document
+ meta = self.env.metadata.get(docname)
+
+ return dict(
+ parents = parents,
+ prev = prev,
+ next = next,
title = title,
+ meta = meta,
+ body = body,
sourcename = sourcename,
- body = self.docwriter.parts['fragment'],
toc = self.render_partial(self.env.get_toc_for(docname))['fragment'],
# only display a TOC if there's more than one item to show
display_toc = (self.env.toc_num_entries[docname] > 1),
- parents = parents,
- prev = prev,
- next = next,
)
- self.index_page(docname, doctree, title)
- self.handle_page(docname, ctx)
+ def write_doc(self, docname, doctree):
+ destination = StringOutput(encoding='utf-8')
+ doctree.settings = self.docsettings
+
+ self.imgpath = relative_uri(self.get_target_uri(docname), '_images')
+ self.docwriter.write(doctree, destination)
+ self.docwriter.assemble_parts()
+ body = self.docwriter.parts['fragment']
+
+ ctx = self.get_doc_context(docname, body)
+ self.index_page(docname, doctree, ctx.get('title', ''))
+ self.handle_page(docname, ctx, event_arg=doctree)
def finish(self):
self.info(bold('writing additional files...'), nonl=1)
@@ -569,9 +576,10 @@
return docname + self.out_suffix
def handle_page(self, pagename, addctx, templatename='page.html',
- outfilename=None):
+ outfilename=None, event_arg=None):
ctx = self.globalcontext.copy()
- ctx['current_page_name'] = pagename
+ # current_page_name is backwards compatibility
+ ctx['pagename'] = ctx['current_page_name'] = pagename
def pathto(otheruri, resource=False,
baseuri=self.get_target_uri(pagename)):
@@ -580,11 +588,11 @@
return relative_uri(baseuri, otheruri)
ctx['pathto'] = pathto
ctx['hasdoc'] = lambda name: name in self.env.all_docs
- sidebarfile = self.config.html_sidebars.get(pagename)
- if sidebarfile:
- ctx['customsidebar'] = sidebarfile
+ ctx['customsidebar'] = self.config.html_sidebars.get(pagename)
ctx.update(addctx)
+ self.app.emit('html-page-context', pagename, templatename, ctx, event_arg)
+
output = self.templates.render(templatename, ctx)
if not outfilename:
outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix)
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html (original)
+++ doctools/trunk/sphinx/templates/layout.html Sat May 31 18:14:36 2008
@@ -75,7 +75,7 @@
{{ rendertemplate(customsidebar) }}
{%- endif %}
{%- block sidebarsearch %}
- {%- if current_page_name != "search" %}
+ {%- if pagename != "search" %}
<h3>{{ builder == 'web' and 'Keyword' or 'Quick' }} search</h3>
<form class="search" action="{{ pathto('search') }}" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Go" />
Modified: doctools/trunk/sphinx/templates/web/settings.html
==============================================================================
--- doctools/trunk/sphinx/templates/web/settings.html (original)
+++ doctools/trunk/sphinx/templates/web/settings.html Sat May 31 18:14:36 2008
@@ -1,6 +1,6 @@
{% extends "layout.html" %}
{% set title = 'Settings' %}
-{% set current_page_name = 'settings' %}
+{% set pagename = 'settings' %}
{% block body %}
<h1>{{ project }} Documentation Settings</h1>
<p>
More information about the Python-checkins
mailing list