diff options
Diffstat (limited to 'doc/development/tutorials')
| -rw-r--r-- | doc/development/tutorials/examples/recipe.py | 6 | ||||
| -rw-r--r-- | doc/development/tutorials/examples/todo.py | 16 | ||||
| -rw-r--r-- | doc/development/tutorials/recipe.rst | 6 | ||||
| -rw-r--r-- | doc/development/tutorials/todo.rst | 25 |
4 files changed, 25 insertions, 28 deletions
diff --git a/doc/development/tutorials/examples/recipe.py b/doc/development/tutorials/examples/recipe.py index 9c54a93f0..6aa17077c 100644 --- a/doc/development/tutorials/examples/recipe.py +++ b/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) diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py index d46f90821..2bcf6788f 100644 --- a/doc/development/tutorials/examples/todo.py +++ b/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, diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst index 25a2c0732..2a3aa6408 100644 --- a/doc/development/tutorials/recipe.rst +++ b/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 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 |