4 files changed, 30 insertions, 8 deletions

diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py
index 2464302da..c7317578b 100644
--- a/doc/development/tutorials/examples/recipe.py
+++ b/doc/development/tutorials/examples/recipe.py
@@ -4,8 +4,7 @@ from docutils.parsers.rst import directives
 
 from sphinx import addnodes
 from sphinx.directives import ObjectDescription
-from sphinx.domains import Domain
-from sphinx.domains import Index
+from sphinx.domains import Domain, Index
 from sphinx.roles import XRefRole
 from sphinx.util.nodes import make_refnode
 
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
index 7eee534d0..59e394ee8 100644
--- a/doc/development/tutorials/examples/todo.py
+++ b/doc/development/tutorials/examples/todo.py
@@ -61,6 +61,13 @@ def purge_todos(app, env, docname):
                           if todo['docname'] != docname]
 
 
+def merge_todos(app, env, docnames, other):
+    if not hasattr(env, 'todo_all_todos'):
+        env.todo_all_todos = []
+    if hasattr(other, 'todo_all_todos'):
+        env.todo_all_todos.extend(other.todo_all_todos)
+
+
 def process_todo_nodes(app, doctree, fromdocname):
     if not app.config.todo_include_todos:
         for node in doctree.traverse(todo):
@@ -119,6 +126,7 @@ def setup(app):
     app.add_directive('todolist', TodolistDirective)
     app.connect('doctree-resolved', process_todo_nodes)
     app.connect('env-purge-doc', purge_todos)
+    app.connect('env-merge-info', merge_todos)
 
     return {
         'version': '0.1',
diff --git a/doc/development/tutorials/index.rst b/doc/development/tutorials/index.rst
index a79e6a8b6..be126b3ca 100644
--- a/doc/development/tutorials/index.rst
+++ b/doc/development/tutorials/index.rst
@@ -1,8 +1,11 @@
+.. _extension-tutorials-index:
+
 Extension tutorials
 ===================
 
 Refer to the following tutorials to get started with extension development.
 
+
 .. toctree::
    :caption: Directive tutorials
    :maxdepth: 1
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst
index e27528b5a..21d9e74be 100644
--- a/doc/development/tutorials/todo.rst
+++ b/doc/development/tutorials/todo.rst
@@ -38,9 +38,10 @@ For that, we will need to add the following elements to Sphinx:
   with the extension name, in order to stay unique) that controls whether todo
   entries make it into the output.
 
-* New event handlers: one for the :event:`doctree-resolved` event, to replace
-  the todo and todolist nodes, and one for :event:`env-purge-doc` (the reason
-  for that will be covered later).
+* New event handlers: one for the :event:`doctree-resolved` event, to
+  replace the todo and todolist nodes, one for :event:`env-merge-info`
+  to merge intermediate results from parallel builds, and one for
+  :event:`env-purge-doc` (the reason for that will be covered later).
 
 
 Prerequisites
@@ -212,12 +213,23 @@ Here we clear out all todos whose docname matches the given one from the
 ``todo_all_todos`` list.  If there are todos left in the document, they will be
 added again during parsing.
 
+The next handler, for the :event:`env-merge-info` event, is used
+during parallel builds. As during parallel builds all threads have
+their own ``env``, there's multiple ``todo_all_todos`` lists that need
+to be merged:
+
+.. literalinclude:: examples/todo.py
+   :language: python
+   :linenos:
+   :lines: 64-68
+
+
 The other handler belongs to the :event:`doctree-resolved` event:
 
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 64-103
+   :lines: 71-113
 
 The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3
 (resolving) <build-phases>` and allows custom resolving to be done. The handler
@@ -230,7 +242,7 @@ where they come from.  The list items are composed of the nodes from the
 ``todo`` entry and docutils nodes created on the fly: a paragraph for each
 entry, containing text that gives the location, and a link (reference node
 containing an italic node) with the backreference. The reference URI is built
-by :meth:`sphinx.builders.Builder.get_relative_uri`` which creates a suitable
+by :meth:`sphinx.builders.Builder.get_relative_uri` which creates a suitable
 URI depending on the used builder, and appending the todo node's (the target's)
 ID as the anchor name.
 
@@ -245,7 +257,7 @@ the other parts of our extension. Let's look at our ``setup`` function:
 .. literalinclude:: examples/todo.py
    :language: python
    :linenos:
-   :lines: 106-
+   :lines: 116-
 
 The calls in this function refer to the classes and functions we added earlier.
 What the individual calls do is the following: