merge with 1.0

4 files changed, 93 insertions, 63 deletions

diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 35981edc..78aaea69 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -309,6 +309,7 @@ in a different style:
    If you don't need the "variable part" indication, use the standard
    ````code```` instead.
 
+There is also an :rst:role:`index` role to generate index entries.
 
 The following roles generate external links:
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 6173589b..44da3aac 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -62,6 +62,85 @@ Meta-information markup
    :confval:`show_authors` configuration value is True.
 
 
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all object descriptions (like
+functions, classes or attributes) like discussed in :ref:`domains`.
+
+However, there is also explicit markup 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.
+
+.. 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.
+
+   For example::
+
+      .. index::
+         single: execution; context
+         module: __main__
+         module: sys
+         triple: module; search; path
+
+      The execution context
+      ---------------------
+
+      ...
+
+   This directive contains five entries, which will be converted to entries in
+   the generated index which link to the exact location of the index statement
+   (or, in case of offline media, the corresponding page number).
+
+   Since index directives generate cross-reference targets at their location in
+   the source, it makes sense to put them *before* the thing they refer to --
+   e.g. a heading, as in the example above.
+
+   The possible entry types are:
+
+   single
+      Creates a single index entry.  Can be made a subentry by separating the
+      subentry text with a semicolon (this notation is also used below to
+      describe what entries are created).
+   pair
+      ``pair: loop; statement`` is a shortcut that creates two index entries,
+      namely ``loop; statement`` and ``statement; loop``.
+   triple
+      Likewise, ``triple: module; search; path`` is a shortcut that creates
+      three index entries, which are ``module; search path``, ``search; path,
+      module`` and ``path; module search``.
+   module, keyword, operator, object, exception, statement, builtin
+      These all create two index entries.  For example, ``module: hashlib``
+      creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
+      are Python-specific and therefore deprecated.)
+
+   For index directives containing only "single" entries, there is a shorthand
+   notation::
+
+      .. index:: BNF, grammar, syntax, notation
+
+   This creates four index entries.
+
+.. rst:role:: index
+
+   While the :rst:dir:`index` directive is a block-level markup and links to the
+   beginning of the next paragraph, there is also a corresponding role that sets
+   the link target directly where it is used.
+
+   The content of the role can be a simple phrase, which is then kept in the
+   text and used as an index entry.  It can also be a combination of text and
+   index entry, styled like with explicit targets of cross-references.  In that
+   case, the "target" part can be a full entry as described for the directive
+   above.  For example::
+
+      This is a normal reST :index:`paragraph` that contains several
+      :index:`index entries <pair: index; entry>`.
+
+   .. versionadded:: 1.1
+
+
 .. _tags:
 
 Including content based on tags
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index ecc6b4a6..52a5019b 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -144,68 +144,6 @@ For local tables of contents, use the standard reST :dudir:`contents directive
 <contents>`.
 
 
-Index-generating markup
------------------------
-
-Sphinx automatically creates index entries from all object descriptions (like
-functions, classes or attributes) like discussed in :ref:`domains`.
-
-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.
-
-.. 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.
-
-   For example::
-
-      .. index::
-         single: execution; context
-         module: __main__
-         module: sys
-         triple: module; search; path
-
-      The execution context
-      ---------------------
-
-      ...
-
-   This directive contains five entries, which will be converted to entries in
-   the generated index which link to the exact location of the index statement
-   (or, in case of offline media, the corresponding page number).
-
-   Since index directives generate cross-reference targets at their location in
-   the source, it makes sense to put them *before* the thing they refer to --
-   e.g. a heading, as in the example above.
-
-   The possible entry types are:
-
-   single
-      Creates a single index entry.  Can be made a subentry by separating the
-      subentry text with a semicolon (this notation is also used below to
-      describe what entries are created).
-   pair
-      ``pair: loop; statement`` is a shortcut that creates two index entries,
-      namely ``loop; statement`` and ``statement; loop``.
-   triple
-      Likewise, ``triple: module; search; path`` is a shortcut that creates
-      three index entries, which are ``module; search path``, ``search; path,
-      module`` and ``path; module search``.
-   module, keyword, operator, object, exception, statement, builtin
-      These all create two index entries.  For example, ``module: hashlib``
-      creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
-      are Python-specific and therefore deprecated.)
-
-   For index directives containing only "single" entries, there is a shorthand
-   notation::
-
-      .. index:: BNF, grammar, syntax, notation
-
-   This creates four index entries.
-
-
 Glossary
 --------
 
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 2c0a418a..0b6a46c1 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -41,6 +41,8 @@ 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.
 
+   **Entries**
+
    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
@@ -59,8 +61,10 @@ tables of contents.  The ``toctree`` directive is the central element.
    You can also add external links, by giving an HTTP URL instead of a document
    name.
 
+   **Section numbering**
+
    If you want to have section numbers even in HTML output, give the toctree a
-   ``numbered`` flag option.  For example::
+   ``numbered`` option.  For example::
 
       .. toctree::
          :numbered:
@@ -71,6 +75,11 @@ tables of contents.  The ``toctree`` directive is the central element.
    Numbering then starts at the heading of ``foo``.  Sub-toctrees are
    automatically numbered (don't give the ``numbered`` flag to those).
 
+   Numbering up to a specific depth is also possible, by giving the depth as a
+   numeric argument to ``numbered``.
+
+   **Additional options**
+
    If you want only the titles of documents in the tree to show up, not other
    headings of the same level, you can use the ``titlesonly`` option::
 
@@ -133,6 +142,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 1.0
       Added "titlesonly" option.
 
+   .. versionchanged:: 1.1
+      Added numeric argument to "numbered".
+
 
 Special names
 -------------