Add env-read-docs event to allow modify docnames list before processing

doc/extdev/appapi.rst

@@ -422,6 +422,14 @@ handlers to the events.  Example:
 
    .. versionadded:: 0.5
 
+.. event:: env-read-docs (app, env, docnames)
+
+   Emited after get the list of all added and changed files and just before
+   read them. It allow extension author modify docnames list before processing;
+   reordering, append and remove.
+
+   .. versionadded:: 1.3.0
+
 .. event:: source-read (app, docname, source)
 
    Emitted when a source file has been read.  The *source* argument is a list

sphinx/application.py

@@ -48,6 +48,7 @@ events = {
     'builder-inited': '',
     'env-get-outdated': 'env, added, changed, removed',
     'env-purge-doc': 'env, docname',
+    'env-read-docs': 'env, docnames',
     'source-read': 'docname, source text',
     'doctree-read': 'the doctree before being pickled',
     'missing-reference': 'env, node, contnode',

sphinx/environment.py

@@ -469,7 +469,14 @@ class BuildEnvironment:
                 self.clear_doc(docname)
 
             # read all new and changed files
-            for docname in sorted(added | changed):
+            docnames = sorted(added | changed)
+            if app:
+                new_docnames = []
+                for mod_docnames in app.emit('env-read-docs', self, docnames):
+                    new_docnames.extend(mod_docnames)
+                if new_docnames:
+                    docnames = new_docnames
+            for docname in docnames:
                 yield docname
                 self.read_doc(docname, app=app)