docs: Address further review comments

todo:
- Subclass SphinxDirective instead of Directive

recipe:
- Remove unnecessary '__init__' methods

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/development/tutorials/examples/recipe.py

@@ -44,9 +44,6 @@ class IngredientIndex(Index):
     localname = 'Ingredient Index'
     shortname = 'Ingredient'
 
-    def __init__(self, *args, **kwargs):
-        super(IngredientIndex, self).__init__(*args, **kwargs)
-
     def generate(self, docnames=None):
         content = defaultdict(list)
 
@@ -84,9 +81,6 @@ class RecipeIndex(Index):
     localname = 'Recipe Index'
     shortname = 'Recipe'
 
-    def __init__(self, *args, **kwargs):
-        super(RecipeIndex, self).__init__(*args, **kwargs)
-
     def generate(self, docnames=None):
         content = defaultdict(list)
 

doc/development/tutorials/examples/todo.py

@@ -1,5 +1,7 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
+
+from sphinx.util.docutils import SphinxDirective
 from sphinx.locale import _
 
 
@@ -25,26 +27,24 @@ class TodolistDirective(Directive):
         return [todolist('')]
 
 
-class TodoDirective(Directive):
+class TodoDirective(SphinxDirective):
 
     # this enables content in the directive
     has_content = True
 
     def run(self):
-        env = self.state.document.settings.env
-
-        targetid = 'todo-%d' % env.new_serialno('todo')
+        targetid = 'todo-%d' % self.env.new_serialno('todo')
         targetnode = nodes.target('', '', ids=[targetid])
 
         todo_node = todo('\n'.join(self.content))
         todo_node += nodes.title(_('Todo'), _('Todo'))
         self.state.nested_parse(self.content, self.content_offset, todo_node)
 
-        if not hasattr(env, 'todo_all_todos'):
-            env.todo_all_todos = []
+        if not hasattr(self.env, 'todo_all_todos'):
+            self.env.todo_all_todos = []
 
-        env.todo_all_todos.append({
-            'docname': env.docname,
+        self.env.todo_all_todos.append({
+            'docname': self.env.docname,
             'lineno': self.lineno,
             'todo': todo_node.deepcopy(),
             'target': targetnode,

doc/development/tutorials/recipe.rst

@@ -103,7 +103,7 @@ reStructuredText in the body.
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 40-108
+   :lines: 40-102
 
 Both ``IngredientIndex`` and ``RecipeIndex`` are derived from :class:`Index`.
 They implement custom logic to generate a tuple of values that define the
@@ -126,7 +126,7 @@ creating here.
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 111-161
+   :lines: 105-155
 
 There are some interesting things to note about this ``recipe`` domain and domains
 in general. Firstly, we actually register our directives, roles and indices
@@ -164,7 +164,7 @@ hook the various parts of our extension into Sphinx. Let's look at the
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 164-
+   :lines: 158-
 
 This looks a little different to what we're used to seeing. There are no calls
 to :meth:`~Sphinx.add_directive` or even :meth:`~Sphinx.add_role`. Instead, we

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
+   :lines: 30-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
+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