[Python-checkins] r65548 - in doctools/trunk: CHANGES doc/ext/appapi.rst sphinx/application.py
georg.brandl
python-checkins at python.org
Tue Aug 5 12:25:41 CEST 2008
Author: georg.brandl
Date: Tue Aug 5 12:25:40 2008
New Revision: 65548
Log:
``Sphinx.add_node()`` now takes optional visitor methods for the HTML,
LaTeX and text translators; this prevents having to manually patch
the classes.
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/ext/appapi.rst
doctools/trunk/sphinx/application.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Tue Aug 5 12:25:40 2008
@@ -26,7 +26,11 @@
* The HTML builders have two additional attributes now that can be used
to disable the anchor-link creation after headlines and definition
- links. EXPERIMENTAL
+ links.
+
+* ``Sphinx.add_node()`` now takes optional visitor methods for the HTML,
+ LaTeX and text translators; this prevents having to manually patch
+ the classes.
* sphinx.doc.autodoc has a new event ``autodoc-process-signature`` that
allows tuning function signature introspection.
Modified: doctools/trunk/doc/ext/appapi.rst
==============================================================================
--- doctools/trunk/doc/ext/appapi.rst (original)
+++ doctools/trunk/doc/ext/appapi.rst Tue Aug 5 12:25:40 2008
@@ -33,11 +33,32 @@
Register an event called *name*.
-.. method:: Sphinx.add_node(node)
+.. method:: Sphinx.add_node(node, **kwds)
Register a Docutils node class. This is necessary for Docutils internals.
It may also be used in the future to validate nodes in the parsed documents.
+ Node visitor functions for the Sphinx HTML, LaTeX and text writers can be
+ given as keyword arguments: the keyword must be one or more of ``'html'``,
+ ``'latex'``, ``'text'``, the value a 2-tuple of ``(visit, depart)`` methods.
+ ``depart`` can be ``None`` if the ``visit`` function raises
+ :exc:`docutils.nodes.SkipNode`. Example::
+
+ class math(docutils.nodes.Element)
+
+ def visit_math_html(self, node):
+ self.body.append(self.starttag(node, 'math'))
+ def depart_math_html(self, node):
+ self.body.append('</math>')
+
+ app.add_node(math, html=(visit_math_html, depart_math_html))
+
+ Obviously, translators for which you don't specify visitor methods will choke
+ on the node when encountered in a document to translate.
+
+ .. versionchanged:: 0.5
+ Added the support for keyword arguments giving visit functions.
+
.. method:: Sphinx.add_directive(name, cls, content, arguments, **options)
Register a Docutils directive. *name* must be the prospective directive
Modified: doctools/trunk/sphinx/application.py
==============================================================================
--- doctools/trunk/sphinx/application.py (original)
+++ doctools/trunk/sphinx/application.py Tue Aug 5 12:25:40 2008
@@ -195,8 +195,26 @@
raise ExtensionError('Event %r already present' % name)
self._events[name] = ''
- def add_node(self, node):
+ def add_node(self, node, **kwds):
nodes._add_node_class_names([node.__name__])
+ for key, val in kwds.iteritems():
+ try:
+ visit, depart = val
+ except ValueError:
+ raise ExtensionError('Value for key %r must be a (visit, depart) '
+ 'function tuple' % key)
+ if key == 'html':
+ from sphinx.htmlwriter import HTMLTranslator as translator
+ elif key == 'latex':
+ from sphinx.latexwriter import LaTeXTranslator as translator
+ elif key == 'text':
+ from sphinx.textwriter import TextTranslator as translator
+ else:
+ # ignore invalid keys for compatibility
+ continue
+ setattr(translator, 'visit_'+node.__name__, visit)
+ if depart:
+ setattr(translator, 'depart_'+node.__name__, depart)
def add_directive(self, name, func, content, arguments, **options):
func.content = content
More information about the Python-checkins
mailing list