diff options
| author | Julien Palard <julien@palard.fr> | 2020-07-06 17:55:03 +0200 |
|---|---|---|
| committer | Julien Palard <julien@palard.fr> | 2020-07-06 17:55:55 +0200 |
| commit | 418576ddd1370f708a866e890935341d849be700 (patch) | |
| tree | 140274d01d316259ca48fbe487edd4f3e8a03f64 /doc/development/tutorials/todo.rst | |
| parent | 44ee514fbe380fb3b9a44c3c64a1106dbc644b71 (diff) | |
| download | sphinx-git-418576ddd1370f708a866e890935341d849be700.tar.gz | |
Doc: Add missing 'env-merge-info' to the todo tutorial.
Diffstat (limited to 'doc/development/tutorials/todo.rst')
| -rw-r--r-- | doc/development/tutorials/todo.rst | 22 |
1 files changed, 17 insertions, 5 deletions
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index 699ed58d0..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 @@ -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: |