Create a parser:: parser = () Several optional arguments may be passed to modify the parser’s behavior. Please see. reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation. It is part of the Docutils project of the Python Doc-SIG ( Documentation. RST is a file format formely created by Python community to write documentation (and so, is part of Docutils). RST files are simple text files with lightweight syntax.

Author: Tojazshura Moran
Country: Brazil
Language: English (Spanish)
Genre: Finance
Published (Last): 19 May 2009
Pages: 430
PDF File Size: 14.69 Mb
ePub File Size: 1.16 Mb
ISBN: 901-3-42213-434-7
Downloads: 11740
Price: Free* [*Free Regsitration Required]
Uploader: Goshicage

Directives begin with an explicit markup start two periods and a spacefollowed 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 listand content in that orderany of which may appear.

Descriptions below list “doctree elements” document dcutils element names; XML DTD generic identifiers corresponding to individual directives. For directive implementation details, see Creating reStructuredText Directives.

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 rrst admonition type. For example, the following “note” admonition directive contains one paragraph and a bullet list consisting of two list items:. The author-supplied title is rat 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:. 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 rdt.


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 image options. The uniform scaling factor of the image.

Rwt no “height” or “width” options are specified, the Python Imaging Library PIL may be used to determine them, if it is installed and the image file is available. A “figure” consists of image data including rsf optionsan optional caption a single paragraphand an optional legend arbitrary body elements. For page-based output media, figures might float to a different position if this helps the page layout. There must be blank lines before the caption paragraph and before the legend.

To specify a legend without a caption, use an empty comment “. The “figure” directive supports all of the options of the “image” directive see image options above. These options except docutilss are passed on to the contained image. Srt 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. This option does not scale the included image; use the “width” image option for that. A docuyils is like a block quote with a title, or a self-contained docktils 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.

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.

The “line-block” directive is deprecated. Use the line block syntax instead. 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: 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 lyricswhere the structure of lines is significant. For example, here’s a classic:. Unlike an ordinary literal block, the “parsed-literal” directive constructs a literal block where the text is parsed for inline markup.

reStructuredText Directives

It is equivalent to a line block with different rendering: Parsed literal blocks are useful docurils adding hyperlinks to code examples. However, care must be taken with the docutlls, 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. 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.

This also avoids warnings when Pygments is not installed or the language is odcutils in the supported languages and markup formats. For inline code, use the “code” role. The “math” directive inserts blocks with mathematical content display formulas, equations into the document. The input dochtils is LaTeX math syntax [1] with support for Unicode symbols, for example:. Support is limited to a subset of LaTeX math by the conversion required for many output formats.


If a writer does not support math typesetting at all, the content is inserted verbatim. For inline formulas, docutisl the “math” role. The “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. 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:. The “highlights” directive produces a “highlights”-class block quote.

See Dcoutils above for an analogous example. A docuti,s 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. 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.

In the example above, a literal block is “embedded” within a sentence that begins in one physical paragraph and ends in another. 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:.

The docuils directive surrounds its contents arbitrary body elements with a generic block-level “container” element. It may be used to group a sequence of elements for user- or application-specific purposes. 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. The “table” directive is used to associate a title with a table or specify options, e. A comma- or space-separated list of column widths. The default is the width of the input columns in characters. Socutils special values “auto” or “grid” may be used by writers to decide whether docutis delegate the determination of column widths to the backend LaTeX, the HTML browser, The “csv-table” directive’s “: The “csv-table” directive is used to create a table from CSV comma-separated values data.

Dicutils 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. A comma- or space-separated list of relative column widths. The special value “auto” docutile be used by writers to decide whether to delegate the docutiks of column widths to the backend LaTeX, the HTML browser, New in Docutils 0.