reStructuredText 基础¶
RestructuredText是Sphinx使用的默认纯文本标记语言。本节简要介绍 reStructuredText(REST)的概念和语法,旨在为作者提供足够的信息,以便高效地编写文档。由于REST被设计成一种简单、不引人注目的标记语言,所以这不会花费太长时间。
参见
权威人士 reStructuredText User Documentation 。本文档中的“ref”链接指向REST参考中各个构造的描述。
段落¶
段落 (ref )是REST文档中最基本的块。段落只是由一个或多个空行分隔的文本块。与Python一样,缩进在REST中很重要,因此同一段落的所有行必须与缩进的同一级别保持对齐。
内联标记¶
标准的REST内联标记非常简单:使用
星号:
*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 )以特殊标记结束段落 ::
. 文本块必须缩进(和所有段落一样,用空行与周围段落分隔)::
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.
处理 ::
标记很智能:
如果它是以自己的段落出现的,则该段落完全不在文档中。
如果前面有空白,则删除标记。
如果前面有非空白,则标记将被单个冒号替换。
这样,上面示例第一段中的第二句话将被表示为“下一段是代码示例:”。
可以在文档范围内为这些文本块启用代码突出显示,方法是使用 highlight
在整个项目范围内,使用 highlight_language
配置选项。这个 code-block
指令可用于逐块设置突出显示。这些指令稍后讨论。
测试块¶
测试块 (ref )是交互式python会话剪切并粘贴到docstring中。他们不需要 literal blocks 语法。doctest块必须以空行结尾,并且应该 not 以未使用的提示结束:
>>> 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/>`_
对于内联Web链接。如果链接文本应该是网址,则根本不需要特殊标记,解析器会在普通文本中查找链接和邮件地址。
重要
链接文本和URL的开头之间必须有空格。
还可以分离链接和目标定义 (ref ,像这样:
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
内部链接¶
内部链接是通过sphinx提供的特殊rest角色完成的,请参见特定标记部分, 交叉引用任意位置 .
小节¶
剖面标头 (ref )通过使用标点符号在节标题上加下划线(也可以选择在节标题上加下划线)创建,至少与文本一样长:
=================
This is a heading
=================
通常情况下,不会将标题级别分配给某些字符,因为结构是根据标题的顺序确定的。但是,此约定用于 Python Developer's Guide for documenting 你可以遵循这一点:
#
带上横线,用于零件*
带上横线,用于章节=
对于各节-
适用于小节^
适用于小节"
对于段落
当然,您可以自由地使用自己的标记字符(参见其余文档),并使用更深的嵌套级别,但请记住,大多数目标格式(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支持以下角色:
emphasis -- equivalent of
*emphasis*
strong -- equivalent of
**strong**
literal -- equivalent of
``literal``
subscript --下标文本
superscript --上标文本
title-reference --书籍、期刊和其他材料的标题
参照 角色 为Sphinx添加的角色。
显式标记¶
“显式标记” (ref )在REST中用于大多数需要特殊处理的结构,如脚注、特别突出显示的段落、注释和一般指令。
显式标记块以一行开头 ..
后面是空白,最后是同一缩进级别的下一段。(在显式标记和普通段落之间需要有空行。这听起来可能有点复杂,但当你写的时候,它就足够直观了。)
指令¶
指示 (ref )是显式标记的通用块。除了角色之外,它也是 reST 的延伸机制之一,Sphinx对其进行了大量的利用。
docutils支持以下指令:
警告: attention , caution , danger , error , hint , important , note , tip , warning 和一般的 admonition . (大多数主题样式只有“注释”和“警告”两种。)
图像:
附加车身元件:
contents (本地文件,即仅限当前文件、目录)
container (具有自定义类的容器,用于生成外部
<div>
在HTML中)rubric (与文件分割无关的标题)
parsed-literal (支持内联标记的文本块)
epigraph (带可选属性行的块引号)
highlights , pull-quote (带自己的类属性的块引号)
compound (复合段)
特殊表格:
table (有标题的表格)
csv-table (由逗号分隔值生成的表)
list-table (从列表列表生成的表)
特别指示:
HTML细节:
影响标记:
default-role (设置新的默认角色)
role (创建新角色)
因为这些只是每个文件,所以最好使用Sphinx的设施来设置
default_role
.
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.
在第一个代码块中,选项行将内容的缩进固定为三个空格,因此内容以四个空格开始。在后者中,缩进由内容本身固定为七个空格,因此它不是以空格开始的。
图像¶
REST支持图像指令 (ref ,使用方式如下:
.. image:: gnu.png
(options)
在Sphinx中使用时,给出的文件名(此处 gnu.png
)必须是相对于源文件的,或者是绝对的,这意味着它们是相对于顶级源目录的。例如,文件 sketch/spam.rst
可以参考图像 images/spam.png
作为 ../images/spam.png
或 /images/spam.png
.
sphinx将自动将图像文件复制到建筑物上输出目录的子目录(例如 _static
用于HTML输出的目录。)
图像大小选项的解释 (width
和 height
)如下所示:如果大小没有单位或单位是像素,则给定的大小仅适用于支持像素的输出通道。其他单位(如 pt
将用于HTML和LaTex输出(后者替换为 pt
通过 bp
因为这是特克斯单位,所以 72bp=1in
)
sphinx通过允许星号作为扩展名来扩展标准docutils行为:
.. image:: gnu.*
然后,Sphinx搜索与提供的模式匹配的所有图像,并确定其类型。然后,每个构建者从这些候选对象中选择最佳的图像。例如,如果文件名 gnu.*
提供了两份文件 gnu.pdf
和 gnu.png
在源代码树中, Latex 生成器将选择前者,而HTML生成器将选择后者。支持的图像类型和选择优先级定义在 Builders .
请注意,图像文件名不应包含空格。
在 0.4 版本发生变更: 添加了对以星号结尾的文件名的支持。
在 0.6 版本发生变更: 图像路径现在可以是绝对的。
在 1.5 版本发生变更: Latex 目标支持像素(默认为 96px=1in
)
脚注¶
脚注 (ref )、使用 [#name]_
标记脚注位置,并将脚注正文添加到文档底部的“footnotes”标题后面,如:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.
你也可以明确地给脚注编号。 ([1]_
)或者使用不带名称的自动编号脚注 ([#]_
)
引文¶
标准 reST 引文 (ref )支持,具有“全局”的附加功能,即可以从所有文件中引用所有引文。像这样使用它们:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
引文用法类似于脚注用法,但标签不是数字或以开头 #
.
替代品¶
reST 支持“替换” (ref ,这是文本中引用的文本和/或标记 |name|
. 它们被定义为带有显式标记块的脚注,如下所示:
.. |name| replace:: replacement *text*
或者:
.. |caution| image:: warning.png
:alt: Warning!
见 reST reference for substitutions 有关详细信息。
如果您希望使用某些替换来替换所有文档,请将它们放入 rst_prolog
或 rst_epilog
或将它们放入单独的文件中,并将其包含在要在其中使用它们的所有文档中。 include 指令。(请确保为包含文件提供与其他源文件不同的文件扩展名,以避免Sphinx将其视为独立文档。)
sphinx定义了一些默认替换,请参见 替代品 .
HTML元数据¶
这个 meta 指令允许指定 metadata element Sphinx文档页面的。例如,指令::
.. 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指令中指定的关键字添加到搜索索引中。因此, lang
考虑元元素的属性。例如,指令:
.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
将以下单词添加到具有不同语言配置的生成的搜索索引中:
pleasefindthiskey
,pleasefindthiskeytoo
到 英语 建造;bittediesenkeyfinden
到 德国的 建造;backup
以所有语言构建。
信源编码¶
由于在REST中包含特殊字符(如em短划线或版权标志)的最简单方法是直接将它们写为Unicode字符,因此必须指定编码。默认情况下,sphinx假定源文件以utf-8编码;您可以使用 source_encoding
配置值。
高查斯¶
在编写REST文档时,通常会遇到一些问题:
内联标记的分离: 如上所述,内联标记跨度必须用非单词字符与周围的文本分隔开,您必须使用反斜杠转义空格来绕过这一点。见 the reference 有关详细信息。
没有嵌套的内联标记: 类似的东西
*see :func:`foo`*
不可能。
评论¶
每个不是有效标记构造的显式标记块(如上面的脚注)都被视为注释。 (ref )例如::
.. This is a comment.
可以在注释开始后缩进文本以形成多行注释::