╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                             reStructuredText Directives                                              ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name  Field Value                                           ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Author     │ David Goodger                                         │
├────────────┼───────────────────────────────────────────────────────┤
│ Contact    │ docutils-develop@lists.sourceforge.net                │
├────────────┼───────────────────────────────────────────────────────┤
│ Revision   │ $Revision: 8959 $                                     │
├────────────┼───────────────────────────────────────────────────────┤
│ Date       │ $Date: 2022-01-21 14:45:42 +0100 (Fr, 21. Jan 2022) $ │
├────────────┼───────────────────────────────────────────────────────┤
│ Copyright  │ This document has been placed in the public domain.   │
└────────────┴───────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Contents                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
This document describes the directives implemented in the reference reStructuredText parser.

Directives have the following syntax:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 +-------+-------------------------------+                                                                            
 | ".. " | directive type "::" directive |                                                                            
 +-------+ block                         |                                                                            
         |                               |                                                                            
         +-------------------------------+                                                                            
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Directives begin with an explicit markup start (two periods and a space), followed by the directive type and two colons 
(collectively, the "directive marker").  The directive block begins immediately after the directive marker, and includes
all subsequent indented lines.  The directive block is divided into arguments, options (a field list), and content (in 
that order), any of which may appear.  See the Directives section in the reStructuredText Markup Specification for 
syntax details.

Descriptions below list "doctree elements" (document tree element names; XML DTD generic identifiers) corresponding to 
individual directives.  For details on the hierarchy of elements, please see The Docutils Document Tree and the Docutils
Generic DTD XML document type definition.  For directive implementation details, see Creating reStructuredText 
Directives.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                     Admonitions                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                 Specific Admonitions                                                 ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                         ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Types     │ "attention", "caution", "danger", "error", "hint",  │
│                     │ "important", "note", "tip", "warning", "admonition" │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ Doctree Elements    │ attention, caution, danger, error, hint, important, │
│                     │ note, tip, warning, admonition, title               │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ Directive Arguments │ None.                                               │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ Directive Options   │ class, name                                         │
├─────────────────────┼─────────────────────────────────────────────────────┤
│ Directive Content   │ Interpreted as body elements.                       │
└─────────────────────┴─────────────────────────────────────────────────────┘
Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can.  They contain arbitrary
body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with
a title matching the admonition type.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. DANGER::                                                                                                          
    Beware killer rabbits!                                                                                            
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This directive might be rendered something like this:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 +------------------------+                                                                                           
 |        !DANGER!        |                                                                                           
 |                        |                                                                                           
 | Beware killer rabbits! |                                                                                           
 +------------------------+                                                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following admonition directives have been implemented:

attention
caution
danger
error
hint
important
note
tip
warning

Any text immediately following the directive indicator (on the same line and/or indented on following lines) is 
interpreted as a directive block and is parsed for normal body elements.  For example, the following "note" admonition 
directive contains one paragraph and a bullet list consisting of two list items:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. note:: This is a note admonition.                                                                                 
    This is the second line of the first paragraph.                                                                   
                                                                                                                      
    - The note contains all indented body elements                                                                    
      following.                                                                                                      
    - It includes this bullet list.                                                                                   
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                  Generic Admonition                                                  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                      ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "admonition"                     │
├─────────────────────┼──────────────────────────────────┤
│ Doctree Elements    │ admonition, title                │
├─────────────────────┼──────────────────────────────────┤
│ Directive Arguments │ One, required (admonition title) │
├─────────────────────┼──────────────────────────────────┤
│ Directive Options   │ class, name                      │
├─────────────────────┼──────────────────────────────────┤
│ Directive Content   │ Interpreted as body elements.    │
└─────────────────────┴──────────────────────────────────┘
This is a generic, titled admonition.  The title may be anything the author desires.

The author-supplied title is also used as a "classes" attribute value after being converted into a valid identifier form
(down-cased; non-alphanumeric characters converted to single hyphens; "admonition-" prefixed).  For example, this 
admonition:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. admonition:: And, by the way...                                                                                   
                                                                                                                      
    You can make up your own admonition too.                                                                          
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
becomes the following document tree (pseudo-XML)
┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐
 <document source="test data">                                                                                        
     <admonition classes="admonition-and-by-the-way">                                                                 
         <title>                                                                                                      
             And, by the way...                                                                                       
         <paragraph>                                                                                                  
             You can make up your own admonition too.                                                                 
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The class option overrides the computed "classes" attribute value.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Images                                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
There are two image directives: "image" and "figure".

It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX 
engine, HTML5 browser, ODT, ...). The following, non exhaustive table provides an overview

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Image                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "image"                    │
├─────────────────────┼────────────────────────────┤
│ Doctree Element     │ image                      │
├─────────────────────┼────────────────────────────┤
│ Directive Arguments │ One, required (image URI). │
├─────────────────────┼────────────────────────────┤
│ Directive Options   │ Possible (see below).      │
├─────────────────────┼────────────────────────────┤
│ Directive Content   │ None.                      │
└─────────────────────┴────────────────────────────┘
An "image" is a simple picture:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. image:: picture.png                                                                                               
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Inline images can be defined with an "image" directive in a substitution definition

The URI for the image source file is specified in the directive argument.  As with hyperlink targets, the image URI may 
begin on the same line as the explicit markup start and target name, or it may begin in an indented text block 
immediately following, with no intervening blank lines.  If there are multiple lines in the link block, they are 
stripped of leading and trailing whitespace and joined together.

Optionally, the image link block may contain a flat field list, the .  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. image:: picture.jpeg                                                                                              
    :height: 100px                                                                                                    
    :width: 200 px                                                                                                    
    :scale: 50 %                                                                                                      
    :alt: alternate text                                                                                              
    :align: right                                                                                                     
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    alt : text
      Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken 
by applications for visually impaired users.

    height : length
      The desired height of the image. Used to reserve space or scale the image vertically.  When the "scale" option is 
also specified, they are combined.  For example, a height of 200px and a scale of 50 is equivalent to a height of 100px 
with no scale.

    width : length or percentage of the current line width
      The width of the image. Used to reserve space or scale the image horizontally.  As with "height" above, when the 
"scale" option is also specified, they are combined.

    scale : integer percentage (the "%" symbol is optional)
      The uniform scaling factor of the image.  The default is "100Â %", i.e. no scaling.  If no "height" or "width" 
options are specified, the Python Imaging Library (PIL/Pillow) may be used to determine them, if it is installed and the
image file is available.

    align : "top", "middle", "bottom", "left", "center", or "right"
      The alignment of the image, equivalent to the HTML <img> tag's deprecated "align" attribute or the corresponding 
"vertical-align" and "text-align" CSS properties. The values "top", "middle", and "bottom" control an image's vertical 
alignment (relative to the text baseline); they are only useful for inline images (substitutions). The values "left", 
"center", and "right" control an image's horizontal alignment, allowing the image to float and have the text flow around
it.  The specific behavior depends upon the browser or rendering software used.

    target : text (URI or reference name)
      Makes the image into a hyperlink reference ("clickable").  The option argument may be a URI (relative or 
absolute), or a reference name with underscore suffix (e.g. `a name`_).
and the common options class and name.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Figure                                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                       ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "figure"                                          │
├─────────────────────┼───────────────────────────────────────────────────┤
│ Doctree Elements    │ figure, image, caption, legend                    │
├─────────────────────┼───────────────────────────────────────────────────┤
│ Directive Arguments │ One, required (image URI).                        │
├─────────────────────┼───────────────────────────────────────────────────┤
│ Directive Options   │ Possible (see below).                             │
├─────────────────────┼───────────────────────────────────────────────────┤
│ Directive Content   │ Interpreted as the figure caption and an optional │
│                     │ legend.                                           │
└─────────────────────┴───────────────────────────────────────────────────┘
A "figure" consists of image data (including image options), an optional caption (a single paragraph), and an optional 
legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps
the page layout.
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. figure:: picture.png                                                                                              
    :scale: 50 %                                                                                                      
    :alt: map to buried treasure                                                                                      
                                                                                                                      
    This is the caption of the figure (a simple paragraph).                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
There must be blank lines before the caption paragraph and before the legend.  To specify a legend without a caption, 
use an empty comment ("..") in place of the caption.

The "figure" directive supports all of the options of the "image" directive (see image options above). These options 
(except "align") are passed on to the contained image.

    align : "left", "center", or "right"
      The horizontal alignment of the figure, allowing the image to float and have the text flow around it.  The 
specific behavior depends upon the browser or rendering software used.
In addition, the following options are recognized:
    figwidth : "image", length, or percentage of current line width
      The width of the figure. Limits the horizontal space used by the figure. A special value of "image" is allowed, in
which case the included image's actual width is used (requires the Python Imaging Library). If the image file is not 
found or the required software is unavailable, this option is ignored.  Sets the "width" attribute of the "figure" 
doctree element.  This option does not scale the included image; use the "width" image option for that.

    figclass : text
      Set a "classes" attribute value on the figure element.  See the class directive below.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                    Body Elements                                                     ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Topic                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                    ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "topic"                        │
├─────────────────────┼────────────────────────────────┤
│ Doctree Element     │ topic                          │
├─────────────────────┼────────────────────────────────┤
│ Directive Arguments │ One, required (topic title).   │
├─────────────────────┼────────────────────────────────┤
│ Directive Options   │ class, name                    │
├─────────────────────┼────────────────────────────────┤
│ Directive Content   │ Interpreted as the topic body. │
└─────────────────────┴────────────────────────────────┘
A topic is like a block quote with a title, or a self-contained section with no subsections.  Use the "topic" directive 
to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or
transition may occur.  Body elements and topics may not contain nested topics.

The directive's sole argument is interpreted as the topic title; the next line must be blank.  All subsequent lines make
up the topic body, interpreted as body elements.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. topic:: Topic Title                                                                                               
                                                                                                                      
     Subsequent indented lines comprise                                                                               
     the body of the topic, and are                                                                                   
     interpreted as body elements.                                                                                    
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Sidebar                                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                      ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "sidebar"                        │
├─────────────────────┼──────────────────────────────────┤
│ Doctree Element     │ sidebar                          │
├─────────────────────┼──────────────────────────────────┤
│ Directive Arguments │ One, optional (sidebar title).   │
├─────────────────────┼──────────────────────────────────┤
│ Directive Options   │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ Directive Content   │ Interpreted as the sidebar body. │
└─────────────────────┴──────────────────────────────────┘
Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference 
material.  A sidebar is typically offset by a border and "floats" to the side of the page; the document's main text may 
flow around it.  Sidebars can also be likened to super-footnotes; their content is outside of the flow of the document's
main text.

Sidebars may occur anywhere a section or transition may occur.  Body elements (including sidebars) may not contain 
nested sidebars.

The directive's sole argument is interpreted as the sidebar title, which may be followed by a subtitle option (see 
below); the next line must be blank.  All subsequent lines make up the sidebar body, interpreted as body elements.  For 
example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. sidebar:: Optional Sidebar Title                                                                                  
    :subtitle: Optional Sidebar Subtitle                                                                              
                                                                                                                      
    Subsequent indented lines comprise                                                                                
    the body of the sidebar, and are                                                                                  
    interpreted as body elements.                                                                                     
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    subtitle : text
      The sidebar's subtitle.
and the common options class and name.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Line Block                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╭──────────────────────────────────────────────────── Admonition:  ────────────────────────────────────────────────────╮
│ Deprecated  The "line-block" directive is deprecated.  Use the line block syntax instead.                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                         ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "line-block"                        │
├─────────────────────┼─────────────────────────────────────┤
│ Doctree Element     │ line_block                          │
├─────────────────────┼─────────────────────────────────────┤
│ Directive Arguments │ None.                               │
├─────────────────────┼─────────────────────────────────────┤
│ Directive Options   │ class, name                         │
├─────────────────────┼─────────────────────────────────────┤
│ Directive Content   │ Becomes the body of the line block. │
└─────────────────────┴─────────────────────────────────────┘
The "line-block" directive constructs an element where line breaks and initial indentation is significant and inline 
markup is supported.  It is equivalent to a parsed literal block with different rendering: typically in an ordinary 
serif typeface instead of a typewriter/monospaced face, and not automatically indented.  (Have the line-block directive 
begin a block quote to get an indented line block.)  Line blocks are useful for address blocks and verse (poetry, song 
lyrics), where the structure of lines is significant.  For example, here's a classic:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by                                                          
 Ewan McTeagle (for Lassie O'Shea):                                                                                   
                                                                                                                      
     .. line-block::                                                                                                  
                                                                                                                      
         Lend us a couple of bob till Thursday.                                                                       
         I'm absolutely skint.                                                                                        
         But I'm expecting a postal order and I can pay you back                                                      
             as soon as it comes.                                                                                     
         Love, Ewan.                                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                 Parsed Literal Block                                                 ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                            ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "parsed-literal"                       │
├─────────────────────┼────────────────────────────────────────┤
│ Doctree Element     │ literal_block                          │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Arguments │ None.                                  │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Options   │ class, name                            │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Content   │ Becomes the body of the literal block. │
└─────────────────────┴────────────────────────────────────────┘
Unlike an ordinary literal block, the "parsed-literal" directive constructs a literal block where the text is parsed for
inline markup. It is equivalent to a line block with different rendering: typically in a typewriter/monospaced typeface,
like an ordinary literal block.  Parsed literal blocks are useful for adding hyperlinks to code examples.

However, care must be taken with the text, because inline markup is recognized and there is no protection from parsing. 
Backslash-escapes may be necessary to prevent unintended parsing.  And because the markup characters are removed by the 
parser, care must also be taken with vertical alignment.  Parsed "ASCII art" is tricky, and extra whitespace may be 
necessary.

For example, all the element names in this content model are links:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. parsed-literal::                                                                                                  
                                                                                                                      
    ( (title_, subtitle_?)?,                                                                                          
      decoration_?,                                                                                                   
      (docinfo_, transition_?)?,                                                                                      
      `%structure.model;`_ )                                                                                          
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                         Code                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name             Field Value                            ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type        │ "code"                                 │
├───────────────────────┼────────────────────────────────────────┤
│ Doctree Element       │ literal_block, inline elements         │
├───────────────────────┼────────────────────────────────────────┤
│ Directive Arguments   │ One, optional (formal language).       │
├───────────────────────┼────────────────────────────────────────┤
│ Directive Options     │ name, class, number-lines.             │
├───────────────────────┼────────────────────────────────────────┤
│ Directive Content     │ Becomes the body of the literal block. │
├───────────────────────┼────────────────────────────────────────┤
│ Configuration Setting │ syntax_highlight.                      │
└───────────────────────┴────────────────────────────────────────┘
The "code" directive constructs a literal block. If the code language is specified, the content is parsed by the 
Pygments syntax highlighter and tokens are stored in nested inline elements with class arguments according to their 
syntactic category. The actual highlighting requires a style-sheet (e.g. one generated by Pygments, see the 
sandbox/stylesheets for examples).

The parsing can be turned off with the syntax_highlight configuration setting and command line option or by specifying 
the language as class option instead of directive argument. This also avoids warnings when Pygments is not installed or 
the language is not in the supported languages and markup formats.

For inline code, use the "code" role.

The following options are recognized:

    number-lines : [integer] (start line number)
      Precede every line with a line number. The optional argument is the number of the first line (default 1).
and the common options class and name.Example:

┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 The content of the following directive ::                                                                            
                                                                                                                      
   .. code:: python                                                                                                   
                                                                                                                      
     def my_function():                                                                                               
         "just a test"                                                                                                
         print 8/2                                                                                                    
                                                                                                                      
 is parsed and marked up as Python source code.                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                         Math                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name             Field Value                                          ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type        │ "math"                                               │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ Doctree Element       │ math_block                                           │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ Directive Arguments   │ None.                                                │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ Directive Options     │ class, name                                          │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ Directive Content     │ Becomes the body of the math block.                  │
│                       │ (Content blocks separated by a blank line are put in │
│                       │ adjacent math blocks.)                               │
├───────────────────────┼──────────────────────────────────────────────────────┤
│ Configuration Setting │ math_output                                          │
└───────────────────────┴──────────────────────────────────────────────────────┘
The "math" directive inserts blocks with mathematical content (display formulas, equations) into the document. The input
format is LaTeX math syntax with support for Unicode symbols, for example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. math::                                                                                                            
                                                                                                                      
   α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Support is limited to a subset of LaTeX math by the conversion required for many output formats.  For HTML, the 
math_output configuration setting (or the corresponding --math-output command line option) select between alternative 
output formats with different subsets of supported elements. If a writer does not support math typesetting, the content 
is inserted verbatim.

For inline formulas, use the "math" role.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Rubric                                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                  ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "rubric"                     │
├─────────────────────┼──────────────────────────────┤
│ Doctree Element     │ rubric                       │
├─────────────────────┼──────────────────────────────┤
│ Directive Arguments │ One, required (rubric text). │
├─────────────────────┼──────────────────────────────┤
│ Directive Options   │ class, name                  │
├─────────────────────┼──────────────────────────────┤
│ Directive Content   │ None.                        │
└─────────────────────┴──────────────────────────────┘
rubric n. 1. a title, heading, or the like, in a manuscript,
book, statute, etc., written or printed in red or otherwise
distinguished from the rest of the text. ...
  - Random House Webster's College Dictionary, 1991The "rubric" directive inserts a "rubric" element into the document 
tree.  A rubric is like an informal heading that doesn't correspond to the document's structure.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Epigraph                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "epigraph"                                  │
├─────────────────────┼─────────────────────────────────────────────┤
│ Doctree Element     │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Arguments │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Options   │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Content   │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
An epigraph is an apposite (suitable, apt, or pertinent) short inscription, often a quotation or poem, at the beginning 
of a document or section.

The "epigraph" directive produces an "epigraph"-class block quote. For example, this input:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. epigraph::                                                                                                        
                                                                                                                      
    No matter where you go, there you are.                                                                            
                                                                                                                      
    -- Buckaroo Banzai                                                                                                
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
becomes this document tree fragment:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 <block_quote classes="epigraph">                                                                                     
     <paragraph>                                                                                                      
         No matter where you go, there you are.                                                                       
     <attribution>                                                                                                    
         Buckaroo Banzai                                                                                              
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Highlights                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "highlights"                                │
├─────────────────────┼─────────────────────────────────────────────┤
│ Doctree Element     │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Arguments │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Options   │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Content   │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
Highlights summarize the main points of a document or section, often consisting of a list.

The "highlights" directive produces a "highlights"-class block quote. See Epigraph above for an analogous example.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Pull-Quote                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "pull-quote"                                │
├─────────────────────┼─────────────────────────────────────────────┤
│ Doctree Element     │ block_quote                                 │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Arguments │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Options   │ None.                                       │
├─────────────────────┼─────────────────────────────────────────────┤
│ Directive Content   │ Interpreted as the body of the block quote. │
└─────────────────────┴─────────────────────────────────────────────┘
A pull-quote is a small selection of text "pulled out and quoted", typically in a larger typeface.  Pull-quotes are used
to attract attention, especially in long articles.

The "pull-quote" directive produces a "pull-quote"-class block quote. See Epigraph above for an analogous example.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                  Compound Paragraph                                                  ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                   ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "compound"                    │
├─────────────────────┼───────────────────────────────┤
│ Doctree Element     │ compound                      │
├─────────────────────┼───────────────────────────────┤
│ Directive Arguments │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ Directive Options   │ class, name                   │
├─────────────────────┼───────────────────────────────┤
│ Directive Content   │ Interpreted as body elements. │
└─────────────────────┴───────────────────────────────┘
The "compound" directive is used to create a compound paragraph, which is a single logical paragraph containing multiple
physical body elements such as simple paragraphs, literal blocks, tables, lists, etc., instead of directly containing 
text and inline elements.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. compound::                                                                                                        
                                                                                                                      
    The 'rm' command is very dangerous.  If you are logged                                                            
    in as root and enter ::                                                                                           
                                                                                                                      
        cd /                                                                                                          
        rm -rf *                                                                                                      
                                                                                                                      
    you will erase the entire contents of your file system.                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
In the example above, a literal block is "embedded" within a sentence that begins in one physical paragraph and ends in 
another.

╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮
│ The "compound" directive is not a generic block-level container like HTML's <div> element.  Do not use it only to    │
│ group a sequence of elements, or you may get unexpected results.  If you need a generic block-level container,       │
│ please use the container directive, described below.                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to 
emphasize their logical unity:

If paragraphs are rendered with a first-line indent, only the first physical paragraph of a compound paragraph should
have that indent -- second and further physical paragraphs should omit the indents;
vertical spacing between physical elements may be reduced;
and so on.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Container                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                          ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "container"                          │
├─────────────────────┼──────────────────────────────────────┤
│ Doctree Element     │ container                            │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Arguments │ One or more, optional (class names). │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Options   │ name                                 │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Content   │ Interpreted as body elements.        │
└─────────────────────┴──────────────────────────────────────┘
The "container" directive surrounds its contents (arbitrary body elements) with a generic block-level "container" 
element.  Combined with the optional "classes" attribute argument(s), this is an extension mechanism for users & 
applications.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. container:: custom                                                                                                
                                                                                                                      
    This paragraph might be rendered in a custom way.                                                                 
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Parsing the above results in the following pseudo-XML
┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐
 <container classes="custom">                                                                                         
     <paragraph>                                                                                                      
         This paragraph might be rendered in a custom way.                                                            
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The "container" directive is the equivalent of HTML's <div> element.  It may be used to group a sequence of elements for
user- or application-specific purposes.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Tables                                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Formal tables need more structure than the reStructuredText syntax supplies.  Tables may be given titles with the table 
directive. Sometimes reStructuredText tables are inconvenient to write, or table data in a standard format is readily 
available.  The csv-table directive supports CSV data.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Table                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                      ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "table"                          │
├─────────────────────┼──────────────────────────────────┤
│ Doctree Element     │ table                            │
├─────────────────────┼──────────────────────────────────┤
│ Directive Arguments │ One, optional (table title).     │
├─────────────────────┼──────────────────────────────────┤
│ Directive Options   │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ Directive Content   │ A normal reStructuredText table. │
└─────────────────────┴──────────────────────────────────┘
The "table" directive is used to associate a title with a table or specify options, e.g.:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. table:: Truth table for "not"                                                                                     
    :widths: auto                                                                                                     
                                                                                                                      
    =====  =====                                                                                                      
      A    not A                                                                                                      
    =====  =====                                                                                                      
    False  True                                                                                                       
    True   False                                                                                                      
    =====  =====                                                                                                      
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    align : "left", "center", or "right"
      The horizontal alignment of the table (new in Docutils 0.13).

    width : length or percentage
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.  

    widths : "auto", "grid", or a list of integers
      A list of relative column widths. The default is the width of the input columns (in characters).  "auto" delegates
the determination of column widths to the backend (LaTeX, the HTML browser, ...).  "grid" restores the default, 
overriding a table_style or class value "colwidths-auto".
Plus the common options class and name.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      CSV Table                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                           ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "csv-table"                           │
├─────────────────────┼───────────────────────────────────────┤
│ Doctree Element     │ table                                 │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Arguments │ One, optional (table title).          │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Options   │ Possible (see below).                 │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Content   │ A CSV (comma-separated values) table. │
└─────────────────────┴───────────────────────────────────────┘
╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮
│ The "csv-table" directive's ":file:" and ":url:" options represent a potential security holes.  They can be disabled │
│ with the "file_insertion_enabled" runtime setting.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
The "csv-table" directive is used to create a table from CSV (comma-separated values) data.  CSV is a common data format
generated by spreadsheet applications and commercial databases.  The data may be internal (an integral part of the 
document) or external (a separate file).

Block markup and inline markup within cells is supported.  Line ends are recognized within cells.
There is no support for checking that the number of columns in each row is the same. The directive automatically adds
empty entries at the end of short rows.  Add "strict" option to verify input?

Example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. csv-table:: Frozen Delights!                                                                                      
    :header: "Treat", "Quantity", "Description"                                                                       
    :widths: 15, 10, 30                                                                                               
                                                                                                                      
    "Albatross", 2.99, "On a stick!"                                                                                  
    "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be                                                   
    crunchy, now would it?"                                                                                           
    "Gannet Ripple", 1.99, "On a stick!"                                                                              
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    align : "left", "center", or "right"
      The horizontal alignment of the table. (New in Docutils 0.13)

    delim : char | "tab" | "space" 
      A one-character string used to separate fields. Defaults to , (comma).  May be specified as a Unicode code point; 
see the unicode directive for syntax details.

    encoding : string
      The text encoding of the external CSV data (file or URL). Defaults to the document's input_encoding.

    escape : char
      A one-character string used to escape the delimiter or quote characters.  May be specified as a Unicode code 
point; see the unicode directive for syntax details.  Used when the delimiter is used in an unquoted field, or when 
quote characters are used within a field.  The default is to double-up the character, e.g. "He said, ""Hi!"""  Add 
another possible value, "double", to explicitly indicate the default case?

    file : string (newlines removed)
      The local filesystem path to a CSV data file.

    header : CSV data
      Supplemental data for the table header, added independently of and before any header-rows from the main CSV data. 
Must use the same CSV format as the main CSV data.

    header-rows : integer
      The number of rows of CSV data to use in the table header. Defaults to 0.

    keepspace : flag (empty)
      Treat whitespace immediately following the delimiter as significant.  The default is to ignore such whitespace.

    quote : char
      A one-character string used to quote elements containing the delimiter or which start with the quote character.  
Defaults to " (quote).  May be specified as a Unicode code point; see the unicode directive for syntax details.

    stub-columns : integer
      The number of table columns to use as stubs (row titles, on the left).  Defaults to 0.

    url : string (whitespace removed)
      An Internet URL reference to a CSV data file.

    widths : integer [integer...] or "auto"
      A list of relative column widths. The default is equal-width columns (100%/#columns).  "auto" delegates the 
determination of column widths to the backend (LaTeX, the HTML browser, ...).

    width : length or percentage
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.
and the common options class and name.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      List Table                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                      ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "list-table"                     │
├─────────────────────┼──────────────────────────────────┤
│ Doctree Element     │ table                            │
├─────────────────────┼──────────────────────────────────┤
│ Directive Arguments │ One, optional (table title).     │
├─────────────────────┼──────────────────────────────────┤
│ Directive Options   │ Possible (see below).            │
├─────────────────────┼──────────────────────────────────┤
│ Directive Content   │ A uniform two-level bullet list. │
└─────────────────────┴──────────────────────────────────┘
(This is an initial implementation; further ideas may be implemented in the future.)

The "list-table" directive is used to create a table from data in a uniform two-level bullet list.  "Uniform" means that
each sublist (second-level list) must contain the same number of list items.

Example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. list-table:: Frozen Delights!                                                                                     
    :widths: 15 10 30                                                                                                 
    :header-rows: 1                                                                                                   
                                                                                                                      
    * - Treat                                                                                                         
      - Quantity                                                                                                      
      - Description                                                                                                   
    * - Albatross                                                                                                     
      - 2.99                                                                                                          
      - On a stick!                                                                                                   
    * - Crunchy Frog                                                                                                  
      - 1.49                                                                                                          
      - If we took the bones out, it wouldn't be                                                                      
        crunchy, now would it?                                                                                        
    * - Gannet Ripple                                                                                                 
      - 1.99                                                                                                          
      - On a stick!                                                                                                   
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    align : "left", "center", or "right"
      The horizontal alignment of the table. (New in Docutils 0.13)

    header-rows : integer
      The number of rows of list data to use in the table header. Defaults to 0.

    stub-columns : integer
      The number of table columns to use as stubs (row titles, on the left).  Defaults to 0.  

    width : length or percentage
      Sets the width of the table to the specified length or percentage of the line width.  If omitted, the renderer 
determines the width of the table based on its contents or the column widths.  

    widths : integer [integer...] or "auto"
      A list of relative column widths. The default is equal-width columns (100%/#columns).  "auto" delegates the 
determination of column widths to the backend (LaTeX, the HTML browser, ...).
and the common options class and name.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                    Document Parts                                                    ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                  Table of Contents                                                   ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value           ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "contents"            │
├─────────────────────┼───────────────────────┤
│ Doctree Elements    │ pending, topic        │
├─────────────────────┼───────────────────────┤
│ Directive Arguments │ One, optional: title. │
├─────────────────────┼───────────────────────┤
│ Directive Options   │ Possible (see below). │
├─────────────────────┼───────────────────────┤
│ Directive Content   │ None.                 │
└─────────────────────┴───────────────────────┘
The "contents" directive generates a table of contents (TOC) in a topic.  Topics, and therefore tables of contents, may 
occur anywhere a section or transition may occur.  Body elements and topics may not contain tables of contents.

Here's the directive in its simplest form:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. contents::                                                                                                        
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Language-dependent boilerplate text will be used for the title.  The English default title text is "Contents".

An explicit title may be specified:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. contents:: Table of Contents                                                                                      
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The title may span lines, although it is not recommended:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. contents:: Here's a very long Table of                                                                            
    Contents title                                                                                                    
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Options may be specified for the directive, using a field list:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. contents:: Table of Contents                                                                                      
    :depth: 2                                                                                                         
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
If the default title is to be used, the options field list may begin on the same line as the directive marker:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. contents:: :depth: 2                                                                                              
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The following options are recognized:

    depth : integer
      The number of section levels that are collected in the table of contents.  The default is unlimited depth.

    local : flag (empty)
      Generate a local table of contents.  Entries will only include subsections of the section in which the directive 
is given.  If no explicit title is given, the table of contents will not be titled.

    backlinks : "entry" or "top" or "none"
      Generate links from section headers back to the table of contents entries, the table of contents itself, or 
generate no back-links.

    class : text
      Set a "classes" attribute value on the topic element.  See the class directive below.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                             Automatic Section Numbering                                              ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name             Field Value                                 ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type        │ "sectnum" or "section-numbering" (synonyms) │
├───────────────────────┼─────────────────────────────────────────────┤
│ Doctree Elements      │ pending, generated                          │
├───────────────────────┼─────────────────────────────────────────────┤
│ Directive Arguments   │ None.                                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ Directive Options     │ Possible (see below).                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ Directive Content     │ None.                                       │
├───────────────────────┼─────────────────────────────────────────────┤
│ Configuration Setting │ sectnum_xform                               │
└───────────────────────┴─────────────────────────────────────────────┘
The "sectnum" (or "section-numbering") directive automatically numbers sections and subsections in a document (if not 
disabled by the --no-section-numbering command line option or the sectnum_xform configuration setting).

Section numbers are of the "multiple enumeration" form, where each level has a number, separated by periods.  For 
example, the title of section 1, subsection 2, subsubsection 3 would have "1.2.3" prefixed.

The "sectnum" directive does its work in two passes: the initial parse and a transform.  During the initial parse, a 
"pending" element is generated which acts as a placeholder, storing any options internally. At a later stage in the 
processing, the "pending" element triggers a transform, which adds section numbers to titles.  Section numbers are 
enclosed in a "generated" element, and titles have their "auto" attribute set to "1".

The following options are recognized:

    depth : integer
      The number of section levels that are numbered by this directive. The default is unlimited depth.

    prefix : string
      An arbitrary string that is prefixed to the automatically generated section numbers.  It may be something like 
"3.2.", which will produce "3.2.1", "3.2.2", "3.2.2.1", and so on.  Note that any separating punctuation (in the 
example, a period, ".") must be explicitly provided.  The default is no prefix.

    suffix : string
      An arbitrary string that is appended to the automatically generated section numbers.  The default is no suffix.

    start : integer
      The value that will be used for the first section number. Combined with prefix, this may be used to force the 
right numbering for a document split over several source files.  The default is 1.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                               Document Header & Footer                                               ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                   ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Types     │ "header" and "footer"         │
├─────────────────────┼───────────────────────────────┤
│ Doctree Elements    │ decoration, header, footer    │
├─────────────────────┼───────────────────────────────┤
│ Directive Arguments │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ Directive Options   │ None.                         │
├─────────────────────┼───────────────────────────────┤
│ Directive Content   │ Interpreted as body elements. │
└─────────────────────┴───────────────────────────────┘
The "header" and "footer" directives create document decorations, useful for page navigation, notes, time/datestamp, 
etc.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. header:: This space for rent.                                                                                     
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This will add a paragraph to the document header, which will appear at the top of the generated web page or at the top 
of every printed page.

These directives may be used multiple times, cumulatively.  There is currently support for only one header and footer.

╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮
│ While it is possible to use the "header" and "footer" directives to create navigational elements for web pages, you  │
│ should be aware that Docutils is meant to be used for document processing, and that a navigation bar is not          │
│ typically part of a document.  Thus, you may soon find Docutils' abilities to be insufficient for these purposes.    │
│ At that time, you should consider using a documentation generator like Sphinx rather than the "header" and "footer"  │
│ directives.                                                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
In addition to the use of these directives to populate header and footer content, content may also be added 
automatically by the processing system.  For example, if certain runtime settings are enabled, the document footer is 
populated with processing information such as a datestamp, a link to the Docutils website, etc.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      References                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                   Target Footnotes                                                   ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                           ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "target-notes"                        │
├─────────────────────┼───────────────────────────────────────┤
│ Doctree Elements    │ pending, footnote, footnote_reference │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Arguments │ None.                                 │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Options   │ class, name                           │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Options   │ Possible (see below).                 │
├─────────────────────┼───────────────────────────────────────┤
│ Directive Content   │ None.                                 │
└─────────────────────┴───────────────────────────────────────┘
The "target-notes" directive creates a footnote for each external target in the text, and corresponding footnote 
references after each reference.  For every explicit target (of the form, .. _target name: URL) in the text, a footnote 
will be generated containing the visible URL as content.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Footnotes                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
NOT IMPLEMENTED YET

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value    ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "footnotes"    │
├─────────────────────┼────────────────┤
│ Doctree Elements    │ pending, topic │
├─────────────────────┼────────────────┤
│ Directive Arguments │ None?          │
├─────────────────────┼────────────────┤
│ Directive Options   │ Possible?      │
├─────────────────────┼────────────────┤
│ Directive Content   │ None.          │
└─────────────────────┴────────────────┘
@@@

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Citations                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
NOT IMPLEMENTED YET

┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value    ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "citations"    │
├─────────────────────┼────────────────┤
│ Doctree Elements    │ pending, topic │
├─────────────────────┼────────────────┤
│ Directive Arguments │ None?          │
├─────────────────────┼────────────────┤
│ Directive Options   │ Possible?      │
├─────────────────────┼────────────────┤
│ Directive Content   │ None.          │
└─────────────────────┴────────────────┘
@@@

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                    HTML-Specific                                                     ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Imagemap                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
NOT IMPLEMENTED YET

Non-standard element: imagemap.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                       Directives for Substitution Definitions                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
The directives in this section may only be used in substitution definitions.  They may not be used directly, in 
standalone context. The image directive may be used both in substitution definitions and in the standalone context.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                   Replacement Text                                                   ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                    ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "replace"                                      │
├─────────────────────┼────────────────────────────────────────────────┤
│ Doctree Element     │ Text & inline elements                         │
├─────────────────────┼────────────────────────────────────────────────┤
│ Directive Arguments │ None.                                          │
├─────────────────────┼────────────────────────────────────────────────┤
│ Directive Options   │ None.                                          │
├─────────────────────┼────────────────────────────────────────────────┤
│ Directive Content   │ A single paragraph; may contain inline markup. │
└─────────────────────┴────────────────────────────────────────────────┘
The "replace" directive is used to indicate replacement text for a substitution reference.  It may be used within 
substitution definitions only.  For example, this directive can be used to expand abbreviations:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. |reST| replace:: reStructuredText                                                                                 
                                                                                                                      
 Yes, |reST| is a long word, so I can't blame anyone for wanting to                                                   
 abbreviate it.                                                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use 
substitutions with the "replace" directive:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 I recommend you try |Python|_.                                                                                       
                                                                                                                      
 .. |Python| replace:: Python, *the* best language around                                                             
 .. _Python: https://www.python.org/                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                               Unicode Character Codes                                                ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                     ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "unicode"                                       │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Doctree Element     │ Text                                            │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Arguments │ One or more, required (Unicode character codes, │
│                     │ optional text, and comments).                   │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Options   │ Possible (see below).                           │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Content   │ None.                                           │
└─────────────────────┴─────────────────────────────────────────────────┘
The "unicode" directive converts Unicode character codes (numerical values) to characters, and may be used in 
substitution definitions only.

The arguments, separated by spaces, can be:

  character codes as
  decimal numbers or  hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character 
entities, e.g. &#x1a2b;
    decimal numbers or
    hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &#x
hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &#x1a2b
text, which is used as-is.

Text following " .. " is a comment and is ignored.  The spaces between the arguments are ignored and thus do not appear 
in the output. Hexadecimal codes are case-insensitive.

For example, the following text:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 Copyright |copy| 2003, |BogusMegaCorp (TM)| |---|                                                                    
 all rights reserved.                                                                                                 
                                                                                                                      
 .. |copy| unicode:: 0xA9 .. copyright sign                                                                           
 .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122                                                               
    .. with trademark sign                                                                                            
 .. |---| unicode:: U+02014 .. em dash                                                                                
    :trim:                                                                                                            
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
results in:

    Copyright copy 2003, BogusMegaCorp (TM) --- all rights reserved.

The following options are recognized:
    ltrim : flag (empty)
      Whitespace to the left of the substitution reference is removed.

    rtrim : flag (empty)
      Whitespace to the right of the substitution reference is removed.

    trim : flag (empty)
      Equivalent to ltrim plus rtrim; whitespace on both sides of the substitution reference is removed.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                         Date                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                  ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "date"                       │
├─────────────────────┼──────────────────────────────┤
│ Doctree Element     │ Text                         │
├─────────────────────┼──────────────────────────────┤
│ Directive Arguments │ One, optional (date format). │
├─────────────────────┼──────────────────────────────┤
│ Directive Options   │ None.                        │
├─────────────────────┼──────────────────────────────┤
│ Directive Content   │ None.                        │
└─────────────────────┴──────────────────────────────┘
The "date" directive generates the current local date and inserts it into the document as text.  This directive may be 
used in substitution definitions only.

The optional directive content is interpreted as the desired date format, using the same codes as Python's 
time.strftime() function.  The default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also be used.  
Examples:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. |date| date::                                                                                                     
 .. |time| date:: %H:%M                                                                                               
                                                                                                                      
 Today's date is |date|.                                                                                              
                                                                                                                      
 This document was generated on |date| at |time|.                                                                     
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                    Miscellaneous                                                     ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                       Including an External Document Fragment                                        ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name             Field Value                                  ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type        │ "include"                                    │
├───────────────────────┼──────────────────────────────────────────────┤
│ Doctree Elements      │ Depend on data being included                │
│                       │ (literal_block with code or literal option). │
├───────────────────────┼──────────────────────────────────────────────┤
│ Directive Arguments   │ One, required (path to the file to include). │
├───────────────────────┼──────────────────────────────────────────────┤
│ Directive Options     │ Possible (see below).                        │
├───────────────────────┼──────────────────────────────────────────────┤
│ Directive Content     │ None.                                        │
├───────────────────────┼──────────────────────────────────────────────┤
│ Configuration Setting │ file_insertion_enabled                       │
└───────────────────────┴──────────────────────────────────────────────┘
╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮
│ The "include" directive represents a potential security hole.  It can be disabled with the "file_insertion_enabled"  │
│ runtime setting.                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to 
the document containing the directive. Unless the options literal, code, or parser are given, the file is parsed in the 
current document's context at the point of the directive. For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 This first example will be parsed at the document level, and can                                                     
 thus contain any construct, including section headers.                                                               
                                                                                                                      
 .. include:: inclusion.txt                                                                                           
                                                                                                                      
 Back in the main document.                                                                                           
                                                                                                                      
     This second example will be parsed in a block quote context.                                                     
     Therefore it may only contain body elements.  It may not                                                         
     contain section headers.                                                                                         
                                                                                                                      
     .. include:: inclusion.txt                                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
If an included document fragment contains section structure, the title adornments must match those of the master 
document.

Standard data files intended for inclusion in reStructuredText documents are distributed with the Docutils source code, 
located in the "docutils" package in the docutils/parsers/rst/include directory.  To access these files, use the special
syntax for standard "include" data files, angle brackets around the file name:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. include:: <isonum.txt>                                                                                            
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The current set of standard "include" data files consists of sets of substitution definitions.  See reStructuredText 
Standard Definition Files for details.

The following options are recognized:

    start-line : integer
      Only the content starting from this line will be included. (As usual in Python, the first line has index 0 and 
negative values count from the end.)

    end-line : integer
      Only the content up to (but excluding) this line will be included.

    start-after : text to find in the external data file
      Only the content after the first occurrence of the specified text will be included.

    end-before : text to find in the external data file
      Only the content before the first occurrence of the specified text (but after any after text) will be included.

    parser : parser name
      Parse the included content with the specified parser. (New in Docutils 0.17)

    literal : flag (empty)
      The entire included text is inserted into the document as a single literal block.

    code : [string] (formal language)
      The argument and the included content are passed to the code directive (useful for program listings).

    number-lines : [integer] (start line number)
      Precede every code line with a line number. The optional argument is the number of the first line (default 1). 
Works only with code or literal.

    encoding : string
      The text encoding of the external data file.  Defaults to the document's input_encoding.  

    tab-width : integer
      Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the 
tab_width configuration setting.  
With code or literal the common options class and name are recognized as well.Combining start/end-line and 
start-after/end-before is possible. The text markers will be searched in the specified lines (further limiting the 
included content).
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                Raw Data Pass-Through                                                 ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name             Field Value                                        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type        │ "raw"                                              │
├───────────────────────┼────────────────────────────────────────────────────┤
│ Doctree Element       │ raw                                                │
├───────────────────────┼────────────────────────────────────────────────────┤
│ Directive Arguments   │ One or more, required (output format types).       │
├───────────────────────┼────────────────────────────────────────────────────┤
│ Directive Options     │ Possible (see below).                              │
├───────────────────────┼────────────────────────────────────────────────────┤
│ Directive Content     │ Stored verbatim, uninterpreted.  None (empty) if a │
│                       │ "file" or "url" option given.                      │
├───────────────────────┼────────────────────────────────────────────────────┤
│ Configuration Setting │ raw_enabled                                        │
└───────────────────────┴────────────────────────────────────────────────────┘
╭───────────────────────────────────────────────────── Warning:  ──────────────────────────────────────────────────────╮
│ The "raw" directive represents a potential security hole.  It can be disabled with the "raw_enabled" or              │
│ "file_insertion_enabled" runtime settings.                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────── Caution:  ──────────────────────────────────────────────────────╮
│ The "raw" directive is a stop-gap measure allowing the author to bypass reStructuredText's markup.  It is a          │
│ "power-user" feature that should not be overused or abused.  The use of "raw" ties documents to specific output      │
│ formats and makes them less portable.  If you often need to use the "raw" directive or a "raw"-derived interpreted   │
│ text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText.        │
│ Please describe your situation in a message to the Docutils-users mailing list.                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
The "raw" directive indicates non-reStructuredText data that is to be passed untouched to the Writer.  The names of the 
output formats are given in the directive arguments.  The interpretation of the raw data is up to the Writer.  A Writer 
may ignore any raw output not matching its format.

For example, the following input would be passed untouched by an HTML Writer:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. raw:: html                                                                                                        
                                                                                                                      
    <hr width=50 size=10>                                                                                             
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
A LaTeX Writer could insert the following raw content into its output stream:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. raw:: latex                                                                                                       
                                                                                                                      
    \setlength{\parindent}{0pt}                                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Raw data can also be read from an external file, specified in a directive option.  In this case, the content block must 
be empty.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. raw:: html                                                                                                        
    :file: inclusion.html                                                                                             
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Inline equivalents of the "raw" directive can be defined via custom interpreted text roles derived from the "raw" role.

The following options are recognized:

    file : string (newlines removed)
      The local filesystem path of a raw data file to be included.

    url : string (whitespace removed)
      An Internet URL reference to a raw data file to be included.

    encoding : string
      The text encoding of the external raw data (file or URL). Defaults to the document's encoding (if specified).
and the common option class.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                        Class                                                         ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                      ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "class"                                          │
├─────────────────────┼──────────────────────────────────────────────────┤
│ Doctree Element     │ pending                                          │
├─────────────────────┼──────────────────────────────────────────────────┤
│ Directive Arguments │ One or more, required (class names / attribute   │
│                     │ values).                                         │
├─────────────────────┼──────────────────────────────────────────────────┤
│ Directive Options   │ None.                                            │
├─────────────────────┼──────────────────────────────────────────────────┤
│ Directive Content   │ Optional.  If present, it is interpreted as body │
│                     │ elements.                                        │
└─────────────────────┴──────────────────────────────────────────────────┘
The "class" directive sets the "classes" attribute value on its content or on the first immediately following  
non-comment element . The directive argument consists of one or more space-separated class names. The names are 
transformed to conform to the regular expression [a-z](-?[a-z0-9]+)* (see Identifier Normalization below).

Examples:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. class:: special                                                                                                   
                                                                                                                      
 This is a "special" paragraph.                                                                                       
                                                                                                                      
 .. class:: exceptional remarkable                                                                                    
                                                                                                                      
 An Exceptional Section                                                                                               
 ======================                                                                                               
                                                                                                                      
 This is an ordinary paragraph.                                                                                       
                                                                                                                      
 .. class:: multiple                                                                                                  
                                                                                                                      
    First paragraph.                                                                                                  
                                                                                                                      
    Second paragraph.                                                                                                 
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The text above is parsed and transformed into this doctree fragment:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. code-block:: xml                                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
    <paragraph classes="special">  This is a "special" paragraph.  <section classes="exceptional remarkable">  <title>  
An Exceptional Section  <paragraph>  This is an ordinary paragraph.  <paragraph classes="multiple">  First paragraph.  
<paragraph classes="multiple">  Second paragraph.


╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                               Identifier Normalization                                               ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Docutils class names and identifier keys are normalized to conform to the regular expression "[a-z](-?[a-z0-9]+)*" by 
converting

alphabetic characters to lowercase,
accented characters to the base character,
non-alphanumeric characters to hyphens,
consecutive hyphens into one hyphen

and stripping

leading hyphens and number characters, and
trailing hyphens.

For example "Rot.Gelb&Grün:+2008" becomes "rot-gelb-grun-2008" and "1000_Steps!" becomes "steps".

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                      Rationale:                                                      ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Identifier keys must be valid in all supported output formats.

For HTMLÂ 4.1 + CSS1 compatibility, identifiers should have no underscores, colons, or periods.  Hyphens may be used.

The HTML 4.01 spec defines identifiers based on SGML tokens:  ID and NAME tokens must begin with a letter ([A-Za-z]) 
may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods 
(".").  https://www.w3.org/TR/html401/types.html#type-name
The CSS1 spec defines identifiers based on the "name" token ("flex" tokenizer notation below; "latin1" and "escape" 
8-bit characters have been replaced with XML entities):  unicode     \\[0-9a-f]{1,4} latin1      [&iexcl;-&yuml;] escape
{unicode}|\\[ -~&iexcl;-&yuml;] nmchar      [-A-Za-z0-9]|{latin1}|{escape} name        {nmchar}+

The CSS1 rule requires underscores ("_"), colons (":"), and periods (".") to be escaped , therefore "classes" and "ids" 
attributes should not contain these characters.  Combined with HTML4.1 requirements (the first character must be a 
letter; no "unicode", "latin1", or "escape" characters), this results in the regular expression [A-Za-z][-A-Za-z0-9]*. 
Docutils adds a normalization by downcasing and merge of consecutive hyphens.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                            Custom Interpreted Text Roles                                             ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                                     ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "role"                                          │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Doctree Element     │ None; affects subsequent parsing.               │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Arguments │ Two; one required (new role name), one optional │
│                     │ (base role name, in parentheses).               │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Options   │ Possible (depends on base role).                │
├─────────────────────┼─────────────────────────────────────────────────┤
│ Directive Content   │ depends on base role.                           │
└─────────────────────┴─────────────────────────────────────────────────┘
The "role" directive dynamically creates a custom interpreted text role and registers it with the parser.  This means 
that after declaring a role like this:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. role:: custom                                                                                                     
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
the document may use the new "custom" role:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 An example of using :custom:`interpreted text`                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This will be parsed into the following document tree fragment:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. code-block:: xml                                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
    <paragraph>  An example of using <inline classes="custom">  <rst-document>:1726: (ERROR/3) Unexpected indentation.  
interpreted text

The role must be declared in a document before it can be used.Role names are case insensitive and must conform to the 
rules of simple reference names (but do not share a namespace with hyperlinks, footnotes, and citations).The new role 
may be based on an existing role, specified as a second argument in parentheses (whitespace optional):

┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. role:: custom(emphasis)                                                                                           
                                                                                                                      
 :custom:`text`                                                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
The parsed result is as follows:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. code-block:: xml                                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
    <paragraph>  <emphasis classes="custom">  text

A special case is the "raw" role: derived roles enable inline raw data pass-through, e.g.:

┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. role:: raw-role(raw)                                                                                              
    :format: html latex                                                                                               
                                                                                                                      
 :raw-role:`raw text`                                                                                                 
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
If no base role is explicitly specified, a generic custom role is automatically used.  Subsequent interpreted text will 
produce an "inline" element with a "classes" attribute, as in the first example above.

With most roles, the ":class:" option can be used to set a "classes" attribute that is different from the role name.  
For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. role:: custom                                                                                                     
    :class: special                                                                                                   
                                                                                                                      
 :custom:`interpreted text`                                                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This is the parsed result:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. code-block:: xml                                                                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
    <paragraph>  <inline classes="special">  interpreted text

The following option is recognized by the "role" directive for most base roles:
    class : text
      Set the "classes" attribute value on the element produced (inline, or element associated with a base class) when 
the custom interpreted text role is used.  If no directive options are specified, a "class" option with the directive 
argument (role name) as the value is implied.  See the class directive above.
Specific base roles may support other options and/or directive content.  See the reStructuredText Interpreted Text Roles
document for details.
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                      Setting the Default Interpreted Text Role                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                            ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "default-role"                         │
├─────────────────────┼────────────────────────────────────────┤
│ Doctree Element     │ None; affects subsequent parsing.      │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Arguments │ One, optional (new default role name). │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Options   │ None.                                  │
├─────────────────────┼────────────────────────────────────────┤
│ Directive Content   │ None.                                  │
└─────────────────────┴────────────────────────────────────────┘
The "default-role" directive sets the default interpreted text role, the role that is used for interpreted text without 
an explicit role. For example, after setting the default role like this:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. default-role:: subscript                                                                                          
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
any subsequent use of implicit-role interpreted text in the document will use the "subscript" role:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 An example of a `default` role.                                                                                      
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This will be parsed into the following document tree fragment
┌──────────────────────────────────────────────────────── xml ─────────────────────────────────────────────────────────┐
 <paragraph>                                                                                                          
     An example of a                                                                                                  
     <subscript>                                                                                                      
         default                                                                                                      
      role.                                                                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Custom roles may be used (see the "role" directive above), but it must have been declared in a document before it can be
set as the default role.  See the reStructuredText Interpreted Text Roles document for details of built-in roles.

The directive may be used without an argument to restore the initial default interpreted text role, which is 
application-dependent.  The initial default interpreted text role of the standard reStructuredText parser is 
"title-reference".

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                       Metadata                                                       ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                     ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "meta"                          │
├─────────────────────┼─────────────────────────────────┤
│ Doctree Element     │ meta                            │
├─────────────────────┼─────────────────────────────────┤
│ Directive Arguments │ None.                           │
├─────────────────────┼─────────────────────────────────┤
│ Directive Options   │ None.                           │
├─────────────────────┼─────────────────────────────────┤
│ Directive Content   │ Must contain a flat field list. │
└─────────────────────┴─────────────────────────────────┘
The "meta" directive is used to specify metadata to be stored in, e.g., HTML meta elements or as ODT file properties. 
The LaTeX writer passes it to the pdfinfo option of the hyperref package. If an output format does not support 
"invisible" metadata, content is silently dropped by the writer.

╭─────────────────────────────────────────────────────── Note:  ───────────────────────────────────────────────────────╮
│ Data from some bibliographic fields is automatically extracted and stored as metadata, too. However, Bibliographic   │
│ Fields are also displayed in the document's screen rendering or printout.  For an "invisible" document title, see    │
│ the metadata document title directive below.                                                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Within the directive block, a flat field list provides the syntax for metadata.  The field name becomes the contents of 
the "name" attribute of the META tag, and the field body (interpreted as a single string without inline markup) becomes 
the contents of the "content" attribute.  For example:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. meta::                                                                                                            
    :description: The reStructuredText plaintext markup language                                                      
    :keywords: plaintext, markup language                                                                             
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
This would be converted to the following HTML
┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐
 <meta name="description"                                                                                             
     content="The reStructuredText plaintext markup language">                                                        
 <meta name="keywords" content="plaintext, markup language">                                                          
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Support for other META attributes ("http-equiv", "scheme", "lang", "dir") are provided through field arguments, which 
must be of the form "attr=value":
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. meta::                                                                                                            
    :description lang=en: An amusing story                                                                            
    :description lang=fr: Une histoire amusante                                                                       
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
And their HTML equivalents
┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐
 <meta name="description" lang="en" content="An amusing story">                                                       
 <meta name="description" lang="fr" content="Une histoire amusante">                                                  
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
Some META tags use an "http-equiv" attribute instead of the "name" attribute.  To specify "http-equiv" META tags, simply
omit the name:
┌─────────────────────────────────────────────────────── python ───────────────────────────────────────────────────────┐
 .. meta::                                                                                                            
    :http-equiv=Content-Type: text/html; charset=ISO-8859-1                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
HTML equivalent
┌──────────────────────────────────────────────────────── html ────────────────────────────────────────────────────────┐
 <meta http-equiv="Content-Type"                                                                                      
      content="text/html; charset=ISO-8859-1">                                                                        
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                               Metadata Document Title                                                ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                          ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "title"                              │
├─────────────────────┼──────────────────────────────────────┤
│ Doctree Element     │ Sets the document's title attribute. │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Arguments │ One, required (the title text).      │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Options   │ None.                                │
├─────────────────────┼──────────────────────────────────────┤
│ Directive Content   │ None.                                │
└─────────────────────┴──────────────────────────────────────┘
The "title" directive specifies the document title as metadata, which does not become part of the document body. It 
overrides the document-supplied document title and the "title" configuration setting. For example, in HTML output the 
metadata document title appears in the title bar of the browser window.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                           Restructuredtext-Test-Directive                                            ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field Name           Field Value                       ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Directive Type      │ "restructuredtext-test-directive" │
├─────────────────────┼───────────────────────────────────┤
│ Doctree Element     │ system_warning                    │
├─────────────────────┼───────────────────────────────────┤
│ Directive Arguments │ None.                             │
├─────────────────────┼───────────────────────────────────┤
│ Directive Options   │ None.                             │
├─────────────────────┼───────────────────────────────────┤
│ Directive Content   │ Interpreted as a literal block.   │
└─────────────────────┴───────────────────────────────────┘
This directive is provided for test purposes only.  (Nobody is expected to type in a name that long!)  It is converted 
into a level-1 (info) system message showing the directive data, possibly followed by a literal block containing the 
rest of the directive block.

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                                    Common Options                                                    ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
Most of the directives that generate doctree elements support the following options:

    class : text (space separated list of class names)
      Set a "classes" attribute value on the doctree element generated by the directive. See also the class directive.  

    name : text
      Add text to the "names" attribute of the doctree element generated by the directive. This allows hyperlink 
references to the element using text as reference name.  Specifying the name option of a directive, e.g.,  .. image:: 
bild.png    :name: my picture  is a concise syntax alternative to preceding it with a hyperlink target  .. _my picture: 
.. image:: bild.png
╭───────────────────────────────── System Message: INFO/1 (<rst-document>, line 982); ─────────────────────────────────╮
 <rst-document>:982: (INFO/1) Duplicate implicit target name: "contents".                                             
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 1965); ─────────────────────────────────╮
 <rst-document>:1965: (INFO/1) Duplicate implicit target name: "class".                                               
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2006); ─────────────────────────────────╮
 <rst-document>:2006: (INFO/1) Duplicate implicit target name: "figure".                                              
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2010); ─────────────────────────────────╮
 <rst-document>:2010: (INFO/1) Duplicate implicit target name: "image".                                               
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2022); ─────────────────────────────────╮
 <rst-document>:2022: (INFO/1) Duplicate implicit target name: "rubric".                                              
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2023); ─────────────────────────────────╮
 <rst-document>:2023: (INFO/1) Duplicate implicit target name: "sidebar".                                             
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2024); ─────────────────────────────────╮
 <rst-document>:2024: (INFO/1) Duplicate implicit target name: "table".                                               
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── System Message: INFO/1 (<rst-document>, line 2027); ─────────────────────────────────╮
 <rst-document>:2027: (INFO/1) Duplicate implicit target name: "topic".                                               
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
┌─────────────────────────────────────────────────────── Footer ───────────────────────────────────────────────────────┐
                            "Metadata" is data about data, in this case data about the                                
                            document. Metadata is, e.g., used to describe and classify web                            
                            pages in the World Wide Web, in a form that is easy for search                            
                            engines to extract and collate.                                                           
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘