[Python-checkins] r62317 - in doctools/trunk: CHANGES doc/ext/appapi.rst sphinx/application.py sphinx/environment.py
georg.brandl
python-checkins at python.org
Sun Apr 13 10:20:12 CEST 2008
Author: georg.brandl
Date: Sun Apr 13 10:20:11 2008
New Revision: 62317
Log:
Support Sphinx.add_transform().
Modified:
doctools/trunk/CHANGES
doctools/trunk/doc/ext/appapi.rst
doctools/trunk/sphinx/application.py
doctools/trunk/sphinx/environment.py
Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES (original)
+++ doctools/trunk/CHANGES Sun Apr 13 10:20:11 2008
@@ -5,6 +5,10 @@
It works like ``add_description_unit`` but the directive will only
create a target and no output.
+* sphinx.application: Support a new method, ``add_transform``.
+ It takes a standard docutils ``Transform`` subclass which is then
+ applied by Sphinx' reader on parsing reST document trees.
+
* sphinx.ext.autodoc: Don't check ``__module__`` for explicitly given
members. Remove "self" in class constructor argument list.
Modified: doctools/trunk/doc/ext/appapi.rst
==============================================================================
--- doctools/trunk/doc/ext/appapi.rst (original)
+++ doctools/trunk/doc/ext/appapi.rst Sun Apr 13 10:20:11 2008
@@ -117,6 +117,11 @@
(Of course, the element following the ``topic`` directive needn't be a
section.)
+.. method:: Sphinx.add_transform(transform)
+
+ Add the standard docutils :class:`Transform` subclass *transform* to the list
+ of transforms that are applied after Sphinx parses a reST document.
+
.. method:: Sphinx.connect(event, callback)
Register *callback* to be called when *event* is emitted. For details on
Modified: doctools/trunk/sphinx/application.py
==============================================================================
--- doctools/trunk/sphinx/application.py (original)
+++ doctools/trunk/sphinx/application.py Sun Apr 13 10:20:11 2008
@@ -22,6 +22,7 @@
from sphinx.config import Config
from sphinx.builder import builtin_builders
from sphinx.directives import desc_directive, target_directive, additional_xref_types
+from sphinx.environment import SphinxStandaloneReader
from sphinx.util.console import bold
@@ -213,3 +214,6 @@
roles.register_canonical_role(rolename, xfileref_role)
if ref_nodeclass is not None:
innernodetypes[rolename] = ref_nodeclass
+
+ def add_transform(self, transform):
+ SphinxStandaloneReader.transforms.append(transform)
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py (original)
+++ doctools/trunk/sphinx/environment.py Sun Apr 13 10:20:11 2008
@@ -131,17 +131,18 @@
node.replace_self(node.children[0])
-class MyStandaloneReader(standalone.Reader):
+class SphinxStandaloneReader(standalone.Reader):
"""
Add our own transforms.
"""
+ transforms = [DefaultSubstitutions, MoveModuleTargets,
+ FilterMessages, HandleCodeBlocks]
def get_transforms(self):
tf = standalone.Reader.get_transforms(self)
- return tf + [DefaultSubstitutions, MoveModuleTargets,
- FilterMessages, HandleCodeBlocks]
+ return tf + self.transforms
-class MyContentsFilter(ContentsFilter):
+class SphinxContentsFilter(ContentsFilter):
"""
Used with BuildEnvironment.add_toc_from() to discard cross-file links
within table-of-contents link nodes.
@@ -156,10 +157,6 @@
The environment in which the ReST files are translated.
Stores an inventory of cross-file targets and provides doctree
transformations to resolve links to them.
-
- Not all doctrees are stored in the environment, only those of files
- containing a "toctree" directive, because they have to change if sections
- are edited in other files. This keeps the environment size moderate.
"""
# --------- ENVIRONMENT PERSISTENCE ----------------------------------------
@@ -428,11 +425,13 @@
del self.images[imgsrc]
- # --------- SINGLE FILE BUILDING -------------------------------------------
+ # --------- SINGLE FILE READING --------------------------------------------
def read_doc(self, docname, src_path=None, save_parsed=True, app=None):
- """Parse a file and add/update inventory entries for the doctree.
- If srcpath is given, read from a different source file."""
+ """
+ Parse a file and add/update inventory entries for the doctree.
+ If srcpath is given, read from a different source file.
+ """
# remove all inventory entries for that file
self.clear_doc(docname)
@@ -442,7 +441,7 @@
self.docname = docname
doctree = publish_doctree(None, src_path, FileInput,
settings_overrides=self.settings,
- reader=MyStandaloneReader())
+ reader=SphinxStandaloneReader())
self.process_dependencies(docname, doctree)
self.process_images(docname, doctree)
self.process_metadata(docname, doctree)
@@ -553,7 +552,7 @@
"""
for node in document.traverse(nodes.section):
titlenode = nodes.title()
- visitor = MyContentsFilter(document)
+ visitor = SphinxContentsFilter(document)
node[0].walkabout(visitor)
titlenode += visitor.get_entry_text()
self.titles[docname] = titlenode
@@ -619,7 +618,7 @@
title = subnode[0]
# copy the contents of the section title, but without references
# and unnecessary stuff
- visitor = MyContentsFilter(document)
+ visitor = SphinxContentsFilter(document)
title.walkabout(visitor)
nodetext = visitor.get_entry_text()
if not numentries[0]:
More information about the Python-checkins
mailing list