merge with trunk

3 files changed, 22 insertions, 18 deletions

diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 0a3dae8fb..754f22eb4 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -123,26 +123,28 @@ the following public API:
 
    .. versionadded:: 0.6
 
-.. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
+.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')
 
-   This method is a very convenient way to add a new type of information that
+   This method is a very convenient way to add a new :term:`object` type that
    can be cross-referenced.  It will do this:
 
-   * Create a new directive (called *directivename*) for a :term:`description
-     unit`.  It will automatically add index entries if *indextemplate* is
-     nonempty; if given, it must contain exactly one instance of ``%s``.  See
-     the example below for how the template will be interpreted.
+   * Create a new directive (called *directivename*) for documenting an object.
+     It will automatically add index entries if *indextemplate* is nonempty; if
+     given, it must contain exactly one instance of ``%s``.  See the example
+     below for how the template will be interpreted.
    * Create a new role (called *rolename*) to cross-reference to these
-     description units.
+     object descriptions.
    * If you provide *parse_node*, it must be a function that takes a string and
      a docutils node, and it must populate the node with children parsed from
      the string.  It must then return the name of the item to be used in
      cross-referencing and index entries.  See the :file:`ext.py` file in the
      source for this documentation for an example.
+   * The *objname* (if not given, will default to *directivename*) names the
+     type of object.  It is used when listing objects, e.g. in search results.
 
    For example, if you have this call in a custom Sphinx extension::
 
-      app.add_description_unit('directive', 'dir', 'pair: %s; directive')
+      app.add_object_type('directive', 'dir', 'pair: %s; directive')
 
    you can use this markup in your documents::
 
@@ -164,12 +166,15 @@ the following public API:
    ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use
    ``docutils.nodes.generated`` if you want no further text decoration).
 
-   For the role content, you have the same options as for standard Sphinx roles
-   (see :ref:`xref-syntax`).
+   For the role content, you have the same syntactical possibilities as for
+   standard Sphinx roles (see :ref:`xref-syntax`).
 
-.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None)
+   This method is also available under the deprecated alias
+   :meth:`add_description_unit`.
 
-   This method is very similar to :meth:`add_description_unit` except that the
+.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
+
+   This method is very similar to :meth:`add_object_type` except that the
    directive it generates must be empty, and will produce no output.
 
    That means that you can add semantic targets to your sources, and refer to
diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst
index bb11bfe2f..3ace26871 100644
--- a/doc/ext/builderapi.rst
+++ b/doc/ext/builderapi.rst
@@ -13,7 +13,6 @@ Writing new builders
 
    These methods are predefined and will be called from the application:
 
-   .. automethod:: load_env
    .. automethod:: get_relative_uri
    .. automethod:: build_all
    .. automethod:: build_specific
diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst
index c44748d23..43d12ccb6 100644
--- a/doc/ext/tutorial.rst
+++ b/doc/ext/tutorial.rst
@@ -201,8 +201,7 @@ The ``todo`` directive function looks like this::
        def run(self):
            env = self.state.document.settings.env
 
-           targetid = "todo-%s" % env.index_num
-           env.index_num += 1
+           targetid = "todo-%s" % env.new_serialno('todo')
            targetnode = nodes.target('', '', ids=[targetid])
 
            ad = make_admonition(todo, self.name, [_('Todo')], self.options,
@@ -225,9 +224,10 @@ to the build environment instance using ``self.state.document.settings.env``.
 
 Then, to act as a link target (from the todolist), the todo 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.index_num`` which is
-persistent between directive calls and therefore leads to unique target names.
-The target node is instantiated without any text (the first two arguments).
+will be the anchor name) is generated by using ``env.new_serialno`` which is
+returns a new integer directive on each call and therefore leads to unique
+target names.  The target node is instantiated without any text (the first two
+arguments).
 
 An admonition is created using a standard docutils function (wrapped in Sphinx
 for docutils cross-version compatibility).  The first argument gives the node