Rename env-read-docs to env-before-read-docs, add changelog entry and fixup tests.

CHANGES

@@ -73,6 +73,8 @@ Features added
 * #623: `sphinx.ext.viewcode` supports imported function/class aliases.
 * PR#275: `sphinx.ext.intersphinx` supports multiple target for the
   inventory. Thanks to Brigitta Sipocz.
+* PR#261: Added the `env-before-read-docs` event that can be connected to modify
+  the order of documents before they are read by the environment.
 * #1284: Program options documented with :rst:dir:`option` can now start with
   ``+``.
 

doc/extdev/appapi.rst

@@ -437,13 +437,17 @@ handlers to the events.  Example:
 
    .. versionadded:: 0.5
 
-.. event:: env-read-docs (app, env, docnames)
+.. event:: env-before-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.
+   Emitted after the environment has determined the list of all added and
+   changed files and just before it reads them.  It allows extension authors to
+   reorder the list of docnames (*inplace*) before processing, or add more
+   docnames that Sphinx did not consider changed.
 
-   .. versionadded:: 1.3.0
+   You can also remove document names; do this with caution since it will make
+   Sphinx treat changed files as unchanged.
+
+   .. versionadded:: 1.3
 
 .. event:: source-read (app, docname, source)
 

sphinx/application.py

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

sphinx/environment.py

@@ -479,7 +479,7 @@ class BuildEnvironment:
             # read all new and changed files
             docnames = sorted(added | changed)
             if app:
-                app.emit('env-read-docs', self, docnames)
+                app.emit('env-before-read-docs', self, docnames)
             for docname in docnames:
                 yield docname
                 self.read_doc(docname, app=app)

tests/test_env_read_docs.py

@@ -1,52 +0,0 @@
-# -*- 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)

tests/test_environment.py

@@ -103,6 +103,28 @@ def test_second_update():
     assert 'autodoc' not in env.found_docs
 
 
+def test_env_read_docs():
+    """By default, docnames are read in alphanumeric order"""
+    def on_env_read_docs_1(app, env, docnames):
+        pass
+
+    app.connect('env-before-read-docs', on_env_read_docs_1)
+
+    msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app)
+    read_docnames = [docname for docname in it]
+    assert len(read_docnames) > 2 and read_docnames == sorted(read_docnames)
+
+    def on_env_read_docs_2(app, env, docnames):
+        docnames.reverse()
+
+    app.connect('env-before-read-docs', on_env_read_docs_2)
+
+    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) > 2 and read_docnames == reversed_read_docnames
+
+
 def test_object_inventory():
     refs = env.domaindata['py']['objects']