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.
|Published (Last):||8 August 2014|
|PDF File Size:||5.44 Mb|
|ePub File Size:||18.47 Mb|
|Price:||Free* [*Free Regsitration Required]|
This document is a detailed technical specification; it is not a tutorial docutiks a primer. These constructs are equally easy to read in raw and processed forms.
This document is itself an example of reStructuredText raw, if you are reading the text file, or processed, if you are reading an HTML document, for example. The reStructuredText parser is a rt of Docutils. Simple, implicit markup is used to indicate special constructs, such as section headings, bullet lists, and emphasis. The markup used is as minimal and unobtrusive as possible.
Less often-used constructs and extensions to the basic reStructuredText syntax may have more elaborate or explicit markup. Python docstrings to the quite large this document. The first section gives a quick overview of the syntax of the reStructuredText markup by example. A complete specification is given in the Syntax Details section.
Literal blocks in which no markup processing is done are used for examples throughout this document, to illustrate the plaintext markup. A reStructuredText document is made up of body or block-level elements, and may be structured into sections. Some body elements contain further elements, such as lists containing list items, which in turn may contain paragraphs and other body elements.
Others, such as paragraphs, contain text and inline markup elements. Paragraphs and inline markup:. Option listsfor listing command-line options:. Grid tables ; complete, but complex and verbose:. Simple tables ; easy and compact, but limited:. Explicit markup blocks all begin with an explicit block marker, two periods and a space:.
Descriptions below list “doctree elements” document tree element names; XML DTD generic identifiers corresponding to syntax constructs.
Spaces are recommended for indentationbut tabs may also be used. Tabs will be converted to spaces. Tab stops are at every 8th column. Other whitespace characters form feeds [chr 12 ] and vertical tabs [chr 11 ] are converted to single spaces before processing.
Blank lines are used to separate paragraphs and other elements. Multiple successive blank lines are equivalent to a single blank line, except within literal blocks where all whitespace is preserved. Blank lines may be omitted when the markup makes element separation unambiguous, in conjunction with indentation.
The first line of a document is treated as if it is preceded by a blank line, and the last line of a document is treated as if it is followed by a blank line. Indentation is used to indicate — and is only significant in indicating — block quotes, definitions in definition list itemsand local nested content:. Any text whose indentation is less than that of the current level i. Since all indentation is significant, the level of indentation must be consistent. For example, indentation is the sole markup indicator for block quotes:.
When a paragraph or other construct consists of more than one line of text, the lines must be left-aligned:. Several constructs begin with a marker, and the body of the construct must be indented relative to the marker.
For constructs using simple markers bullet listsenumerated listsfootnotescitationshyperlink targetsdirectivesand commentsthe level of indentation of the body is determined by the position of the first line of text, which begins on the same line as the marker.
For example, bullet list bodies must be indented by at least two columns relative to the left edge of the bullet:. For constructs using complex markers field lists and option listswhere the marker may contain arbitrary text, the indentation of the first line after the marker determines the left edge of the body. For example, field lists may have very long markers containing the field names:. No matter what characters are used for markup, they will already have multiple meanings in written text.
Therefore markup characters will sometimes appear in text without being intended as markup.
docutjls Any serious markup system requires an escaping mechanism to override the default meaning of the characters used for the markup. In reStructuredText we use the backslash, commonly used as an escaping character in fst domains. A backslash followed by any character except whitespace characters in non-URI contexts escapes that character. The escaped character represents the character itself, and is prevented from playing a role in any markup interpretation.
The backslash is removed from the output. A literal backslash is represented by two backslashes in a row the first backslash “escapes” the second, preventing it being interpreted in an “escaping” role.
reStructuredText – Wikipedia
In non-URI contexts, backslash-escaped whitespace characters are removed from the document. This allows for character-level inline markup.
There are two contexts in which backslashes have no special meaning: In these contexts, a single backslash represents a literal backslash, without having to double up. Please note that rsr reStructuredText specification and parser do not address the issue doxutils the representation or extraction of text input how and in what form the text actually reaches the parser.
Backslashes and other characters may serve a character-escaping purpose in certain contexts and must be dealt with appropriately. For example, Python uses backslashes in strings to escape certain characters, but not others. The simplest solution when backslashes appear in Python docstrings is to use raw docstrings:. Simple reference names are single words consisting of alphanumerics plus isolated no two adjacent internal hyphens, underscores, periods, colons and plus signs; no whitespace or other characters are allowed.
Reference names using punctuation or whose names are phrases two or more space-separated words are called “phrase-references”.
Phrase-references are expressed by enclosing the phrase in backquotes and treating the backquoted text as a reference name:. Reference names are whitespace-neutral and case-insensitive. When resolving reference names internally:. For example, the following hyperlink references are equivalent:. Hyperlinksfootnotesand citations all share the same namespace for reference names.
The labels of citations simple reference names and manually-numbered footnotes numbers are entered into the same database as other hyperlink names. This means that a footnote defined as “. Of course, each type of reference hyperlink, footnote, citation may be processed and rendered differently. Some care should be taken to avoid reference name conflicts. The top-level element of a parsed reStructuredText document is the “document” docufils.
After initial parsing, the document element is a simple container for a document fragment, consisting of body elementstransitionsand sectionsbut lacking a document title or other bibliographic elements. The code that calls the parser may choose to run one or more optional post-parse transformsrearranging the document fragment into a complete document rs a title and possibly other metadata elements author, date, etc. Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText.
Similarly, a lone second-level section title immediately after the “document title” can become the document subtitle. The rest of the sections are then lifted up a vocutils or two. See the DocTitle transform for details. Sections are identified through their fst, which are marked up with adornment: When an docutjls is used, the rat and character used must match the underline.
Underline-only adornment styles are distinct from overline-and-underline styles that use the same character. There may be any number of levels of section titles, although some output formats may have limits HTML has 6 levels.
Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered. The first style encountered will be an outermost title like HTML H1the second style will be a subtitle, the third will be a subsubtitle, and so on. When a title has both docutil underline and an overline, the title text may be inset, as in the first two examples above.
This is merely aesthetic and not significant. Underline-only title text may not be inset. A blank line after a title is optional. All text blocks up to the next title of the same or higher level are included in a section or subsection, etc. All section title styles need not be used, nor need any specific section title style be used.
However, a document must be consistent in its use of section titles: Each section title automatically generates a hyperlink target pointing to the section. The text of the hyperlink target the “reference name” is the same as ret of the section title.
See Implicit Hyperlink Targets for a complete description. Sections may contain body elementstransitionsand nested sections. Instead of subheads, rts space or a type ornament between paragraphs may be used to mark text divisions or to signal changes in docutild or emphasis.
Transitions are commonly seen in novels and short fiction, as a gap spanning one or more lines, docutild or without a type ornament such as a row of asterisks.
Transitions separate other body elements.
Source code for docutils.parsers.rst
A transition should not begin or end a section or document, nor should two transitions be immediately adjacent. The syntax for a transition marker is a horizontal line of 4 or more repeated punctuation characters. The syntax is the same as section title underlines without title text. Transition markers require blank lines before and after:. Unlike section title underlines, no hierarchy of transition markers is enforced, nor do differences in transition markers accomplish anything.
It is recommended that a single consistent style be used. The processing system is free to render transitions in output in any way it likes.