diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 8df819439..65dd7c692 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -437,6 +437,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 6d30ab51a..52c1990be 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -49,6 +49,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 8e94ef4ea..457ecaf03 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -477,7 +477,10 @@ class BuildEnvironment: self.clear_doc(docname) # read all new and changed files - for docname in sorted(added | changed): + docnames = sorted(added | changed) + if app: + app.emit('env-read-docs', self, docnames) + for docname in docnames: yield docname self.read_doc(docname, app=app) diff --git a/tests/test_env_read_docs.py b/tests/test_env_read_docs.py new file mode 100644 index 000000000..2e7033344 --- /dev/null +++ b/tests/test_env_read_docs.py @@ -0,0 +1,52 @@ +# -*- coding: utf-8 -*- +""" + test_env_read_docs + ~~~~~~~~~~~~~~~~~~ + + Test docnames read order modification using the env-read-docs event. + + :copyright: Copyright 2014 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import pickle + +from docutils.parsers.rst.directives.html import MetaBody + +from sphinx import addnodes +from sphinx.versioning import add_uids, merge_doctrees, get_ratio + +from util import test_root, TestApp + +def setup_module(): + pass + +def test_default_docnames_order(): + """By default, docnames are read in alphanumeric order""" + def on_env_read_docs(app, env, docnames): + pass + + app = TestApp(srcdir='(temp)', freshenv=True) + env = app.env + app.connect('env-read-docs', on_env_read_docs) + + msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app) + read_docnames = [docname for docname in it] + assert len(read_docnames) > 1 and read_docnames == sorted(read_docnames) + +def test_inverse_docnames_order(): + """By default, docnames are read in alphanumeric order""" + def on_env_read_docs(app, env, docnames): + docnames.reverse() + + app = TestApp(srcdir='(temp)', freshenv=True) + env = app.env + app.connect('env-read-docs', on_env_read_docs) + + msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app) + read_docnames = [docname for docname in it] + reversed_read_docnames = sorted(read_docnames, reverse=True) + assert len(read_docnames) > 1 and read_docnames == reversed_read_docnames + +def teardown_module(): + (test_root / '_build').rmtree(True)