From b4b15181b4727c328530b381e91f27be56dd45f6 Mon Sep 17 00:00:00 2001 From: Guillem Barba Date: Thu, 31 Jul 2014 18:28:47 +0200 Subject: [PATCH 1/3] Add env-read-docs event to allow modify docnames list before processing --- doc/extdev/appapi.rst | 8 ++++++++ sphinx/application.py | 1 + sphinx/environment.py | 9 ++++++++- 3 files changed, 17 insertions(+), 1 deletion(-) 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) From 24c5eb6e9cebf038675543b675135303ef3365c0 Mon Sep 17 00:00:00 2001 From: Guillem Barba Date: Mon, 1 Sep 2014 09:19:43 +0200 Subject: [PATCH 2/3] Add unit test for new env-read-docs event --- tests/test_env_read_docs.py | 54 +++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 tests/test_env_read_docs.py diff --git a/tests/test_env_read_docs.py b/tests/test_env_read_docs.py new file mode 100644 index 000000000..0b57815bd --- /dev/null +++ b/tests/test_env_read_docs.py @@ -0,0 +1,54 @@ +# -*- 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): + return docnames + + 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() + return docnames + + 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)[:] + reversed_read_docnames.reverse() + assert len(read_docnames) > 1 and read_docnames == reversed_read_docnames + +def teardown_module(): + (test_root / '_build').rmtree(True) From fe077ea18ba2b8c5618b3ca89b9d97214ca08e2c Mon Sep 17 00:00:00 2001 From: Guillem Barba Date: Sun, 21 Sep 2014 19:50:46 +0200 Subject: [PATCH 3/3] Don't multiply docnames list size per each listener of env-read-docs The env-read-docs listener function doesn't return the modified docnames list but change the list received as parameter. Updated the tests --- sphinx/environment.py | 6 +----- tests/test_env_read_docs.py | 6 ++---- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index a4901a746..38218729f 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -471,11 +471,7 @@ class BuildEnvironment: # read all new and changed files 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 + 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 index 0b57815bd..2e7033344 100644 --- a/tests/test_env_read_docs.py +++ b/tests/test_env_read_docs.py @@ -24,7 +24,7 @@ def setup_module(): def test_default_docnames_order(): """By default, docnames are read in alphanumeric order""" def on_env_read_docs(app, env, docnames): - return docnames + pass app = TestApp(srcdir='(temp)', freshenv=True) env = app.env @@ -38,7 +38,6 @@ def test_inverse_docnames_order(): """By default, docnames are read in alphanumeric order""" def on_env_read_docs(app, env, docnames): docnames.reverse() - return docnames app = TestApp(srcdir='(temp)', freshenv=True) env = app.env @@ -46,8 +45,7 @@ def test_inverse_docnames_order(): 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)[:] - reversed_read_docnames.reverse() + reversed_read_docnames = sorted(read_docnames, reverse=True) assert len(read_docnames) > 1 and read_docnames == reversed_read_docnames def teardown_module():