Support Sphinx.add_transform().

CHANGES

@@ -5,6 +5,10 @@ Changes in trunk
   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.
 

doc/ext/appapi.rst

@@ -117,6 +117,11 @@ the following public API:
    (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

sphinx/application.py

@@ -22,6 +22,7 @@ from sphinx.roles import xfileref_role, innernodetypes
 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 @@ class Sphinx(object):
         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)

sphinx/environment.py

@@ -131,17 +131,18 @@ class HandleCodeBlocks(Transform):
                 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,
+        return tf + self.transforms
-                     FilterMessages, HandleCodeBlocks]
 
 
-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 @@ class BuildEnvironment:
     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 @@ class BuildEnvironment:
                 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 @@ class BuildEnvironment:
         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 @@ class BuildEnvironment:
         """
         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 @@ class BuildEnvironment:
                 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]: