The `env-updated` event can now return a value, which is interpreted as an iterable of additional docnames that need to be rewritten.

(reference: #1683)

CHANGES

@@ -11,6 +11,8 @@ Features added
 
 * Added ``highlight_options`` configuration value.
 * The ``language`` config value is now available in the HTML templates.
+* The ``env-updated`` event can now return a value, which is interpreted
+  as an iterable of additional docnames that need to be rewritten.
 
 Bugs fixed
 ----------

doc/extdev/appapi.rst

@@ -530,8 +530,15 @@ handlers to the events.  Example:
    Emitted when the :meth:`update` method of the build environment has
    completed, that is, the environment and all doctrees are now up-to-date.
 
+   You can return an iterable of docnames from the handler.  These documents
+   will then be considered updated, and will be (re-)written during the writing
+   phase.
+
    .. versionadded:: 0.5
 
+   .. versionchanged:: 1.3
+      The handlers' return value is now used.
+
 .. event:: html-collect-pages (app)
 
    Emitted when the HTML builder is starting to write non-document pages.  You

sphinx/environment.py

@@ -589,8 +589,12 @@ class BuildEnvironment:
                       self.doc2path(config.master_doc))
 
         self.app = None
-        app.emit('env-updated', self)
-        return docnames
+
+        for retval in app.emit('env-updated', self):
+            if retval is not None:
+                docnames.extend(retval)
+
+        return sorted(docnames)
 
     def _read_serial(self, docnames, app):
         for docname in app.status_iterator(docnames, 'reading sources... ',