Add "source-read" event.

Author: birkenfeld

CHANGES

@@ -81,8 +81,8 @@ New features added
   - Added ``Sphinx.add_javascript()`` that adds scripts to load in the
     default HTML template.
 
-  - Added new events: ``env-updated``, ``missing-reference``,
-    ``build-finished``.
+  - Added new events: ``source-read``, ``env-updated``,
+    ``missing-reference``, ``build-finished``.
 
 * Other changes:
 

doc/ext/appapi.rst

@@ -208,6 +208,14 @@ registered event handlers.
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: source-read (app, docname, source)
+
+   Emitted when a source file has been read.  The *source* argument is a list
+   whose single element is the contents of the source file.  You can process the
+   contents and replace this item to implement source-level transformations.
+
+   .. versionadded:: 0.5
+   
 .. event:: doctree-read (app, doctree)
 
    Emitted when a doctree has been parsed and read by the environment, and is

sphinx/application.py

@@ -58,6 +58,7 @@ def __str__(self):
 # List of all known core events. Maps name to arguments description.
 events = {
     'builder-inited': '',
+    'source-read': 'docname, source text',
     'doctree-read': 'the doctree before being pickled',
     'missing-reference': 'env, node, contnode',
     'doctree-resolved': 'doctree, docname',

sphinx/environment.py

@@ -485,8 +485,18 @@ def read_doc(self, docname, src_path=None, save_parsed=True, app=None):
             else:
                 self.warn(docname, 'default role %s not found' %
                           self.config.default_role)
+
+        class SphinxSourceClass(FileInput):
+            def read(self):
+                data = FileInput.read(self)
+                if app:
+                    arg = [data]
+                    app.emit('source-read', docname, arg)
+                    data = arg[0]
+                return data
+
         self.docname = docname
-        doctree = publish_doctree(None, src_path, FileInput,
+        doctree = publish_doctree(None, src_path, SphinxSourceClass,
                                   settings_overrides=self.settings,
                                   reader=SphinxStandaloneReader())
         self.filter_messages(doctree)