3 files changed, 30 insertions, 4 deletions
diff --git a/doc/development/tutorials/examples/todo.py b/doc/development/tutorials/examples/todo.py
index 6ba39944f..7eee534d0 100644
--- a/doc/development/tutorials/examples/todo.py
+++ b/doc/development/tutorials/examples/todo.py
@@ -70,6 +70,9 @@ def process_todo_nodes(app, doctree, fromdocname):
     # Augment each todo with a backlink to the original location.
     env = app.builder.env
 
+    if not hasattr(env, 'todo_all_todos'):
+        env.todo_all_todos = []
+
     for node in doctree.traverse(todolist):
         if not app.config.todo_include_todos:
             node.replace_self([])
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst
index 2a3aa6408..dcfe42c1a 100644
--- a/doc/development/tutorials/recipe.rst
+++ b/doc/development/tutorials/recipe.rst
@@ -75,7 +75,7 @@ The first thing to examine is the ``RecipeDirective`` directive:
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 17-37
+   :pyobject: RecipeDirective
 
 Unlike :doc:`helloworld` and :doc:`todo`, this directive doesn't derive from
 :class:`docutils.parsers.rst.Directive` and doesn't define a ``run`` method.
@@ -103,7 +103,12 @@ reStructuredText in the body.
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 40-102
+   :pyobject: IngredientIndex
+
+.. literalinclude:: examples/recipe.py
+   :language: python
+   :linenos:
+   :pyobject: RecipeIndex
 
 Both ``IngredientIndex`` and ``RecipeIndex`` are derived from :class:`Index`.
 They implement custom logic to generate a tuple of values that define the
@@ -117,6 +122,10 @@ all it really is is a list of tuples like ``('tomato', 'TomatoSoup', 'test',
 'rec-TomatoSoup',...)``. Refer to the :doc:`domain API guide
 </extdev/domainapi>` for more information on this API.
 
+These index pages can be referred by combination of domain name and its
+``name`` using :rst:role:`ref` role.  For example, ``RecipeIndex`` can be
+referred by ``:ref:`recipe-recipe```.
+
 .. rubric:: The domain
 
 A Sphinx domain is a specialized container that ties together roles,
@@ -126,7 +135,7 @@ creating here.
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 105-155
+   :pyobject: RecipeDomain
 
 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 +173,7 @@ hook the various parts of our extension into Sphinx. Let's look at the
 .. literalinclude:: examples/recipe.py
    :language: python
    :linenos:
-   :lines: 158-
+   :pyobject: setup
 
 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 f4ac85ac9..e27528b5a 100644
--- a/doc/development/tutorials/todo.rst
+++ b/doc/development/tutorials/todo.rst
@@ -107,6 +107,20 @@ is just a "general" node.
    <http://docutils.sourceforge.net/docs/ref/doctree.html>`__ and :ref:`Sphinx
    <nodes>`.
 
+.. attention::
+
+   It is important to know that while you can extend Sphinx without
+   leaving your ``conf.py``, if you declare an inherited node right
+   there, you'll hit an unobvious :py:class:`PickleError`. So if
+   something goes wrong, please make sure that you put inherited nodes
+   into a separate Python module.
+
+   For more details, see:
+
+   - https://github.com/sphinx-doc/sphinx/issues/6751
+   - https://github.com/sphinx-doc/sphinx/issues/1493
+   - https://github.com/sphinx-doc/sphinx/issues/1424
+
 .. rubric:: The directive classes
 
 A directive class is a class deriving usually from