https://github.com/xunxuny/zh-sphinx-doc/blob/master/rest.rst
本章节介绍 restructuredtext (rest)
的概念和语法，为文档生成者提供足够的信息. rest
被认为是简单，实用的标记语言，因此学习它不会花太多时间.
段落
段落 (ref ) 是rest 文件的基本模块.
段落是由空行分隔的一段文本. 和python一样, 对齐也是rest的操作符,
因此同一段落的行都是左对齐的.
内联标记 标准的rest 内联标记相当简单:
星号: *text*是强调 (斜体), 双星号: **text**重点强调 (加粗), 反引号: text代码样式. 星号及反引号在文本中容易与内联标记符号混淆，可使用反斜杠符号转义.
标记需注意的一些限制:
不能相互嵌套, 内容前后不能由空白: 这样写 * text*是错误的, 如果内容需要特殊字符分隔. 使用反斜杠转义，如: thisis\ *one*\ word. 这些限制在未来版本可能会被改善.
rest 也允许自定义 “文本解释角色”‘, 这意味着可以以特定的方式解释文本.
sphinx以此方式提供语义标记及参考索引，操作符为 :rolename:`content.
标准rest 提供以下规则:
* :durole:emphasis` – 写成 *emphasis** strong – 写成
**strong*** literal – 写成 literal* subscript – 下标 *
superscript – 上标 * title-reference – 书、期刊等材料的标题
详情请查看 inline-markup .
列表与引用
列表标记 (ref ) 的使用最自然:
仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;也可以使用符号
#自动加序号:
* 这是一个项目符号列表.* 它有两项， 第二项使用两行.1. 这是个有序列表.2. 也有两项.#. 是个有序列表.#. 也有两项.
列表可以嵌套，但是需跟父列表使用空行分隔 :
* 这是* 一个列表 * 嵌套列表 * 子项* 父列表继续
定义列表 (ref ) :
术语 (term 文本开头行) 定义术语，必须缩进 可以有多段组成下一术语（term） 描述.
一行仅能写一个术语.
引用段落 (ref ) 仅使用缩进（相对于周围段落）创建.
行模块 (ref ) 可以这样分隔 :
| 这些行| 在源文件里| 被分隔的一模一样.
还有其他有用的模块:
字段列表 (ref ) 选项列表(ref ) 字面引用模块 (ref ) 文档测试模块 (ref ) 源代码 字面代码块 (ref ) 在段落的后面使用标记 ::引出.
代码块必须缩进(同段落，需要与周围文本以空行分隔):
这是一段正常文本. 下一段是代码文字:: 它不需要特别处理，仅是 缩进就可以了. 它可以有多行.再是正常的文本段.
这个 ::标记很优雅:
如果作为独立段落存在,则整段都不会出现在文档里. 如果前面有空白，则标记被移除. 如果前面是非空白，则标记被一个冒号取代. 因此上面的例子第一段文字将变为”下一段是代码文字:”.
表格 支持两种表格. 一种是 网格表格(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 falsetrue false falsefalse true falsetrue true true===== ===== =======
超链接 外部链接 使用 `链接文本 `_可以插入网页链接.
链接文本是网址，则不需要特别标记，分析器会自动发现文本里的链接或邮件地址.
可以把链接和标签分开 (ref), 如下:
段落里包含 `a link`_... _a link: http://example.com/
内部链接 内部链接是sphinx特定的rest角色, 查看章节 ref-role.
章节 章节的标题 (ref ) 在双上划线符号之间（或为下划线）,并且符号的长度不能小于文本的长度:
=================this is a heading=================
通常没有专门的符号表示标题的等级，但是对于python 文档，可以这样认为:
#及上划线表示部分 *及上划线表示章节 =, 小章节 -, 子章节 ^, 子章节的子章节 , 段落 当然也可以标记（查看 rest 文档),定义章节的层次，但是需要注意输出格式(html, latex)所支持的层次深度 .
显式标记 显式标记”explicit markup” (ref )用在那些需做特殊处理的rest结构中, 如尾注，突出段落，评论，通用指令.
显式标记以 ..开始，后跟空白符，与下面段落的缩进一样.
(在显示标记与正常的段落间需有空行，这听起来有些复杂，但是写起来会非常直观.)
指令 指令 (ref ) 是显式标记最常用的模块. 也是rest的扩展规则, 在 sphinx 经常被用到.
文档工具支持以下指令:
警告: attention, caution, danger, error, hint, important, note, tip,warning 及通用标记 admonition. (大多数模式仅支持 “note” 及“warning” ) 图像: image (详情可看下面的 图像_ ) figure (有标题及可选说明的图像) 额外的主体元素: contents (本地，仅是当前文件的内容表格) container (自定义容器，用来生成html的 ) rubric (和文档章节无关的标题) topic, sidebar (高亮显示的主体元素) parsed-literal (支持内联标记的斜体模块) epigraph (可选属性行的摘要模块) highlights, pull-quote (有自己的类属性的摘要模块) compound ( 复合段落) 专用表格: table (有标题的表格) csv-table (csv自动生成表格) list-table (列表生成的表格) 专用指令: raw (包含原始格式的标记) include (包含restructuredtext标记的文件) –在sphinx中,如果包含绝对文件路径，指令会以源目录地址做为参照 class (将类属性指派给下一个元素) [^1] html 特性: meta (生成html 标签) title (覆盖文档标题) 影响标记:
default-role (设置新的默认角色) role (创建新的角色) 如果仅有一个文件，最好使用 default_role.
设置不使用指令 sectnum, header 及 footer.
sphinx 新增指令可查阅 sphinxmarkup.
指令有名字，参数，选项及内容组成.(记住这些，在下面一小节中自定义指令里会用到).来看一个例子:
.. function:: foo(x) foo(y, z) :module: some.module.name 返回用户输入的一行文本.
function是指令名字. 在第一行和第二行给出了两个参数, 及一个选项
module(如你所见，选项在参数后给出，由冒号引出).
选项必须与指令有一样的缩进.
指令的内容在隔开一个空行后，与指令有一样缩进.
图像 rest 支持图像指令 (ref ), 如下:
.. image:: gnu.png (选项)
这里给出的文件名( gnu.png)
必须是源文件的相对路径，如果是绝对路径则以源目录为根目录. 例如，在文件
sketch/spam.rst引用图像 images/spam.png，则使用
../images/spam.png或者 /images/spam.png.
sphinx 会自动将图像文件拷贝到输出目录的子目录里，( 输出html时目录为
_static)
图像的大小选项 ( width及 height) : 如果没有单位或单位为像素,
给定的尺寸信息仅在输出通道支持像素时才有用 ( 如输出latex 没用).
其他单位在输出(如 pt)html、latex 时被用到.
sphinx 延伸了标准的文档化行为，只需在后面加星号:
.. image:: gnu.*
上面这样写，sphinx 会搜索所有名字匹配的图像，而不管图像类型.
每个生成器则会选择最合适的图像. 一般，在源文件目录里文件名 gnu.* 会含有两个文件 gnu.pdf 和 gnu.png , latex 生成器会选择前者，而html
生成器则匹配后者.
尾注 尾注 (ref ), 使用 [#name]_标记尾注的位置,
尾注的内容则在文档底部红色标题”footnotes”的后面 , 如下:
lorem ipsum [#f1]_ dolor sit amet ... [#f2]_.. rubric:: footnotes.. [#f1] 第一条尾注的文本... [#f2] 第二条尾注的文本.
你也可以使用数字尾注 ( [1]_) 或使用自动排序的( [#]_).
引用 支持标准的rest 引用 (ref ) , 且新增了”global”特性,所有参考文献不受所在文件的限制. 如:
lorem ipsum [ref]_ dolor sit amet... [ref] 参考文献, 书,url 等.
引用的使用同尾注很相近，但是它们没有数字标签或以 #开始.
替换 rest 支持替换 “substitutions” (ref ),
有一小段文本或标记被关联到 |name|.
定义与尾注一样需有明确的标记块，如下:
.. |name| replace:: replacement *text*
或者:
.. |caution| image:: warning.png :alt: warning!
详情查看rest reference for substitutions .
如果想在所有文档中使用这些替换, 需把它们放在 rst_prolog
或一个单独文件里， 然后在使用它们的文档文件里包含这个文件，包含指令
:rstinclude .
(请给出包含文件的扩展名，已区别于其他的源文件，避免sphinx将其作为独立的文档文件.)
sphinx 定义了一些默认的替换, 请查看 default-substitutions.
评论 有明确标记块但又不是有效的结构标记的标记 (像上面的尾注）都被视为评论(ref ). 例如:
.. 这是一个评论.
可以通过缩进产生多行评论:
.. 这整个缩进块都是 一个评论. 仍是一个评论.
源编码 在rest使用unicode字符可以容易的包含特殊字符如破折号，版权标志. sphinx默认源文件使用utf-8 编码; 你可以通过 source_encoding 的配置值改变编码.
常见问题 具体使用中可能会遇到一些问题:
内联标记的分离如上面所讲，内联标记需与周围的文本使用空格分隔, 内联标记内部则使用反斜线转义空格.: the
reference
. 内联标记不能嵌套像这样写 *see :func:`foo`*是不允许的. footnotes [^1]: 当默认主域里包含指令 :rstclass , 这个指令将被隐藏 因此, sphinx使用:rstrst-class.