From d7e2a48555783edbf876c6eb9c19e7a6a781f883 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 16 Oct 2008 19:04:45 +0000
Subject: [PATCH] Add "source-read" event.

---
 CHANGES               |  4 ++--
 doc/ext/appapi.rst    |  8 ++++++++
 sphinx/application.py |  1 +
 sphinx/environment.py | 12 +++++++++++-
 4 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index 33118c939..7f9ad3b47 100644
--- a/CHANGES
+++ b/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:
 
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 551a94774..bb8ff7dd4 100644
--- a/doc/ext/appapi.rst
+++ b/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
diff --git a/sphinx/application.py b/sphinx/application.py
index c4a307b86..4ac520fe1 100644
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -58,6 +58,7 @@ class ExtensionError(SphinxError):
 # 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',
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 80736b6af..94f06d87c 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -485,8 +485,18 @@ class BuildEnvironment:
             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)