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)

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