diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 1a0b95bf2..c6f5ee4c0 100644 --- a/doc/extdev/appapi.rst +++ b/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 diff --git a/sphinx/application.py b/sphinx/application.py index dc4563e0c..7f2c382e9 100644 --- a/sphinx/application.py +++ b/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', diff --git a/sphinx/environment.py b/sphinx/environment.py index 5b92c0376..a4901a746 100644 --- a/sphinx/environment.py +++ b/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)