Commits

Georg Brandl committed f0cae30

Use the new rst domain in the sphinx docs.

Comments (0)

Files changed (24)

 .. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
-   This builder produces an HTML overview of all :dir:`versionadded`,
-   :dir:`versionchanged` and :dir:`deprecated` directives for the current
+   This builder produces an HTML overview of all :rst:dir:`versionadded`,
+   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the current
    :confval:`version`.  This is useful to generate a ChangeLog file, for
    example.
 
 
 from sphinx import addnodes
 
-dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
-
-def parse_directive(env, sig, signode):
-    if not sig.startswith('.'):
-        dec_sig = '.. %s::' % sig
-        signode += addnodes.desc_name(dec_sig, dec_sig)
-        return sig
-    m = dir_sig_re.match(sig)
-    if not m:
-        signode += addnodes.desc_name(sig, sig)
-        return sig
-    name, args = m.groups()
-    dec_name = '.. %s::' % name
-    signode += addnodes.desc_name(dec_name, dec_name)
-    signode += addnodes.desc_addname(args, args)
-    return name
-
-
-def parse_role(env, sig, signode):
-    signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
-    return sig
-
 
 event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
 
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-    app.add_description_unit('directive', 'dir', 'pair: %s; directive',
-                             parse_directive)
-    app.add_description_unit('role', 'role', 'pair: %s; role', parse_role)
     app.add_description_unit('confval', 'confval',
                              objname='configuration value',
                              indextemplate='pair: %s; configuration value')
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
-   contains the root :dir:`toctree` directive.  Default is ``'contents'``.
+   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.
 
 .. confval:: exclude_patterns
 
    "filter".  The default is ``None``, which doesn't reassign the default role.
 
    The default role can always be set within individual documents using the
-   standard reST :dir:`default-role` directive.
+   standard reST :rst:dir:`default-role` directive.
 
    .. versionadded:: 0.4
 
 
    A boolean that decides whether module names are prepended to all
    :term:`object` names (for object types where a "module" of some kind is
-   defined), e.g. for :dir:`function` directives.  Default is ``True``.
+   defined), e.g. for :rst:dir:`function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 
-   A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
+   A boolean that decides whether :rst:dir:`moduleauthor` and :rst:dir:`sectionauthor`
    directives produce any output in the built files.
 
 .. confval:: modindex_common_prefix
 describe Python objects, a default domain can be selected with either the config
 value :confval:`default_domain` or this directive:
 
-.. directive:: .. default-domain:: name
+.. rst:directive:: .. default-domain:: name
 
    Select a new default domain.  While the :confval:`default_domain` selects a
    global default, this only has an effect within the same file.
 The Python domain (name **py**) provides the following directives for module
 declarations:
 
-.. directive:: .. py:module:: name
+.. rst:directive:: .. py:module:: name
 
    This directive marks the beginning of the description of a module (or package
    submodule, in which case the name should be fully qualified, including the
-   package name).  It does not create content (like e.g. :dir:`py:class` does).
+   package name).  It does not create content (like e.g. :rst:dir:`py:class` does).
 
    This directive will also cause an entry in the global module index.
 
    deprecated; it will be designated as such in various locations then.
 
 
-.. directive:: .. py:currentmodule:: name
+.. rst:directive:: .. py:currentmodule:: name
 
    This directive tells Sphinx that the classes, functions etc. documented from
-   here are in the given module (like :dir:`py:module`), but it will not create
+   here are in the given module (like :rst:dir:`py:module`), but it will not create
    index entries, an entry in the Global Module Index, or a link target for
-   :role:`mod`.  This is helpful in situations where documentation for things in
+   :rst:role:`mod`.  This is helpful in situations where documentation for things in
    a module is spread over multiple files or sections -- one location has the
-   :dir:`py:module` directive, the others only :dir:`py:currentmodule`.
+   :rst:dir:`py:module` directive, the others only :rst:dir:`py:currentmodule`.
 
 
 The following directives are provided for module and class contents:
 
-.. directive:: .. py:data:: name
+.. rst:directive:: .. py:data:: name
 
    Describes global data in a module, including both variables and values used
    as "defined constants."  Class and object attributes are not documented
    using this environment.
 
-.. directive:: .. py:exception:: name
+.. rst:directive:: .. py:exception:: name
 
    Describes an exception class.  The signature can, but need not include
    parentheses with constructor arguments.
 
-.. directive:: .. py:function:: name(signature)
+.. rst:directive:: .. py:function:: name(signature)
 
    Describes a module-level function.  The signature should include the
    parameters, enclosing optional parameters in brackets.  Default values can be
    are modified), side effects, and possible exceptions.  A small example may be
    provided.
 
-.. directive:: .. py:class:: name[(signature)]
+.. rst:directive:: .. py:class:: name[(signature)]
 
    Describes a class.  The signature can include parentheses with parameters
    which will be shown as the constructor arguments.  See also
 
    The first way is the preferred one.
 
-.. directive:: .. py:attribute:: name
+.. rst:directive:: .. py:attribute:: name
 
    Describes an object data attribute.  The description should include
    information about the type of the data to be expected and whether it may be
    changed directly.
 
-.. directive:: .. py:method:: name(signature)
+.. rst:directive:: .. py:method:: name(signature)
 
    Describes an object method.  The parameters should not include the ``self``
    parameter.  The description should include similar information to that
    described for ``function``.  See also :ref:`signatures`.
 
-.. directive:: .. py:staticmethod:: name(signature)
+.. rst:directive:: .. py:staticmethod:: name(signature)
 
-   Like :dir:`py:method`, but indicates that the method is a static method.
+   Like :rst:dir:`py:method`, but indicates that the method is a static method.
 
    .. versionadded:: 0.4
 
-.. directive:: .. py:classmethod:: name(signature)
+.. rst:directive:: .. py:classmethod:: name(signature)
 
-   Like :dir:`py:method`, but indicates that the method is a class method.
+   Like :rst:dir:`py:method`, but indicates that the method is a class method.
 
    .. versionadded:: 0.6
 
 The following roles refer to objects in modules and are possibly hyperlinked if
 a matching identifier is found:
 
-.. role:: py:mod
+.. rst:role:: py:mod
 
    Reference a module; a dotted name may be used.  This should also be used for
    package names.
 
-.. role:: py:func
+.. rst:role:: py:func
 
    Reference a Python function; dotted names may be used.  The role text needs
    not include trailing parentheses to enhance readability; they will be added
    automatically by Sphinx if the :confval:`add_function_parentheses` config
    value is true (the default).
 
-.. role:: py:data
+.. rst:role:: py:data
 
    Reference a module-level variable.
 
-.. role:: py:const
+.. rst:role:: py:const
 
    Reference a "defined" constant.  This may be a C-language ``#define`` or a
    Python variable that is not intended to be changed.
 
-.. role:: py:class
+.. rst:role:: py:class
 
    Reference a class; a dotted name may be used.
 
-.. role:: py:meth
+.. rst:role:: py:meth
 
    Reference a method of an object.  The role text can include the type name and
    the method name; if it occurs within the description of a type, the type name
    can be omitted.  A dotted name may be used.
 
-.. role:: py:attr
+.. rst:role:: py:attr
 
    Reference a data attribute of an object.
 
-.. role:: py:exc
+.. rst:role:: py:exc
 
    Reference an exception.  A dotted name may be used.
 
-.. role:: py:obj
+.. rst:role:: py:obj
 
    Reference an object of unspecified type.  Useful e.g. as the
    :confval:`default_role`.
 
 The C domain (name **c**) is suited for documentation of C API.
 
-.. directive:: .. c:function:: type name(signature)
+.. rst:directive:: .. c:function:: type name(signature)
 
    Describes a C function. The signature should be given as in C, e.g.::
 
    Note that you don't have to backslash-escape asterisks in the signature, as
    it is not parsed by the reST inliner.
 
-.. directive:: .. c:member:: type name
+.. rst:directive:: .. c:member:: type name
 
    Describes a C struct member. Example signature::
 
    the value should be interpreted, and whether the value can be changed.
    References to structure members in text should use the ``member`` role.
 
-.. directive:: .. c:macro:: name
+.. rst:directive:: .. c:macro:: name
 
    Describes a "simple" C macro.  Simple macros are macros which are used for
    code expansion, but which do not take arguments so cannot be described as
    of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
    :c:macro:`Py_BEGIN_ALLOW_THREADS`.
 
-.. directive:: .. c:type:: name
+.. rst:directive:: .. c:type:: name
 
    Describes a C type (whether defined by a typedef or struct). The signature
    should just be the type name.
 
-.. directive:: .. c:var:: type name
+.. rst:directive:: .. c:var:: type name
 
    Describes a global C variable.  The signature should include the type, such
    as::
 The following roles create cross-references to C-language constructs if they are
 defined in the documentation:
 
-.. role:: c:data
+.. rst:role:: c:data
 
    Reference a C-language variable.
 
-.. role:: c:func
+.. rst:role:: c:func
 
    Reference a C-language function. Should include trailing parentheses.
 
-.. role:: c:macro
+.. rst:role:: c:macro
 
    Reference a "simple" C macro, as defined above.
 
-.. role:: c:type
+.. rst:role:: c:type
 
    Reference a C-language type.
 
 
 The following directives are available:
 
-.. directive:: .. cpp:class:: signatures
+.. rst:directive:: .. cpp:class:: signatures
                .. cpp:function:: signatures
                .. cpp:member:: signatures
                .. cpp:type:: signatures
 
          Describes the indexing operator of IntArrays.
 
-.. directive:: .. cpp:namespace:: namespace
+.. rst:directive:: .. cpp:namespace:: namespace
 
    Select the current C++ namespace for the following objects.
 
 These roles link to the given object types:
 
-.. role:: cpp:class
+.. rst:role:: cpp:class
           cpp:func
           cpp:member
           cpp:type
 
 There is a set of directives allowing documenting command-line programs:
 
-.. directive:: .. option:: name args, name args, ...
+.. rst:directive:: .. option:: name args, name args, ...
 
    Describes a command line option or switch.  Option argument names should be
    enclosed in angle brackets.  Example::
          Run a module as a script.
 
    The directive will create a cross-reference target named after the *first*
-   option, referencable by :role:`option` (in the example case, you'd use
+   option, referencable by :rst:role:`option` (in the example case, you'd use
    something like ``:option:`-m```).
 
-.. directive:: .. envvar:: name
+.. rst:directive:: .. envvar:: name
 
    Describes an environment variable that the documented code or program uses or
-   defines.  Referencable by :role:`envvar`.
+   defines.  Referencable by :rst:role:`envvar`.
 
-.. directive:: .. program:: name
+.. rst:directive:: .. program:: name
 
-   Like :dir:`py:currentmodule`, this directive produces no output.  Instead, it
-   serves to notify Sphinx that all following :dir:`option` directives
+   Like :rst:dir:`py:currentmodule`, this directive produces no output.  Instead, it
+   serves to notify Sphinx that all following :rst:dir:`option` directives
    document options for the program called *name*.
 
-   If you use :dir:`program`, you have to qualify the references in your
-   :role:`option` roles by the program name, so if you have the following
+   If you use :rst:dir:`program`, you have to qualify the references in your
+   :rst:role:`option` roles by the program name, so if you have the following
    situation ::
 
       .. program:: rm
 There is also a very generic object description directive, which is not tied to
 any domain:
 
-.. directive:: .. describe:: text
+.. rst:directive:: .. describe:: text
                .. object:: text
 
    This directive produces the same formatting as the specific ones provided by
 
 The JavaScript domain (name **js**) provides the following directives:
 
-.. directive:: .. js:function:: name(signature)
+.. rst:directive:: .. js:function:: name(signature)
 
    Describes a JavaScript function, method or constructor.  If you want to
    describe arguments as optional use square brackets as :ref:`documented
         :throws SomeError: For whatever reason in that case.
         :returns: Something
 
-.. directive:: .. js:data:: name
+.. rst:directive:: .. js:data:: name
 
    Describes a global variable or constant.
 
-.. directive:: .. js:attribute:: object.name
+.. rst:directive:: .. js:attribute:: object.name
 
    Describes the attribute *name* of *object*.
 
 These roles are provided to refer to the described objects:
 
-.. role:: js:func
+.. rst:role:: js:func
           js:data
           js:attr
 
 
 The reStructuredText domain (name **rst**) provides the following directives:
 
-.. directive:: .. rst:directive:: name
+.. rst:directive:: .. rst:directive:: name
 
    Describes a reST directive.  The *name* can be a single directive name or
    actual directive syntax (`..` prefix and `::` suffix) with arguments that
 
          Bar description.
 
-.. directive:: .. rst:role:: name
+.. rst:directive:: .. rst:role:: name
 
    Describes a reST role.  For example::
 

doc/ext/appapi.rst

      instead which does the right thing even on docutils 0.4 (which doesn't
      support directive classes otherwise).
 
-   For example, the (already existing) :dir:`literalinclude` directive would be
+   For example, the (already existing) :rst:dir:`literalinclude` directive would be
    added like this:
 
    .. code-block:: python
 
    you can use this markup in your documents::
 
-      .. directive:: function
+      .. rst:directive:: function
 
          Document a function.
 
       <...>
 
-      See also the :dir:`function` directive.
+      See also the :rst:dir:`function` directive.
 
    For the directive, an index entry will be generated as if you had prepended ::
 
    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
-   them using custom roles instead of generic ones (like :role:`ref`).  Example
+   them using custom roles instead of generic ones (like :rst:role:`ref`).  Example
    call::
 
       app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)

doc/ext/autodoc.rst

 auto-generated-looking pure API documentation.
 
 :mod:`autodoc` provides several directives that are versions of the usual
-:dir:`module`, :dir:`class` and so forth.  On parsing time, they import the
+:rst:dir:`module`, :rst:dir:`class` and so forth.  On parsing time, they import the
 corresponding module and extract the docstring of the given objects, inserting
-them into the page source under a suitable :dir:`module`, :dir:`class` etc.
+them into the page source under a suitable :rst:dir:`module`, :rst:dir:`class` etc.
 directive.
 
 .. note::
 
-   Just as :dir:`class` respects the current :dir:`module`, :dir:`autoclass`
-   will also do so, and likewise with :dir:`method` and :dir:`class`.
+   Just as :rst:dir:`class` respects the current :rst:dir:`module`, :rst:dir:`autoclass`
+   will also do so, and likewise with :rst:dir:`method` and :rst:dir:`class`.
 
 
-.. directive:: automodule
+.. rst:directive:: automodule
                autoclass
                autoexception
 
 
      .. versionadded:: 0.4
 
-   * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives
+   * The :rst:dir:`automodule`, :rst:dir:`autoclass` and :rst:dir:`autoexception` directives
      also support a flag option called ``show-inheritance``.  When given, a list
      of base classes will be inserted just below the class signature (when used
-     with :dir:`automodule`, this will be inserted for every class that is
+     with :rst:dir:`automodule`, this will be inserted for every class that is
      documented in the module).
 
      .. versionadded:: 0.4
 
    * All autodoc directives support the ``noindex`` flag option that has the
-     same effect as for standard :dir:`function` etc. directives: no index
+     same effect as for standard :rst:dir:`function` etc. directives: no index
      entries are generated for the documented object (and all autodocumented
      members).
 
      .. versionadded:: 0.4
 
-   * :dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
-     ``deprecated`` options that the standard :dir:`module` directive supports.
+   * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
+     ``deprecated`` options that the standard :rst:dir:`module` directive supports.
 
      .. versionadded:: 0.5
 
-   * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option
+   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
      that can be used to override the global value of
      :confval:`autodoc_member_order` for one directive.
 
 
    .. note::
 
-      In an :dir:`automodule` directive with the ``members`` option set, only
+      In an :rst:dir:`automodule` directive with the ``members`` option set, only
       module members whose ``__module__`` attribute is equal to the module name
       as given to ``automodule`` will be documented.  This is to prevent
       documentation of imported classes or functions.
 
 
-.. directive:: autofunction
+.. rst:directive:: autofunction
                autodata
                automethod
                autoattribute
 
-   These work exactly like :dir:`autoclass` etc., but do not offer the options
+   These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
    For module data members and class attributes, documentation can either be put
           """Docstring for attribute Foo.baz."""
 
    .. versionchanged:: 0.6
-      :dir:`autodata` and :dir:`autoattribute` can now extract docstrings.
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
 
    .. note::
 
 .. confval:: autoclass_content
 
    This value selects what content will be inserted into the main body of an
-   :dir:`autoclass` directive.  The possible values are:
+   :rst:dir:`autoclass` directive.  The possible values are:
 
    ``"class"``
       Only the class' docstring is inserted.  This is the default.  You can
-      still document ``__init__`` as a separate method using :dir:`automethod`
-      or the ``members`` option to :dir:`autoclass`.
+      still document ``__init__`` as a separate method using :rst:dir:`automethod`
+      or the ``members`` option to :rst:dir:`autoclass`.
    ``"both"``
       Both the class' and the ``__init__`` method's docstring are concatenated
       and inserted.

doc/ext/autosummary.rst

 
 The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
-1. There is an :dir:`autosummary` directive for generating summary listings that
+1. There is an :rst:dir:`autosummary` directive for generating summary listings that
    contain links to the documented items, and short summary blurbs extracted
    from their docstrings.
 
 2. The convenience script :program:`sphinx-autogen` or the new
    :confval:`autosummary_generate` config value can be used to generate short
-   "stub" files for the entries listed in the :dir:`autosummary` directives.
+   "stub" files for the entries listed in the :rst:dir:`autosummary` directives.
    These by default contain only the corresponding :mod:`sphinx.ext.autodoc`
    directive.
 
 
-.. directive:: autosummary
+.. rst:directive:: autosummary
 
    Insert a table that contains links to documented items, and a short summary
    blurb (the first sentence of the docstring) for each of them.  The
-   :dir:`autosummary` directive can also optionally serve as a :dir:`toctree`
+   :rst:dir:`autosummary` directive can also optionally serve as a :rst:dir:`toctree`
    entry for the included items.
 
    For example, ::
 
    **Options**
 
-   * If you want the :dir:`autosummary` table to also serve as a :dir:`toctree`
+   * If you want the :rst:dir:`autosummary` table to also serve as a :rst:dir:`toctree`
      entry, use the ``toctree`` option, for example::
 
          .. autosummary::
      directory. If no argument is given, output is placed in the same directory
      as the file that contains the directive.
 
-   * If you don't want the :dir:`autosummary` to show function signatures in the
+   * If you don't want the :rst:dir:`autosummary` to show function signatures in the
      listing, include the ``nosignatures`` option::
 
          .. autosummary::
 --------------------------------------------------------
 
 The :program:`sphinx-autogen` script can be used to conveniently generate stub
-documentation pages for items included in :dir:`autosummary` listings.
+documentation pages for items included in :rst:dir:`autosummary` listings.
 
 For example, the command ::
 
     $ sphinx-autogen -o generated *.rst
 
-will read all :dir:`autosummary` tables in the :file:`*.rst` files that have the
+will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have the
 ``:toctree:`` option set, and output corresponding stub pages in directory
 ``generated`` for all documented items.  The generated pages by default contain
 text of the form::
 
 .. note::
 
-   You can use the :dir:`autosummary` directive in the stub pages.
+   You can use the :rst:dir:`autosummary` directive in the stub pages.
    Stub pages are generated also based on these directives.

doc/ext/doctest.rst

 ``default`` group).  Otherwise, it must be a comma-separated list of group
 names.
 
-.. directive:: .. testsetup:: [group]
+.. rst:directive:: .. testsetup:: [group]
 
    A setup code block.  This code is not shown in the output for other builders,
    but executed before the doctests of the group(s) it belongs to.
 
 
-.. directive:: .. doctest:: [group]
+.. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
    controlling how actual output is compared with what you give as output.  By
    output.
 
 
-.. directive:: .. testcode:: [group]
+.. rst:directive:: .. testcode:: [group]
 
    A code block for a code-output-style test.
 
       applies to testcode/testoutput as well.
 
 
-.. directive:: .. testoutput:: [group]
+.. rst:directive:: .. testoutput:: [group]
 
    The corresponding output, or the exception message, for the last
-   :dir:`testcode` block.
+   :rst:dir:`testcode` block.
 
    This directive supports two options:
 
 
 
 The following is an example for the usage of the directives.  The test via
-:dir:`doctest` and the test via :dir:`testcode` and :dir:`testoutput` are
+:rst:dir:`doctest` and the test via :rst:dir:`testcode` and :rst:dir:`testoutput` are
 equivalent. ::
 
    The parrot module
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
+   :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
    achieve the latter in all code blocks with Python console content.

doc/ext/graphviz.rst

 It adds these directives:
 
 
-.. directive:: graphviz
+.. rst:directive:: graphviz
 
    Directive to embed graphviz code.  The input code for ``dot`` is given as the
    content.  For example::
    rendered to an embeddable PDF file.
 
 
-.. directive:: graph
+.. rst:directive:: graph
 
    Directive for embedding a single undirected graph.  The name is given as a
    directive argument, the contents of the graph are the directive content.
          "bar" -- "baz";
 
 
-.. directive:: digraph
+.. rst:directive:: digraph
 
    Directive for embedding a single directed graph.  The name is given as a
    directive argument, the contents of the graph are the directive content.

doc/ext/ifconfig.rst

 
 This extension is quite simple, and features only one directive:
 
-.. directive:: ifconfig
+.. rst:directive:: ifconfig
 
    Include content of the directive only if the Python expression given as an
    argument is ``True``, evaluated in the namespace of the project's

doc/ext/inheritance.rst

 
 It adds this directive:
 
-.. directive:: inheritance-diagram
+.. rst:directive:: inheritance-diagram
 
    This directive has one or more arguments, each giving a module or class
    name.  Class names can be unqualified; in that case they are taken to exist
-   in the currently described module (see :dir:`module`).
+   in the currently described module (see :rst:dir:`module`).
 
    For each given class, and each class in each given module, the base classes
    are determined.  Then, from all classes and their base classes, a graph is
 
 :mod:`mathbase` defines these new markup elements:
 
-.. role:: math
+.. rst:role:: math
 
    Role for inline math.  Use like this::
 
       Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
 
-.. directive:: math
+.. rst:directive:: math
 
    Directive for displayed math (math that takes the whole line for itself).
 
    Normally, equations are not numbered.  If you want your equation to get a
    number, use the ``label`` option.  When given, it selects a label for the
    equation, by which it can be cross-referenced, and causes an equation number
-   to be issued.  See :role:`eqref` for an example.  The numbering style depends
+   to be issued.  See :rst:role:`eqref` for an example.  The numbering style depends
    on the output format.
 
    There is also an option ``nowrap`` that prevents any wrapping of the given
             f(x) & = & x^2 + 2xy + y^2
          \end{eqnarray}
 
-.. role:: eq
+.. rst:role:: eq
 
    Role for cross-referencing equations via their label.  This currently works
    only within the same document.  Example::
 
 There are two additional directives when using this extension:
 
-.. directive:: todo
+.. rst:directive:: todo
 
-   Use this directive like, for example, :dir:`note`.
+   Use this directive like, for example, :rst:dir:`note`.
 
    It will only show up in the output if :confval:`todo_include_todos` is true.
 
 
-.. directive:: todolist
+.. rst:directive:: todolist
 
    This directive is replaced by a list of all todo directives in the whole
    documentation, if :confval:`todo_include_todos` is true.
 
 .. confval:: todo_include_todos
 
-   If this is ``True``, :dir:`todo` and :dir:`todolist` produce output, else
+   If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, else
    they produce nothing.  The default is ``False``.
 
 ... get section numbers?
    They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
-   the :dir:`toctree` directive where you want to start numbering.
+   the :rst:dir:`toctree` directive where you want to start numbering.
 
 ... customize the look of the built HTML files?
    Use themes, see :doc:`theming`.
       changed documents.
 
    master document
-      The document that contains the root :dir:`toctree` directive.
+      The document that contains the root :rst:dir:`toctree` directive.
 
    object
       The basic building block of Sphinx documentation.  Every "object
-      directive" (e.g. :dir:`function` or :dir:`object`) creates such a block;
+      directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a block;
       and most objects can be cross-referenced to.
 
    role

doc/invocation.rst

 
 .. option:: -t tag
 
-   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
+   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that only
    include their content if this tag is set.
 
    .. versionadded:: 0.6

doc/markup/code.rst

   This language is used until the next ``highlight`` directive is encountered.
 
 * For documents that have to show snippets in different languages, there's also
-  a :dir:`code-block` directive that is given the highlighting language
+  a :rst:dir:`code-block` directive that is given the highlighting language
   directly::
 
      .. code-block:: ruby
 
         Some Ruby code.
 
-  The directive's alias name :dir:`sourcecode` works as well.
+  The directive's alias name :rst:dir:`sourcecode` works as well.
 
 * The valid values for the highlighting language are:
 
 
 If installed, Pygments can generate line numbers for code blocks.  For
 automatically-highlighted blocks (those started by ``::``), line numbers must be
-switched on in a :dir:`highlight` directive, with the ``linenothreshold``
+switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
 option::
 
    .. highlight:: python
 
 This will produce line numbers for all code blocks longer than five lines.
 
-For :dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
+For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
 on line numbers for the individual block::
 
    .. code-block:: ruby
 Includes
 ^^^^^^^^
 
-.. directive:: .. literalinclude:: filename
+.. rst:directive:: .. literalinclude:: filename
 
    Longer displays of verbatim text may be included by storing the example text in
    an external file containing only plain text.  The file may be included using the

doc/markup/inline.rst

 Cross-referencing arbitrary locations
 -------------------------------------
 
-.. role:: ref
+.. rst:role:: ref
 
    To support cross-referencing to arbitrary locations in any document, the
    standard reST labels are used.  For this to work label names must be unique
      to, but you must give the link an explicit title, using this syntax:
      ``:ref:`Link title <label-name>```.
 
-   Using :role:`ref` is advised over standard reStructuredText links to sections
+   Using :rst:role:`ref` is advised over standard reStructuredText links to sections
    (like ```Section title`_``) because it works across files, when section
    headings are changed, and for all builders that support cross-references.
 
 
 There is also a way to directly link to documents:
 
-.. role:: doc
+.. rst:role:: doc
 
    Link to the specified document; the document name can be specified in
    absolute or relative fashion.  For example, if the reference
 
 .. versionadded:: 0.6
 
-.. role:: download
+.. rst:role:: download
 
    This role lets you link to files within your source tree that are not reST
    documents that can be viewed, but files that can be downloaded.
 The following roles don't do anything special except formatting the text
 in a different style:
 
-.. role:: abbr
+.. rst:role:: abbr
 
    An abbreviation.  If the role content contains a parenthesized explanation,
    it will be treated specially: it will be shown in a tool-tip in HTML, and
 
    .. versionadded:: 0.6
 
-.. role:: command
+.. rst:role:: command
 
    The name of an OS-level command, such as ``rm``.
 
-.. role:: dfn
+.. rst:role:: dfn
 
    Mark the defining instance of a term in the text.  (No index entries are
    generated.)
 
-.. role:: file
+.. rst:role:: file
 
    The name of a file or directory.  Within the contents, you can use curly
    braces to indicate a "variable" part, for example::
    In the built documentation, the ``x`` will be displayed differently to
    indicate that it is to be replaced by the Python minor version.
 
-.. role:: guilabel
+.. rst:role:: guilabel
 
    Labels presented as part of an interactive user interface should be marked
    using ``guilabel``.  This includes labels from text-based interfaces such as
    labels, window titles, field names, menu and menu selection names, and even
    values in selection lists.
 
-.. role:: kbd
+.. rst:role:: kbd
 
    Mark a sequence of keystrokes.  What form the key sequence takes may depend
    on platform- or application-specific conventions.  When there are no relevant
    reference to a specific application or platform, the same sequence should be
    marked as ``:kbd:`Control-x Control-f```.
 
-.. role:: mailheader
+.. rst:role:: mailheader
 
    The name of an RFC 822-style mail header.  This markup does not imply that
    the header is being used in an email message, but can be used to refer to any
    being preferred where there is more than one common usage. For example:
    ``:mailheader:`Content-Type```.
 
-.. role:: makevar
+.. rst:role:: makevar
 
    The name of a :command:`make` variable.
 
-.. role:: manpage
+.. rst:role:: manpage
 
    A reference to a Unix manual page including the section,
    e.g. ``:manpage:`ls(1)```.
 
-.. role:: menuselection
+.. rst:role:: menuselection
 
    Menu selections should be marked using the ``menuselection`` role.  This is
    used to mark a complete sequence of menu selections, including selecting
    ellipsis some operating systems use to indicate that the command opens a
    dialog, the indicator should be omitted from the selection name.
 
-.. role:: mimetype
+.. rst:role:: mimetype
 
    The name of a MIME type, or a component of a MIME type (the major or minor
    portion, taken alone).
 
-.. role:: newsgroup
+.. rst:role:: newsgroup
 
    The name of a Usenet newsgroup.
 
-.. role:: program
+.. rst:role:: program
 
    The name of an executable program.  This may differ from the file name for
    the executable for some platforms.  In particular, the ``.exe`` (or other)
    extension should be omitted for Windows programs.
 
-.. role:: regexp
+.. rst:role:: regexp
 
    A regular expression. Quotes should not be included.
 
-.. role:: samp
+.. rst:role:: samp
 
    A piece of literal text, such as code.  Within the contents, you can use
    curly braces to indicate a "variable" part, as in ``:file:``.
 
 The following roles generate external links:
 
-.. role:: pep
+.. rst:role:: pep
 
    A reference to a Python Enhancement Proposal.  This generates appropriate
    index entries. The text "PEP *number*\ " is generated; in the HTML output,
    this text is a hyperlink to an online copy of the specified PEP.
 
-.. role:: rfc
+.. rst:role:: rfc
 
    A reference to an Internet Request for Comments.  This generates appropriate
    index entries. The text "RFC *number*\ " is generated; in the HTML output,
 The following roles do possibly create a cross-reference, but do not refer to
 objects:
 
-.. role:: envvar
+.. rst:role:: envvar
 
    An environment variable.  Index entries are generated.  Also generates a link
-   to the matching :dir:`envvar` directive, if it exists.
+   to the matching :rst:dir:`envvar` directive, if it exists.
 
-.. role:: token
+.. rst:role:: token
 
    The name of a grammar token (used to create links between
-   :dir:`productionlist` directives).
+   :rst:dir:`productionlist` directives).
 
-.. role:: keyword
+.. rst:role:: keyword
 
    The name of a keyword in Python.  This creates a link to a reference label
    with that name, if it exists.
 
-.. role:: option
+.. rst:role:: option
 
    A command-line option to an executable program.  The leading hyphen(s) must
-   be included.  This generates a link to a :dir:`option` directive, if it
+   be included.  This generates a link to a :rst:dir:`option` directive, if it
    exists.
 
 
 The following role creates a cross-reference to the term in the glossary:
 
-.. role:: term
+.. rst:role:: term
 
    Reference to a term in the glossary.  The glossary is created using the
    ``glossary`` directive containing a definition list with terms and

doc/markup/misc.rst

 Meta-information markup
 -----------------------
 
-.. directive:: .. sectionauthor:: name <email>
+.. rst:directive:: .. sectionauthor:: name <email>
 
    Identifies the author of the current section.  The argument should include
    the author's name such that it can be used for presentation and email
    output.
 
 
-.. directive:: .. codeauthor:: name <email>
+.. rst:directive:: .. codeauthor:: name <email>
 
-   The :dir:`codeauthor` directive, which can appear multiple times, names the
-   authors of the described code, just like :dir:`sectionauthor` names the
+   The :rst:dir:`codeauthor` directive, which can appear multiple times, names the
+   authors of the described code, just like :rst:dir:`sectionauthor` names the
    author(s) of a piece of documentation.  It too only produces output if the
    :confval:`show_authors` configuration value is True.
 
 Including content based on tags
 -------------------------------
 
-.. directive:: .. only:: <expression>
+.. rst:directive:: .. only:: <expression>
 
    Include the content of the directive only if the *expression* is true.  The
    expression should consist of tags, like this::
 column width is hard to determine correctly automatically.  For this reason, the
 following directive exists:
 
-.. directive:: .. tabularcolumns:: column spec
+.. rst:directive:: .. tabularcolumns:: column spec
 
    This directive gives a "column spec" for the next table occurring in the
    source file.  The spec is the second argument to the LaTeX ``tabulary``
    therefore set with the standard LaTeX ``tabular`` environment.  Also, the
    verbatim environment used for literal blocks only works in ``p{width}``
    columns, which means that by default, Sphinx generates such column specs for
-   such tables.  Use the :dir:`tabularcolumns` directive to get finer control
+   such tables.  Use the :rst:dir:`tabularcolumns` directive to get finer control
    over such tables.

doc/markup/para.rst

 These directives create short paragraphs and can be used inside information
 units as well as normal text:
 
-.. directive:: .. note::
+.. rst:directive:: .. note::
 
    An especially important bit of information about an API that a user should be
    aware of when using whatever bit of API the note pertains to.  The content of
 
          This function is not suitable for sending spam e-mails.
 
-.. directive:: .. warning::
+.. rst:directive:: .. warning::
 
    An important bit of information about an API that a user should be very aware
    of when using whatever bit of API the warning pertains to.  The content of
    the directive should be written in complete sentences and include all
-   appropriate punctuation. This differs from :dir:`note` in that it is
-   recommended over :dir:`note` for information regarding security.
+   appropriate punctuation. This differs from :rst:dir:`note` in that it is
+   recommended over :rst:dir:`note` for information regarding security.
 
-.. directive:: .. versionadded:: version
+.. rst:directive:: .. versionadded:: version
 
    This directive documents the version of the project which added the described
    feature to the library or C API. When this applies to an entire module, it
    Note that there must be no blank line between the directive head and the
    explanation; this is to make these blocks visually continuous in the markup.
 
-.. directive:: .. versionchanged:: version
+.. rst:directive:: .. versionchanged:: version
 
-   Similar to :dir:`versionadded`, but describes when and what changed in the named
+   Similar to :rst:dir:`versionadded`, but describes when and what changed in the named
    feature in some way (new parameters, changed side effects, etc.).
 
 --------------
 
-.. directive:: seealso
+.. rst:directive:: seealso
 
    Many sections include a list of references to module documentation or
-   external documents.  These lists are created using the :dir:`seealso`
+   external documents.  These lists are created using the :rst:dir:`seealso`
    directive.
 
-   The :dir:`seealso` directive is typically placed in a section just before any
+   The :rst:dir:`seealso` directive is typically placed in a section just before any
    sub-sections.  For the HTML output, it is shown boxed off from the main flow
    of the text.
 
-   The content of the :dir:`seealso` directive should be a reST definition list.
+   The content of the :rst:dir:`seealso` directive should be a reST definition list.
    Example::
 
       .. seealso::
    .. versionadded:: 0.5
       The short form.
 
-.. directive:: .. rubric:: title
+.. rst:directive:: .. rubric:: title
 
    This directive creates a paragraph heading that is not used to create a
    table of contents node.
       empty heading.
 
 
-.. directive:: centered
+.. rst:directive:: centered
 
    This directive creates a centered boldfaced line of text.  Use it as
    follows::
       .. centered:: LICENSE AGREEMENT
 
 
-.. directive:: hlist
+.. rst:directive:: hlist
 
    This directive must contain a bullet list.  It will transform it into a more
    compact list by either distributing more than one item horizontally, or
 Table-of-contents markup
 ------------------------
 
-The :dir:`toctree` directive, which generates tables of contents of
+The :rst:dir:`toctree` directive, which generates tables of contents of
 subdocuments, is described in :ref:`toctree-directive`.
 
 For local tables of contents, use the standard reST :rstdir:`contents directive
 comprehensive and enable index entries in documents where information is not
 mainly contained in information units, such as the language reference.
 
-.. directive:: .. index:: <entries>
+.. rst:directive:: .. index:: <entries>
 
    This directive contains one or more index entries.  Each entry consists of a
    type and a value, separated by a colon.
 Glossary
 --------
 
-.. directive:: .. glossary::
+.. rst:directive:: .. glossary::
 
    This directive must contain a reST definition list with terms and
-   definitions.  The definitions will then be referencable with the :role:`term`
+   definitions.  The definitions will then be referencable with the :rst:role:`term`
    role.  Example::
 
       .. glossary::
 displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
 the definition of the symbol.  There is this directive:
 
-.. directive:: .. productionlist:: [name]
+.. rst:directive:: .. productionlist:: [name]
 
    This directive is used to enclose a group of productions.  Each production is
    given on a single line and consists of a name, separated by a colon from the
    continuation line must begin with a colon placed at the same column as in the
    first line.
 
-   The argument to :dir:`productionlist` serves to distinguish different sets of
+   The argument to :rst:dir:`productionlist` serves to distinguish different sets of
    production lists that belong to different grammars.
 
    Blank lines are not allowed within ``productionlist`` directive arguments.
    The definition can contain token names which are marked as interpreted text
    (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
    to the productions of these tokens.  Outside of the production list, you can
-   reference to token productions using :role:`token`.
+   reference to token productions using :rst:role:`token`.
 
    Note that no further reST parsing is done in the production, so that you
    don't have to escape ``*`` or ``|`` characters.

doc/markup/toctree.rst

 relations between the single files the documentation is made of, as well as
 tables of contents.  The ``toctree`` directive is the central element.
 
-.. directive:: toctree
+.. rst:directive:: toctree
 
    This directive inserts a "TOC tree" at the current location, using the
    individual TOCs (including "sub-TOC trees") of the documents given in the
      document, the library index.  From this information it generates "next
      chapter", "previous chapter" and "parent chapter" links.
 
-   Document titles in the :dir:`toctree` will be automatically read from the
+   Document titles in the :rst:dir:`toctree` will be automatically read from the
    title of the referenced document. If that isn't what you want, you can
    specify an explicit title and target using a similar syntax to reST
    hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
   page, respectively.
 
   The general index is populated with entries from modules, all index-generating
-  :ref:`object descriptions <basic-domain-markup>`, and from :dir:`index`
+  :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
   directives.
 
-  The module index contains one entry per :dir:`module` directive.
+  The module index contains one entry per :rst:dir:`module` directive.
 
   The search page contains a form that uses the generated JSON search index and
   JavaScript to full-text search the generated documents for search words; it
 
 If you want to use some substitutions for all documents, put them into a
 separate file and include it into all documents you want to use them in, using
-the :dir:`include` directive.  Be sure to give the include file a file name
+the :rst:dir:`include` directive.  Be sure to give the include file a file name
 extension differing from that of other source files, to avoid Sphinx finding it
 as a standalone document.
 
 
 .. rubric:: Footnotes
 
-.. [1] When the default domain contains a :dir:`class` directive, this directive
-       will be shadowed.  Therefore, Sphinx re-exports it as :dir:`rst-class`.
+.. [1] When the default domain contains a :rst:dir:`class` directive, this directive
+       will be shadowed.  Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.
 In Sphinx source files, you can use most features of standard reStructuredText.
 There are also several features added by Sphinx.  For example, you can add
 cross-file references in a portable way (which works for all output types) using
-the :role:`ref` role.
+the :rst:role:`ref` role.
 
 For an example, if you are viewing the HTML version you can look at the source
 for this document -- use the "Show Source" link in the sidebar.
 does the same job if you keep the default setting for the default domain.
 
 There are several more directives for documenting other types of Python objects,
-for example :dir:`py:class` or :dir:`py:method`.  There is also a
+for example :rst:dir:`py:class` or :rst:dir:`py:method`.  There is also a
 cross-referencing :dfn:`role` for each of these object types.  This markup will
 create a link to the documentation of ``enumerate()``::
 

sphinx/domains/rst.py

             self.state.document.note_explicit_target(signode)
 
             objects = self.env.domaindata['rst']['objects']
-            if name in objects:
-                self.env.warn(
-                    self.env.docname,
-                    'duplicate object description of %s, ' % name +
-                    'other instance in ' +
-                    self.env.doc2path(objects[name][0]),
-                    self.lineno)
-            objects[name] = self.env.docname, self.objtype
+            if (self.objtype, name) in objects:
+                self.env.warn(self.env.docname,
+                              'duplicate description of %s %s, ' %
+                              (self.objtype, name) +
+                              'other instance in ' +
+                              self.env.doc2path(objects[name][0]),
+                              self.lineno)
+            objects[self.objtype, name] = self.env.docname
         indextext = self.get_index_text(self.objtype, name)
         if indextext:
             self.indexnode['entries'].append(('single', indextext,
     }
 
     def clear_doc(self, docname):
-        for name, (doc, _) in self.data['objects'].items():
+        for (typ, name), doc in self.data['objects'].items():
             if doc == docname:
-                del self.data['objects'][name]
+                del self.data['objects'][typ, name]
 
     def resolve_xref(self, env, fromdocname, builder, typ, target, node,
                      contnode):
         objects = self.data['objects']
 
-        if not target in objects:
+        if not (typ, target) in objects:
             return None
-        return make_refnode(builder, fromdocname, objects[target][0], target,
-               contnode, target)
+        return make_refnode(builder, fromdocname, objects[typ, target][0],
+                            target, contnode, target)
 
     def get_objects(self):
-        for name, (docname, type) in self.data['objects'].iteritems():
-            yield name, type, docname, name, 1
+        for (typ, name), docname in self.data['objects'].iteritems():
+            yield name, typ, docname, name, 1