Georg Brandl  committed d51d271

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

  • Participants
  • Parent commits 43939af

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:

File doc/ext/appapi.rst

    Emitted when the builder object has been created.  It is available as
+.. 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)

File sphinx/

 # 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',

File sphinx/

         # clear all files no longer present
         for docname in removed:
+            if app:
+                app.emit('env-purge-doc', self, 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)
         if src_path is None: