# reStructuredText

reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本""，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。 (据cnblogs.com引述)

官方文档: RESTRUCTUREDTEXT 简介

标记语法速查手册

典型例子：

• Note 显示用户使用API时的注意事项. 指令的内容应该使用完整的语句及标点符号.

.. note::

   该功能不适于发送垃圾邮件.

• warning 显示用户使用API时的注意事项. 指令包含完整的句子和标点符号. 不同于 note ，它一般显示的是信息安全方面的注意事项. .. warning::

• seealso 许多章节包含模块文档或者扩展文档的参考索引列表.这些列表由指令 .. seealso:: 创建.

• toctree目录索引 产生子文档的目录表格(Table Of Content)

.. toctree::
   :maxdepth: 3

   mdfilename_of_topic
   rstfilename_of_topic

生成标题文件引用，不需要文件扩展名。实际显示在菜单列表的是文件内的首标题文字（不是文件名）。

• 章节的标题 (:duref:ref <sections>) 在双上划线符号之间（或为下划线）, 并且符号的长度不能小于文本的长度:

  =================
  这是标题
  =================
  

通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:

    # 及上划线表示部分（一级标题）
    * 及上划线表示章节（二级标题）
    =, 小章节（三级标题）
    -, 子章节（四级标题）
    ^, 子章节的子章节（五级标题）
    ", 段落（六级标题）

• 列表 符号列表(Bullet Lists): 可以使用* - +表示都可以，注意缩进表示层级关系。 不同的符号结尾需要加上空行，下级列表需要有空格缩进。

枚举列表(Enumerated Lists)：即顺序(序号)列表，可以使用不同的枚举序号来表示列表。 枚举列表可以结合 # 自动生成枚举序号。

可以使用的枚举有：阿拉伯数字·1, 2, 3, ... (无上限)·，大写字母A-Z，小写字母a-z，大写罗马数字I, II, III, IV, ...，小写罗马数字i, ii, iii, iv, ...等。

可以为序号添加前缀和后缀，下面的是被允许的。

. 后缀: "1.", "A.", "a.", "I.", "i."。
() 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 后缀: "1)", "A)", "a)", "I)", "i)"。

• 内联标记

标准的reST内联标记:

    星号: *文本内容* 是强调 (斜体),
    双星号: **文本内容** 重点强调 (加粗),
    反引号: ``code text`` 代码样式.

在文本内容中的星号及反引号，可使用反斜杠符号转义。

标记限制:

* 不能相互嵌套,
* 内容前后不能有空白

• 外部链接

  例如： `云小考官网 <http://www.suncai.net>`_
  （前有空格，注意不是单引号）
  

来源：Sphinx 使用手册

reStructuredText 简介( https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html )等。