指令

作者

David Goodger

Contact

docutils-develop@lists.sourceforge.net

调整

$Revision: 8186 $

Date

$Date: 2017-10-17 15:32:24 +0200 (Di, 17. Okt 2017) $

版权

本文档已置于公共领域。

本文档描述了参考reStructuredText解析器中实现的指令。

指令具有以下语法:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

Directives begin with an explicit markup start (two periods and a space), followed by the directive type and two colons (collectively, the “directive marker”). The directive block begins immediately after the directive marker, and includes all subsequent indented lines. The directive block is divided into arguments, options (a field list), and content (in that order), any of which may appear. See the Directives section in the reStructuredText Markup Specification for syntax details.

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

忠告

具体的警告

指令类型

“attention”, “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, “warning”, “admonition”

Doctree元素

attention, caution, danger, error, hint, important, note, tip, warning, admonition, title

指令参数

没有。

指令选项

:class:, :name:

指令内容

解释为身体元素。

Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. For example:

.. DANGER::
   Beware killer rabbits!

该指令可能会像这样呈现:

+------------------------+
|        !DANGER!        |
|                        |
| Beware killer rabbits! |
+------------------------+

已实施以下警告指令:

  • attention

  • caution

  • danger

  • error

  • hint

  • important

  • note

  • tip

  • warning

Any text immediately following the directive indicator (on the same line and/or indented on following lines) is interpreted as a directive block and is parsed for normal body elements. For example, the following “note” admonition directive contains one paragraph and a bullet list consisting of two list items:

.. note:: This is a note admonition.
   This is the second line of the first paragraph.

   - The note contains all indented body elements
     following.
   - It includes this bullet list.

Generic Admonition

指令类型

“admonition”

Doctree元素

admonition, title

指令参数

One, required (admonition title)

指令选项

Possible, see below.

指令内容

解释为身体元素。

This is a generic, titled admonition. The title may be anything the author desires.

The author-supplied title is also used as a “classes” attribute value after being converted into a valid identifier form (down-cased; non-alphanumeric characters converted to single hyphens; “admonition-” prefixed). For example, this admonition:

.. admonition:: And, by the way...

   You can make up your own admonition too.

becomes the following document tree (pseudo-XML):

<document source="test data">
    <admonition classes="admonition-and-by-the-way">
        <title>
            And, by the way...
        <paragraph>
            You can make up your own admonition too.

The common options are recognized:

classtext

Overrides the computed “classes” attribute value.

nametext

Add text to the “names” attribute of the admonition element.

图片

有两个图像指令: “image” 和 “figure”.

图片

指令类型

“image”

Doctree元素

image

指令参数

One, required (image URI).

指令选项

可能。

指令内容

没有。

An “image” is a simple picture:

.. image:: picture.png

Inline images can be defined with an “image” directive in a substitution definition

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

Optionally, the image link block may contain a flat field list, the image options. For example:

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right

可识别以下选项:

alttext

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

height长度

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

width : 当前行宽的 length 或 percentage当前行宽的长度或百分比

图像的宽度。用于保留空间或水平缩放图像。与上面的 “height” 一样, 当还指定了 “scale” 选项时, 它们会被组合在一起。

scaleinteger percentage (the “%” symbol is optional)

The uniform scaling factor of the image. The default is “100聽%”, i.e. no scaling.

If no “height” or “width” options are specified, the Python Imaging Library (PIL) may be used to determine them, if it is installed and the image file is available.

align“top”, “middle”, “bottom”, “left”, “center”, or “right”

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

targettext (URI or reference name)

Makes the image into a hyperlink reference (“clickable”). The option argument may be a URI (relative or absolute), or a reference name with underscore suffix (e.g. `a name`_).

和共有选项 :class: 和 :name:.

Figure

指令类型

“figure”

Doctree元素

figure, image, caption, legend

指令参数

One, required (image URI).

指令选项

可能。

指令内容

Interpreted as the figure caption and an optional legend.

A “figure” consists of image data (including image options), an optional caption (a single paragraph), and an optional legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps the page layout.

.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

   The legend consists of all elements after the caption.  In this
   case, the legend consists of this paragraph and the following
   table:

   +-----------------------+-----------------------+
   | Symbol                | Meaning               |
   +=======================+=======================+
   | .. image:: tent.png   | Campground            |
   +-----------------------+-----------------------+
   | .. image:: waves.png  | Lake                  |
   +-----------------------+-----------------------+
   | .. image:: peak.png   | Mountain              |
   +-----------------------+-----------------------+

There must be blank lines before the caption paragraph and before the legend. To specify a legend without a caption, use an empty comment (“..”) in place of the caption.

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

align“left”, “center”, or “right”

The horizontal alignment of the figure, allowing the image to float and have the text flow around it. The specific behavior depends upon the browser or rendering software used.

In addition, the following options are recognized:

figwidth“image”, length, or percentage of current line width

The width of the figure. Limits the horizontal space used by the figure. A special value of “image” is allowed, in which case the included image’s actual width is used (requires the Python Imaging Library). If the image file is not found or the required software is unavailable, this option is ignored.

Sets the “width” attribute of the “figure” doctree element.

This option does not scale the included image; use the “width” image option for that.

+---------------------------+
|        figure             |
|                           |
|<------ figwidth --------->|
|                           |
|  +---------------------+  |
|  |     image           |  |
|  |                     |  |
|  |<--- width --------->|  |
|  +---------------------+  |
|                           |
|The figure's caption should|
|wrap at this width.        |
+---------------------------+
figclasstext

Set a “classes” attribute value on the figure element. See the class directive below.

正文元素

话题

指令类型

“topic”

Doctree元素

topic

指令参数

一, 必需(主题标题)。

指令选项

:class:, :name:

指令内容

解释为主题正文。

主题就像带有标题的块引用，或者没有子部分的自包含部分。 使用 “topic” 指令指示独立于文档流的独立构思。 主题可能出现在可能发生部分或转换的任何地方。 正文元素和主题可能不包含嵌套主题。

该指令的唯一参数被解释为主题标题;下一行必须为空白。 所有后续行构成主题主体，解释为主体元素。 例如:

.. topic:: Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.

线块

弃用

不推荐使用 “line-block” 指令。请改用 line block syntax 。

指令类型

“line-block”

Doctree元素

line_block

指令参数

没有。

指令选项

:class:, :name:

指令内容

成为行块的主体。

“line-block ”指令构造一个元素，其中换行符和初始缩进很重要，并且支持内联标记。 它相当于具有不同渲染的`解析文字​​块`_：通常在普通的衬线字体而不是打字机/等宽字体，而不是自动缩进。 (让行块指令开始一个块引用以获得一个缩进的行块。) 行块对于地址块和诗歌（诗歌，歌词）很有用，其中行的结构很重要。 例如，这是一个经典之作:

"To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
Ewan McTeagle (for Lassie O'Shea):

    .. line-block::

        Lend us a couple of bob till Thursday.
        I'm absolutely skint.
        But I'm expecting a postal order and I can pay you back
            as soon as it comes.
        Love, Ewan.

解析文字块

指令类型

“parsed-literal”

Doctree元素

literal_block

指令参数

没有。

指令选项

:class:, :name:

指令内容

成为字面块的主体。

与普通的文字块不同， “parsed-literal” 指令构造一个文字块，其中文本被解析为内联标记。 它相当于具有不同渲染的`line block`_：通常在打字机/等宽字体中，就像普通的文字块一样。 解析的文字块对于向代码示例添加超链接非常有用。

但是，必须注意文本，因为内联标记已被识别，并且没有解析保护。 可能需要使用反斜杠转义来防止意外解析。 并且因为解析器删除了标记字符，所以还必须注意垂直对齐。 解析 “ASCII art” 是棘手的，可能需要额外的空格。

例如，此内容模型中的所有元素名称都是链接:

.. parsed-literal::

   ( (title_, subtitle_?)?,
     decoration_?,
     (docinfo_, transition_?)?,
     `%structure.model;`_ )

码

指令类型

“code”

Doctree元素

literal_block, inline elements

指令参数

One, optional (formal language).

指令选项

name, class, number-lines.

指令内容

成为字面块的主体。

配置设置

syntax_highlight.

(Docutils 0.9中的新功能)

The “code” directive constructs a literal block. If the code language is specified, the content is parsed by the Pygments syntax highlighter and tokens are stored in nested inline elements with class arguments according to their syntactic category. The actual highlighting requires a style-sheet (e.g. one generated by Pygments, see the sandbox/stylesheets for examples).

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

For inline code, use the “code” role.

可识别以下选项:

number-lines[start line number]

Precede every line with a line number. The optional argument is the number of the first line (defaut 1).

和共有选项 :class: 和 :name:.

例:

以下指令的内容:

.. code:: python

  def my_function():
      "just a test"
      print 8/2

被解析并标记为Python源代码。

Math

指令类型

“math”

Doctree元素

math_block

指令参数

没有。

指令选项

:class:, :name:

指令内容

Becomes the body of the math block. (Content blocks separated by a blank line are put in adjacent math blocks.)

配置设置

math_output

(New in Docutils 0.8)

The “math” directive inserts blocks with mathematical content (display formulas, equations) into the document. The input format is LaTeX math syntax1 with support for Unicode symbols, for example:

.. math::

  伪_t(i) = P(O_1, O_2, 鈥� O_t, q_t = S_i 位)

Support is limited to a subset of LaTeX math by the conversion required for many output formats. For HTML, the math_output configuration setting (or the corresponding --math-output command line option) select between alternative output formats with different subsets of supported elements. If a writer does not support math typesetting at all, the content is inserted verbatim.

1

The supported LaTeX commands include AMS extensions (see, e.g., the Short Math Guide).

For inline formulas, use the “math” role.

Rubric

指令类型

“rubric”

Doctree元素

rubric

指令参数

One, required (rubric text).

指令选项

:class:, :name:

指令内容

没有。

rubric n. 1. a title, heading, or the like, in a manuscript, book, statute, etc., written or printed in red or otherwise distinguished from the rest of the text. …

—Random House Webster’s College Dictionary, 1991

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.

Epigraph

指令类型

“epigraph”

Doctree元素

block_quote

指令参数

没有。

指令选项

没有。

指令内容

Interpreted as the body of the block quote.

An epigraph is an apposite (suitable, apt, or pertinent) short inscription, often a quotation or poem, at the beginning of a document or section.

The “epigraph” directive produces an “epigraph”-class block quote. For example, this input:

.. epigraph::

   No matter where you go, there you are.

   -- Buckaroo Banzai

becomes this document tree fragment:

<block_quote classes="epigraph">
    <paragraph>
        No matter where you go, there you are.
    <attribution>
        Buckaroo Banzai

Highlights

指令类型

“highlights”

Doctree元素

block_quote

指令参数

没有。

指令选项

没有。

指令内容

Interpreted as the body of the block quote.

Highlights summarize the main points of a document or section, often consisting of a list.

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

Pull-Quote

指令类型

“pull-quote”

Doctree元素

block_quote

指令参数

没有。

指令选项

没有。

指令内容

Interpreted as the body of the block quote.

A pull-quote is a small selection of text “pulled out and quoted”, typically in a larger typeface. Pull-quotes are used to attract attention, especially in long articles.

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

复合段落

指令类型

“compound”

Doctree元素

compound

指令参数

没有。

指令选项

:class:, :name:

指令内容

解释为身体元素。

(Docutils 0.3.6中的新功能)

The “compound” directive is used to create a compound paragraph, which is a single logical paragraph containing multiple physical body elements such as simple paragraphs, literal blocks, tables, lists, etc., instead of directly containing text and inline elements. For example:

.. compound::

   The 'rm' command is very dangerous.  If you are logged
   in as root and enter ::

       cd /
       rm -rf *

   you will erase the entire contents of your file system.

In the example above, a literal block is “embedded” within a sentence that begins in one physical paragraph and ends in another.

注解

The “compound” directive is not a generic block-level container like HTML’s <div> element. Do not use it only to group a sequence of elements, or you may get unexpected results.

If you need a generic block-level container, please use the container directive, described below.

Compound paragraphs are typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity:

  • If paragraphs are rendered with a first-line indent, only the first physical paragraph of a compound paragraph should have that indent – second and further physical paragraphs should omit the indents;

  • vertical spacing between physical elements may be reduced;

  • 等等。

Container

指令类型

“container”

Doctree元素

container

指令参数

一个或多个，可选（类名）。

指令选项

:name:

指令内容

解释为身体元素。

(Docutils 0.3.10中的新功能)

The “container” directive surrounds its contents (arbitrary body elements) with a generic block-level “container” element. Combined with the optional “classes” attribute argument(s), this is an extension mechanism for users & applications. For example:

.. container:: custom

   This paragraph might be rendered in a custom way.

解析上述结果会产生以下 pseudo-XML:

<container classes="custom">
    <paragraph>
        This paragraph might be rendered in a custom way.

The “container” directive is the equivalent of HTML’s <div> element. It may be used to group a sequence of elements for user- or application-specific purposes.

表格

正式表需要比 reStructuredText 语法提供的结构更多的结构。表可以使用 table 指令给出标题。有时reStructuredText 表不便于编写, 或者标准格式的表数据随时可用。 csv-table 指令支持CSV数据。

表格

指令类型

“table”

Doctree元素

table

指令参数

一, 可选(表格标题)。

指令选项

可能(见下文)。

指令内容

一个普通的reStructuredText表。

(Docutils 0.3.1中的新功能)

“table” 指令用于将标题与表关联或指定选项, 例如:

.. table:: Truth table for "not"
   :widths: auto

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

可识别以下选项:

align“left”, “center”, or “right”

表格的水平对齐方式。 (Docutils 0.13中的新功能)

widths“auto”, “grid” 或整数列表

以逗号或空格分隔的列宽列表。默认值是输入列的宽度(以字符为单位)。

作者可以使用特殊值 “auto” 或 “grid” 来决定是否将列宽的确定委托给后端(LaTeX, HTML浏览器……)。 另请参阅 table_style 配置选项。

width : 当前行宽的 length 或 percentage当前行宽的长度或百分比

强制表格的宽度为指定的长度或线宽的百分比。 如果省略, 则渲染器将根据其内容确定表的宽度。

和共有选项 :class: 和 :name:.

CSV表

指令类型

“csv-table”

Doctree元素

table

指令参数

一, 可选(表格标题)。

指令选项

可能(见下文)。

指令内容

CSV(逗号分隔值)表。

警告

“csv-table” 指令的 “:file:” 和 “:url:” 选项代表潜在的安全漏洞。可以使用 “file_insertion_enabled” 运行时设置禁用它们。

(Docutils 0.3.4中的新功能)

“csv-table” 指令用于从CSV(逗号分隔值)数据创建表。CSV是电子表格应用程序和商业数据库生成的常见数据格式。数据可以是内部(文档的组成部分)或外部(单独的文件)。

例:

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

支持单元格内的块标记和内联标记。线端在单元内被识别。

工作限制:

  • 不支持检查每行中的列数是否相同。但是, 此指令支持CSV生成器, 它不会在短行的末尾插入 “empty” 条目, 方法是自动添加空条目。

2

仅支持外部CSV文件的空白分隔符。

3(1,2,3)

对于Python2, delimiter, quote 和 escape 选项的值必须是ASCII字符。(csv模块不支持Unicode, 所有非ASCII字符都编码为多字节utf-8字符串). Python3下不存在此限制。

可识别以下选项:

widths整数 [, integer…] 要么 “auto”

以逗号或空格分隔的相对列宽列表。默认值为等宽列(100%/#columns)。

作者可以使用特殊值 “auto” 来决定是否将列宽的确定委托给后端(LaTeX, HTML浏览器……)。

width : 当前行宽的 length 或 percentage当前行宽的长度或百分比

强制表格的宽度为指定的长度或线宽的百分比。 如果省略, 则渲染器将根据其内容确定表的宽度。

header-rows整数

要在表标头中使用的CSV数据的行数。默认为0。

stub-columns整数

要用作存根的表列数(左侧的行标题)。 默认为0。

headerCSV数据

表头的补充数据, 独立于主CSV数据的“header-rows”之前和之前添加。 必须使用与主CSV数据相同的CSV格式。

file字符串(删除换行符)

CSV数据文件的本地文件系统路径。

url字符串(删除了空格)

对CSV数据文件的Internet URL引用。

encoding文本编码的名称

外部CSV数据(文件或URL)的文本编码。默认为文档的编码(如果指定)。

delimchar | “tab” | “space” 2

单字符串[#ASCII-char] _用于分隔字段。 默认为``, ``(逗号)。 可以指定为Unicode代码点;有关语法详细信息, 请参阅unicode_指令。

quotechar

单字符串3 用于引用包含分隔符或以引号字符开头的元素。 默认为 " (引用)。 可以指定为Unicode代码点;有关语法详细信息, 请参阅 unicode 指令。

keepspace旗

立即将分隔符后面的空格视为重要空格。 默认是忽略这样的空格。

escapechar

用于转义分隔符或引用字符的单字符3 字符串。 可以指定为Unicode代码点;有关语法详细信息, 请参阅 unicode 指令。 在分隔符用于不带引号的字段时, 或者在字段中使用引号字符时使用。 默认设置是将字符加倍, 例如 “He said, “”Hi!”“”

align“left”, “center”, or “right”

表格的水平对齐方式。 (Docutils 0.13中的新功能)

和共有选项 :class: 和 :name:.

列表

指令类型

“list-table”

Doctree元素

table

指令参数

一, 可选(表格标题)。

指令选项

可能(见下文)。

指令内容

统一的两级子弹列表。

(Docutils 0.3.8中的新内容。这是初始实施; further ideas 可能在未来实施。)

“list-table” 指令用于根据统一的两级项目符号列表中的数据创建表。 “Uniform” 表示每个子列表(第二级列表)必须包含相同数量的列表项。

例:

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

可识别以下选项:

widths整数 [integer…] 要么 “auto”

以逗号或空格分隔的相对列宽列表。默认值为等宽列(100%/#columns)。

作者可以使用特殊值 “auto” 来决定是否将列宽的确定委托给后端(LaTeX, HTML浏览器……)。

width : 当前行宽的 length 或 percentage当前行宽的长度或百分比

强制表格的宽度为指定的长度或线宽的百分比。 如果省略, 则渲染器将根据其内容确定表的宽度。

header-rows整数

要在表头中使用的列表数据的行数。默认为0。

stub-columns整数

要用作存根的表列数(左侧的行标题)。 默认为0。

align“left”, “center”, or “right”

表格的水平对齐方式。 (Docutils 0.13中的新功能)

和共有选项 :class: 和 :name:.

文档部分

目录

指令类型

“内容”

Doctree元素

pending, topic

指令参数

一, 可选:标题。

指令选项

可能。

指令内容

没有。

The “contents” directive generates a table of contents (TOC) in a topic. Topics, and therefore tables of contents, may occur anywhere a section or transition may occur. Body elements and topics may not contain tables of contents.

这是最简单形式的指令:

.. contents::

Language-dependent boilerplate text will be used for the title. The English default title text is “Contents”.

An explicit title may be specified:

.. contents:: Table of Contents

标题可能跨越线，但不建议使用:

.. contents:: Here's a very long Table of
   Contents title

可以使用字段列表为指令指定选项:

.. contents:: Table of Contents
   :depth: 2

If the default title is to be used, the options field list may begin on the same line as the directive marker:

.. contents:: :depth: 2

可识别以下选项:

depth整数

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

local旗（空）

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

backlinks“entry” or “top” or “none”

Generate links from section headers back to the table of contents entries, the table of contents itself, or generate no backlinks.

classtext

Set a “classes” attribute value on the topic element. See the class directive below.

自动章节编号

指令类型

“sectnum” or “section-numbering” (synonyms)

Doctree元素

pending, generated

指令参数

没有。

指令选项

可能。

指令内容

没有。

配置设置

sectnum_xform

The “sectnum” (or “section-numbering”) directive automatically numbers sections and subsections in a document (if not disabled by the --no-section-numbering command line option or the sectnum_xform configuration setting).

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

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

可识别以下选项:

depth整数

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

prefixstring

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

suffixstring

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

start整数

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

参考

目标脚注

指令类型

“target-notes”

Doctree元素

pending, footnote, footnote_reference

指令参数

没有。

指令选项

:class:, :name:

指令选项

可能。

指令内容

没有。

The “target-notes” directive creates a footnote for each external target in the text, and corresponding footnote references after each reference. For every explicit target (of the form, .. _target name: URL) in the text, a footnote will be generated containing the visible URL as content.

Footnotes

NOT IMPLEMENTED YET

指令类型

“footnotes”

Doctree元素

pending, topic

指令参数

None?

指令选项

可能?

指令内容

没有。

@@@

Citations

NOT IMPLEMENTED YET

指令类型

“citations”

Doctree元素

pending, topic

指令参数

None?

指令选项

可能?

指令内容

没有。

@@@

HTML专用

Meta

指令类型

“meta”

Doctree元素

meta (non-standard)

指令参数

没有。

指令选项

没有。

指令内容

Must contain a flat field list.

The “meta” directive is used to specify HTML metadata stored in HTML META tags. “Metadata” is data about data, in this case data about web pages. Metadata is used to describe and classify web pages in the World Wide Web, in a form that is easy for search engines to extract and collate.

Within the directive block, a flat field list provides the syntax for metadata. The field name becomes the contents of the “name” attribute of the META tag, and the field body (interpreted as a single string without inline markup) becomes the contents of the “content” attribute. For example:

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

This would be converted to the following HTML:

<meta name="description"
    content="The reStructuredText plaintext markup language">
<meta name="keywords" content="plaintext, markup language">

Support for other META attributes (“http-equiv”, “scheme”, “lang”, “dir”) are provided through field arguments, which must be of the form “attr=value”:

.. meta::
   :description lang=en: An amusing story
   :description lang=fr: Une histoire amusante

And their HTML equivalents:

<meta name="description" lang="en" content="An amusing story">
<meta name="description" lang="fr" content="Une histoire amusante">

Some META tags use an “http-equiv” attribute instead of the “name” attribute. To specify “http-equiv” META tags, simply omit the name:

.. meta::
   :http-equiv=Content-Type: text/html; charset=ISO-8859-1

HTML equivalent:

<meta http-equiv="Content-Type"
     content="text/html; charset=ISO-8859-1">

Imagemap

NOT IMPLEMENTED YET

Non-standard element: imagemap.

替代定义指令

The directives in this section may only be used in substitution definitions. They may not be used directly, in standalone context. The image directive may be used both in substitution definitions and in the standalone context.

Replacement Text

指令类型

“replace”

Doctree元素

Text & inline elements

指令参数

没有。

指令选项

没有。

指令内容

A single paragraph; may contain inline markup.

The “replace” directive is used to indicate replacement text for a substitution reference. It may be used within substitution definitions only. For example, this directive can be used to expand abbreviations:

.. |reST| replace:: reStructuredText

Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.

As reStructuredText doesn’t support nested inline markup, the only way to create a reference with styled text is to use substitutions with the “replace” directive:

I recommend you try |Python|_.

.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/

Unicode Character Codes

指令类型

“unicode”

Doctree元素

Text

指令参数

One or more, required (Unicode character codes, optional text, and comments).

指令选项

可能。

指令内容

没有。

The “unicode” directive converts Unicode character codes (numerical values) to characters, and may be used in substitution definitions only.

The arguments, separated by spaces, can be:

  • character codes as

    • decimal numbers or

    • hexadecimal numbers, prefixed by 0x, x, \x, U+, u, or \u or as XML-style hexadecimal character entities, e.g. &#x1a2b;

  • text, which is used as-is.

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

For example, the following text:

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

.. |copy| unicode:: 0xA9 .. copyright sign
.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
   .. with trademark sign
.. |---| unicode:: U+02014 .. em dash
   :trim:

results in:

Copyright © 2003, BogusMegaCorp™—all rights reserved.

可识别以下选项:

ltrim旗

Whitespace to the left of the substitution reference is removed.

rtrim旗

Whitespace to the right of the substitution reference is removed.

trim旗

Equivalent to ltrim plus rtrim; whitespace on both sides of the substitution reference is removed.

Date

指令类型

“date”

Doctree元素

Text

指令参数

One, optional (date format).

指令选项

没有。

指令内容

没有。

The “date” directive generates the current local date and inserts it into the document as text. This directive may be used in substitution definitions only.

The optional directive content is interpreted as the desired date format, using the same codes as Python’s time.strftime function. The default format is “%Y-%m-%d” (ISO 8601 date), but time fields can also be used. Examples:

.. |date| date::
.. |time| date:: %H:%M

Today's date is |date|.

This document was generated on |date| at |time|.

杂

包括外部文档片段

指令类型

“include”

Doctree元素

Depend on data being included (literal_block with code or literal option).

指令参数

One, required (path to the file to include).

指令选项

可能。

指令内容

没有。

配置设置

file_insertion_enabled

警告

The “include” directive represents a potential security hole. It can be disabled with the “file_insertion_enabled” runtime setting.

The “include” directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. Unless the options literal or code are given, the file is parsed in the current document’s context at the point of the directive. For example:

This first example will be parsed at the document level, and can
thus contain any construct, including section headers.

.. include:: inclusion.txt

Back in the main document.

    This second example will be parsed in a block quote context.
    Therefore it may only contain body elements.  It may not
    contain section headers.

    .. include:: inclusion.txt

If an included document fragment contains section structure, the title adornments must match those of the master document.

Standard data files intended for inclusion in reStructuredText documents are distributed with the Docutils source code, located in the “docutils” package in the docutils/parsers/rst/include directory. To access these files, use the special syntax for standard “include” data files, angle brackets around the file name:

.. include:: <isonum.txt>

The current set of standard “include” data files consists of sets of substitution definitions. See reStructuredText Standard Definition Files for details.

可识别以下选项:

start-line整数

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

end-line整数

Only the content up to (but excluding) this line will be included.

start-aftertext to find in the external data file

Only the content after the first occurrence of the specified text will be included.

end-beforetext to find in the external data file

Only the content before the first occurrence of the specified text (but after any after text) will be included.

literal旗（空）

The entire included text is inserted into the document as a single literal block.

codeformal language (optional)

The argument and the content of the included file are passed to the code directive (useful for program listings). (New in Docutils 0.9)

number-lines[start line number]

Precede every code line with a line number. The optional argument is the number of the first line (defaut 1). Works only with code or literal. (New in Docutils 0.9)

encoding文本编码的名称

The text encoding of the external data file. Defaults to the document’s input_encoding.

tab-width整数

Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the tab_width configuration setting.

With code or literal the common options :class: and :name: are recognized as well.

Combining start/end-line and start-after/end-before is possible. The text markers will be searched in the specified lines (further limiting the included content).

Raw Data Pass-Through

指令类型

“raw”

Doctree元素

raw

指令参数

One or more, required (output format types).

指令选项

可能。

指令内容

Stored verbatim, uninterpreted. None (empty) if a “file” or “url” option given.

配置设置

raw_enabled

警告

The “raw” directive represents a potential security hole. It can be disabled with the “raw_enabled” or “file_insertion_enabled” runtime settings.

警告

The “raw” directive is a stop-gap measure allowing the author to bypass reStructuredText’s markup. It is a “power-user” feature that should not be overused or abused. The use of “raw” ties documents to specific output formats and makes them less portable.

If you often need to use the “raw” directive or a “raw”-derived interpreted text role, that is a sign either of overuse/abuse or that functionality may be missing from reStructuredText. Please describe your situation in a message to the Docutils-users mailing list.

The “raw” directive indicates non-reStructuredText data that is to be passed untouched to the Writer. The names of the output formats are given in the directive arguments. The interpretation of the raw data is up to the Writer. A Writer may ignore any raw output not matching its format.

For example, the following input would be passed untouched by an HTML Writer:

.. raw:: html

   <hr width=50 size=10>

A LaTeX Writer could insert the following raw content into its output stream:

.. raw:: latex

   \setlength{\parindent}{0pt}

Raw data can also be read from an external file, specified in a directive option. In this case, the content block must be empty. For example:

.. raw:: html
   :file: inclusion.html

Inline equivalents of the “raw” directive can be defined via custom interpreted text roles derived from the “raw” role.

可识别以下选项:

file字符串(删除换行符)

The local filesystem path of a raw data file to be included.

url字符串(删除了空格)

An Internet URL reference to a raw data file to be included.

encoding文本编码的名称

The text encoding of the external raw data (file or URL). Defaults to the document’s encoding (if specified).

Class

指令类型

“class”

Doctree元素

pending

指令参数

One or more, required (class names / attribute values).

指令选项

没有。

指令内容

Optional. If present, it is interpreted as body elements.

The “class” directive sets the “classes” attribute value on its content or on the first immediately following 4 non-comment element 5. For details of the “classes” attribute, see the classes entry in The Docutils Document Tree.

The directive argument consists of one or more space-separated class names. The names are transformed to conform to the regular expression [a-z](-?[a-z0-9]+)* by converting

  • alphabetic characters to lowercase,

  • accented characters to the base character,

  • non-alphanumeric characters to hyphens,

  • consecutive hyphens into one hyphen.

For example “Rot-Gelb.Blau Gr眉n:+2008” becomes “rot-gelb-blau grun-2008”. (For the rationale, see below.)

Examples:

.. class:: special

This is a "special" paragraph.

.. class:: exceptional remarkable

An Exceptional Section
======================

This is an ordinary paragraph.

.. class:: multiple

   First paragraph.

   Second paragraph.

The text above is parsed and transformed into this doctree fragment:

<paragraph classes="special">
    This is a "special" paragraph.
<section classes="exceptional remarkable">
    <title>
        An Exceptional Section
    <paragraph>
        This is an ordinary paragraph.
    <paragraph classes="multiple">
        First paragraph.
    <paragraph classes="multiple">
        Second paragraph.
4

This is also true, if the class directive is “nested” at the end of an indented text block, for example:

.. note:: the class values set in this directive-block do not apply to
   the note but the next paragraph.

   .. class:: special

This is a paragraph with class value "special".

This allows the “classification” of individual list items (except the first, as a preceding class directive applies to the list as a whole):

* bullet list

  .. class:: classy item

* second item, with class argument
5

To set a “classes” attribute value on a block quote, the “class” directive must be followed by an empty comment:

.. class:: highlights
..

    Block quote text.

Without the empty comment, the indented text would be interpreted as the “class” directive’s content, and the classes would be applied to each element (paragraph, in this case) individually, instead of to the block quote as a whole.

Rationale for “classes” Attribute Value Conversion

Docutils identifiers are converted to conform to the regular expression [a-z](-?[a-z0-9]+)*. For HTML + CSS compatibility, identifiers (the “classes” and “id” attributes) should have no underscores, colons, or periods. Hyphens may be used.

  • The HTML 4.01 spec defines identifiers based on SGML tokens:

    ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens (“-“), underscores (“_”), colons (“:”), and periods (“.”).

  • The CSS1 spec defines identifiers based on the “name” token (“flex” tokenizer notation below; “latin1” and “escape” 8-bit characters have been replaced with XML entities):

    unicode     \\[0-9a-f]{1,4}
latin1      [&iexcl;-&yuml;]
escape      {unicode}|\\[ -~&iexcl;-&yuml;]
nmchar      [-A-Za-z0-9]|{latin1}|{escape}
name        {nmchar}+

The CSS rule does not include underscores (“_”), colons (“:”), or periods (“.”), therefore “classes” and “id” attributes should not contain these characters. Combined with HTML’s requirements (the first character must be a letter; no “unicode”, “latin1”, or “escape” characters), this results in the regular expression [A-Za-z][-A-Za-z0-9]*. Docutils adds a normalisation by downcasing and merge of consecutive hyphens.

Custom Interpreted Text Roles

指令类型

“role”

Doctree元素

None; affects subsequent parsing.

指令参数

Two; one required (new role name), one optional (base role name, in parentheses).

指令选项

Possible (depends on base role).

指令内容

depends on base role.

(New in Docutils 0.3.2)

The “role” directive dynamically creates a custom interpreted text role and registers it with the parser. This means that after declaring a role like this:

.. role:: custom

the document may use the new “custom” role:

An example of using :custom:`interpreted text`

This will be parsed into the following document tree fragment:

<paragraph>
    An example of using
    <inline classes="custom">
        interpreted text

The role must be declared in a document before it can be used.

The new role may be based on an existing role, specified as a second argument in parentheses (whitespace optional):

.. role:: custom(emphasis)

:custom:`text`

The parsed result is as follows:

<paragraph>
    <emphasis classes="custom">
        text

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

.. role:: raw-role(raw)
   :format: html latex

:raw-role:`raw text`

If no base role is explicitly specified, a generic custom role is automatically used. Subsequent interpreted text will produce an “inline” element with a “classes” attribute, as in the first example above.

With most roles, the “:class:” option can be used to set a “classes” attribute that is different from the role name. For example:

.. role:: custom
   :class: special

:custom:`interpreted text`

This is the parsed result:

<paragraph>
    <inline classes="special">
        interpreted text

The following option is recognized by the “role” directive for most base roles:

classtext

Set the “classes” attribute value on the element produced (inline, or element associated with a base class) when the custom interpreted text role is used. If no directive options are specified, a “class” option with the directive argument (role name) as the value is implied. See the class directive above.

Specific base roles may support other options and/or directive content. See the reStructuredText Interpreted Text Roles document for details.

Setting the Default Interpreted Text Role

指令类型

“default-role”

Doctree元素

None; affects subsequent parsing.

指令参数

One, optional (new default role name).

指令选项

没有。

指令内容

没有。

(Docutils 0.3.10中的新功能)

The “default-role” directive sets the default interpreted text role, the role that is used for interpreted text without an explicit role. For example, after setting the default role like this:

.. default-role:: subscript

any subsequent use of implicit-role interpreted text in the document will use the “subscript” role:

An example of a `default` role.

This will be parsed into the following document tree fragment:

<paragraph>
    An example of a
    <subscript>
        default
     role.

Custom roles may be used (see the “role” directive above), but it must have been declared in a document before it can be set as the default role. See the reStructuredText Interpreted Text Roles document for details of built-in roles.

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

Metadata Document Title

指令类型

“title”

Doctree元素

没有。

指令参数

One, required (the title text).

指令选项

没有。

指令内容

没有。

The “title” directive specifies the document title as metadata, which does not become part of the document body. It overrides a document-supplied title. For example, in HTML output the metadata document title appears in the title bar of the browser window.

Restructuredtext-Test-Directive

指令类型

“restructuredtext-test-directive”

Doctree元素

system_warning

指令参数

没有。

指令选项

没有。

指令内容

Interpreted as a literal block.

This directive is provided for test purposes only. (Nobody is expected to type in a name that long!) It is converted into a level-1 (info) system message showing the directive data, possibly followed by a literal block containing the rest of the directive block.

常见选项

生成doctree元素的大多数指令都支持以下选项:

:class:text

在指令生成的doctree元素上设置 “classes” 属性值。另请参见 class 指令。

:name:text

将 text 添加到指令生成的doctree元素的 “names” 属性中。 这允许使用 text 作为 reference name 对元素进行超链接引用。

指定指令的 name 选项, 例如,

.. image:: bild.png
   :name: my picture

是一个简洁的语法替代它前面的 hyperlink target

.. _my picture:

.. image:: bild.png

Docutils 0.8中的新功能。