IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7922 from JulienPalard/tuto-todo

Browse Source 
Doc: Add missing 'env-merge-info' to the todo tutorial.
This commit is contained in:
Takeshi KOMIYA 2020-07-07 01:25:22 +09:00 committed by GitHub
commit 533b4ac7d6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 25 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/development/tutorials/examples/todo.py
View File

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

22
doc/development/tutorials/todo.rst
View File

@ -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: