
Paragraph-level markup
**********************

These directives create short paragraphs and can be used inside
information units as well as normal text:

.. 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 the directive should be written in complete
   sentences and include all appropriate punctuation.

   Example:

      .. note::

         This function is not suitable for sending spam e-mails.

.. 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 "note" in that it is recommended over "note" for information
   regarding security.

.. 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 should be placed at the top of the module section
   before any prose.

   The first argument must be given and is the version in question;
   you can add a second argument consisting of a *brief* explanation
   of the change.

   Example:

      .. versionadded:: 2.5
         The *spam* parameter.

   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.

.. versionchanged:: version

   Similar to "versionadded", but describes when and what changed in
   the named feature in some way (new parameters, changed side
   effects, etc.).

.. deprecated:: version

   Similar to "versionchanged", but describes when the feature was
   deprecated.  An explanation can also be given, for example to
   inform the reader what should be used instead.  Example:

      .. deprecated:: 3.1
         Use :func:`spam` instead.

======================================================================

.. seealso::

   Many sections include a list of references to module documentation
   or external documents.  These lists are created using the "seealso"
   directive.

   The "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 "seealso" directive should be a reST definition
   list. Example:

      .. seealso::

         Module :py:mod:`zipfile`
            Documentation of the :py:mod:`zipfile` standard module.

         `GNU tar manual, Basic Tar Format <http://link>`_
            Documentation for tar archive files, including GNU tar extensions.

   There's also a "short form" allowed that looks like this:

      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

   New in version 0.5: The short form.

.. rubric:: title

   This directive creates a paragraph heading that is not used to
   create a table of contents node.

   Note: If the *title* of the rubric is "Footnotes" (or the selected
     language's equivalent), this rubric is ignored by the LaTeX
     writer, since it is assumed to only contain footnote definitions
     and therefore would create an empty heading.

.. centered::

   This directive creates a centered boldfaced line of text.  Use it
   as follows:

      .. centered:: LICENSE AGREEMENT

   Deprecated since version 1.1: This presentation-only directive is a
   legacy from older versions.  Use a "rst-class" directive instead
   and add an appropriate style.

.. 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 reducing spacing between items, depending on the
   builder.

   For builders that support the horizontal distribution, there is a
   "columns" option that specifies the number of columns; it defaults
   to 2.  Example:

      .. hlist::
         :columns: 3

         * A list of
         * short items
         * that should be
         * displayed
         * horizontally

   New in version 0.6.


Table-of-contents markup
************************

The "toctree" directive, which generates tables of contents of
subdocuments, is described in *The TOC tree*.

For local tables of contents, use the standard reST contents
directive.


Glossary
********

.. glossary:: 

   This directive must contain a reST definition-list-like markup with
   terms and definitions.  The definitions will then be referencable
   with the "term" role.  Example:

      .. glossary::

         environment
            A structure where information about all documents under the root is
            saved, and used for cross-referencing.  The environment is pickled
            after the parsing stage, so that successive runs only need to read
            and parse new and changed documents.

         source directory
            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.)

   New in version 0.6: You can now give the glossary directive a
   ":sorted:" flag that will automatically sort the entries
   alphabetically.

   Changed in version 1.1: Now supports multiple terms and inline
   markup in terms.


Grammar production displays
***************************

Special markup is available for displaying the productions of a formal
grammar. The markup is simple and does not attempt to model all
aspects of BNF (or any 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:

.. 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 following definition.  If the
   definition spans multiple lines, each continuation line must begin
   with a colon placed at the same column as in the first line.

   The argument to "productionlist" serves to distinguish different
   sets of production lists that belong to different grammars.

   Blank lines are not allowed within "productionlist" directive
   arguments.

   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 "token".

   Note that no further reST parsing is done in the production, so
   that you don't have to escape "*" or "|" characters.

The following is an example taken from the Python Reference Manual:

   .. productionlist::
      try_stmt: try1_stmt | try2_stmt
      try1_stmt: "try" ":" `suite`
               : ("except" [`expression` ["," `target`]] ":" `suite`)+
               : ["else" ":" `suite`]
               : ["finally" ":" `suite`]
      try2_stmt: "try" ":" `suite`
               : "finally" ":" `suite`
