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] 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): def process_todo_nodes(app, doctree, fromdocname):
if not app.config.todo_include_todos: if not app.config.todo_include_todos:
for node in doctree.traverse(todo): for node in doctree.traverse(todo):
@ -119,6 +126,7 @@ def setup(app):
app.add_directive('todolist', TodolistDirective) app.add_directive('todolist', TodolistDirective)
app.connect('doctree-resolved', process_todo_nodes) app.connect('doctree-resolved', process_todo_nodes)
app.connect('env-purge-doc', purge_todos) app.connect('env-purge-doc', purge_todos)
app.connect('env-merge-info', merge_todos)
return { return {
'version': '0.1', '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 with the extension name, in order to stay unique) that controls whether todo
entries make it into the output. entries make it into the output.
* New event handlers: one for the :event:`doctree-resolved` event, to replace * New event handlers: one for the :event:`doctree-resolved` event, to
the todo and todolist nodes, and one for :event:`env-purge-doc` (the reason replace the todo and todolist nodes, one for :event:`env-merge-info`
for that will be covered later). to merge intermediate results from parallel builds, and one for
:event:`env-purge-doc` (the reason for that will be covered later).
Prerequisites 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 ``todo_all_todos`` list. If there are todos left in the document, they will be
added again during parsing. 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: The other handler belongs to the :event:`doctree-resolved` event:
.. literalinclude:: examples/todo.py .. literalinclude:: examples/todo.py
:language: python :language: python
:linenos: :linenos:
:lines: 64-103 :lines: 71-113
The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3 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 (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 .. literalinclude:: examples/todo.py
:language: python :language: python
:linenos: :linenos:
:lines: 106- :lines: 116-
The calls in this function refer to the classes and functions we added earlier. The calls in this function refer to the classes and functions we added earlier.
What the individual calls do is the following: What the individual calls do is the following: