Georg Brandl avatar Georg Brandl committed d51d271

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

Comments (0)

Files changed (4)

     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

    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)
 .. 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

 # 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

 
         # 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
         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:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.