diff options
Diffstat (limited to 'doc/markup/para.rst')
| -rw-r--r-- | doc/markup/para.rst | 91 |
1 files changed, 24 insertions, 67 deletions
diff --git a/doc/markup/para.rst b/doc/markup/para.rst index ecc6b4a6..b532bc63 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -52,7 +52,7 @@ units as well as normal text: Similar to :rst:dir:`versionadded`, but describes when and what changed in the named feature in some way (new parameters, changed side effects, etc.). -.. rst:directive:: .. deprecated:: vesion +.. rst:directive:: .. deprecated:: version Similar to :rst:dir:`versionchanged`, but describes when the feature was deprecated. An explanation can also be given, for example to inform the @@ -112,6 +112,10 @@ units as well as normal text: .. centered:: LICENSE AGREEMENT + .. deprecated:: 1.1 + This presentation-only directive is a legacy from older versions. Use a + :rst:dir:`rst-class` directive instead and add an appropriate style. + .. rst:directive:: hlist @@ -141,69 +145,7 @@ 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 :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. +<table-of-contents>`. Glossary @@ -211,9 +153,9 @@ Glossary .. rst:directive:: .. glossary:: - This directive must contain a reST definition list with terms and - definitions. The definitions will then be referencable with the :rst:role:`term` - role. Example:: + This directive must contain a reST definition-list-like markup with terms and + definitions. The definitions will then be referencable with the + :rst:role:`term` role. Example:: .. glossary:: @@ -227,10 +169,25 @@ Glossary The directory which, including its subdirectories, contains all source files for one Sphinx project. + In contrast to regular definition lists, *multiple* terms per entry are + allowed, and inline markup is allowed in terms. You can link to all of the + terms. For example:: + + .. glossary:: + + term 1 + term 2 + Definition of both terms. + + (When the glossary is sorted, the first term determines the sort order.) + .. versionadded:: 0.6 You can now give the glossary directive a ``:sorted:`` flag that will automatically sort the entries alphabetically. + .. versionchanged:: 1.1 + Now supports multiple terms and inline markup in terms. + Grammar production displays --------------------------- |