#306: Added :event:env-get-outdated event.

CHANGES

@@ -67,6 +67,8 @@ Release 1.1 (in development)
 * #259: HTML table rows now have even/odd CSS classes to enable
   "Zebra styling".
 
+* #306: Added :event:`env-get-outdated` event.
+
 * C++ domain now supports array definitions.
 
 

doc/ext/appapi.rst

@@ -352,6 +352,15 @@ registered event handlers.
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: env-get-outdated (app, env, added, changed, removed)
+
+   Emitted when the environment determines which source files have changed and
+   should be re-read.  *added*, *changed* and *removed* are sets of docnames
+   that the environment has determined.  You can return a list of docnames to
+   re-read in addition to these.
+
+   .. versionadded:: 1.1
+
 .. event:: env-purge-doc (app, env, docname)
 
    Emitted when all traces of a source file should be cleaned from the

sphinx/application.py

@@ -40,6 +40,7 @@ from sphinx.util.console import bold
 # List of all known core events. Maps name to arguments description.
 events = {
     'builder-inited': '',
+    'env-get-outdated': 'env, added, changed, removed',
     'env-purge-doc': 'env, docname',
     'source-read': 'docname, source text',
     'doctree-read': 'the doctree before being pickled',

sphinx/environment.py

@@ -548,6 +548,10 @@ class BuildEnvironment:
 
         added, changed, removed = self.get_outdated_files(config_changed)
 
+        # allow user intervention as well
+        for docs in app.emit('env-get-outdated', self, added, changed, removed):
+            changed.update(set(docs) & self.found_docs)
+
         # if files were added or removed, all documents with globbed toctrees
         # must be reread
         if added or removed: