Use the new rst domain in the sphinx docs.

2025-02-25 18:55:22 -06:00 · 2010-04-17 10:39:51 +02:00
parent 541e30b36e
commit f4f3066581
24 changed files with 202 additions and 227 deletions
--- 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)
--- 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.
--- 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.
--- 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.
--- 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.
--- 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
--- 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
--- 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::
--- 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``.