Merged in guillemNaN/sphinx (pull request #261)

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

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

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',

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)
 

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)