From 7d10dd72f4aaec0b8ccf8a06bfd98a254df65e0a Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 27 Apr 2025 17:32:44 -0600 Subject: [PATCH 1/2] docs(extending_build.rst): update to match example/todo.py It appears `todo.py` was previously updated shifting some lines down and this caused 5 code examples to be missing 1 or more lines at the end. This was fixed, as well as replacing an old function with a new function that parses directive content into nodes: `parse_content_to_nodes()`. Additionally, clarified when `doctree-resolved` event gets fired so make the example more understandable. --- doc/development/tutorials/extending_build.rst | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/development/tutorials/extending_build.rst b/doc/development/tutorials/extending_build.rst index 4d3606a0a33..442678418cb 100644 --- a/doc/development/tutorials/extending_build.rst +++ b/doc/development/tutorials/extending_build.rst @@ -143,7 +143,7 @@ Looking first at the ``TodolistDirective`` directive: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 24-27 + :lines: 25-29 It's very simple, creating and returning an instance of our ``todolist`` node class. The ``TodolistDirective`` directive itself has neither content nor @@ -153,7 +153,7 @@ directive: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 30-53 + :lines: 30-54 Several important things are covered here. First, as you can see, we're now subclassing the :class:`~sphinx.util.docutils.SphinxDirective` helper class @@ -168,9 +168,8 @@ new unique integer on each call and therefore leads to unique target names. The target node is instantiated without any text (the first two arguments). On creating admonition node, the content body of the directive are parsed using -``self.state.nested_parse``. The first argument gives the content body, and -the second one gives content offset. The third argument gives the parent node -of parsed result, in our case the ``todo`` node. Following this, the ``todo`` +``self.parse_content_to_nodes()``. It has one optional argument +``allow_section_headings`` that defaults to ``False``. Following this, the ``todo`` node is added to the environment. This is needed to be able to create a list of all todo entries throughout the documentation, in the place where the author puts a ``todolist`` directive. For this case, the environment attribute @@ -211,7 +210,7 @@ the :event:`env-purge-doc` event: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 56-61 + :lines: 55-63 Since we store information from source files in the environment, which is persistent, it may become out of date when the source file changes. Therefore, @@ -229,7 +228,7 @@ to be merged: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 64-68 + :lines: 64-70 The other handler belongs to the :event:`doctree-resolved` event: @@ -237,11 +236,12 @@ The other handler belongs to the :event:`doctree-resolved` event: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 71-113 + :lines: 71-118 -The :event:`doctree-resolved` event is emitted at the end of :ref:`phase 3 -(resolving) ` and allows custom resolving to be done. The handler -we have written for this event is a bit more involved. If the +The :event:`doctree-resolved` event is emitted for each document that is about to +be written at the end of :ref:`phase 3 (resolving) ` and allows +custom resolving to be done on that document. The handler we have written for +this event is a bit more involved. If the ``todo_include_todos`` config value (which we'll describe shortly) is false, all ``todo`` and ``todolist`` nodes are removed from the documents. If not, ``todo`` nodes just stay where and how they are. ``todolist`` nodes are @@ -266,7 +266,7 @@ the other parts of our extension. Let's look at our ``setup`` function: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 116- + :lines: 119- The calls in this function refer to the classes and functions we added earlier. What the individual calls do is the following: From 64879f6ad6c44798f6c1ca6be08dceb7151aeac4 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Sun, 27 Apr 2025 18:13:31 -0600 Subject: [PATCH 2/2] docs: fix 2 minor grammar points for readability --- doc/development/tutorials/extending_build.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/tutorials/extending_build.rst b/doc/development/tutorials/extending_build.rst index 442678418cb..6d641d9fac7 100644 --- a/doc/development/tutorials/extending_build.rst +++ b/doc/development/tutorials/extending_build.rst @@ -272,10 +272,10 @@ The calls in this function refer to the classes and functions we added earlier. What the individual calls do is the following: * :meth:`~Sphinx.add_config_value` lets Sphinx know that it should recognize the - new *config value* ``todo_include_todos``, whose default value should be - ``False`` (this also tells Sphinx that it is a boolean value). + new *config value* ``todo_include_todos``, whose default value is + ``False`` (which also tells Sphinx that it is a boolean value). - If the third argument was ``'html'``, HTML documents would be full rebuild if the + If the third argument was ``'html'``, HTML documents would be fully rebuilt if the config value changed its value. This is needed for config values that influence reading (build :ref:`phase 1 (reading) `).