diff options
| -rw-r--r-- | doc/builders.rst | 4 | ||||
| -rw-r--r-- | doc/conf.py | 25 | ||||
| -rw-r--r-- | doc/config.rst | 8 | ||||
| -rw-r--r-- | doc/domains.rst | 108 | ||||
| -rw-r--r-- | doc/ext/appapi.rst | 8 | ||||
| -rw-r--r-- | doc/ext/autodoc.rst | 36 | ||||
| -rw-r--r-- | doc/ext/autosummary.rst | 18 | ||||
| -rw-r--r-- | doc/ext/doctest.rst | 14 | ||||
| -rw-r--r-- | doc/ext/graphviz.rst | 6 | ||||
| -rw-r--r-- | doc/ext/ifconfig.rst | 2 | ||||
| -rw-r--r-- | doc/ext/inheritance.rst | 4 | ||||
| -rw-r--r-- | doc/ext/math.rst | 8 | ||||
| -rw-r--r-- | doc/ext/todo.rst | 8 | ||||
| -rw-r--r-- | doc/faq.rst | 2 | ||||
| -rw-r--r-- | doc/glossary.rst | 4 | ||||
| -rw-r--r-- | doc/invocation.rst | 2 | ||||
| -rw-r--r-- | doc/markup/code.rst | 10 | ||||
| -rw-r--r-- | doc/markup/inline.rst | 58 | ||||
| -rw-r--r-- | doc/markup/misc.rst | 14 | ||||
| -rw-r--r-- | doc/markup/para.rst | 42 | ||||
| -rw-r--r-- | doc/markup/toctree.rst | 8 | ||||
| -rw-r--r-- | doc/rest.rst | 6 | ||||
| -rw-r--r-- | doc/tutorial.rst | 4 | ||||
| -rw-r--r-- | sphinx/domains/rst.py | 30 |
24 files changed, 202 insertions, 227 deletions
diff --git a/doc/builders.rst b/doc/builders.rst index 0eeb584c..6e90ccc6 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -223,8 +223,8 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf .. 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. diff --git a/doc/conf.py b/doc/conf.py index 98dc6565..08e447f2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -69,28 +69,6 @@ man_pages = [ 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*\((.*)\)') @@ -112,9 +90,6 @@ def parse_event(env, sig, signode): 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') diff --git a/doc/config.rst b/doc/config.rst index 611b7476..57772127 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -87,7 +87,7 @@ General configuration .. 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 @@ -203,7 +203,7 @@ General configuration "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 @@ -328,11 +328,11 @@ Project information 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 diff --git a/doc/domains.rst b/doc/domains.rst index d8f6515c..0f62f176 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -71,7 +71,7 @@ To avoid having to writing the domain name all the time when you e.g. only 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. @@ -114,11 +114,11 @@ The Python Domain 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. @@ -135,30 +135,30 @@ declarations: 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 @@ -176,7 +176,7 @@ The following directives are provided for module and class contents: 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 @@ -197,27 +197,27 @@ The following directives are provided for module and class contents: 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 @@ -304,46 +304,46 @@ Cross-referencing Python objects 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`. @@ -372,7 +372,7 @@ The C Domain 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.:: @@ -384,7 +384,7 @@ The C domain (name **c**) is suited for documentation of C API. 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:: @@ -394,7 +394,7 @@ The C domain (name **c**) is suited for documentation of C API. 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 @@ -402,12 +402,12 @@ The C domain (name **c**) is suited for documentation of C API. 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:: @@ -421,19 +421,19 @@ Cross-referencing C constructs 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. @@ -445,7 +445,7 @@ The C++ domain (name **cpp**) supports documenting C++ projects. The following directives are available: -.. directive:: .. cpp:class:: signatures +.. rst:directive:: .. cpp:class:: signatures .. cpp:function:: signatures .. cpp:member:: signatures .. cpp:type:: signatures @@ -457,13 +457,13 @@ The following directives are available: 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 @@ -484,7 +484,7 @@ The standard domain is also where custom object descriptions, added using the 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:: @@ -494,22 +494,22 @@ There is a set of directives allowing documenting command-line programs: 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 @@ -536,7 +536,7 @@ There is a set of directives allowing documenting command-line programs: 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 @@ -553,7 +553,7 @@ The JavaScript Domain 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 @@ -585,17 +585,17 @@ The JavaScript domain (name **js**) provides the following directives: :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 @@ -605,7 +605,7 @@ The reStructuredText domain 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 @@ -629,7 +629,7 @@ The reStructuredText domain (name **rst**) provides the following directives: Bar description. -.. directive:: .. rst:role:: name +.. rst:directive:: .. rst:role:: name Describes a reST role. For example:: diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index cfdaaaa8..402dd72f 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -121,7 +121,7 @@ the following public API: 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 @@ -188,13 +188,13 @@ the following public API: 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 :: @@ -218,7 +218,7 @@ the following public API: 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) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 7e280b34..bd725cfa 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -27,18 +27,18 @@ two locations for documentation, while at the same time avoiding 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 @@ -127,27 +127,27 @@ directive. .. 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. @@ -161,18 +161,18 @@ 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 @@ -190,7 +190,7 @@ directive. """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:: @@ -209,12 +209,12 @@ There are also new config values that you can set: .. 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. diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 8193bc52..9f66e510 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -15,22 +15,22 @@ one of them on a separate page makes them easier to read. 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, :: @@ -60,7 +60,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: **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:: @@ -76,7 +76,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: 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:: @@ -104,13 +104,13 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: -------------------------------------------------------- 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:: @@ -227,5 +227,5 @@ The following variables available in the templates: .. 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. diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 03d35e02..20e747de 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -39,13 +39,13 @@ interpreted as follows: if it is empty, the block is assigned to the group named ``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 @@ -78,7 +78,7 @@ names. output. -.. directive:: .. testcode:: [group] +.. rst:directive:: .. testcode:: [group] A code block for a code-output-style test. @@ -107,10 +107,10 @@ names. 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: @@ -134,7 +134,7 @@ names. 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 @@ -220,5 +220,5 @@ There are also these config values for customizing the doctest extension: 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. diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 77eae7d8..3741cec6 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -14,7 +14,7 @@ your documents. 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:: @@ -30,7 +30,7 @@ It adds these directives: 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. @@ -43,7 +43,7 @@ It adds these directives: "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. diff --git a/doc/ext/ifconfig.rst b/doc/ext/ifconfig.rst index d7d16981..a11e3072 100644 --- a/doc/ext/ifconfig.rst +++ b/doc/ext/ifconfig.rst @@ -8,7 +8,7 @@ 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 diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst index 72849e05..76388a94 100644 --- a/doc/ext/inheritance.rst +++ b/doc/ext/inheritance.rst @@ -13,11 +13,11 @@ This extension allows you to include inheritance diagrams, rendered via the 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 diff --git a/doc/ext/math.rst b/doc/ext/math.rst index c1602558..b9f6ab12 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -27,13 +27,13 @@ further translation is necessary when building LaTeX output. :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). @@ -66,7 +66,7 @@ further translation is necessary when building LaTeX output. 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 @@ -81,7 +81,7 @@ further translation is necessary when building LaTeX output. 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:: diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index 4f5a379d..349d286a 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -9,14 +9,14 @@ 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. @@ -26,5 +26,5 @@ There is also an additional config value: .. 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``. diff --git a/doc/faq.rst b/doc/faq.rst index 1a993204..613283c5 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -16,7 +16,7 @@ How do I... ... 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`. diff --git a/doc/glossary.rst b/doc/glossary.rst index aa71b2b8..2a82e20f 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -64,11 +64,11 @@ Glossary 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 diff --git a/doc/invocation.rst b/doc/invocation.rst index 94b5db2e..6b8b9ee3 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -67,7 +67,7 @@ The :program:`sphinx-build` script has several options: .. 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 diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 96871115..eaaf17d0 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -43,14 +43,14 @@ installed) and handled in a smart way: 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: @@ -70,7 +70,7 @@ Line numbers 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 @@ -78,7 +78,7 @@ option:: 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 @@ -90,7 +90,7 @@ on line numbers for the individual block:: 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 diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 298c999c..558f813d 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -49,7 +49,7 @@ more versatile: 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 @@ -87,7 +87,7 @@ Cross-referencing arbitrary locations 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. @@ -99,7 +99,7 @@ Cross-referencing documents 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 @@ -116,7 +116,7 @@ Referencing downloadable files .. 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. @@ -144,7 +144,7 @@ Other semantic markup 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 @@ -154,16 +154,16 @@ in a different style: .. 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:: @@ -173,7 +173,7 @@ in a different style: 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 @@ -182,7 +182,7 @@ in a different style: 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 @@ -192,7 +192,7 @@ in a different style: 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 @@ -202,16 +202,16 @@ in a different style: 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 @@ -227,26 +227,26 @@ in a different style: 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:``. @@ -257,13 +257,13 @@ in a different style: 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, @@ -280,31 +280,31 @@ Cross-referencing other items of interest 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 diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index ba045165..6173589b 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -39,7 +39,7 @@ At the moment, these metadata fields are recognized: 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 @@ -54,10 +54,10 @@ Meta-information markup 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. @@ -67,7 +67,7 @@ Meta-information markup 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:: @@ -92,7 +92,7 @@ HTML output, however there are some gotchas when using tables in LaTeX: the 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`` @@ -128,5 +128,5 @@ following directive exists: 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. diff --git a/doc/markup/para.rst b/doc/markup/para.rst index 9abae1dc..2fdc8d5a 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -9,7 +9,7 @@ Paragraph-level markup 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 @@ -22,15 +22,15 @@ units as well as normal text: 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 @@ -47,24 +47,24 @@ units as well as normal text: 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:: @@ -82,7 +82,7 @@ units as well as normal text: .. 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. @@ -95,7 +95,7 @@ units as well as normal text: empty heading. -.. directive:: centered +.. rst:directive:: centered This directive creates a centered boldfaced line of text. Use it as follows:: @@ -103,7 +103,7 @@ units as well as normal text: .. 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 @@ -127,7 +127,7 @@ units as well as normal text: 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 @@ -144,7 +144,7 @@ However, there is also an explicit directive available, to make the index more 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. @@ -199,10 +199,10 @@ mainly contained in information units, such as the language reference. 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:: @@ -231,7 +231,7 @@ derived forms), but provides enough to allow context-free grammars to be 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 @@ -239,7 +239,7 @@ the definition of the symbol. There is this directive: 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. @@ -247,7 +247,7 @@ the definition of the symbol. There is this directive: 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. diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index af2fc223..9b987a2e 100644 --- a/doc/markup/toctree.rst +++ b/doc/markup/toctree.rst @@ -11,7 +11,7 @@ documents into multiple output files, Sphinx uses a custom directive to add 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 @@ -40,7 +40,7 @@ tables of contents. The ``toctree`` directive is the central element. 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 @@ -147,10 +147,10 @@ The special document names (and pages generated for them) are: 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 diff --git a/doc/rest.rst b/doc/rest.rst index 856775e1..6693c217 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -428,7 +428,7 @@ for details. 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. @@ -479,5 +479,5 @@ There are some problems one commonly runs into while authoring reST documents: .. 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`. diff --git a/doc/tutorial.rst b/doc/tutorial.rst index bb4116ba..fa6ee2ab 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -90,7 +90,7 @@ Adding content 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. @@ -164,7 +164,7 @@ prefix the markup with the domain name:: 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()``:: diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py index 23dcc41a..8578a84a 100644 --- a/sphinx/domains/rst.py +++ b/sphinx/domains/rst.py @@ -35,14 +35,14 @@ class ReSTMarkup(ObjectDescription): 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, @@ -116,19 +116,19 @@ class ReSTDomain(Domain): } 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 |