IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Use the new rst domain in the sphinx docs.

Browse Source
This commit is contained in:
Georg Brandl 2010-04-17 10:39:51 +02:00
parent 541e30b36e
commit f4f3066581
24 changed files with 202 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/builders.rst
View File

@ -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.

25
doc/conf.py
View File

@ -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')

8
doc/config.rst
View File

@ -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

108
doc/domains.rst
View File

@ -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::

8
doc/ext/appapi.rst
View File

@ -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)

36
doc/ext/autodoc.rst
View File

@ -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.

18
doc/ext/autosummary.rst
View File

@ -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.

14
doc/ext/doctest.rst
View File

@ -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.

6
doc/ext/graphviz.rst
View File

@ -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.

2
doc/ext/ifconfig.rst
View File

@ -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

4
doc/ext/inheritance.rst
View File

@ -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

8
doc/ext/math.rst
View File

@ -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::

8
doc/ext/todo.rst
View File

@ -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``.

2
doc/faq.rst
View File

@ -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`.

4
doc/glossary.rst
View File

@ -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

2
doc/invocation.rst
View File

@ -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

10
doc/markup/code.rst
View File

@ -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

58
doc/markup/inline.rst
View File

@ -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

14
doc/markup/misc.rst
View File

@ -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.

42
doc/markup/para.rst
View File

@ -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.

8
doc/markup/toctree.rst
View File

@ -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

6
doc/rest.rst
View File

@ -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`.

4
doc/tutorial.rst
View File

@ -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()``::

30
sphinx/domains/rst.py
View File

@ -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