#504: Add an `index` role, to make inline index entries.

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