reStructuredText标记规范

Author

David Goodger

Contact

docutils-develop@lists.sourceforge.net

Revision

$Revision: 8205 $

Date

$Date: 2017-11-27 12:07:28 +0100 (Mo, 27. Nov 2017) $

Copyright

本文档已置于公共领域.

注解

本文档是详细的技术规范;它不是教程或入门. 如果这是您第一次接触reStructuredText, 请首先阅读 A ReStructuredText Primer 和 Quick reStructuredText 用户参考.

reStructuredText 是纯文本, 它使用简单直观的结构来指示文档的结构. 这些结构同样易于以原始和处理形式阅读. 本文档本身就是reStructuredText的一个示例 (如果您正在阅读文本文件, 则为raw, 如果您正在阅读HTML文档, 则进行处理) . reStructuredText解析器是 Docutils 的一个组件.

简单的隐式标记用于指示特殊构造, 例如章节标题, 项目符号列表和重点. 使用的标记尽可能小且不引人注目. 较少使用的构造和对基本reStructuredText语法的扩展可能具有更复杂或明确的标记.

reStructuredText适用于任何长度的文档, 从非常小的 (例如内联程序文档片段, 例如Python文档字符串) 到相当大的文档 (本文档) .

第一部分通过示例快速概述了reStructuredText标记的语法. 完整的规范在 Syntax Details 部分给出.

在本文档中, Literal blocks (其中没有进行标记处理) 用于示例, 以说明明文标记.

快速语法概述

reStructuredText文档由正文或块级元素组成, 并且可以构造成部分. Sections 通过标题样式 (下划线和可选的上划线) 表示. 部分包含主体元素和/或子部分. 一些body元素包含其他元素, 例如包含列表项的列表, 而列表项又包含段落和其他body元素. 其他的, 如段落, 包含文本和 inline markup 元素.

以下是 body elements 的示例:

  • Paragraphs (和 inline markup)

    Paragraphs contain text and may contain inline markup:
*emphasis*, **strong emphasis**, `interpreted text`, ``inline
literals``, standalone hyperlinks (http://www.python.org),
external hyperlinks (Python_), internal cross-references
(example_), footnote references ([1]_), citation references
([CIT2002]_), substitution references (|example|), and _`inline
internal targets`.

Paragraphs are separated by blank lines and are left-aligned.

  • 五种类型的清单:

    1. Bullet lists:

      - This is a bullet list.

- Bullets can be "*", "+", or "-".

    2. Enumerated lists:

      1. This is an enumerated list.

2. Enumerators may be arabic numbers, letters, or roman
   numerals.

    3. Definition lists:

      what
    Definition lists associate a term with a definition.

how
    The term is a one-line phrase, and the definition is one
    or more paragraphs or body elements, indented relative to
    the term.

    4. Field lists:

      :what: Field lists map field names to field bodies, like
       database records.  They are often part of an extension
       syntax.

:how: The field marker is a colon, the field name, and a
      colon.

      The field body may contain one or more body elements,
      indented relative to the field marker.

    5. Option lists, 用于列出命令行选项:

      -a            command-line option "a"
-b file       options can have arguments
              and long descriptions
--long        options can be long also
--input=file  long options can also have
              arguments
/V            DOS/VMS-style options too

      选项和描述之间必须至少有两个空格.

  • Literal blocks:

    Literal blocks are either indented or line-prefix-quoted blocks,
and indicated with a double-colon ("::") at the end of the
preceding paragraph (right here -->)::

    if literal_block:
        text = 'is left as-is'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = None

  • Block quotes:

    Block quotes consist of indented body elements:

    This theory, that is mine, is mine.

    -- Anne Elk (Miss)

  • Doctest blocks:

    >>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)

  • Two syntaxes for tables:

    1. Grid tables; 完整, 但复杂而冗长:

      +------------------------+------------+----------+
| Header row, column 1   | Header 2   | Header 3 |
+========================+============+==========+
| body row 1, column 1   | column 2   | column 3 |
+------------------------+------------+----------+
| body row 2             | Cells may span        |
+------------------------+-----------------------+

    2. Simple tables; 简单紧凑, 但有限:

      ====================  ==========  ==========
Header row, column 1  Header 2    Header 3
====================  ==========  ==========
body row 1, column 1  column 2    column 3
body row 2            Cells may span columns
====================  ======================

  • Explicit markup blocks 都以显式块标记, 两个句点和一个空格开头:

    • Footnotes:

      .. [1] A footnote contains body elements, consistently
   indented by at least 3 spaces.

    • Citations:

      .. [CIT2002] Just like a footnote, except the label is
   textual.

    • Hyperlink targets:

      .. _Python: http://www.python.org

.. _example:

The "_example" target above points to this paragraph.

    • Directives:

      .. image:: mylogo.png

    • Substitution definitions:

      .. |symbol here| image:: symbol.png

    • Comments:

      .. Comments begin with two dots and a space.  Anything may
   follow, except for the syntax of footnotes/citations,
   hyperlink targets, directives, or substitution definitions.

语法详细信息

下面的描述列出了与语法结构相对应的 “doctree elements” (文档树元素名称; XML DTD通用标识符) . 有关元素层次结构的详细信息, 请参阅 Docutils Document Tree 和 Docutils Generic DTD XML文档类型定义.

空白

建议使用空格来缩进, 但也可以使用制表符. 标签将转换为空格. 制表位在每第8列.

其他空白字符 (换页符 [chr(12)] 和垂直制表符 [chr(11)]) 在处理之前转换为单个空格.

空白行

空行用于分隔段落和其他元素. 多个连续的空白行相当于一个空行, 但文字块 (保留所有空格) 除外. 当标记与缩进一起使元素分离明确时, 可以省略空行. 文档的第一行被视为前面有一个空行, 文档的最后一行被视为后跟一个空行.

缩进

缩进用于指示 – 并且仅在指示中有意义 – 块引号, 定义 (在定义列表项中) 和本地嵌套内容:

  • 列表项内容 (列表项的多行内容, 列表项中的多个主体元素, 包括嵌套列表) ,

  • 文字块的内容, 和

  • 显式标记块的内容.

缩进小于当前级别的任何文本 (即, 未缩进的文本或 “dedents”) 将结束当前缩进级别.

由于所有压痕都很重要, 压痕水平必须一致. 例如, 缩进是 block quotes 的唯一标记指示符:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

    Paragraph 2 of the first-level block quote.

块引用中的多个缩进级别将导致更复杂的结构:

This is a top-level paragraph.

    This paragraph belongs to a first-level block quote.

        This paragraph belongs to a second-level block quote.

Another top-level paragraph.

        This paragraph belongs to a second-level block quote.

    This paragraph belongs to a first-level block quote.  The
    second-level block quote above is inside this first-level
    block quote.

当段落或其他构造由多行文本组成时, 这些行必须左对齐:

This is a paragraph.  The lines of
this paragraph are aligned at the left.

    This paragraph has problems.  The
lines are not left-aligned.  In addition
  to potential misinterpretation, warning
    and/or error messages will be generated
  by the parser.

几个构造以标记开头, 构造体必须相对于标记缩进. 对于使用简单标记(bullet lists, enumerated lists, footnotes, citations, hyperlink targets, directives_和comments) 的构造, body的缩进程度由第一行的位置决定文本的开头, 与标记在同一行. 例如, 项目符号列表主体必须相对于项目符号的左边缘至少缩进两列:

- This is the first line of a bullet list
  item's paragraph.  All lines must align
  relative to the first line.  [1]_

      This indented paragraph is interpreted
      as a block quote.

Because it is not sufficiently indented,
this paragraph does not belong to the list
item.

.. [1] Here's a footnote.  The second line is aligned
   with the beginning of the footnote label.  The ".."
   marker is what determines the indentation.

For constructs using complex markers (field lists and option lists), where 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):

:Hello: This field has a short field name, so aligning the field
        body with the first line is feasible.

:Number-of-African-swallows-required-to-carry-a-coconut: It would
    be very difficult to align the field body with the left edge
    of the first line.  It may even be preferable not to begin the
    body on the same line as the marker.

转意机制

普通文档 (7位ASCII)普遍可用的字符集是有限的. 无论用于标记的字符是什么, 它们在书面文本中已经具有多种含义. 因此, 标记字符 将 有时会出现在文本中, 而不是用作标记. 任何严格的标记系统都需要一个转义机制来覆盖用于标记的字符的默认含义. 在reStructuredText中, 我们使用反斜杠, 通常用作其他域中的转义字符.

任何字符后跟一个反斜杠 (非URI上下文中的空格字符除外)都会转义该字符. 转义字符代表字符本身, 并且无法在任何标记解释中发挥作用. 从输出中删除反斜杠. 文字反斜杠由一行中的两个反斜杠表示 (第一个反斜杠 “转义” 第二个, 防止它被解释为 “转义” 角色).

在非URI上下文中, 从文档中删除反斜杠转义的空白字符. 这允许字符级 inline markup.

在URI中, 反斜杠转义的空格表示单个空格.

有两种情况, 反斜杠没有特殊含义:文字块和内联文字. 在这些上下文中, 单个反斜杠表示字面反斜杠, 而不必加倍.

请注意, reStructuredText规范和解析器不解决文本输入的表示或提取问题 (文本实际上如何以及以何种形式 到达 解析器). 反斜杠和其他角色可能在某些情况下起到转意角色的作用, 必须妥善处理. 例如, Python在字符串中使用反斜杠来转义某些字符, 而不是其他字符. 在Python文档字符串中出现反斜杠时最简单的解决方案是使用原始文档字符串:

r"""This is a raw docstring.  Backslashes (\) are not touched."""

参考名称

简单的参考名称是由字母数字加上孤立的 (没有两个相邻的)内部连字符, 下划线, 句号, 冒号和加号组成的单个单词;不允许有空格或其他字符. 脚注标签 (Footnotes ＆ Footnote References), 引文标签 (Citations ＆ Citation References), `解释文本`_角色和一些`超链接引用`_使用简单的引用名称语法.

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:

Want to learn about `my favorite programming language`_?

.. _my favorite programming language: http://www.python.org

简单的引用名称也可以选择使用反引号.

Reference names are whitespace-neutral and case-insensitive. When resolving reference names internally:

  • whitespace is normalized (one or more spaces, horizontal or vertical tabs, newlines, carriage returns, or form feeds, are interpreted as a single space), and

  • case is normalized (all alphabetic characters are converted to lowercase).

例如, 以下 hyperlink references 是等效的:

- `A HYPERLINK`_
- `a    hyperlink`_
- `A
  Hyperlink`_

Hyperlinks, footnotes, and 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 “.. [1]”) which can be referred to by a footnote reference ([1]_), can also be referred to by a plain hyperlink reference (1). 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.

文件结构

文献

Doctree元素:文档.

The top-level element of a parsed reStructuredText document is the “document” element. After initial parsing, the document element is a simple container for a document fragment, consisting of body elements, transitions, and sections, but lacking a document title or other bibliographic elements. The code that calls the parser may choose to run one or more optional post-parse transforms, rearranging the document fragment into a complete document with a title and possibly other metadata elements (author, date, etc.; see Bibliographic Fields).

Specifically, there is no way to indicate a document title and subtitle explicitly in reStructuredText. 1 Instead, a lone top-level section title (see Sections below) can be treated as the document title. 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 level or two. See the DocTitle transform for details.

1

The title configuration setting can set a document title that does not become part of the document body.

章节

Doctree元素:章节, 标题.

Sections are identified through their titles, which are marked up with adornment: “underlines” below the title text, or underlines and matching “overlines” above the title. An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. Specifically, an underline/overline character may be any non-alphanumeric printable 7-bit ASCII character 2. When an overline is used, the length 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).

2

The following are all valid section title adornment characters:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Some characters are more suitable than others. The following are recommended:

= - ` : . ' " ~ ^ _ * + #

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 H1), the second style will be a subtitle, the third will be a subsubtitle, and so on.

以下是节标题样式的示例:

===============
 Section Title
===============

---------------
 Section Title
---------------

Section Title
=============

Section Title
-------------

Section Title
`````````````

Section Title
'''''''''''''

Section Title
.............

Section Title
~~~~~~~~~~~~~

Section Title
*************

Section Title
+++++++++++++

Section Title
^^^^^^^^^^^^^

When a title has both an 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: once a hierarchy of title styles is established, sections must use that hierarchy.

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 that of the section title. See Implicit Hyperlink Targets for a complete description.

Sections may contain body elements, transitions, and nested sections.

翻译

Doctree元素: transition.

Instead of subheads, extra space or a type ornament between paragraphs may be used to mark text divisions or to signal changes in subject or emphasis.

(芝加哥风格手册, 第14版, 第1.80节)

Transitions are commonly seen in novels and short fiction, as a gap spanning one or more lines, with or without a type ornament such as a row of asterisks. Transitions separate other body elements. 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:

Para.

----------

Para.

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. For example, horizontal rules (<hr>) in HTML output would be an obvious choice.

主体元素

段落

Doctree 元件: 段.

Paragraphs consist of blocks of left-aligned text with no markup indicating any other body element. Blank lines separate paragraphs from each other and from other body elements. Paragraphs may contain inline markup.

语法图:

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

子弹列表

Doctree元素: bullet_list, list_item.

A text block which begins with a “*”, “+”, “-“, “•”, “‣”, or “⁃”, followed by whitespace, is a bullet list item (a.k.a. “unordered” list item). List item bodies must be left-aligned and indented relative to the bullet; the text immediately after the bullet determines the indentation. For example:

- This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.

- This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

- This is the third item of the main list.

This paragraph is not part of the list.

以下是 错误 格式的项目符号列表的示例:

- This first line is fine.
A blank line is required between list items and paragraphs.
(Warning)

- The following line appears to be a new sublist, but it is not:
  - This is a paragraph continuation, not a sublist (since there's
    no blank line).  This line is also incorrectly indented.
  - Warnings may be issued by the implementation.

语法图:

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+

枚举列表

Doctree 元素: enumerated_list, list_item.

Enumerated lists (a.k.a. “ordered” lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an enumeration sequence member and formatting, followed by whitespace. The following enumeration sequences are recognized:

  • 阿拉伯数字:1,2,3 ……(无上限).

  • 大写字母字符:A, B, C, …, Z.

  • 小写字母字符:a, b, c, …, z.

  • 大写罗马数字:I, II, III, IV, …, MMMMCMXCIX(4999).

  • 小写罗马数字:i, ii, iii, iv, …, mmmmcmxcix(4999).

In addition, the auto-enumerator, “#”, may be used to automatically enumerate a list. Auto-enumerated lists may begin with explicit enumeration, which sets the sequence. Fully auto-enumerated lists use arabic numerals and begin with 1. (Auto-enumerated lists are new in Docutils 0.3.8.)

识别以下格式类型:

  • 以句号结尾: “1.”, “A.”, “a.”, “I.”, “i.”.

  • 被括号括起来: “(1)”, “(A)”, “(a)”, “(I)”, “(i)”.

  • 后缀右括号: “1)”, “A)”, “a)”, “I)”, “i)”.

在解析枚举列表时, 每当启动一个新列表时:

  • An enumerator is encountered which does not have the same format and sequence type as the current list (e.g. “1.”, “(a)” produces two separate lists).

  • The enumerators are not in sequence (e.g., “1.”, “3.” produces two separate lists).

It is recommended that the enumerator of the first list item be ordinal-1 (“1”, “A”, “a”, “I”, or “i”). Although other start-values will be recognized, they may not be supported by the output format. A level-1 [info] system message will be generated for any list beginning with a non-ordinal-1 enumerator.

Lists using Roman numerals must begin with “I”/”i” or a multi-character value, such as “II” or “XV”. Any other single-character Roman numeral (“V”, “X”, “L”, “C”, “D”, “M”) will be interpreted as a letter of the alphabet, not as a Roman numeral. Likewise, lists using letters of the alphabet may not begin with “I”/”i”, since these are recognized as Roman numeral 1.

The second line of each enumerated list item is checked for validity. This is to prevent ordinary paragraphs from being mistakenly interpreted as list items, when they happen to begin with text identical to enumerators. For example, this text is parsed as an ordinary paragraph:

A. Einstein was a really
smart dude.

However, ambiguity cannot be avoided if the paragraph consists of only one line. This text is parsed as an enumerated list item:

A. Einstein was a really smart dude.

If a single-line paragraph begins with text identical to an enumerator (“A.”, “1.”, “(b)”, “I)”, etc.), the first character will have to be escaped in order to have the line parsed as an ordinary paragraph:

\A. Einstein was a really smart dude.

嵌套枚举列表的示例:

1. Item 1 initial text.

   a) Item 1a.
   b) Item 1b.

2. a) Item 2a.
   b) Item 2b.

示例语法图:

+-------+----------------------+
| "1. " | list item            |
+-------| (body elements)+     |
        +----------------------+

定义列表

Doctree elements: definition_list, definition_list_item, term, classifier, definition.

Each definition list item contains a term, optional classifiers, and a definition. A term is a simple one-line word or phrase. Optional classifiers may follow the term on the same line, each after an inline ” : ” (space, colon, space). A definition is a block indented relative to the term, and may contain multiple paragraphs and other body elements. There may be no blank line between a term line and a definition block (this distinguishes definition lists from block quotes). Blank lines are required before the first and after the last definition list item, but are optional in-between. For example:

term 1
    Definition 1.

term 2
    Definition 2, paragraph 1.

    Definition 2, paragraph 2.

term 3 : classifier
    Definition 3.

term 4 : classifier one : classifier two
    Definition 4.

Inline markup is parsed in the term line before the classifier delimiter (” : “) is recognized. The delimiter will only be recognized if it appears outside of any inline markup.

定义列表可以以各种方式使用, 包括:

  • As a dictionary or glossary. The term is the word itself, a classifier may be used to indicate the usage of the term (noun, verb, etc.), and the definition follows.

  • To describe program variables. The term is the variable name, a classifier may be used to indicate the type of the variable (string, integer, etc.), and the definition describes the variable’s use in the program. This usage of definition lists supports the classifier syntax of Grouch, a system for describing and enforcing a Python object schema.

语法图:

+----------------------------+
| term [ " : " classifier ]* |
+--+-------------------------+--+
   | definition                 |
   | (body elements)+           |
   +----------------------------+

现场名单

Doctree 元素: field_list, field, field_name, field_body.

Field lists are used as part of an extension syntax, such as options for directives, or database-like records meant for further processing. They may also be used for two-column table-like structures resembling database records (label & data pairs). Applications of reStructuredText may recognize field names and transform fields or field bodies in certain contexts. For examples, see Bibliographic Fields below, or the “image” and “meta” directives in reStructuredText Directives.

Field lists are mappings from field names to field bodies, modeled on RFC822 headers. A field name may consist of any characters, but colons (“:”) inside of field names must be backslash-escaped when followed by whitespace.3 Inline markup is parsed in field names, but care must be taken when using interpreted text with explicit roles in field names: the role must be a suffix to the interpreted text. Field names are case-insensitive when further processed or transformed. The field name, along with a single colon prefix and suffix, together form the field marker. The field marker is followed by whitespace and the field body. The field body may contain multiple body elements, indented relative to the field marker. The first line after the field name marker determines the indentation of the field body. For example:

:Date: 2001-08-16
:Version: 1
:Authors: - Me
          - Myself
          - I
:Indentation: Since the field marker may be quite long, the second
   and subsequent lines of the field body do not have to line up
   with the first line, but they must be indented relative to the
   field name marker, and they must line up with each other.
:Parameter i: integer

The interpretation of individual words in a multi-word field name is up to the application. The application may specify a syntax for the field name. For example, second and subsequent words may be treated as “arguments”, quoted phrases may be treated as a single argument, and direct support for the “name=value” syntax may be added.

Standard RFC822 headers cannot be used for this construct because they are ambiguous. A word followed by a colon at the beginning of a line is common in written text. However, in well-defined contexts such as when a field list invariably occurs at the beginning of a document (PEPs and email messages), standard RFC822 headers could be used.

语法图(简化):

+--------------------+----------------------+
| ":" field name ":" | field body           |
+-------+------------+                      |
        | (body elements)+                  |
        +-----------------------------------+
3

Up to Docutils 0.14, field markers were not recognized when containing a colon.

书目领域

Doctree elements: docinfo, author, authors, organization, contact, version, status, date, copyright, field, topic.

When a field list is the first non-comment element in a document (after the document title, if there is one), it may have its fields transformed to document bibliographic data. This bibliographic data corresponds to the front matter of a book, such as the title page and copyright page.

Certain registered field names (listed below) are recognized and transformed to the corresponding doctree elements, most becoming child elements of the “docinfo” element. No ordering is required of these fields, although they may be rearranged to fit the document structure, as noted. Unless otherwise indicated below, each of the bibliographic elements’ field bodies may contain a single paragraph only. Field bodies may be checked for RCS keywords and cleaned up. Any unrecognized fields will remain as generic fields in the docinfo element.

The registered bibliographic field names and their corresponding doctree elements are as follows:

  • Field name “Author”: author element.

  • “Authors”: authors.

  • “Organization”: organization.

  • “Contact”: contact.

  • “Address”: address.

  • “Version”: version.

  • “Status”: status.

  • “Date”: date.

  • “Copyright”: copyright.

  • “Dedication”: topic.

  • “Abstract”: topic.

The “Authors” field may contain either: a single paragraph consisting of a list of authors, separated by “;” or “,” (“;” is checked first, so “Doe, Jane; Doe, John” will work.); multiple paragraphs (one per author); or a bullet list whose elements each contain a single paragraph per author. In some languages (e.g. Swedish), there is no singular/plural distinction between “Author” and “Authors”, so only an “Authors” field is provided, and a single name is interpreted as an “Author”. If a single name contains a comma, end it with a semicolon to disambiguate: “:Authors: Doe, Jane;”.

The “Address” field is for a multi-line surface mailing address. Newlines and whitespace will be preserved.

The “Dedication” and “Abstract” fields may contain arbitrary body elements. Only one of each is allowed. They become topic elements with “Dedication” or “Abstract” titles (or language equivalents) immediately following the docinfo element.

This field-name-to-element mapping can be replaced for other languages. See the DocInfo transform implementation documentation for details.

Unregistered/generic fields may contain one or more paragraphs or arbitrary body elements. The field name is also used as a “classes” attribute value after being converted into a valid identifier form.

RCS 关键词

Bibliographic fields recognized by the parser are normally checked for RCS 4 keywords and cleaned up 5. RCS keywords may be entered into source files as “$keyword$”, and once stored under RCS or CVS 6, they are expanded to “$keyword: expansion text $”. For example, a “Status” field will be transformed to a “status” element:

:Status: $keyword: expansion text $
4

修订控制系统.

5

可以关闭RCS关键字处理(未实现).

6

并发版本系统. CVS使用与RCS相同的关键字.

Processed, the “status” element’s text will become simply “expansion text”. The dollar sign delimiters and leading RCS keyword name are removed.

The RCS keyword processing only kicks in when the field list is in bibliographic context (first non-comment construct in the document, after a document title if there is one).

选项列表

Doctree elements: option_list, option_list_item, option_group, option, option_string, option_argument, description.

Option lists are two-column lists of command-line options and descriptions, documenting a program’s options. For example:

-a         Output all.
-b         Output both (this description is
           quite long).
-c arg     Output just arg.
--long     Output all day long.

-p         This option has two paragraphs in the description.
           This is the first.

           This is the second.  Blank lines may be omitted between
           options (as above) or left in (as here and below).

--very-long-option  A VMS-style option.  Note the adjustment for
                    the required two spaces.

--an-even-longer-option
           The description can also start on the next line.

-2, --two  This option has two variants.

-f FILE, --file=FILE  These two options are synonyms; both have
                      arguments.

/V         A VMS/DOS-style option.

reStructuredText可识别几种类型的选项:

  • 短POSIX选项由一个破折号和一个选项字母组成.

  • Long POSIX options consist of two dashes and an option word; some systems use a single dash.

  • Old GNU-style “plus” options consist of one plus and an option letter (“plus” options are deprecated now, their use discouraged).

  • DOS / VMS选项由斜杠和选项字母或单词组成.

Please note that both POSIX-style and DOS/VMS-style options may be used by DOS or Windows software. These and other variations are sometimes used mixed together. The names above have been chosen for convenience only.

The syntax for short and long POSIX options is based on the syntax supported by Python’s getopt.py module, which implements an option parser similar to the GNU libc getopt_long() function but with some restrictions. There are many variant option systems, and reStructuredText option lists do not support all of them.

Although long POSIX and DOS/VMS option words may be allowed to be truncated by the operating system or the application when used on the command line, reStructuredText option lists do not show or support this with any special syntax. The complete option word should be given, supported by notes about truncation if and when applicable.

Options may be followed by an argument placeholder, whose role and syntax should be explained in the description text. Either a space or an equals sign may be used as a delimiter between options and option argument placeholders; short options (“-” or “+” prefix only) may omit the delimiter. Option arguments may take one of two forms:

  • Begins with a letter ([a-zA-Z]) and subsequently consists of letters, numbers, underscores and hyphens ([a-zA-Z0-9_-]).

  • Begins with an open-angle-bracket (<) and ends with a close-angle-bracket (>); any characters except angle brackets are allowed internally.

Multiple option “synonyms” may be listed, sharing a single description. They must be separated by comma-space.

There must be at least two spaces between the option(s) and the description. The description may contain multiple body elements. The first line after the option marker determines the indentation of the description. As with other types of lists, blank lines are required before the first option list item and after the last, but are optional between option entries.

语法图(简化):

+----------------------------+-------------+
| option [" " argument] "  " | description |
+-------+--------------------+             |
        | (body elements)+                 |
        +----------------------------------+

文字块

Doctree 元素: literal_block.

A paragraph consisting of two colons (“::”) signifies that the following text block(s) comprise a literal block. The literal block must either be indented or quoted (see below). No markup processing is done within a literal block. It is left as-is, and is typically rendered in a monospaced typeface:

This is a typical paragraph.  An indented literal block follows.

::

    for a in [5,4,3,2,1]:   # this is program code, shown as-is
        print a
    print "it's..."
    # a literal block continues until the indentation ends

This text has returned to the indentation of the first paragraph,
is outside of the literal block, and is therefore treated as an
ordinary paragraph.

The paragraph containing only “::” will be completely removed from the output; no empty paragraph will remain.

As a convenience, the “::” is recognized at the end of any paragraph. If immediately preceded by whitespace, both colons will be removed from the output (this is the “partially minimized” form). When text immediately precedes the “::”, one colon will be removed from the output, leaving only one colon visible (i.e., “::” will be replaced by “:”; this is the “fully minimized” form).

In other words, these are all equivalent (please pay attention to the colons after “Paragraph”):

  1. 扩展形式:

    Paragraph:

::

    Literal block

  2. 部分最小化的形式:

    Paragraph: ::

    Literal block

  3. 完全最小化形式:

    Paragraph::

    Literal block

All whitespace (including line breaks, but excluding minimum indentation for indented literal blocks) is preserved. Blank lines are required before and after a literal block, but these blank lines are not included as part of the literal block.

缩进的文字块

Indented literal blocks are indicated by indentation relative to the surrounding text (leading whitespace on each line). The minimum indentation will be removed from each line of an indented literal block. The literal block need not be contiguous; blank lines are allowed between sections of indented text. The literal block ends with the end of the indentation.

语法图:

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
   +---------------------------+
   | indented literal block    |
   +---------------------------+
引用的文字块

Quoted literal blocks are unindented contiguous blocks of text where each line begins with the same non-alphanumeric printable 7-bit ASCII character 7. A blank line ends a quoted literal block. The quoting characters are preserved in the processed document.

7

以下是所有有效的引用字符:

! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~

Note that these are the same characters as are valid for title adornment of sections.

可能的用途包括Haskell中的文字编程和电子邮件引用:

John Doe wrote::

>> Great idea!
>
> Why didn't I think of that?

You just did!  ;-)

语法图:

+------------------------------+
| paragraph                    |
| (ends with "::")             |
+------------------------------+
+------------------------------+
| ">" per-line-quoted          |
| ">" contiguous literal block |
+------------------------------+

线块

Doctree 元素: line_block, line. (Docutils 0.3.5中的新功能.)

Line blocks are useful for address blocks, verse (poetry, song lyrics), and unadorned lists, where the structure of lines is significant. Line blocks are groups of lines beginning with vertical bar (“|”) prefixes. Each vertical bar prefix indicates a new line, so line breaks are preserved. Initial indents are also significant, resulting in a nested structure. Inline markup is supported. Continuation lines are wrapped portions of long lines; they begin with a space in place of the vertical bar. The left edge of a continuation line must be indented, but need not be aligned with the left edge of the text above it. A line block ends with a blank line.

此示例说明了延续行:

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

This example illustrates the nesting of line blocks, indicated by the initial indentation of new lines:

Take it away, Eric the Orchestra Leader!

    | A one, two, a one two three four
    |
    | Half a bee, philosophically,
    |     must, *ipso facto*, half not be.
    | But half the bee has got to be,
    |     *vis a vis* its entity.  D'you see?
    |
    | But can a bee be said to be
    |     or not to be an entire bee,
    |         when half the bee is not a bee,
    |             due to some ancient injury?
    |
    | Singing...

语法图:

+------+-----------------------+
| "| " | line                  |
+------| continuation line     |
       +-----------------------+

阻止行情

Doctree 元素: block_quote, attribution.

A text block that is indented relative to the preceding text, without preceding markup indicating it to be a literal block or other content, is a block quote. All markup processing (for body elements and inline markup) continues within the block quote:

This is an ordinary paragraph, introducing a block quote.

    "It is my business to know things.  That is my trade."

    -- Sherlock Holmes

A block quote may end with an attribution: a text block beginning with “–”, “—”, or a true em-dash, flush left within the block quote. If the attribution consists of multiple lines, the left edges of the second and subsequent lines must align.

Multiple block quotes may occur consecutively if terminated with attributions.

未缩进的段落.

阻止报价1.

—Attribution 1

阻止报价2.

Empty comments may be used to explicitly terminate preceding constructs that would otherwise consume a block quote:

* List item.

..

    Block quote 3.

空注释也可用于分隔块引号:

    Block quote 4.

..

    Block quote 5.

Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote.

语法图:

+------------------------------+
| (current level of            |
| indentation)                 |
+------------------------------+
   +---------------------------+
   | block quote               |
   | (body elements)+          |
   |                           |
   | -- attribution text       |
   |    (optional)             |
   +---------------------------+

Doctest块

Doctree 元素: doctest_block.

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They are meant to illustrate usage by example, and provide an elegant and powerful testing environment via the doctest module in the Python standard library.

Doctest blocks are text blocks which begin with ">>> ", the Python interactive interpreter main prompt, and end with a blank line. Doctest blocks are treated as a special case of literal blocks, without requiring the literal block syntax. If both are present, the literal block syntax takes priority over Doctest block syntax:

This is an ordinary paragraph.

>>> print 'this is a Doctest block'
this is a Doctest block

The following is a literal block::

    >>> This is not recognized as a doctest block by
    reStructuredText.  It *will* be recognized by the doctest
    module, though!

doctest块不需要缩进.

表

Doctree 元素: table, tgroup, colspec, thead, tbody, row, entry.

ReStructuredText提供了两种用于描述表格单元格的语法: Grid Tables 和 Simple Tables.

与其他身体元素一样, 表格前后需要空白行. 表的左边缘应与前面文本块的左边缘对齐;如果缩进, 则该表被视为块引用的一部分.

一旦被隔离, 每个表格单元被视为微型文件;顶部和底部单元格边界用作分隔空行. 每个单元格包含零个或多个主体元素. 单元格内容可以包括左边距和/或右边距, 其在处理之前被移除.

网格表

网格表通过类似网格的 “ASCII art” 提供完整的表格表示. 网格表允许任意单元格内容(主体元素), 以及行和列跨度. 但是, 网格表生成起来很麻烦, 特别是对于简单的数据集. Emacs表模式`_是一个允许在Emacs中轻松编辑网格表的工具. 请参阅 `Simple Tables 以获得更简单(但有限)的表示.

网格表用可视网格描述, 网格由字符 “-” , “=” , “|” 和 “+ ” 组成. 连字符(“-“)用于水平线(行分隔符). 等号(“=”)可用于将可选标题行与表体分开(不支持 Emacs table mode). 垂直条(“|”)用于垂直线(列分隔符). 加号(“+ “)用于水平和垂直线的交叉. 例:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

必须注意网格表, 以避免在极少数情况下与单元格文本发生意外交互. 例如, 下表包含第2行中从第2列到第4列的单元格:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

如果在该单元格的文本中使用垂直条, 则如果意外地与列边界对齐, 则可能会产生意外影响:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

有几种解决方案可行. 所需要的只是打破单元格轮廓矩形的连续性. 一种可能性是通过在之前添加额外空间来移动文本:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        |  Use the command ``ls | more``.  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+

另一种可能性是在第2行添加额外的行:

+--------------+----------+-----------+-----------+
| row 1, col 1 | column 2 | column 3  | column 4  |
+--------------+----------+-----------+-----------+
| row 2        | Use the command ``ls | more``.   |
|              |                                  |
+--------------+----------+-----------+-----------+
| row 3        |          |           |           |
+--------------+----------+-----------+-----------+
简单的表格

简单表格为简单数据集提供了紧凑且易于键入但有限的面向行的表格表示. 单元格内容通常是单个段落, 但是在大多数单元格中可以表示任意的主体元素. 简单表允许多行行(除了第一列以外的所有行)和列跨度, 但不允许行跨度. 请参阅上面的 “网格表格” 以获得完整的表格表示.

描述简单表格的水平边框由 “=” 和 ” -” 字符组成. 等号(“=”)用于顶部和底部表格边框, 并将可选的标题行与表格主体分开. 连字符(“-“)用于通过为连接列加下划线来指示单行中的列跨度, 并且可以可选地用于显式地和/或可视地分隔行.

一个简单的表格以等号的顶部边框开始, 每个列边界有一个或多个空格(建议使用两个或多个空格). 无论跨度如何, 顶部边框*必须*完全描述所有表格列. 表中必须至少有两列(以区别于节标题). 顶部边框后面可能是标题行, 最后一个可选标题行用’=’加下划线, 同样在列边界有空格. 标题行分隔符下面可能没有空行;它将被解释为表格的底部边界. 表的底部边界由’=’下划线组成, 在列边界处也有空格. 例如, 这是一个真值表, 一个包含一个标题行和四个主体行的三列表:

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

‘-‘ 的下划线可用于通过 “填充” 列边距来连接相邻列来指示列跨度. 列跨度下划线必须完整(它们必须覆盖所有列)并与已建立的列边界对齐. 包含列跨度下划线的文本行不能包含任何其他文本. 列跨度下划线仅适用于紧邻其上方的一行. 例如, 这是一个在标题中包含列跨度的表:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

每行文本必须在列边界处包含空格, 除非通过列跨度连接单元格. 每行文本都会开始一个新行, 除非第一列中有空白单元格. 在这种情况下, 该行文本被解析为延续行. 因此, 新行的第一列中的单元格(不 是延续线)*必须*包含一些文本;空白细胞会导致误解(但请参阅下面的提示). 此外, 此机制将第一列中的单元格限制为仅一行文本. 如果此限制是不可接受的, 请使用 grid tables.

小技巧

要在已处理输出的第一列中没有文本的简单表中启动新行, 请使用其中一个:

  • 空注释(“..”), 可以从已处理的输出中省略(参见下面的 Comments)

  • 一个反斜杠转义符(“\”)后跟一个空格(参见上面的’转义机制`)

‘-‘ 的下划线也可用于在视觉上分隔行, 即使没有列跨度. 这在长表中特别有用, 其中行的行数很多.

简单表中允许使用空行. 他们的解释取决于背景. *行之间的空行*将被忽略. *多行行内的空行*可以分隔单元格内的段落或其他正文元素.

最右边的列是无界的;文本可能会继续超出表格的边缘(如表格边框所示). 但是, 建议将边框设置得足够长以包含整个文本.

以下示例说明了连续行(第2行由两行文本组成, 第四行包含第3行), 空白行分隔段落(第3行, 第2列), 文本延伸超过表格的右边缘, 以及新的在处理的输出的第一列中没有文本的行(第4行):

=====  =====
col 1  col 2
=====  =====
1      Second column of row 1.
2      Second column of row 2.
       Second line of paragraph.
3      - Second column of row 3.

       - Second item in bullet
         list (row 3, column 2).
\      Row 4; column 1 will be empty.
=====  =====

显式标记块

显式标记块是文本块:

  • 其第一行以 “..” 开头, 后跟空格(“显式标记开始”),

  • 其第二行和后续行(如果有的话)相对于第一行缩进, 并且

  • 它在一条未缩进的线之前结束.

显式标记块类似于项目符号列表项, 其中 “..” 作为项目符号. 显式标记开始之后的行上的文本确定块体的缩进. 始终从块体的第二行和后续行中移除最大公共缩进. 因此, 如果第一个构造适合一行, 并且第一个和第二个构造的缩进应该不同, 则第一个构造不应该与显式标记开始在同一行上开始.

显式标记块和其他元素之间需要空行, 但在显式标记块之间是明确的, 这是明确的.

显式标记语法用于脚注, 引用, 超链接目标, 指令, 替换定义和注释.

脚注

也可以看看: Footnote References.

Doctree 元素: footnote, label.

配置设置: footnote_references.

每个脚注包含一个显式标记开头(“.. “), 一个左方括号, 脚注标签, 一个右方括号和空格, 后跟缩进的主体元素. 脚注标签可以是:

脚注内容(主体元素)必须始终缩进(至少3个空格)并左对齐. 脚注中的第一个body元素通常可以与脚注标签位于同一行. 但是, 如果第一个元素适合一行并且其余元素的缩进不同, 则第一个元素必须从脚注标签后的行开始. 否则, 将不会检测到缩进的差异.

Footnotes may occur anywhere in the document, not only at the end. Where and how they appear in the processed output depends on the processing system.

Here is a manually numbered footnote:

.. [1] Body elements go here.

Each footnote automatically generates a hyperlink target pointing to itself. The text of the hyperlink target name is the same as that of the footnote label. Auto-numbered footnotes generate a number as their footnote label and reference name. See Implicit Hyperlink Targets for a complete description of the mechanism.

语法图:

+-------+-------------------------+
| ".. " | "[" label "]" footnote  |
+-------+                         |
        | (body elements)+        |
        +-------------------------+
自动编号的脚注

A number sign (“#”) may be used as the first character of a footnote label to request automatic numbering of the footnote or footnote reference.

The first footnote to request automatic numbering is assigned the label “1”, the second is assigned the label “2”, and so on (assuming there are no manually numbered footnotes present; see Mixed Manual and Auto-Numbered Footnotes below). A footnote which has automatically received a label “1” generates an implicit hyperlink target with name “1”, just as if the label was explicitly specified.

A footnote may specify a label explicitly while at the same time requesting automatic numbering: [#label]. These labels are called autonumber labels. Autonumber labels do two things:

  • On the footnote itself, they generate a hyperlink target whose name is the autonumber label (doesn’t include the “#”).

  • They allow an automatically numbered footnote to be referred to more than once, as a footnote reference or hyperlink reference. For example:

    If [#note]_ is the first footnote reference, it will show up as
"[1]".  We can refer to it again as [#note]_ and again see
"[1]".  We can also refer to it as note_ (an ordinary internal
hyperlink reference).

.. [#note] This is the footnote labeled "note".

The numbering is determined by the order of the footnotes, not by the order of the references. For footnote references without autonumber labels ([#]_), the footnotes and footnote references must be in the same relative order but need not alternate in lock-step. For example:

[#]_ is a reference to footnote 1, and [#]_ is a reference to
footnote 2.

.. [#] This is footnote 1.
.. [#] This is footnote 2.
.. [#] This is footnote 3.

[#]_ is a reference to footnote 3.

Special care must be taken if footnotes themselves contain auto-numbered footnote references, or if multiple references are made in close proximity. Footnotes and references are noted in the order they are encountered in the document, which is not necessarily the same as the order in which a person would read them.

自我符号叉车

An asterisk (“*”) may be used for footnote labels to request automatic symbol generation for footnotes and footnote references. The asterisk may be the only character in the label. For example:

Here is a symbolic footnote reference: [*]_.

.. [*] This is the footnote.

A transform will insert symbols as labels into corresponding footnotes and footnote references. The number of references must be equal to the number of footnotes. One symbol footnote cannot have multiple references.

The standard Docutils system uses the following symbols for footnote marks 8:

  • asterisk/star (“*”)

  • dagger (HTML字符实体 “&dagger;”, Unicode U+02020)

  • double dagger (“&Dagger;”/U+02021)

  • section mark (“&sect;”/U+000A7)

  • pilcrow or paragraph mark (“&para;”/U+000B6)

  • number sign (“#”)

  • spade suit (“&spades;”/U+02660)

  • heart suit (“&hearts;”/U+02665)

  • diamond suit (“&diams;”/U+02666)

  • club suit (“&clubs;”/U+02663)

8

This list was inspired by the list of symbols for “Note Reference Marks” in The Chicago Manual of Style, 14th edition, section 12.51. “Parallels” (“||”) were given in CMoS instead of the pilcrow. The last four symbols (the card suits) were added arbitrarily.

If more than ten symbols are required, the same sequence will be reused, doubled and then tripled, and so on (“**” etc.).

注解

When using auto-symbol footnotes, the choice of output encoding is important. Many of the symbols used are not encodable in certain common text encodings such as Latin-1 (ISO 8859-1). The use of UTF-8 for the output encoding is recommended. An alternative for HTML and XML output is to use the “xmlcharrefreplace” output encoding error handler.

混合手动和自动编号脚注

Manual and automatic footnote numbering may both be used within a single document, although the results may not be expected. Manual numbering takes priority. Only unused footnote numbers are assigned to auto-numbered footnotes. The following example should be illustrative:

[2]_ will be "2" (manually numbered),
[#]_ will be "3" (anonymous auto-numbered), and
[#label]_ will be "1" (labeled auto-numbered).

.. [2] This footnote is labeled manually, so its number is fixed.

.. [#label] This autonumber-labeled footnote will be labeled "1".
   It is the first auto-numbered footnote and no other footnote
   with label "1" exists.  The order of the footnotes is used to
   determine numbering, not the order of the footnote references.

.. [#] This footnote will be labeled "3".  It is the second
   auto-numbered footnote, but footnote label "2" is already used.
引文

另请参阅: Citation References.

Doctree 元素: citation

Citations are identical to footnotes except that they use only non-numeric labels such as [note] or [GVR2001]. Citation labels are simple reference names (case-insensitive single words consisting of alphanumerics plus internal hyphens, underscores, and periods; no whitespace). Citations may be rendered separately and differently from footnotes. For example:

Here is a citation reference: [CIT2002]_.

.. [CIT2002] This is the citation.  It's just like a footnote,
   except the label is textual.
指令

Doctree 元素: 取决于指令.

Directives are an extension mechanism for reStructuredText, a way of adding support for new constructs without adding new primary syntax (directives may support additional syntax locally). All standard directives (those implemented and registered in the reference reStructuredText parser) are described in the reStructuredText Directives document, and are always available. Any other directives are domain-specific, and may require special action to make them available when processing the document.

例如，这里是如何放置image:

.. image:: mylogo.jpeg

figure_（带有标题的图形）可以像这样放置:

.. figure:: larch.png

   The larch.

admonition （注意，警告等）包含其他身体元素:

.. note:: This is a paragraph

   - Here is a bullet list.

Directives are indicated by an explicit markup start (“.. “) followed by the directive type, two colons, and whitespace (together called the “directive marker”). Directive types are case-insensitive single words (alphanumerics plus isolated internal hyphens, underscores, plus signs, colons, and periods; no whitespace). Two colons are used after the directive type for these reasons:

  • 两个冒号是独特的，不太可能在普通文本中使用。

  • 两个冒号避免与常见的评论文本冲突:

    .. Danger: modify at your own risk!

  • If an implementation of reStructuredText does not recognize a directive (i.e., the directive-handler is not installed), a level-3 (error) system message is generated, and the entire directive block (including the directive itself) will be included as a literal block. Thus “::” is a natural choice.

The directive block is consists of any text on the first line of the directive after the directive marker, and any subsequent indented text. The interpretation of the directive block is up to the directive code. There are three logical parts to the directive block:

  1. 指令论点。

  2. 指令选项。

  3. 指令内容。

Individual directives can employ any combination of these parts. Directive arguments can be filesystem paths, URLs, title text, etc. Directive options are indicated using field lists; the field names and contents are directive-specific. Arguments and options must form a contiguous block beginning on the first or second line of the directive; a blank line indicates the beginning of the directive content block. If either arguments and/or options are employed by the directive, a blank line must separate them from the directive content. The “figure” directive employs all three parts:

.. figure:: larch.png
   :scale: 50

   The larch.

Simple directives may not require any content. If a directive that does not employ a content block is followed by indented text anyway, it is an error. If a block quote should immediately follow a directive, use an empty comment in-between (see Comments below).

Actions taken in response to directives and the interpretation of text in the directive content block or subsequent text block(s) are directive-dependent. See reStructuredText Directives for details.

Directives are meant for the arbitrary processing of their contents, which can be transformed into something possibly unrelated to the original text. It may also be possible for directives to be used as pragmas, to modify the behavior of the parser, such as to experiment with alternate syntax. There is no parser support for this functionality at present; if a reasonable need for pragma directives is found, they may be supported.

Directives do not generate “directive” elements; they are a parser construct only, and have no intrinsic meaning outside of reStructuredText. Instead, the parser will transform recognized directives into (possibly specialized) document elements. Unknown directives will trigger level-3 (error) system messages.

语法图:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+
替代定义

Doctree 元素: substitution_definition.

Substitution definitions are indicated by an explicit markup start (“.. “) followed by a vertical bar, the substitution text, another vertical bar, whitespace, and the definition block. Substitution text may not begin or end with whitespace. A substitution definition block contains an embedded inline-compatible directive (without the leading “.. “), such as “image” or “replace”. For example:

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

It is an error for a substitution definition block to directly or indirectly contain a circular substitution reference.

Substitution references are replaced in-line by the processed contents of the corresponding definition (linked by matching substitution text). Matches are case-sensitive but forgiving; if no exact match is found, a case-insensitive comparison is attempted.

Substitution definitions allow the power and flexibility of block-level directives to be shared by inline text. They are a way to include arbitrarily complex inline structures within text, while keeping the details out of the flow of text. They are the equivalent of SGML/XML’s named entities or programming language macros.

Without the substitution mechanism, every time someone wants an application-specific new inline structure, they would have to petition for a syntax change. In combination with existing directive syntax, any inline structure can be coded without new syntax (except possibly a new directive).

语法图:

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

Following are some use cases for the substitution mechanism. Please note that most of the embedded directives shown are examples only and have not been implemented.

对象

Substitution references may be used to associate ambiguous text with a unique object identifier.

For example, many sites may wish to implement an inline “user” directive:

|Michael| and |Jon| are our widget-wranglers.

.. |Michael| user:: mjones
.. |Jon|     user:: jhl

Depending on the needs of the site, this may be used to index the document for later searching, to hyperlink the inline text in various ways (mailto, homepage, mouseover Javascript with profile and contact information, etc.), or to customize presentation of the text (include username in the inline text, include an icon image with a link next to the text, make the text bold or a different color, etc.).

The same approach can be used in documents which frequently refer to a particular type of objects with unique identifiers but ambiguous common names. Movies, albums, books, photos, court cases, and laws are possible. For example:

|The Transparent Society| offers a fascinating alternate view
on privacy issues.

.. |The Transparent Society| book:: isbn=0738201448

Classes or functions, in contexts where the module or class names are unclear and/or interpreted text cannot be used, are another possibility:

4XSLT has the convenience method |runString|, so you don't
have to mess with DOM objects if all you want is the
transformed output.

.. |runString| function:: module=xml.xslt class=Processor
图片

Images are a common use for substitution references:

West led the |H| 3, covered by dummy's |H| Q, East's |H| K,
and trumped in hand with the |S| 2.

.. |H| image:: /images/heart.png
   :height: 11
   :width: 11
.. |S| image:: /images/spade.png
   :height: 11
   :width: 11

* |Red light| means stop.
* |Green light| means go.
* |Yellow light| means go really fast.

.. |Red light|    image:: red_light.png
.. |Green light|  image:: green_light.png
.. |Yellow light| image:: yellow_light.png

|-><-| is the official symbol of POEE_.

.. |-><-| image:: discord.png
.. _POEE: http://www.poee.org/

The “image” directive has been implemented.

样式 10

Substitution references may be used to associate inline text with an externally defined presentation style:

Even |the text in Texas| is big.

.. |the text in Texas| style:: big

The style name may be meaningful in the context of some particular output format (CSS class name for HTML output, LaTeX style name for LaTeX, etc), or may be ignored for other output formats (such as plaintext).

10

There may be sufficient need for a “style” mechanism to warrant simpler syntax such as an extension to the interpreted text role syntax. The substitution mechanism is cumbersome for simple text styling.

模板

Inline markup may be used for later processing by a template engine. For example, a Zope author might write:

Welcome back, |name|!

.. |name| tal:: replace user/getUserName

处理后，将产生此ZPT输出:

Welcome back,
<span tal:replace="user/getUserName">name</span>!

Zope would then transform this to something like “Welcome back, David!” during a session with an actual user.

替换文字

The substitution mechanism may be used for simple macro substitution. This may be appropriate when the replacement text is repeated many times throughout one or more documents, especially if it may need to change later. A short example is unavoidably contrived:

|RST|_ is a little annoying to type over and over, especially
when writing about |RST| itself, and spelling out the
bicapitalized word |RST| every time isn't really necessary for
|RST| source readability.

.. |RST| replace:: reStructuredText
.. _RST: http://docutils.sourceforge.net/rst.html

Note the trailing underscore in the first use of a substitution reference. This indicates a reference to the corresponding hyperlink target.

Substitution is also appropriate when the replacement text cannot be represented using other inline constructs, or is obtrusively long:

But still, that's nothing compared to a name like
|j2ee-cas|__.

.. |j2ee-cas| replace::
   the Java `TM`:super: 2 Platform, Enterprise Edition Client
   Access Services
__ http://developer.java.sun.com/developer/earlyAccess/
   j2eecas/

The “replace” directive has been implemented.

评论

Doctree 元素: comment.

Arbitrary indented text may follow the explicit markup start and will be processed as a comment element. No further processing is done on the comment block text; a comment contains a single “text blob”. Depending on the output formatter, comments may be removed from the processed output. The only restriction on comments is that they not use the same syntax as any of the other explicit markup constructs: substitution definitions, directives, footnotes, citations, or hyperlink targets. To ensure that none of the other explicit markup constructs is recognized, leave the “..” on a line by itself:

.. This is a comment
..
   _so: is this!
..
   [and] this!
..
   this:: too!
..
   |even| this:: !

An explicit markup start followed by a blank line and nothing else (apart from whitespace) is an “empty comment”. It serves to terminate a preceding construct, and does not consume any indented text following. To have a block quote follow a list or any indented construct, insert an unindented empty comment in-between.

语法图:

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

内联标记

In reStructuredText, inline markup applies to words or phrases within a text block. The same whitespace and punctuation that serves to delimit words in written text is used to delimit the inline markup syntax constructs (see the inline markup recognition rules for details). The text within inline markup may not begin or end with whitespace. Arbitrary character-level inline markup is supported although not encouraged. Inline markup cannot be nested.

There are nine inline markup constructs. Five of the constructs use identical start-strings and end-strings to indicate the markup:

Three constructs use different start-strings and end-strings:

Standalone hyperlinks are recognized implicitly, and use no extra markup.

内联标记识别规则

Inline markup start-strings and end-strings are only recognized if the following conditions are met:

  1. Inline markup start-strings must be immediately followed by non-whitespace.

  2. 内联标记结束字符串必须紧跟非空白字符串。

  3. The inline markup end-string must be separated by at least one character from the start-string.

  4. Both, inline markup start-string and end-string must not be preceded by an unescaped backslash (except for the end-string of inline literals). See Escaping Mechanism above for details.

  5. If an inline markup start-string is immediately preceded by one of the ASCII characters ' " < ( [ { or a similar non-ASCII character 11, it must not be followed by the corresponding closing character from ' " ) ] } > or a similar non-ASCII character 12. (For quotes, matching characters can be any of the quotation marks in international usage.)

If the configuration setting simple-inline-markup is False (default), additional conditions apply to the characters “around” the inline markup:

  1. Inline markup start-strings must start a text block or be immediately preceded by

    • 空白，

    • 其中一个ASCII字符 - : / ' " < ( [ {

    • 或类似的非ASCII标点字符。 13

  2. Inline markup end-strings must end a text block or be immediately followed by

    • 空白，

    • one of the ASCII characters - . , : ; ! ? \ / ' " ) ] } >

    • 或类似的非ASCII标点字符。 14

11

Unicode categories Ps (Open), Pi (Initial quote), or Pf (Final quote). 15

12

Unicode categories Pe (Close), Pi (Initial quote), or Pf (Final quote). 15

13

Unicode categories Ps (Open), Pi (Initial quote), Pf (Final quote), Pd (Dash), or Po (Other). 15

14

Unicode categories Pe (Close), Pi (Initial quote), Pf (Final quote), Pd (Dash), or Po (Other). 15

15(1,2,3,4)

The category of some characters changed with the development of the Unicode standard. Docutils 0.13 uses Unicode version 5.2.0.

The inline markup recognition rules were devised to allow 90% of non-markup uses of “*”, “`”, “_”, and “|” without escaping. For example, none of the following terms are recognized as containing inline markup strings:

  • 2 * x a ** b (* BOM32_* ` `` _ __ | (breaks rule 1)

  • || (breaks rule 3)

  • “*” ‘|’ (*) [*] {*} <*> ‘*’ ‚*‘ ‘*‚ ’*’ ‚*’ “*” „*“ “*„ ”*” „*” »*« ›*‹ «*» »*» ›*› (breaks rule 5)

  • 2*x a**b O(N**2) e**(x*y) f(x)*f(y) a|b file*.* __init__ __init__() (breaks rule 6)

以下内联标记示例中不需要转义:

  • *2 * x  *a **b *.txt* (breaks rule 2; renders as “2 * x *a **b *.txt”)

  • *2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)* (breaks rule 7; renders as “2*x a**b O(N**2) e**(x*y) f(x)*f(y) a*(1+2)”)

It may be desirable to use inline literals for some of these anyhow, especially if they represent code snippets. It’s a judgment call.

The following terms do require either literal-quoting or escaping to avoid misinterpretation:

*4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt

In most use cases, inline literals or literal blocks are the best choice (by default, this also selects a monospaced font). Alternatively, the inline markup characters can be escaped:

\*4, class\_, \*args, \**kwargs, \`TeX-quoted', \*ML, \*.txt

For languages that don’t use whitespace between words (e.g. Japanese or Chinese) it is recommended to set simple-inline-markup to True and eventually escape inline markup characters. The examples breaking rules 6 and 7 above show which constructs may need special attention.

认可令

Inline markup delimiter characters are used for multiple constructs, so to avoid ambiguity there must be a specific recognition order for each character. The inline markup recognition order is as follows:

字符级内联标记

It is possible to mark up individual characters within a word with backslash escapes (see Escaping Mechanism above). Backslash escapes can be used to allow arbitrary text to immediately follow inline markup:

Python ``list``\s use square bracket syntax.

The backslash will disappear from the processed document. The word “list” will appear as inline literal text, and the letter “s” will immediately follow it as normal text, with no space in-between.

Arbitrary text may immediately precede inline markup using backslash-escaped whitespace:

Possible in *re*\ ``Structured``\ *Text*, though not encouraged.

The backslashes and spaces separating “re”, “Structured”, and “Text” above will disappear from the processed document.

警告

The use of backslash-escapes for character-level inline markup is not encouraged. Such use is ugly and detrimental to the unprocessed document’s readability. Please use this feature sparingly and only where absolutely necessary.

重点

Doctree 元素: emphasis.

Start-string = end-string = “*”.

Text enclosed by single asterisk characters is emphasized:

This is *emphasized text*.

Emphasized text is typically displayed in italics.

强烈的重点

Doctree 元素: strong.

Start-string = end-string = “**”.

Text enclosed by double-asterisks is emphasized strongly:

This is **strong text**.

Strongly emphasized text is typically displayed in boldface.

口译文本

Doctree 元素: depends on the explicit or implicit role and processing.

Start-string = end-string = “`”.

Interpreted text is text that is meant to be related, indexed, linked, summarized, or otherwise processed, but the text itself is typically left alone. Interpreted text is enclosed by single backquote characters:

This is `interpreted text`.

The “role” of the interpreted text determines how the text is interpreted. The role may be inferred implicitly (as above; the “default role” is used) or indicated explicitly, using a role marker. A role marker consists of a colon, the role name, and another colon. 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. A role marker is either a prefix or a suffix to the interpreted text, whichever reads better; it’s up to the author:

:role:`interpreted text`

`interpreted text`:role:

Interpreted text allows extensions to the available inline descriptive markup constructs. To emphasis, strong emphasis, inline literals, and hyperlink references, we can add “title reference”, “index entry”, “acronym”, “class”, “red”, “blinking” or anything else we want. Only pre-determined roles are recognized; unknown roles will generate errors. A core set of standard roles is implemented in the reference parser; see reStructuredText Interpreted Text Roles for individual descriptions. The role directive can be used to define custom interpreted text roles. In addition, applications may support specialized roles.

In field lists, care must be taken when using interpreted text with explicit roles in field names: the role must be a suffix to the interpreted text. The following are recognized as field list items:

:`field name`:code:: interpreted text with explicit role as suffix

:a `complex`:code:\  field name: a backslash-escaped space
                                 is necessary

The following are not recognized as field list items:

::code:`not a field name`: paragraph with interpreted text

:code:`not a field name`: paragraph with interpreted text

边缘情况:

:field\:`name`: interpreted text (standard role) requires
                escaping the leading colon in a field name

:field:\`name`: not interpreted text

内联文字

Doctree 元素: literal.

Start-string = end-string = “``”.

双引号括起来的文本被视为内联文字:

This text is an example of ``inline literals``.

Inline literals may contain any characters except two adjacent backquotes in an end-string context (according to the recognition rules above). No markup interpretation (including backslash-escape interpretation) is done within inline literals.

Line breaks are not preserved in inline literals. Although a reStructuredText parser will preserve runs of spaces in its output, the final representation of the processed document is dependent on the output formatter, thus the preservation of whitespace cannot be guaranteed. If the preservation of line breaks and/or other whitespace is important, literal blocks should be used.

Inline literals are useful for short code snippets. For example:

The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches
floating-point numbers (without exponents).

内联内部目标

Doctree 元素: target.

Start-string = “_`”, end-string = “`”.

Inline internal targets are the equivalent of explicit internal hyperlink targets, but may appear within running text. The syntax begins with an underscore and a backquote, is followed by a hyperlink name or phrase, and ends with a backquote. Inline internal targets may not be anonymous.

For example, the following paragraph contains a hyperlink target named “Norwegian Blue”:

Oh yes, the _`Norwegian Blue`.  What's, um, what's wrong with it?

See Implicit Hyperlink Targets for the resolution of duplicate reference names.

脚注参考

另请参阅: Footnotes

Doctree 元素: footnote_reference.

Configuration settings: footnote_references, trim_footnote_reference_space.

Start-string = “[“, end-string = “]_”.

Each footnote reference consists of a square-bracketed label followed by a trailing underscore. Footnote labels are one of:

例如:

Please RTFM [1]_.

.. [1] Read The Fine Manual

Inline markup recognition rules may require whitespace in front of the footnote reference. To remove the whitespace from the output, use an escaped whitespace character (see Escaping Mechanism) or set the trim_footnote_reference_space configuration setting. Leading whitespace is removed by default, if the footnote_references setting is “superscript”.

引文参考文献

另请参阅: Citations

Doctree 元素: citation_reference.

Start-string = “[“, end-string = “]_”.

Each citation reference consists of a square-bracketed label followed by a trailing underscore. Citation labels are simple reference names (case-insensitive single words, consisting of alphanumerics plus internal hyphens, underscores, and periods; no whitespace).

例如:

Here is a citation reference: [CIT2002]_.

替代参考文献

Doctree 元素: substitution_reference, reference.

Start-string = “|”, end-string = “|” (optionally followed by “_” or “__”).

Vertical bars are used to bracket the substitution reference text. A substitution reference may also be a hyperlink reference by appending a “_” (named) or “__” (anonymous) suffix; the substitution text is used for the reference text in the named case.

The processing system replaces substitution references with the processed contents of the corresponding substitution definitions (which see for the definition of “correspond”). Substitution definitions produce inline-compatible elements.

例子:

This is a simple |substitution reference|.  It will be replaced by
the processing system.

This is a combination |substitution and hyperlink reference|_.  In
addition to being replaced, the replacement text or element will
refer to the "substitution and hyperlink reference" target.

单位

(Docutils 0.3.10中的新功能。)

All measures consist of a positive floating point number in standard (non-scientific) notation and a unit, possibly separated by one or more spaces.

Units are only supported where explicitly mentioned in the reference manuals.

长度单位

reStructuredText解析器支持以下长度单位:

  • em (em unit, the element’s font size)

  • ex (ex unit, x-height of the element’s font)

  • mm (millimeters; 1Â mm = 1/1000Â m)

  • cm (centimeters; 1Â cm = 10Â mm)

  • in (inches; 1Â in = 2.54Â cm = 96Â px)

  • px (pixels, 1Â px = 1/96Â in) 17

  • pt (points; 1Â pt = 1/72Â in)

  • pc (picas; 1Â pc = 1/6Â in = 12Â pt)

This set corresponds to the length units in CSS2 (a subset of length units in CSS3).

17

In LaTeX, the default definition is 1Â px = 1/72Â in (cf. How to configure the size of a pixel in the LaTeX writer documentation).

以下是所有有效长度值: “1.5em”, “20 mm”, “.5in”.

Length values without unit are completed with a writer-dependent default (e.g. “px” with HTML, “pt” with latex2e). See the writer specific documentation in the user doc for details.

百分比单位

百分比值使用百分号 (“%”) 作为单位。 百分比值相对于其他值，具体取决于它们出现的上下文。

错误处理

Doctree 元素: system_message, problematic.

标记错误根据 PEP 258 中的规范进行处理。