Document env-merge-info event, add parallel reading to changelog

3 files changed, 23 insertions, 1 deletions

diff --git a/CHANGES b/CHANGES
index cec06655..895f2143 100644
--- a/CHANGES
+++ b/CHANGES
@@ -28,6 +28,10 @@ Features added
 * Add support for docutils 0.12
 * Added ``sphinx.ext.napoleon`` extension for NumPy and Google style docstring
   support.
+* Added support for parallel reading (parsing) of source files with the
+  `sphinx-build -j` option.  Third-party extensions will need to be checked for
+  compatibility and may need to be adapted if they store information in the
+  build environment object.  See `env-merge-info`.
 * Added the `any` role that can be used to find a cross-reference of
   *any* type in *any* domain.  Custom domains should implement the new
   `Domain.resolve_any_xref` method to make this work properly.
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index d65f91a5..d5d1c033 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -493,6 +493,24 @@ handlers to the events.  Example:
    Here is the place to replace custom nodes that don't have visitor methods in
    the writers, so that they don't cause errors when the writers encounter them.
 
+.. event:: env-merge-info (env, docnames, other)
+
+   This event is only emitted when parallel reading of documents is enabled.  It
+   is emitted once for every subprocess that has read some documents.
+
+   You must handle this event in an extension that stores data in the
+   environment in a custom location.  Otherwise the environment in the main
+   process will not be aware of the information stored in the subprocess.
+
+   *other* is the environment object from the subprocess, *env* is the
+   environment from the main process.  *docnames* is a set of document names
+   that have been read in the subprocess.
+
+   For a sample of how to deal with this event, look at the standard
+   ``sphinx.ext.viewcode`` extension.
+
+   .. versionadded:: 1.3
+
 .. event:: env-updated (app, env)
 
    Emitted when the :meth:`update` method of the build environment has
diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py
index 6ebaeb79..66d4c677 100644
--- a/sphinx/domains/__init__.py
+++ b/sphinx/domains/__init__.py
@@ -204,7 +204,7 @@ class Domain(object):
 
     def merge_domaindata(self, docnames, otherdata):
         """Merge in data regarding *docnames* from a different domaindata
-        inventory.
+        inventory (coming from a subprocess in parallel builds).
         """
         raise NotImplementedError('merge_domaindata must be implemented in %s '
                                   'to be able to do parallel builds!' %