From be080234bb17bb994ba19d4015ee5376dba8874b Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sun, 13 Apr 2008 08:20:11 +0000
Subject: [PATCH] Support Sphinx.add_transform().

---
 CHANGES               |  4 ++++
 doc/ext/appapi.rst    |  5 +++++
 sphinx/application.py |  4 ++++
 sphinx/environment.py | 27 +++++++++++++--------------
 4 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/CHANGES b/CHANGES
index 4c560b13c..e75df843a 100644
--- a/CHANGES
+++ b/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.
 
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 9e5e303ab..3cbdf0533 100644
--- a/doc/ext/appapi.rst
+++ b/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
diff --git a/sphinx/application.py b/sphinx/application.py
index 0e9637224..5ea08edef 100644
--- a/sphinx/application.py
+++ b/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)
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 78b05be37..17532589d 100644
--- a/sphinx/environment.py
+++ b/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,
-                     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 @@ 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]: