Finish renaming description units to object (description)s.

doc/concepts.rst

@@ -166,7 +166,7 @@ The special document names (and pages generated for them) are:
   respectively.
 
   The general index is populated with entries from modules, all index-generating
-  :ref:`description units <desc-units>`, and from :dir:`index` directives.
+  :ref:`object descriptions <desc-units>`, and from :dir:`index` directives.
 
   The module index contains one entry per :dir:`module` directive.
 

doc/config.rst

@@ -298,8 +298,8 @@ Project information
 .. confval:: add_module_names
 
    A boolean that decides whether module names are prepended to all
-   :term:`description unit` titles, e.g. for :dir:`function` directives.
+   :term:`object` names (for object types where a "module" of some kind is
-   Default is ``True``.
+   defined), e.g. for :dir:`function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 

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
+   * Create a new directive (called *directivename*) for documenting an object.
-     unit`.  It will automatically add index entries if *indextemplate* is
+     It will automatically add index entries if *indextemplate* is nonempty; if
-     nonempty; if given, it must contain exactly one instance of ``%s``.  See
+     given, it must contain exactly one instance of ``%s``.  See the example
-     the example below for how the template will be interpreted.
+     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
+   For the role content, you have the same syntactical possibilities as for
-   (see :ref:`xref-syntax`).
+   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

doc/glossary.rst

@@ -19,17 +19,17 @@ Glossary
       the :term:`source directory`, but can be set differently with the **-c**
       command-line option.
 
-   description unit
-      The basic building block of Sphinx documentation.  Every "description
-      directive" (e.g. :dir:`function` or :dir:`describe`) creates such a unit;
-      and most units can be cross-referenced to.
-
    environment
       A structure where information about all documents under the root is saved,
       and used for cross-referencing.  The environment is pickled after the
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   object
+      The basic building block of Sphinx documentation.  Every "object
+      directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
+      and most objects can be cross-referenced to.
+
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.

doc/markup/desc.rst

@@ -67,10 +67,12 @@ The directives you can use for module declarations are:
 
 .. _desc-units:
 
-Object description units
+Object descriptions
-------------------------
+-------------------
 
-There are a number of directives used to describe specific features provided by
+.. XXX generalize for domains
+
+There are a number of directives used to describe specific objects provided by
 modules.  Each directive requires one or more signatures to provide basic
 information about what is being described, and the content should be the
 description.  The basic version makes entries in the general index; if no index
@@ -243,7 +245,7 @@ Info field lists
 
 .. versionadded:: 0.4
 
-Inside description unit directives, reST field lists with these fields are
+Inside object description directives, reST field lists with these fields are
 recognized and formatted nicely:
 
 * ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
@@ -340,8 +342,8 @@ There is a set of directives allowing documenting command-line programs:
    .. versionadded:: 0.5
 
 
-Custom description units
+Custom object types
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
 
 There is also a generic version of these directives:
 
@@ -356,4 +358,4 @@ There is also a generic version of these directives:
          Describes a Python bytecode instruction.
 
 Extensions may add more directives like that, using the
-:func:`~sphinx.application.Sphinx.add_description_unit` method.
+:func:`~sphinx.application.Sphinx.add_object_type` method.

sphinx/addnodes.py

@@ -14,7 +14,7 @@ from docutils import nodes
 # index markup
 class index(nodes.Invisible, nodes.Inline, nodes.TextElement): pass
 
-# domain-specific object description units (class, function etc.)
+# domain-specific object descriptions (class, function etc.)
 
 # parent node for signature and content
 class desc(nodes.Admonition, nodes.Element): pass

sphinx/application.py

@@ -382,7 +382,6 @@ class Sphinx(object):
 
     def add_object_type(self, directivename, rolename, indextemplate='',
                         parse_node=None, ref_nodeclass=None, objname=''):
-        # XXX document objname
         StandardDomain.object_types[directivename] = \
             ObjType(objname or directivename, rolename)
         # create a subclass of GenericObject as the new directive
@@ -398,7 +397,6 @@ class Sphinx(object):
 
     def add_crossref_type(self, directivename, rolename, indextemplate='',
                           ref_nodeclass=None, objname=''):
-        # XXX document objname
         StandardDomain.object_types[directivename] = \
             ObjType(objname or directivename, rolename)
         # create a subclass of Target as the new directive

sphinx/domains/std.py

@@ -30,7 +30,7 @@ option_desc_re = re.compile(
 
 class GenericObject(ObjectDescription):
     """
-    A generic x-ref directive registered with Sphinx.add_description_unit().
+    A generic x-ref directive registered with Sphinx.add_object_type().
     """
     indextemplate = ''
     parse_node = None

sphinx/environment.py

@@ -888,7 +888,7 @@ class BuildEnvironment:
             if name.isdigit() or node.has_key('refuri') or \
                    node.tagname.startswith('desc_'):
                 # ignore footnote labels, labels automatically generated from a
-                # link and description units
+                # link and object descriptions
                 continue
             if name in self.labels:
                 self.warn(docname, 'duplicate label %s, ' % name +

tests/root/conf.py

@@ -85,5 +85,5 @@ def setup(app):
     app.add_config_value('value_from_conf_py', 42, False)
     app.add_directive('funcdir', functional_directive, opt=lambda x: x)
     app.add_directive('clsdir', ClassDirective)
-    app.add_description_unit('userdesc', 'userdescrole', '%s (userdesc)',
+    app.add_object_type('userdesc', 'userdescrole', '%s (userdesc)',
-                             userdesc_parse)
+                        userdesc_parse, objname='user desc')