diff options
Diffstat (limited to 'doc/development/tutorials/todo.rst')
| -rw-r--r-- | doc/development/tutorials/todo.rst | 25 |
1 files changed, 14 insertions, 11 deletions
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst index c04e14e99..78a37c2fe 100644 --- a/doc/development/tutorials/todo.rst +++ b/doc/development/tutorials/todo.rst @@ -93,7 +93,7 @@ Let's start with the node classes: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 6-19 + :lines: 8-21 Node classes usually don't have to do anything except inherit from the standard docutils classes defined in :mod:`docutils.nodes`. ``todo`` inherits from @@ -120,7 +120,7 @@ Looking first at the ``TodolistDirective`` directive: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 22-25 + :lines: 24-27 It's very simple, creating and returning an instance of our ``todolist`` node class. The ``TodolistDirective`` directive itself has neither content nor @@ -130,15 +130,18 @@ directive: .. literalinclude:: examples/todo.py :language: python :linenos: - :lines: 28-53 - -Several important things are covered here. First, as you can see, you can refer -to the :ref:`build environment instance <important-objects>` using -``self.state.document.settings.env``. Then, to act as a link target (from -``TodolistDirective``), the ``TodoDirective`` directive needs to return a target -node in addition to the ``todo`` node. The target ID (in HTML, this will be the -anchor name) is generated by using ``env.new_serialno`` which returns a new -unique integer on each call and therefore leads to unique target names. The + :lines: 30-53 + +Several important things are covered here. First, as you can see, we're now +subclassing the :class:`~sphinx.util.docutils.SphinxDirective` helper class +instead of the usual :class:`~docutils.parsers.rst.Directive` class. This +gives us access to the :ref:`build environment instance <important-objects>` +using the ``self.env`` property. Without this, we'd have to use the rather +convoluted ``self.state.document.settings.env``. Then, to act as a link target +(from ``TodolistDirective``), the ``TodoDirective`` directive needs to return a +target node in addition to the ``todo`` node. The target ID (in HTML, this will +be the anchor name) is generated by using ``env.new_serialno`` which returns a +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 |