reStructuredText初级入门¶

reStructuredText是Sphinx使用的默认的纯文本标记语言。此部分简要介绍reStructuredText(reST)的概念和语法，目标是给文档创作者足够的知识，以高效地编写文档。由于reST被设计为简单、隐蔽的标记语言，所以不会用太长的篇幅。

参见

权威的 reStructuredText用户文档。本文档中的"ref"链接指向上述reStructuredText参考中对各个构造的描述。

段落¶

段落(ref)是reStructuredText文档中最基本的块。段落只是由一个或多个空行分隔的文本块。就像在 Python 中一样，缩进在reStructuredText中也是很重要的，所以同一段落的所有行必须左对齐到相同的缩进级别。

行内标记¶

标准的reStructuredText行内标记非常简单：使用

一个星号： *文本* 表示强调（斜体），
两个星号： **文本** 表示强强调（粗体），以及
反单引号： ``text`` 表示代码样例。

如果文本中的星号或者反单引号可能被混淆为行内标记分隔符，添加反斜杠转义即可。

注意，这些标记有些功能限制：

不能嵌套，
标记内的内容不能以空格开始或结束： * text* 就不行，
行内标记符号外只能是非文字字符。如果想要在行内标记符号外使用文字字符，使用反斜线转义空格来绕过限制：thisis\ *one*\ word 被呈现为 thisisoneword。

这些限制，在将来的 docutils 版本中可能会被取消。

也可以使用角色来替换或扩展一些行内标记。详参角色。

列表和引用类块(Quote-like blocks)¶

列表标记(ref)是自然的：只要在段落的开头加上星号并正确地缩进即可。编号列表也是如此；它们也可以使用 # 符号来自动编号:

* This is a bulleted list.
* It has two items, the second
  item uses two lines.

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

列表也可以嵌套，但注意它们必须通过空行与父列表项分开:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

定义列表（ref）创建如下：

term (up to a line of text)
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

next term
   Description.

请注意，定义'term'所在处，不能有多于一行的文本。

引用的段落(ref)通过比周围的段落多缩进一级即可创建。

line blocks(ref)是一种保留换行符的方法：

| These lines are
| broken exactly like in
| the source file.

还有几个特殊的块可用：

字段列表(ref，在字段列表中有说明)
选项列表(ref)
引用文字块(ref)
doctest块(ref)

Literal blocks¶

literal code block(ref)是通过在段落结束时使用特殊标记 :: 来引入的。文字块必须缩进（和所有段落一样，用空行隔开周围的段落）:

This is a normal text paragraph. The next paragraph is a code sample::

   It is not processed in any way, except
   that the indentation is removed.

   It can span multiple lines.

This is a normal text paragraph again.

:: 标记的处理很灵活：

如果它作为一个单独的段落出现，那么该段落将完全从文档中删除。
如果前面有空格，则删除该标记。
如果前面有非空格，则该标记将被单个冒号替换。

这样，上面示例的第一段的第二句话将被呈现为 "The next paragraph is a code sample:"。

在本文档范围内使用 highlight 指令，或者在项目范围内使用 highlight_language 配置选项，可以为literal block启用代码高亮。 code-block 指令可以用于以块为单位设置高亮显示。稍后将讨论这些指令。

doctest块¶

Doctest块(ref)是将交互式的Python会话剪切粘贴到文档字符串中。它们不需要 literal blocks 语法。doctest 块必须以空行结束，并且不以未使用的提示符结束:

>>> 1 + 1
2

表格¶

对于 grid tables (ref)，你必须自己"绘制"单元格网格。它们是这样的:

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

简单表格 （ref）更容易撰写，但有限制：它们必须包含不止一行，第一列单元格不能包含多行。如:

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

另外还支持两种语法: CSV表 和列表。它们使用显式标记块。参考表格获取更多信息。

超链接¶

外部链接¶

URL和电子邮件地址在文本中会被自动链接，根本不需要显式标记。例如，https://domain.invalid/ 在本文档的源文件中没有使用特殊标记，并被识别为外部超链接。

要创建带有链接的文本，通常最好的方法是将URL放在段落下面(ref)，如下所示:

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

这使得源代码中的段落更易读。

或者，你也可以在文章中嵌入URL来创建'行内链接'。这可能会导致行变长，但有一个好处是将链接文本和所指向的URL放在同一个地方。这使用以下语法： `Link text <https://domain.invalid/>`__ (ref)。

重要

链接文本和URL的左尖括号（'<'）之间必须有一个空格。

小技巧

嵌入URL时使用两个尾随下划线。技术上讲，单个下划线也可以，但那样会创建一个命名引用，而不是匿名引用。当URL被嵌入时，命名引用通常没有好处。此外，它们的缺点是你必须确保在文档中不为另一个链接使用相同的"链接文本"。

您也可以把链接和目标定义分开(ref)，就像这样:

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/

内部链接¶

Sphinx 提供了一种特殊的reStructuredText角色来完成内部链接，详见交叉引用任意位置。

章节¶

在章节标题的下一行添加英文标点符号做装饰，这样就创建了章节头 (ref) 。也可以同时在章节标题的上一行添加标点符号来创建，只是无论哪种方式，标点字符串的长度至少要和标题一样长:

=================
This is a heading
=================

通常，某些字符不会被分配标题级别，因为结构是由标题的连续性决定的。但是，在 Python 开发者指南之文档编制中使用了这种惯例，你可以遵循：

# 用于"部分(parts)" ，也可以加上上方的一行
* 用于"章(chapter)"，也可以加上上方的一行
= 用于"节(section)"
- 用于"小节(subsection)"
^ 用于"子小节(subsubsection)"
" 用于"段落(paragraph)"

当然，你可以自由使用自己的标记字符（参见reStructuredText文档），并使用更深的嵌套级别，但请记住，大多数目标格式（HTML，LaTeX）都只支持有限的嵌套深度。

字段列表¶

字段列表(ref)是这样标记的字段序列:

:fieldname: Field content

它们通常在Python文档中使用:

def my_function(my_arg, my_other_arg):
    """A function just for me.

    :param my_arg: The first of my arguments.
    :param my_other_arg: The second of my arguments.

    :returns: A message (just for me, of course).
    """

Sphinx扩展了标准的docutils行为，并截取文档开头指定的字段列表。请参考字段列表以获得更多信息。

角色¶

角色或"自定义解释文本角色"(ref)是行内的显式标记。它表示被包含的文本应以特定的方式进行解释。Sphinx 使用它来提供语义标记和标识符的交叉引用，如相应章节所述。一般语法是 :rolename:`content`。比如 :emphasis:`text` 会将 text 强调显示为 text。

Docutils支持以下角色：

emphasis-- 相当于 *text*
strong -- 相当于 **text**
literal -- 相当于 ``text``
subscript -- 下标文字
superscript -- 上标文字
title-reference -- 用于表示书名、期刊，以及其他的素材

有关 Sphinx 中添加的角色，可参考角色。

显式标记¶

"显式标记"(ref)用于reStructuredText中需特殊处理的大多数构造，比如脚注、特殊高亮段落、注释和通用指令。

显式标记块以一行开头，以 .. 开头，后跟空格，并在相同的缩进级别由下一段终止。 (显式标记和普通段落之间需要有一个空行。这可能听起来有点复杂，但是当你写它时它足够直观。)

指令¶

指令(ref)是通用的显式标记块。与角色一起，它是reStructuredText的扩展机制之一，Sphinx大量使用它。

Docutils支持以下指令：

警告：attention, caution, danger, error, hint, important, note, tip, warning 以及通用的 admonitions。(大多数主题仅对"note"和"warning"做特殊样式设计。)
图片：
- image (另见下方 Images)
- figure (带有标题和可选图例的图片)
附加构成元素：
- contents (本地，即仅是当前文件的目录)
- container (一个带有自定义类的容器，用于在HTML中生成外部 <div>)
- rubric (与文档切片无关的标题)
- topic, sidebar (突出显示的构成元素)
- parsed-literal (支持行内标记的文字块)
- epigraph (带有可选归因线的块引用)
- highlights, pull-quote (带有自己的类属性的块引号)
- compound paragraph (复合段)
特殊表格：
- table (带标题的表格)
- csv-table (从逗号分隔值生成的表)
- list-table (从列表列表生成的表)
特别指令：
- raw (包括原始目标格式标记)
- include (包含其它reStructuredText文件) -- 在Sphinx中，当给定一个绝对包含文件路径时，该指令将其作为相对于源目录的路径
- class (为下一个元素分配class属性)
  
  备注
  
  当默认域包含 class 指令时，该指令将被覆盖。因此，Sphinx 将其重新导出为 rst-class。
  
  小技巧
  
  如果你想为指令添加一个类，可以用 :class: option 替代，大多数指令都支持它，其表示起来更紧凑。
HTML特有的：
- meta (生成HTML <meta> 标签，另见下方的 HTML 元数据)
- title (覆盖文档标题)
影响标记：
- default-role (设置一个新的默认角色)
- role (创建一个新角色)
由于这些只是在每个文件内生效，因此最好使用 default_role 来设置。

警告

不要使用指令 sectnum，header 和 footer 。

Sphinx添加的指令见指令。

指令基本上由名称、参数、选项和内容组成。(记住此术语，它将在下一个描述自定义指令的章节中使用。)看看这个例子，

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   Return a line of text input from the user.

function 是指令名称。这里给出了两个参数，第一行的其余部分和第二行，以及一个选项 module （如你所见，选项在紧跟在参数后面的行中给出并由冒号表示）。选项必须缩进到与指令内容相同的级别。

指令内容在空行之后，并相对于指令开始缩进，或者如果存在选项，则与选项缩进量相同。

请注意，缩进不是固定数量的空格，例如三个，而是任意数量的空格。这在整个文档中使用固定缩进时可能会令人惊讶，并且对于对空格敏感的指令可能会有所不同。比较:

.. code-block::
   :caption: A cool example

       The output of this line starts with four spaces.

.. code-block::

       The output of this line has no spaces at the beginning.

在第一个代码块中，内容的缩进由选项行固定为三个空格，因此内容以四个空格开头。在后者中，缩进由内容本身固定为七个空格，因此它不是以空格开头。

图像¶

reStructuredText支持图像指令(ref)，用法如下:

.. image:: gnu.png
   (options)

当在 Sphinx 中使用时，给定的文件名(这里是 gnu.png )必须是相对于源文件的相对文件名，或者是绝对路径（这意味着相对于工程根目录）。例如，文件 sketch/spam.rst 可以将图像 images/spam.png 引用为 ../images/spam.png 或 /images/spam.png 。

Sphinx会自动将图像文件复制到构建的输出目录的子目录中(例如，用于HTML输出的 _static 目录。)

图像大小选项(width和height)的解释:如果没有单位或单位是像素，则只有支持像素的输出通道才会考虑给定大小。其他单位(如pt)将用于HTML和LaTeX输出(后者用bp替换pt，因为这是TeX单位， 72bp=1in)。

Sphinx通过允许扩展名的星号来扩展标准的docutils行为：

.. image:: gnu.*

然后，Sphinx搜索与提供的模式匹配的所有图像并确定其类型。然后，每个生成器从这些候选者中选择最佳图像。例如，如果给出了文件名 gnu.* 并且源树中存在两个文件 gnu.pdf 和 gnu.png，则LaTeX生成器将选择前者，而HTML生成器更喜欢后者。支持的图像类型和选择优先级定义在构建器。

请注意，图像文件名不应包含空格。

在 0.4 版本发生变更: 添加了对以星号结尾的文件名的支持。

在 0.6 版本发生变更: 图像路径现在可以是绝对的。

在 1.5 版本发生变更: latex目标支持像素(默认为 96px=1in)。

脚注¶

对于脚注（ ref），使用 [#name]_ 标记脚注位置，并在"脚注"标题后添加脚注主体在文档底部，像这样：

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

您还可以明确编号脚注（ [1]_ ）或使用不带名字的自动编号脚注（ [#]_ ）。

引文¶

支持标准reStructuredText引用（ref），具有"全局"功能，即所有引用都可以从所有文件中引用。使用方法如下:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] Book or article reference, URL or whatever.

引用用法类似于脚注用法，但标签不是数字或以 # 开头。

替代品¶

reStructuredText支持"替换"(ref)，它们是文本和/或标记的一部分，通过 |name| 在文本中引用。它们像脚注一样用显式标记块定义，就像这样:

.. |name| replace:: replacement *text*

或者:

.. |caution| image:: warning.png
             :alt: Warning!

详情请参阅 reStructuredText reference for substitutions 。

如果您想为所有文档使用一些替换，请将它们放入 rst_prolog 或 rst_epilog 中，或者将它们放入单独的文件中，并使用 include 指令将其包含到您想要使用它们的所有文档中。

Sphinx定义了一些默认替换，请参阅替代品。

注释¶

每个显式标记块都不是有效的标记结构(如上面的脚注)，它被视为注释（ref）。例如：

.. This is a comment.

您可以在评论开始后缩进文本以形成多行注释：

..
   This whole indented block
   is a comment.

   Still in the comment.

HTML 元数据¶

meta 指令允许指定 Sphinx 文档页面的 HTML metadata element 。例如，指令:

.. meta::
   :description: The Sphinx documentation builder
   :keywords: Sphinx, documentation, builder

会产生以下HTML输出：

<meta name="description" content="The Sphinx documentation builder">
<meta name="keywords" content="Sphinx, documentation, builder">

此外，Sphinx将按照元指令中指定的关键字添加到搜索索引中。因此，元元素的 lang 属性被考虑在内。例如，指令:

.. meta::
   :keywords: backup
   :keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
   :keywords lang=de: bittediesenkeyfinden

将下列单词添加到具有不同语言配置的构建的搜索索引中：

pleasefindthiskey，pleasefindthiskeytoo 到英语构建；
bittediesenkeyfinden 到德语构建；
backup，到所有语言的构建。

源编码¶

Sphinx支持UTF-8编码的源文件。这意味着可以直接在reStructuredText中使用所有的 Unicode 字符。

陷阱¶

在编写reStructuredText文档时，通常会遇到一些问题：

行内标记的分离：如上所述，行内标记跨度必须通过非单词字符与周围文本分开，您必须使用反斜杠转义空格来绕过它。有关详细信息，请参阅参考。
不支持嵌套的行内标记：像 *see :func:`foo`* 这样的东西是不可行的。