Directives
**********

As previously discussed, a directive is a generic block of explicit
markup. While Docutils provides a number of directives, Sphinx
provides many more and uses directives as one of the primary extension
mechanisms.

See Domains for roles added by domains.

See also:

  Refer to the reStructuredText Primer for an overview of the
  directives provided by Docutils.


Table of contents
=================

Since reST does not have facilities to interconnect several documents,
or split documents into multiple output files, Sphinx uses a custom
directive to add relations between the single files the documentation
is made of, as well as tables of contents.  The "toctree" directive is
the central element.

Note:

  Simple "inclusion" of one file in another can be done with the
  include directive.

Note:

  To create table of contents for current document (.rst file), use
  the standard reST contents directive.

.. toctree::

   This directive inserts a "TOC tree" at the current location, using
   the individual TOCs (including "sub-TOC trees") of the documents
   given in the directive body.  Relative document names (not
   beginning with a slash) are relative to the document the directive
   occurs in, absolute names are relative to the source directory.  A
   numeric "maxdepth" option may be given to indicate the depth of the
   tree; by default, all levels are included. [1]

   The representation of "TOC tree" is changed in each output format.
   The builders that output multiple files (ex. HTML) treat it as a
   collection of hyperlinks.  On the other hand, the builders that
   output a single file (ex. LaTeX, man page, etc.) replace it with
   the content of the documents on the TOC tree.

   Consider this example (taken from the Python docs' library
   reference index):

      .. toctree::
         :maxdepth: 2

         intro
         strings
         datatypes
         numeric
         (many more documents listed here)

   This accomplishes two things:

   * Tables of contents from all those documents are inserted, with a
     maximum depth of two, that means one nested heading.  "toctree"
     directives in those documents are also taken into account.

   * Sphinx knows the relative order of the documents "intro",
     "strings" and so forth, and it knows that they are children of
     the shown document, the library index.  From this information it
     generates "next chapter", "previous chapter" and "parent chapter"
     links.

   **Entries**

   Document titles in the "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 hyperlinks (and Sphinx's cross-referencing syntax). This
   looks like:

      .. toctree::

         intro
         All about strings <strings>
         datatypes

   The second line above will link to the "strings" document, but will
   use the title "All about strings" instead of the title of the
   "strings" document.

   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
   **toplevel** toctree a "numbered" option.  For example:

      .. toctree::
         :numbered:

         foo
         bar

   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**

   You can use the "caption" option to provide a toctree caption and
   you can use the "name" option to provide an implicit target name
   that can be referenced by using "ref":

      .. toctree::
         :caption: Table of Contents
         :name: mastertoc

         foo

   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:

      .. toctree::
         :titlesonly:

         foo
         bar

   You can use "globbing" in toctree directives, by giving the "glob"
   flag option.  All entries are then matched against the list of
   available documents, and matches are inserted into the list
   alphabetically.  Example:

      .. toctree::
         :glob:

         intro*
         recipe/*
         *

   This includes first all documents whose names start with "intro",
   then all documents in the "recipe" folder, then all remaining
   documents (except the one containing the directive, of course.) [2]

   The special entry name "self" stands for the document containing
   the toctree directive.  This is useful if you want to generate a
   "sitemap" from the toctree.

   You can use the "reversed" flag option to reverse the order of the
   entries in the list. This can be useful when using the "glob" flag
   option to reverse the ordering of the files.  Example:

      .. toctree::
         :glob:
         :reversed:

         recipe/*

   You can also give a "hidden" option to the directive, like this:

      .. toctree::
         :hidden:

         doc_1
         doc_2

   This will still notify Sphinx of the document hierarchy, but not
   insert links into the document at the location of the directive --
   this makes sense if you intend to insert these links yourself, in a
   different style, or in the HTML sidebar.

   In cases where you want to have only one top-level toctree and hide
   all other lower level toctrees you can add the "includehidden"
   option to the top-level toctree entry:

      .. toctree::
         :includehidden:

         doc_1
         doc_2

   All other toctree entries can then be eliminated by the "hidden"
   option.

   In the end, all documents in the *source directory* (or
   subdirectories) must occur in some "toctree" directive; Sphinx will
   emit a warning if it finds a file that is not included, because
   that means that this file will not be reachable through standard
   navigation.

   Use "exclude_patterns" to explicitly exclude documents or
   directories from building completely.  Use the "orphan" metadata to
   let a document be built, but notify Sphinx that it is not reachable
   via a toctree.

   The "root document" (selected by "root_doc") is the "root" of the
   TOC tree hierarchy.  It can be used as the documentation's main
   page, or as a "full table of contents" if you don't give a
   "maxdepth" option.

   Changed in version 0.3: Added "globbing" option.

   Changed in version 0.6: Added "numbered" and "hidden" options as
   well as external links and support for "self" references.

   Changed in version 1.0: Added "titlesonly" option.

   Changed in version 1.1: Added numeric argument to "numbered".

   Changed in version 1.2: Added "includehidden" option.

   Changed in version 1.3: Added "caption" and "name" option.


Special names
-------------

Sphinx reserves some document names for its own use; you should not
try to create documents with these names -- it will cause problems.

The special document names (and pages generated for them) are:

* "genindex", "modindex", "search"

  These are used for the general index, the Python module index, and
  the search page, respectively.

  The general index is populated with entries from modules, all index-
  generating object descriptions, and from "index" directives.

  The Python module index contains one entry per "py:module"
  directive.

  The search page contains a form that uses the generated JSON search
  index and JavaScript to full-text search the generated documents for
  search words; it should work on every major browser that supports
  modern JavaScript.

* every name beginning with "_"

  Though few such names are currently used by Sphinx, you should not
  create documents or document-containing directories with such names.
  (Using "_" as a prefix for a custom template directory is fine.)

Warning:

  Be careful with unusual characters in filenames.  Some formats may
  interpret these characters in unexpected ways:

  * Do not use the colon ":" for HTML based formats.  Links to other
    parts may not work.

  * Do not use the plus "+" for the ePub format.  Some resources may
    not be found.


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 subsections.  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.


Showing code examples
=====================

There are multiple ways to show syntax-highlighted literal code blocks
in Sphinx:

* using reST doctest blocks;

* using reST literal blocks, optionally in combination with the
  "highlight" directive;

* using the "code-block" directive;

* and using the "literalinclude" directive.

Doctest blocks can only be used to show interactive Python sessions,
while the remaining three can be used for other languages. Of these
three, literal blocks are useful when an entire document, or at least
large sections of it, use code blocks with the same syntax and which
should be styled in the same manner. On the other hand, the "code-
block" directive makes more sense when you want more fine-tuned
control over the styling of each block or when you have a document
containing code blocks using multiple varied syntaxes. Finally, the
"literalinclude" directive is useful for including entire code files
in your documentation.

In all cases, Syntax highlighting is provided by Pygments. When using
literal blocks, this is configured using any "highlight" directives in
the source file. When a "highlight" directive is encountered, it is
used until the next "highlight" directive is encountered. If there is
no "highlight" directive in the file, the global highlighting language
is used. This defaults to "python" but can be configured using the
"highlight_language" config value. The following values are supported:

* "none" (no highlighting)

* "default" (similar to "python3" but with a fallback to "none"
  without warning highlighting fails; the default when
  "highlight_language" isn't set)

* "guess" (let Pygments guess the lexer based on contents, only works
  with certain well-recognizable languages)

* "python"

* "rest"

* "c"

* ... and any other lexer alias that Pygments supports

If highlighting with the selected language fails (i.e. Pygments emits
an "Error" token), the block is not highlighted in any way.

Important:

  The list of lexer aliases supported is tied to the Pygment version.
  If you want to ensure consistent highlighting, you should fix your
  version of Pygments.

.. highlight:: language

   Example:

      .. highlight:: c

   This language is used until the next "highlight" directive is
   encountered. As discussed previously, *language* can be any lexer
   alias supported by Pygments.

   -[ options ]-

   :linenothreshold: threshold (number (optional))

      Enable to generate line numbers for code blocks.

      This option takes an optional number as threshold parameter.  If
      any threshold given, the directive will produce line numbers
      only for the code blocks longer than N lines.  If not given,
      line numbers will be produced for all of code blocks.

      Example:

         .. highlight:: python
            :linenothreshold: 5

   :force: (no value)

      If given, minor errors on highlighting are ignored.

      New in version 2.1.

.. code-block:: [language]
.. sourcecode:: [language]

   Example:

      .. code-block:: ruby

         Some Ruby code.

   The directive's alias name "sourcecode" works as well.  This
   directive takes a language name as an argument.  It can be any
   lexer alias supported by Pygments.  If it is not given, the setting
   of "highlight" directive will be used.  If not set,
   "highlight_language" will be used.  To display a code example
   *inline* within other text, rather than as a separate block, you
   can use the "code" role instead.

   Changed in version 2.0: The "language" argument becomes optional.

   -[ options ]-

   :linenos: (no value)

      Enable to generate line numbers for the code block:

         .. code-block:: ruby
            :linenos:

            Some more Ruby code.

   :lineno-start: number (number)

      Set the first line number of the code block.  If present,
      "linenos" option is also automatically activated:

         .. code-block:: ruby
            :lineno-start: 10

            Some more Ruby code, with line numbering starting at 10.

      New in version 1.3.

   :emphasize-lines: line numbers (comma separated numbers)

      Emphasize particular lines of the code block:

         .. code-block:: python
            :emphasize-lines: 3,5

            def some_function():
                interesting = False
                print 'This line is highlighted.'
                print 'This one is not...'
                print '...but this one is.'

      New in version 1.1.

      Changed in version 1.6.6: LaTeX supports the "emphasize-lines"
      option.

   :caption: caption of code block (text)

      Set a caption to the code block.

      New in version 1.3.

   :name: a label for hyperlink (text)

      Define implicit target name that can be referenced by using
      "ref".  For example:

         .. code-block:: python
            :caption: this.py
            :name: this-py

            print 'Explicit is better than implicit.'

      In order to cross-reference a code-block using either the "ref"
      or the "numref" role, it is necessary that both **name** and
      **caption** be defined. The argument of **name** can then be
      given to "numref" to generate the cross-reference. Example:

         See :numref:`this-py` for an example.

      When using "ref", it is possible to generate a cross-reference
      with only **name** defined, provided an explicit title is given.
      Example:

         See :ref:`this code snippet <this-py>` for an example.

      New in version 1.3.

   :class: class names (a list of class names separated by spaces)

      The class name of the graph.

      New in version 1.4.

   :dedent: number (number or no value)

      Strip indentation characters from the code block.  When number
      given, leading N characters are removed.  When no argument
      given, leading spaces are removed via "textwrap.dedent()".  For
      example:

         .. code-block:: ruby
            :linenos:
            :dedent: 4

                some ruby code

      New in version 1.3.

      Changed in version 3.5: Support automatic dedent.

   :force: (no value)

      If given, minor errors on highlighting are ignored.

      New in version 2.1.

.. literalinclude:: filename

   Longer displays of verbatim text may be included by storing the
   example text in an external file containing only plain text.  The
   file may be included using the "literalinclude" directive. [3] For
   example, to include the Python source file "example.py", use:

      .. literalinclude:: example.py

   The file name is usually relative to the current file's path.
   However, if it is absolute (starting with "/"), it is relative to
   the top source directory.

   **Additional options**

   Like "code-block", the directive supports the "linenos" flag option
   to switch on line numbers, the "lineno-start" option to select the
   first line number, the "emphasize-lines" option to emphasize
   particular lines, the "name" option to provide an implicit target
   name, the "dedent" option to strip indentation characters for the
   code block, and a "language" option to select a language different
   from the current file's standard language. In addition, it supports
   the "caption" option; however, this can be provided with no
   argument to use the filename as the caption. Example with options:

      .. literalinclude:: example.rb
         :language: ruby
         :emphasize-lines: 12,15-18
         :linenos:

   Tabs in the input are expanded if you give a "tab-width" option
   with the desired tab width.

   Include files are assumed to be encoded in the "source_encoding".
   If the file has a different encoding, you can specify it with the
   "encoding" option:

      .. literalinclude:: example.py
         :encoding: latin-1

   The directive also supports including only parts of the file.  If
   it is a Python module, you can select a class, function or method
   to include using the "pyobject" option:

      .. literalinclude:: example.py
         :pyobject: Timer.start

   This would only include the code lines belonging to the "start()"
   method in the "Timer" class within the file.

   Alternately, you can specify exactly which lines to include by
   giving a "lines" option:

      .. literalinclude:: example.py
         :lines: 1,3,5-10,20-

   This includes the lines 1, 3, 5 to 10 and lines 20 to the last
   line.

   Another way to control which part of the file is included is to use
   the "start-after" and "end-before" options (or only one of them).
   If "start-after" is given as a string option, only lines that
   follow the first line containing that string are included.  If
   "end-before" is given as a string option, only lines that precede
   the first lines containing that string are included. The "start-at"
   and "end-at" options behave in a similar way, but the lines
   containing the matched string are included.

   "start-after"/"start-at" and "end-before"/"end-at" can have same
   string. "start-after"/"start-at" filter lines before the line that
   contains option string ("start-at" will keep the line). Then "end-
   before"/"end-at" filter lines after the line that contains option
   string ("end-at" will keep the line and "end-before" skip the first
   line).

   Note:

     If you want to select only "[second-section]" of ini file like
     the following, you can use ":start-at: [second-section]" and
     ":end-before: [third-section]":

        [first-section]

        var_in_first=true

        [second-section]

        var_in_second=true

        [third-section]

        var_in_third=true

     Useful cases of these option is working with tag comments.
     ":start-after: [initialized]" and ":end-before: [initialized]"
     options keep lines between comments:

        if __name__ == "__main__":
            # [initialize]
            app.start(":8000")
            # [initialize]

   When lines have been selected in any of the ways described above,
   the line numbers in "emphasize-lines" refer to those selected
   lines, counted consecutively starting at "1".

   When specifying particular parts of a file to display, it can be
   useful to display the original line numbers. This can be done using
   the "lineno-match" option, which is however allowed only when the
   selection consists of contiguous lines.

   You can prepend and/or append a line to the included code, using
   the "prepend" and "append" option, respectively.  This is useful
   e.g. for highlighting PHP code that doesn't include the
   "<?php"/"?>" markers.

   If you want to show the diff of the code, you can specify the old
   file by giving a "diff" option:

      .. literalinclude:: example.py
         :diff: example.py.orig

   This shows the diff between "example.py" and "example.py.orig" with
   unified diff format.

   A "force" option can ignore minor errors on highlighting.

   Changed in version 0.4.3: Added the "encoding" option.

   Changed in version 0.6: Added the "pyobject", "lines", "start-
   after" and "end-before" options, as well as support for absolute
   filenames.

   Changed in version 1.0: Added the "prepend", "append", and "tab-
   width" options.

   Changed in version 1.3: Added the "diff", "lineno-match",
   "caption", "name", and "dedent" options.

   Changed in version 1.4: Added the "class" option.

   Changed in version 1.5: Added the "start-at", and "end-at" options.

   Changed in version 1.6: With both "start-after" and "lines" in use,
   the first line as per "start-after" is considered to be with line
   number "1" for "lines".

   Changed in version 2.1: Added the "force" option.

   Changed in version 3.5: Support automatic dedent.


Glossary
========

.. glossary::

   This directive must contain a reST definition-list-like markup with
   terms and definitions.  The definitions will then be referenceable
   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.)

   If you want to specify "grouping key" for general index entries,
   you can put a "key" as "term : key". For example:

      .. glossary::

         term 1 : A
         term 2 : B
            Definition of both terms.

   Note that "key" is used for grouping key as is. The "key" isn't
   normalized; key "A" and "a" become different groups. The whole
   characters in "key" is used instead of a first character; it is
   used for "Combining Character Sequence" and "Surrogate Pairs"
   grouping key.

   In i18n situation, you can specify "localized term : key" even if
   original text only have "term" part. In this case, translated
   "localized term" will be categorized in "key" group.

   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.

   Changed in version 1.4: Index key for glossary term should be
   considered *experimental*.

   Changed in version 4.4: In internationalized documentation, the
   ":sorted:" flag sorts according to translated terms.


Meta-information markup
=======================

.. sectionauthor:: name <email>

   Identifies the author of the current section.  The argument should
   include the author's name such that it can be used for presentation
   and email address.  The domain name portion of the address should
   be lower case. Example:

      .. sectionauthor:: Guido van Rossum <guido@python.org>

   By default, this markup isn't reflected in the output in any way
   (it helps keep track of contributions), but you can set the
   configuration value "show_authors" to "True" to make them produce a
   paragraph in the output.

.. codeauthor:: name <email>

   The "codeauthor" directive, which can appear multiple times, names
   the authors of the described code, just like "sectionauthor" names
   the author(s) of a piece of documentation.  It too only produces
   output if the "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
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.

.. 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
         pair: module; __main__
         pair: module; sys
         triple: module; search; path
         seealso: scope

      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 sub-entry by
      separating the sub-entry text with a semicolon (this notation is
      also used below to describe what entries are created). Examples:

         .. index:: single: execution
                    single: execution; context

      * "single: execution" creates an index entry labelled
        "execution".

      * "single: execution; context" creates an sub-entry of
        "execution" labelled "context".

   pair
      A shortcut to create two index entries. The pair of values must
      be separated by a semicolon. Example:

         .. index:: pair: loop; statement

      This would create two index entries; "loop; statement" and
      "statement; loop".

   triple
      A shortcut to create three index entries. All three values must
      be separated by a semicolon. Example:

         .. index:: triple: module; search; path

      This would create three index entries; "module; search path",
      "search; path, module", and "path; module search".

   see
      A shortcut to create an index entry that refers to another
      entry. Example:

         .. index:: see: entry; other

      This would create an index entry referring from "entry" to
      "other" (i.e. 'entry': See 'other').

   seealso
      Like "see", but inserts 'see also' instead of 'see'.

   module, keyword, operator, object, exception, statement, builtin
      These **deprecated** shortcuts all create two index entries. For
      example, "module: hashlib" creates the entries "module; hashlib"
      and "hashlib; module".

      Deprecated since version 1.0: These Python-specific entry types
      are deprecated.

      Changed in version 7.1: Removal version set to Sphinx 9.0. Using
      these entry types will now emit warnings with the "index"
      category.

   You can mark up "main" index entries by prefixing them with an
   exclamation mark.  The references to "main" entries are emphasized
   in the generated index.  For example, if two pages contain

      .. index:: Python

   and one page contains

      .. index:: ! Python

   then the backlink to the latter page is emphasized among the three
   backlinks.

   For index directives containing only "single" entries, there is a
   shorthand notation:

      .. index:: BNF, grammar, syntax, notation

   This creates four index entries.

   Changed in version 1.1: Added "see" and "seealso" types, as well as
   marking main entries.

   -[ options ]-

   :name: a label for hyperlink (text)

      Define implicit target name that can be referenced by using
      "ref".  For example:

         .. index:: Python
            :name: py-index

   New in version 3.0.

:index:

   While the "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>`.

   New in version 1.1.


Including content based on tags
===============================

.. only:: <expression>

   Include the content of the directive only if the *expression* is
   true.  The expression should consist of tags, like this:

      .. only:: html and draft

   Undefined tags are false, defined tags (via the "-t" command-line
   option or within "conf.py", see here) are true.  Boolean
   expressions, also using parentheses (like "html and (latex or
   draft)") are supported.

   The *format* and the *name* of the current builder ("html", "latex"
   or "text") are always set as a tag [4].  To make the distinction
   between format and name explicit, they are also added with the
   prefix "format_" and "builder_", e.g. the epub builder defines the
   tags  "html", "epub", "format_html" and "builder_epub".

   These standard tags are set *after* the configuration file is read,
   so they are not available there.

   All tags must follow the standard Python identifier syntax as set
   out in the Identifiers and keywords documentation.  That is, a tag
   expression may only consist of tags that conform to the syntax of
   Python variables.  In ASCII, this consists of the uppercase and
   lowercase letters "A" through "Z", the underscore "_" and, except
   for the first character, the digits "0" through "9".

   New in version 0.6.

   Changed in version 1.2: Added the name of the builder and the
   prefixes.

   Warning:

     This directive is designed to control only content of document.
     It could not control sections, labels and so on.


Tables
======

Use reStructuredText tables, i.e. either

* grid table syntax (ref),

* simple table syntax (ref),

* csv-table syntax,

* or list-table syntax.

The table directive serves as optional wrapper of the *grid* and
*simple* syntaxes.

They work fine in HTML output, but rendering tables to LaTeX is
complex. Check the "latex_table_style".

Changed in version 1.6: Merged cells (multi-row, multi-column, both)
from grid tables containing complex contents such as multiple
paragraphs, blockquotes, lists, literal blocks, will render correctly
to LaTeX output.

.. tabularcolumns:: column spec

   This directive influences only the LaTeX output for the next table
   in source.  The mandatory argument is a column specification (known
   as an "alignment preamble" in LaTeX idiom).  Please refer to a
   LaTeX documentation, such as the wiki page, for basics of such a
   column specification.

   New in version 0.3.

   Note:

     "tabularcolumns" conflicts with ":widths:" option of table
     directives.  If both are specified, ":widths:" option will be
     ignored.

   Sphinx will render tables with more than 30 rows with "longtable".
   Besides the "l", "r", "c" and "p{width}" column specifiers, one can
   also use "\X{a}{b}" (new in version 1.5) which configures the
   column width to be a fraction "a/b" of the total line width and
   "\Y{f}" (new in version 1.6) where "f" is a decimal: for example
   "\Y{0.2}" means that the column will occupy "0.2" times the line
   width.

   When this directive is used for a table with at most 30 rows,
   Sphinx will render it with "tabulary".  One can then use specific
   column types "L" (left), "R" (right), "C" (centered) and "J"
   (justified).  They have the effect of a "p{width}" (i.e. each cell
   is a LaTeX "\parbox") with the specified internal text alignment
   and an automatically computed "width".

   Warning:

     * Cells that contain list-like elements such as object
       descriptions, blockquotes or any kind of lists are not
       compatible with the "LRCJ" column types.  The column type must
       then be some "p{width}" with an explicit "width" (or "\X{a}{b}"
       or "\Y{f}").

     * Literal blocks do not work with "tabulary" at all.  Sphinx will
       fall back to "tabular" or "longtable" environments and generate
       a suitable column specification.

In absence of the "tabularcolumns" directive, and for a table with at
most 30 rows and no problematic cells as described in the above
warning, Sphinx uses "tabulary" and the "J" column-type for every
column.

Changed in version 1.6: Formerly, the "L" column-type was used (text
is flushed-left).  To revert to this, include "\newcolumntype{T}{L}"
in the LaTeX preamble, as in fact Sphinx uses "T" and sets it by
default to be an alias of "J".

Hint:

  A frequent issue with "tabulary" is that columns with little
  contents appear to be "squeezed".  One can add to the LaTeX preamble
  for example "\setlength{\tymin}{40pt}" to ensure a minimal column
  width of "40pt", the "tabulary" default of "10pt" being too small.

Hint:

  To force usage of the LaTeX "longtable" environment pass "longtable"
  as a ":class:" option to table, csv-table, or list-table.  Use rst-
  class for other tables.


Math
====

The input language for mathematics is LaTeX markup.  This is the de-
facto standard for plain-text math notation and has the added
advantage that no further translation is necessary when building LaTeX
output.

Keep in mind that when you put math markup in **Python docstrings**
read by "autodoc", you either have to double all backslashes, or use
Python raw strings ("r"raw"").

.. math::

   Directive for displayed math (math that takes the whole line for
   itself).

   The directive supports multiple equations, which should be
   separated by a blank line:

      .. math::

         (a + b)^2 = a^2 + 2ab + b^2

         (a - b)^2 = a^2 - 2ab + b^2

   In addition, each single equation is set within a "split"
   environment, which means that you can have multiple aligned lines
   in an equation, aligned at "&" and separated by "\\":

      .. math::

         (a + b)^2  &=  (a + b)(a + b) \\
                    &=  a^2 + 2ab + b^2

   For more details, look into the documentation of the AmSMath LaTeX
   package.

   When the math is only one line of text, it can also be given as a
   directive argument:

      .. math:: (a + b)^2 = a^2 + 2ab + b^2

   Normally, equations are not numbered.  If you want your equation to
   get a number, use the "label" option.  When given, it selects an
   internal label for the equation, by which it can be cross-
   referenced, and causes an equation number to be issued.  See "eq"
   for an example.  The numbering style depends on the output format.

   There is also an option "nowrap" that prevents any wrapping of the
   given math in a math environment.  When you give this option, you
   must make sure yourself that the math is properly set up.  For
   example:

      .. math::
         :nowrap:

         \begin{eqnarray}
            y    & = & ax^2 + bx + c \\
            f(x) & = & x^2 + 2xy + y^2
         \end{eqnarray}

See also:

  Math support for HTML outputs in Sphinx
     Rendering options for math with HTML builders.

  "latex_engine"
     Explains how to configure LaTeX builder to support Unicode
     literals in math mark-up.


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:: [productionGroup]

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

   The *productionGroup* argument to "productionlist" serves to
   distinguish different sets of production lists that belong to
   different grammars.  Multiple production lists with the same
   *productionGroup* thus define rules in the same scope.

   Inside of the production list, tokens implicitly refer to
   productions from the current group. You can refer to the production
   of another grammar by prefixing the token with its group name and a
   colon, e.g, ""otherGroup:sum"". If the group of the token should
   not be shown in the production, it can be prefixed by a tilde,
   e.g., ""~otherGroup:sum"". To refer to a production from an unnamed
   grammar, the token should be prefixed by a colon, e.g., "":sum"".

   Outside of the production list, if you have given a
   *productionGroup* argument you must prefix the token name in the
   cross-reference with the group name and a colon, e.g.,
   ""myGroup:sum"" instead of just ""sum"". If the group should not be
   shown in the title of the link either an explicit title can be
   given (e.g., ""myTitle <myGroup:sum>""), or the target can be
   prefixed with a tilde (e.g., ""~myGroup:sum"").

   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`

-[ Footnotes ]-

[1] The LaTeX writer only refers the "maxdepth" option of first
    toctree directive in the document.

[2] A note on available globbing syntax: you can use the standard
    shell constructs "*", "?", "[...]" and "[!...]" with the feature
    that these all don't match slashes.  A double star "**" can be
    used to match any sequence of characters *including* slashes.

[3] There is a standard ".. include" directive, but it raises errors
    if the file is not found.  This one only emits a warning.

[4] For most builders name and format are the same. At the moment only
    builders derived from the html builder distinguish between the
    builder format and the builder name.

    Note that the current builder tag is not available in "conf.py",
    it is only available after the builder is initialized.
