Add env-purge-doc event. Add some examples for event usage.

CHANGES

@@ -121,7 +121,7 @@ New features added
     default HTML template.
 
   - Added new events: ``source-read``, ``env-updated``,
-    ``missing-reference``, ``build-finished``.
+    ``env-purge-doc``, ``missing-reference``, ``build-finished``.
 
 * Other changes:
 

doc/ext/appapi.rst

@@ -208,12 +208,29 @@ registered event handlers.
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: env-purge-doc (app, env, docname)
+
+   Emitted when all traces of a source file should be cleaned from the
+   environment, that is, if the source file is removed or before it is freshly
+   read.  This is for extensions that keep their own caches in attributes of the
+   environment.
+
+   For example, there is a cache of all modules on the environment.  When a
+   source file has been changed, the cache's entries for the file are cleared,
+   since the module declarations could have been removed from the file.
+
+   .. versionadded:: 0.5
+   
 .. 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.
 
+   For example, if you want to use ``$`` signs to delimit inline math, like in
+   LaTeX, you can use a regular expression to replace ``$...$`` by
+   ``:math:`...```.
+
    .. versionadded:: 0.5
    
 .. event:: doctree-read (app, doctree)
@@ -241,7 +258,11 @@ registered event handlers.
 .. event:: doctree-resolved (app, doctree, docname)
 
    Emitted when a doctree has been "resolved" by the environment, that is, all
-   references have been resolved and TOCs have been inserted.
+   references have been resolved and TOCs have been inserted.  The *doctree* can
+   be modified in place.
+
+   Here is the place to replace custom nodes that don't have visitor methods in
+   the writers, so that they don't cause errors when the writers encounter them.
 
 .. event:: env-updated (app, env)
 

sphinx/application.py

@@ -59,6 +59,7 @@ class ExtensionError(SphinxError):
 # List of all known core events. Maps name to arguments description.
 events = {
     'builder-inited': '',
+    'env-purge-doc': 'env, docname',
     'source-read': 'docname, source text',
     'doctree-read': 'the doctree before being pickled',
     'missing-reference': 'env, node, contnode',

sphinx/environment.py

@@ -460,6 +460,8 @@ class BuildEnvironment:
 
         # clear all files no longer present
         for docname in removed:
+            if app:
+                app.emit('env-purge-doc', self, docname)
             self.clear_doc(docname)
 
         # read all new and changed files
@@ -490,6 +492,8 @@ class BuildEnvironment:
         If srcpath is given, read from a different source file.
         """
         # remove all inventory entries for that file
+        if app:
+            app.emit('env-purge-doc', self, docname)
         self.clear_doc(docname)
 
         if src_path is None: