reStructuredText入门

本节简要介绍了reStructuredText (reST)的概念和语法，旨在提供足够的信息来高效地编写文档。因为reST是一个简单的，不显眼的标记语言，这不会花费太长时间来入门。

See also

权威的 reStructuredText用户文档。

段落

段落(原文参考)是reST文档中最基本的块。段落是由一个或多个空白行分离的简单的文本块。在Python中，缩进在reST中是具有重要意义，所以同一段落的所有行必须左对齐而且是同一级缩进。

这是一个段落。他非常短。

这个段落将导致一个文本缩进块， 通常用于引用其他的文本。

这是另外一个段落。

要包含一大段原始格式的, 完全不更改的文本代码块(原文参考), 可让前面的段落以"::"结尾, 原始块在文本达到到其前一段落相同的缩进后结束。例如:

  空格, 新行, 空行, 和各种标记(如 *这个* 或 \这个  :: )
     都在文本块种保留.

看这里, 我把缩进降级了
(但还不够远)

例子结束

注意，如果一个段落仅仅包括"::", 他就会从结果种去除:

这是一个原始文本, 上面
的"::" 段落将被去除

也可以用行块元素 (原文参考) 来保留文本行原样的格式:

These lines are

broken exactly like in

the source file.

章节

章节头 (原文参考) 是用特殊的标点符作为章节标题的下划线来创建的（上划线是可选的），标题是一个单行文本（一个或者多个词），但是附带了修饰:

• 只有一个下标线、或同时有一个下标线和上标线；
• 修饰可使用 破折号"-----", 等号"======", 波浪号"~~~~~~" 或者任何其他你喜欢的非字母的字符``= - ` : ' " ~ ^ _ * + # < >``。
• 一个下标线修饰和使用相同字符的上/下标线修饰区别很明显。
• 上标线和下标线至少要和文本的长度相同。
• 他们是一致的，因为所有使用相同修饰风格的章节被认为处于相同的级别(如果出现新的修饰风格，则表示降低一级标题).

第一章 标题
==========

第1.1节 标题
-----------

第1.1.1子节 标题
~~~~~~~~~~~~~~~

第1.2节 标题
-----------

第二章 标题
===========

• # with overline, for parts
• * with overline, for chapters
• =, for sections
• -, for subsections
• ^, for subsubsections
• ", for paragraphs

当然，您可以自由使用自己的标记字符（参看reST文档），并使用一个更深层次的嵌套级别，但请记住，大多数的目标格式（HTML，LaTeX）有限地支持嵌套深度。

列表

在枚举或说明要点时，或在做名词解释时，我们常常会使用列表的方式来书写， 他可以有任意多的子段落、子列表等， 直至段落或者其他的左边和列表项中文本的第一行对齐，列表的实质就是语义相关的文本块在文章中的表达。

reST列表标记(原文参考) 是自然的：只要在段落开头放置一个星号, 列表必须从一个新的段落开始 (也就是说，必须在一个空行后出现), 对于带编号的列表同样适用，它们也可以通过使用标志 # 自动编号:

• 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.
3. This is a numbered list.
4. It has two items too.

嵌套列表是可能的，但要知道，它们必须由空行从父列表中分隔:

• this is
• a list
  • with a nested list
  • and some subitems
• and here the parent list continues

名词解释风格的列表 (原文参考) 可以这样创建:

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 不能有一个以上的文本行。

这种名词解释风格和引用段落很相似(原文参考) 它的实现也是通过比周围的段落更缩进来创建。

还有其它几个特殊的功能块:

• field lists (原文参考)
• option lists (原文参考)
• quoted literal blocks (原文参考)
• doctest blocks (原文参考)

表格

格子表格 (原文参考)，必须自己“画”自己的单元格。它们看起来像这样:

Header row, column 1 (header rows optional)	Header 2	Header 3	Header 4
body row 1, column 1	column 2	column 3	column 4
body row 2	...	...

简单表格 (原文参考) 更容易书写，但是有限制：表格必须是两行以及以上，而且第一列不能包含多行。它们看起来像这样:

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

链接

使用 `Link text <http://example.com/>`_ 来实现内嵌的网页链接。如果链接文本是Web地址，你一点都不需要特殊标记，解析器可以识别在普通的文本的链接和邮件地址。

你也可以把链接和目标定义(原文参考)分开，像这样:

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

.. _a link: http://example.com/

内部链接则是通过Sphinx提供的一个特殊的reST role来实现的， 详见原文。

可以使用 [#name]_ 标注在脚注的位置，在文档的最后的 .. rubric:: Footnotes 后添加脚注的内容，像这样:

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

.. rubric:: Footnotes

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

你也可以明确用数字标注脚注或者通过不指定 name 使用自动数字标记脚注([#]_)。

Sphinx支持标准reST引文(原文参考)，增加了所有引文是“全局的”的特性，即：所有的文件可以使用所有的引文。这样使用它们:

Lorem ipsum [Ref]_ dolor sit amet.

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

引文用法是类似的脚注的用法，但带标签不是数字，或以``#``开始。

图片

reST支持图片标识(原文参考)，可以像这样使用它:

.. image:: gnu.png
   (options)

在Sphinx中使用图片标识，文件名前面的路径必须是相对于源文件，或者是绝对的但是相对于顶部的源目录，例如，在 sketch/spam.rst 文件中可以使用图片 images/spam.png，也可以使用 ../images/spam.png 或者 /images/spam.png,　Sphinx将会自动将图像文件拷贝到输出目录中（例如HTML格式输出，会拷贝到 _static 目录中。）

对于图片尺寸选项（ width 和 height）的解释如下：如果大小没有单位或单位是像素，那图片大小将会被那些支持像素的输出格式关心（LaTeX格式就不在乎这种情况的图片大小）。HTML和LaTeX输出格式使用其他的单位（像 pt 表示像素点）。

Sphinx扩展了标准的docutils的功能，允许文件扩展名为星号:

.. image:: gnu.*

Sphinx搜索所有的图片匹配提供的模式，并确定其类型。每个生成器会从所有的候选者中选择最佳的图片。比如，如果给出 gnu.* 这样的文件名以及源代码树中存在 gnu.pdf 和 gnu.png 这两个文件，LaTeX 生成器会选择前者，HTML生成器则会选择后者。

文本样式

段落和其它正文的内部，你可对文字添加附加的标记，标准的行内标记相当简单：使用

• 单星号： *text* 强调 (斜体),
• 双星号： **text** 重点强调 (粗体)，以及
• 反引号： ``text`` 代码示例。

如果星号或反引号出现在文本会对行内标记分隔符引起混淆，他们必须用一个反斜杠进行转义。

注意行内标记一些限制:

• 不能嵌套，
• 文本不能以空格开始或者结束: * text* 是不正确的，
• 必须由空格从周围的文本中分离出来。可以通过使用转义的空格来规避这个限制，例如：thisisoneword。

docutils以后的版本可能会取消以上列出的这些限制。

reST也允许自定义“文本解释role”，用来说明所包含的文本应以一种特定的方式解释, 一般的语法格式是 :rolename:`content` 。

标准的reST提供了如下些roles：

• emphasis -- 来替代 *emphasis*
• strong -- 代替 **strong**
• literal -- 代替 ``literal``
• subscript -- 下标文本
• superscript -- 上标文本
• title-reference -- 书，期刊，以及其他材料的标题

Sphinx用它定义了语义标记和交叉引用的标识符。添加的roles请见 inline-markup。

显式标记

"显式标记" (ref) 在reST中是用于需要进行特殊处理的结构，比如脚注，特别突出的段落，注释，和通用指令（标识符）。

显式标记块的第一行是以 .. 开始，接着是紧随着空格，被结束于同样层级缩进的下一段落。（显式标记和正常的段落之间需要有一个空行。当你写它的时候，可能听起来有点复杂，但它是直观的。）

指令（标识符）

指令或者标识符（ref）是一个通用的显式标记块。除了roles，指令或者标识符是reST的扩展机制，Sphinx大量地使用了它。

Docutils支持如下的指令（标识符）：

• 警告: attention, caution, danger, error, hint, important, note, tip, warning 以及 admonition。
• 图片:
  • image (请见下面的 Images_ )
  • figure (带有标题和可选的图例的图片)
• 其它内容元素:
  • contents （一个局部的，即只对当前文件的，内容表）
  • container （具有特定类的容器，用于HTML生成 <div> ）
  • rubric (一个与文件章节无关的标题)
  • topic, sidebar (特别强调了内容元素)
  • parsed-literal (支持行内标记的文字块)
  • epigraph (带有属性行的块引用)
  • highlights, pull-quote （带自己的类属性的块引用）
  • compound (组合段落)
• 特色表格:
  • table （带标题的表格）
  • csv-table （由逗号分开的值生成的表格）
  • list-table （由一系列列表生成的表格）
• 特色指令（标识符）:
  • raw （包括原生格式标记）
  • include (包含其他文件的reStructuredText) -- 在Sphinx中，当给定一个绝对的文件路径，该指令（标识符）将其作为相对于源目录来处理
  • class (class属性赋给下一个元素) [1]
• HTML特性:
  • meta (生成HTML <meta> 标签)
  • title (覆盖文件的标题)
• Influencing markup:
  • default-role (设置一个新的默认role)
  • role (创建一个新的role)

请 不要 使用指令（标识符） sectnum， header 以及 footer。

Sphinx自己增加的指令（标识符）是在 sphinxmarkup 中描述的。

基本上，指令（标识符）由一个名称，参数，选项和内容组成。（请记住这些术语，它被用来在接下来的章节描述了自定义指令或者标识符。）请看例子，:

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

   Return a line of text input from the user.

function 是指令（标识符）的名称。在这里它有两个参数，第一行其余的部分以及第二行，还有一个选项 module （正如可以看到的，选项是在参数的下一行以及以冒号开始以冒号结束）。选项必须跟指令的内容缩进到相同的水平。

指令（标识符）的内容与选项之间空一行，需要相对于指令（标识符）的首行缩进（以指令的首行为缩进的对照点）。

替换

reST支持“替换”(ref)，这是文本和/或标记在文中 |name| 提到。它们是像脚注用显著的标记块，像这样:

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

或者，这样:

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

细节请看 reST reference for substitutions。

如果你想在所有文件使用中一些替换，把它们写入 :confval:`rst_prolog` 或把它们放到一个单独的文件，要使用它们的所有文件中包含它，通过使用 include 指令或者标识符。（务必使得include文件扩展名与其他的源文件不同，以免让Sphinx把它作为一个独立的文件。）

Sphinx自定义了一些默认的替换, 请看 default-substitutions。

评论

不是一个有效的标记结构（如上述的脚注）的每一个明确的标记块被视为一条评论（ref）。例如:

.. This is a comment.

您可以缩进文本在注释开始后，这样可以形成多行注释:

..
   This whole indented block
   is a comment.

   Still in the comment.

源文件编码

由于包括特殊字符如在reST中的破折号或版权标志，最简单的方法是直接写为Unicode字符，指定编码。Sphinx假定源文件默认情况下是使用UTF-8编码；你可以改变 :confval:`source_encoding` 这一配置值。

陷阱

这有些问题通常发生在编写reST文档的时候：

• 分离的内嵌标记: 正如上面所说，行内标记的跨度必须用由非单词字符把周围的文字分开，可以使用转义的空格来避免。详情请看 the reference。
• 没有嵌套内联标记: 像 *see :func:`foo`* 是不可能存在的。

Footnotes

[1]	当默认域包含一个 class 指令（标识符），该指令将被隐藏。因此，Sphinx将它转为 rst-class。