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: Faejas Fenrisho
Country: Jamaica
Language: English (Spanish)
Genre: Art
Published (Last): 1 March 2010
Pages: 33
PDF File Size: 10.36 Mb
ePub File Size: 13.87 Mb
ISBN: 467-8-41973-169-1
Downloads: 72804
Price: Free* [*Free Regsitration Required]
Uploader: Grotilar

However, in well-defined contexts such as when a field list invariably occurs at the beginning of a document PEPs and email messagesstandard RFC headers could be used.

Source code for docutils.parsers.rst

The “code” directive constructs a literal block. In the text body, there is a source link, a reference name with a trailing underscore or two underscores for anonymous hyperlinks: The following are recognized as field list items: Empty comments may be used to explicitly terminate preceding constructs that would otherwise consume a block quote: The “csv-table” directive is used to create a table from CSV comma-separated values data. Source Edit proc renderIndexTerm d: For example, here’s how an image may be placed: Following are some use cases for the substitution mechanism.

Japanese or Chinese it is recommended to set simple-inline-markup to True and eventually escape inline markup characters. Each definition list item contains a term, optional classifiers, and a definition. A role name is a single word consisting of alphanumerics plus isolated internal hyphens, underscores, plus signs, colons, and periods; no whitespace or other characters are allowed. The specific behavior depends upon the browser or rendering software used.


In addition, applications may support specialized roles. Paragraphs may contain inline markup. The default is unlimited depth.

A line block ends with a blank line. For example, Python uses backslashes in strings to escape certain characters, but not others. See Implicit Hyperlink Targets for a complete description of the mechanism.

reStructuredText Markup Specification

The “rubric” directive inserts a “rubric” element into the document tree. Any serious markup system requires an escaping mechanism to override the default meaning of the characters used for the markup. Used when initiating a nested parse. 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:.

This default title can be rzt by the embedded rst, but it helps to prettify the generated index if no title is found. The “figure” directive employs all three parts: Three things are noteworthy in the run method above:. The underscore can be thought of as a right-pointing arrow.

The option argument may be a URI relative or absoluteor a reference name with underscore suffix e. Footnotes and references are noted in the order they are encountered in the document, docutilss is not necessarily the same as the order in which a person would read them. An example of using: Instead, choose the most appropriate elements from the existing Docutils elements.

— docutils documentation

Generated by Docutils from reStructuredText source. Individual directives can employ any combination of these parts. One, optional formal language.


The “pull-quote” directive produces a “pull-quote”-class block quote. The following option is recognized by the “role” directive for most base roles:.

reStructuredText – Wikipedia

There are several types of options recognized by reStructuredText: If the index is empty the file won’t be created. Returns the URI argument with whitespace removed. They are interpreted by the directive parser which runs the directive class: This will be parsed into the following document tree fragment: It is equivalent to a line block with different rendering: This proc will first scan dir for index files doccutils the.

For example, here’s a classic:. A transition should not begin or end a section or document, nor should two transitions be immediately adjacent. In URIs, backslash-escaped whitespace represents a single space.

All in all a good bargain. The explicit markup syntax is used for footnotes, citations, hyperlink targets, directives, substitution definitions, and comments.

Hyphens may be used. Inline markup is supported. Instead, the order of anonymous hyperlink references and targets within the document is significant: The directive’s sole argument is interpreted as the topic title; the next line must be blank.

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: The following are recognized as field list items:.