reStructuredText 入门¶

reStructuredText 是 Sphinx 使用的默认纯文本标记语言.本节是对 reStructuredText（reST）概念和语法的简要介绍,旨在为作者提供足够的信息,以便高效地撰写文档.由于 reStructuredText 设计为一种简单且不干扰的标记语言,因此这不会花费太长时间.

参见

权威的 reStructuredText 用户文档 .本文档中的 “ref” 链接指向 reStructuredText 参考中各个构造的描述.

段落¶

段落 (ref ) 是 reStructuredText 文档中最基本的块.段落只是由一个或多个空行分隔的文本块.与 Python 一样,缩进在 reStructuredText 中是显著的,因此同一段落的所有行必须左对齐到相同的缩进级别.

行内标记¶

标准的reStructuredText内联标记非常简单:使用

一个星号:*text* 表示强调 (斜体),
两个星号:**text** 用于强调（加粗）,并
反引号:````text````用于代码示例.

如果在运行文本中出现星号或反引号,并可能与行内标记分隔符混淆,则必须用反斜杠进行转义.

注意此标记的一些限制:

它可能不能嵌套,
内容不能以空白开头或结尾: * text* 是错误的,
它必须与周围的文本通过非文字字符分隔.使用反斜杠转义的空格来解决这个问题: thisis\ *one*\ word .

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

也可以用角色替换或扩展一些内联标记.有关更多信息,请参阅角色 .

列表和类似引用的块¶

列表标记 ( 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.

注意,该术语不能超过一行文字.

引用段落 (ref ) 只需比周围段落缩进更多即可创建.

行块 ( :ref ) 是一种保留换行符的方式:

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

还有几个特殊的块可以使用:

字段列表 (ref ,注意字段列表中提到的警告)
选项列表 (ref )
引用的文字块 (ref )
doctest 块 (ref )

文字块¶

文字代码块 ( 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 handling of the :: marker is smart:

如果它作为一个独立的段落出现,该段落将完全被省略在文档中.
如果前面有空白字符,则该标记将被移除.
如果前面有非空白字符,则该标记将被替换为一个冒号.

这样,上面示例的第一段中的第二句话将被呈现为:”下一段是一个代码示例:”.

可以使用 highlight 指令在整个文档级别启用这些文字块的代码高亮,并使用 highlight_language 配置选项在整个项目级别启用.:rst:dir:code-block 指令可以用来逐块设置高亮.这些指令将在后面讨论.

文档测试块¶

Doctest块 ( ref ) 是互动的Python会话,直接粘贴到文档字符串中.它们不需要 literal blocks 语法.doctest块必须以空行结束,并且*不能*以未使用的提示结束:

>>> 1 + 1
2

表格¶

对于 网格表 ( 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 表格 和 列表表格.它们使用 显式标记块.有关更多信息,请参阅表格 .

超链接¶

外部链接¶

使用```Link text <https://domain.invalid/>`_``来表示内联网页链接.如果链接文本应为网页地址,则完全不需要特殊标记,解析器会在普通文本中查找链接和邮件地址.

重要

链接文本与URL的开头<之间必须有一个空格.

您还可以分开链接和目标定义 (ref ),如下所示:

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

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

内部链接¶

内部链接通过 Sphinx 提供的特殊 reStructuredText 角色完成,请参阅特定标记部分交叉引用任意位置 .

部分¶

章节标题 ( ref ) 通过用标点字符在章节标题下方（可选地在上方）进行下划线来创建,标点字符的长度至少与文本相同:

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

通常,某些字符没有分配标题级别,因为结构是通过标题的顺序确定的.然而,这种约定在 Python 开发者指南中使用,你可以遵循

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

当然,您可以自由使用自己的标记字符（请参阅 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` .

Docutils支持以下角色:

强调 – 相当于 *强调*
strong – 相当于 **strong**
literal – 相当于````literal````
下标 – 下标文本
superscript – 上标文本
title-reference – 用于书籍、期刊和其他材料的标题

有关 Sphinx 添加的角色,请参见角色 .

显式标记¶

“显式标记” (ref ) 在 reStructuredText 中用于大多数需要特殊处理的结构,例如脚注、特别强调的段落、注释和通用指令.

显式标记块以一行开头,该行以 .. 开头,后跟空格,并由下一个相同缩进级别的段落终止. （显式标记和普通段落之间需要有一行空白.这听起来可能有点复杂,但在书写时足够直观.）

指令¶

一个指令（ref ）是一个通用的显式标记块.它与角色一起,是reStructuredText的扩展机制之一,Sphinx大量使用它.

Docutils 支持以下指令:

警告:注意 ,:dudir:小心 ,:dudir:危险 ,:dudir:错误 ,:dudir:提示 ,:dudir:重要 ,:dudir:注释 ,:dudir:技巧 ,:dudir:警告以及通用的警告 .（大多数主题仅特别样式”注释”和”警告”.）
图像:
- 图像（另见下方的图像）
- figure （带有标题和可选图例的图像）
附加主体元素:
- contents （本地,即仅针对当前文件的内容表）
- container （一个具有自定义类的容器,用于生成HTML中的外部 <div> ）
- rubric （与文档分段无关的标题）
- 主题 , 侧边栏（特殊高亮的主体元素）
- parsed-literal （支持内联标记的文字块）
- epigraph （一个带可选归属行的引用块）
- 高亮 , 引用（具有自己类属性的块引用）
- 复合 (一个复合段落)
特殊表格:
- 表（带标题的表格）
- csv-table （从逗号分隔值生成的表格）
- list-table （从列表生成的表格）
特殊指令:
- 原始（包含原始目标格式标记）
- include （从另一个文件中包含reStructuredText）– 在Sphinx中,当给出绝对包含文件路径时,此指令将其视为相对源目录的路径
- class (将类属性分配给下一个元素)
  
  备注
  
  当默认域包含 class 指令时,该指令将被遮蔽.因此,Sphinx 将其重新导出为 rst-class .
  
  小技巧
  
  如果您想为指令添加一个类,可以考虑使用 :class: 选项 ,该选项被大多数指令支持,并且允许更紧凑的表示法.
HTML 特性:
- meta (生成 HTML <meta> 标签,见下文 HTML 元数据 )
- 标题（覆盖文档标题）
影响标记:
- 默认角色 (设置一个新的默认角色)
- 角色 (创建新角色)
由于这些设置仅限于每个文件,最好使用 Sphinx 提供的设置 default_role 的功能.

警告

请*不要*使用指令:dudir:sectnum 、header 和:dudir:footer .

Sphinx添加的指令在指令中描述.

基本上,指令由名称、参数、选项和内容组成.（请记住这个术语,它将在下一章描述自定义指令时使用.）查看这个例子,:

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

   Return a line of text input from the user.

function is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option module (as you can see, options are given in the lines immediately following the arguments and indicated by the colons). Options must be indented to the same level as the directive content.

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

请注意,缩进不是固定的空格数,例如三,而是任意数量的空格.当整个文档使用固定缩进时,这可能会让人感到惊讶,并且对于对空格敏感的指令可能会产生影响.比较:

.. 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输出（后者将 pt 替换为 bp ,因为这是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 替换参考以获取详细信息.

如果您想要在所有文档中使用一些替代内容,请将它们放入 rst_prolog 或 rst_epilog ,或者放入一个单独的文件,并使用 include 指令将其包含到您希望使用的所有文档中. （请确保给包含文件一个与其他源文件不同的文件名扩展,以避免 Sphinx 将其识别为独立文档.）

Sphinx 定义了一些默认的替换,参见替换符 .

注释¶

每个不是有效标记构造的显式标记块（如上面的脚注）被视为注释 (ref ).例如:

.. This is a comment.

可以在注释开始后缩进文本,以形成多行注释:

..
   This whole indented block
   is a comment.

   Still in the comment.

HTML 元数据¶

The meta directive allows specifying the HTML metadata element of a Sphinx documentation page. For example, the directive:

.. 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 将根据 meta 指令中指定的关键字将其添加到搜索索引中.因此,meta 元素的 lang 属性将被考虑.例如,指令:

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

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

pleasefindthiskey, pleasefindthiskeytoo to English builds;
bittediesenkeyfinden to German builds;
backup to builds in all languages.

源编码¶

因为在reStructuredText中包含特殊字符如长破折号或版权符号的最简单方法是直接将它们写为Unicode字符,所以必须指定编码.Sphinx默认假设源文件以UTF-8编码;你可以通过配置值:confval:source_encoding 来更改此设置.

问题¶

在编写reStructuredText文档时,常常会遇到一些问题:

**行内标记的分离:**如上所述,行内标记的范围必须与周围的文本用非单词字符分开,你必须使用反斜杠转义的空格来规避这个限制.有关详细信息,请参见:duref:参考 <substitution-definitions> .
不支持嵌套行内标记: 像``*see foo() *``这样的用法是不允许的.