RST 语法

reStructuredText 是扩展名为 .rst 的纯文本文件,含义为”重新构建的文本”,也被简称为:RST或reST;是Python编程语言的Docutils项目的一部分,Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息,格式化成程序文档。

.rst 文件是轻量级标记语言的一种,被设计为容易阅读和编写的纯文本,并且可以借助Docutils这样的程序进行文档处理,也可以转换为HTML或PDF等多种格式,或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。

本文语法来自 Quick reStructuredText

内容参考了 seayxu reStructuredText(rst)快速入门语法说明、 赵子清 使用Sphinx + reST编写文档Sphinx 使用手册

一级标题

源码

============
一级标题
============

= 的数量为标题的长度,不同于二级标题,一级标题,上下层都要包含=。

二级标题

源码

二级标题
============

= 的数量为标题的长度。

三级标题

源码

三级标题
----------

- 的数量为标题的长度。

四级标题

源码

四级标题
^^^^^^^^^^^

^ 的数量为标题的长度。
五级标题

源码

五级标题
""""""""""""

" 的数量为标题的长度。
六级标题

源码

六级标题
***********

* 的数量为标题的长度。

字体样式

强调内容

强调内容

源码

*这里是强调内容*

<em> 标签告诉浏览器把其中的文本表示为强调的内容。对于所有浏览器来说,这意味着要把这段文字用斜体来显示。

引用内容

引用内容

源码

`这里是引用内容`
<cite> 标签通常表示它所包含的文本对某个参考文献的引用,比如书籍或者杂志的标题。

粗体

粗体

源码

**这里是粗体内容**
<strong> 标签和 <em> 标签一样,用于强调文本,但它强调的程度更强一些。

等宽文本

等宽文本

源码

``这里是等宽文本``

注解

字体样式设置后,需要保证前后 各空一字符

上标

E = mc2

源码

E = mc\ :sup:`2`

下标

H2O

源码

H\ :sub:`2`\ O

注解

斜杠为了转义空格。

文档标题

文档标题

该文本标题不会在索引中显示。

行居中加粗

居中加粗行

源码

.. centered:: 居中加粗行

段落

段落是被空行分割的文字片段,左侧必须对齐(没有空格,或者有相同多的空格)。

缩进的段落被视为引文。
这里是段落
缩进的段落被视为引文。
这里也是段落
缩进的段落被视为引文。
这里还是段落
缩进的段落被视为引文。

源码

| 这里是段落

  缩进的段落被视为引文。

| 这里也是段落

  缩进的段落被视为引文。

| 这里还是段落

  缩进的段落被视为引文。

注解

段落,可以前空2格,或使用 |,做为段落开头。

行块

行块对于地址、诗句以及无装饰列表是非常有用的。行块是以 | 开头,每一个行块可以是多段文本。

| 前后各有一个空格。

下面是行块内容:
这是一段行块内容
这同样也是行块内容 还是行块内容

这是新的一段。

源码

下面是行块内容:
 | 这是一段行块内容
 | 这同样也是行块内容
   还是行块内容

这是新的一段。

文字块

文字块就是一段文字信息,在需要插入文本块的段落后面加上 ::,接着一个空行,然后就是文字块了。

文字块不能定顶头写,要有缩进,结束标志是,新的一段文本贴开头,即没有缩进。

下面是文字块内容:

这是一段文字块
同样也是文字块
还是文字块

这是新的一段。

源码

下面是文字块内容:
::

   这是一段文字块
   同样也是文字块
   还是文字块

这是新的一段。

定义

定义1
这是定义1的内容
定义2
这是定义2的内容

源码

定义1
  这是定义1的内容

定义2
  这是定义2的内容

字段列表

标题:

reStructuredText语法说明

作者:
  • Seay
  • Seay1
  • Seay2
时间:

2017年12月12日

概述:

这是一篇 关于reStructuredText的语法说明。

你在这里可以了解更多语法信息。

源码

:标题: reStructuredText语法说明

:作者:
 - Seay
 - Seay1
 - Seay2

:时间: 2017年12月12日

:概述: 这是一篇
 关于reStructuredText的语法说明。

 你在这里可以了解更多语法信息。

列表

  • 符号列表1

  • 符号列表2

    • 二级符号列表1
    • 二级符号列表2
    • 二级符号列表3
  • 符号列表3
  • 符号列表4

注解

符号列表可以使用 -*+ 来表示。

不同的符号结尾需要加上空行,下级列表需要有空格缩进。

枚举列表

可以使用的枚举有:

  • 阿拉伯数字: 1, 2, 3, … (无上限)。
  • 大写字母: A-Z。
  • 小写字母: a-z。
  • 大写罗马数字: I, II, III, IV, …, MMMMCMXCIX (4999)。
  • 小写罗马数字: i, ii, iii, iv, …, mmmmcmxcix (4999)。
  1. 枚举列表1
  2. 枚举列表2
  3. 枚举列表3
  1. 枚举列表1
  2. 枚举列表2
  3. 枚举列表3
  1. 枚举列表1
  2. 枚举列表2
  3. 枚举列表3

源码

1. 枚举列表1
#. 枚举列表2
#. 枚举列表3

A. 枚举列表1
#. 枚举列表2
#. 枚举列表3

a. 枚举列表1
#. 枚举列表2
#. 枚举列表3

水平列表

该指令生成水平列表. 它将列表项横向显示并减少项目的间距使其较为紧凑.

生成器需支持水平分布, 这里的 columns 选项定义显示的列数,默认为2. 例如:

  • 列表
  • 的子
  • 项会
  • 水平
  • 排列

源码

.. hlist::
   :columns: 3

   * 列表
   * 的子
   * 项会
   * 水平
   * 排列

代码

在文档中列出代码是开发人员经常用到的一个功能。在reST文档中列出代码有三种方式:

  • 行内代码 用``code``
  • 简单代码块 在代码块的上一个段落后面加2个冒号,空一行后开始代码块,代码块要缩进
  • 复杂代码块 使用code-block指导语句,还可以选择列出行号和高亮重点行等
    • :linenos:显示行号
    • :emphasize-lines:3,6 3,6行高亮

code 方式

echo "Hello World!";

源码

``echo "Hello World!";``

双冒号方式

echo "Hello World!";

源码

双冒号方式 ::

  echo "Hello World!";

code-block 方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";
echo "Hello World!";

源码

.. code-block:: c
  :linenos:
  :emphasize-lines: 3,6

  echo "Hello World!";

超链接

主要有两种方式:

  • 行内超链接 语法`链接文字 <URL>`_
  • 分开的超链接 用到链接的地方`链接文字`_, 定义链接的地方 .. _链接文字: URL

外链接

访问 我的博客 ,可以了解更多信息。

访问 我的博客,可以了解更多信息。

我的博客地址是: http://ramble.3vshej.cn ,以了解更多信息。

这篇文章参考的是:reStructuredText(rst)快速入门语法说明

源码

访问 `我的博客 <http://ramble.3vshej.cn>`_ ,可以了解更多信息。

访问 `我的博客`_,可以了解更多信息。

.. _我的博客: http://ramble.3vshej.cn

我的博客地址是: http://ramble.3vshej.cn ,以了解更多信息。

这篇文章参考的是:`reStructuredText(rst)快速入门语法说明`__。

.. __: http://www.jianshu.com/p/1885d5570b37

内容链接

字体样式,你可以了解与字体相关的配置。

源码

`字体样式`_,你可以了解与字体相关的配置。

锚点

更多信息参考 引用文档

这里是其他内容

这是引用部分的内容

源码

更多信息参考 引用文档_

这里是其他内容

.. _引用文档:

这是引用部分的内容

图片

http://ramble.3vshej.cn/wp-content/uploads/2017/12/2017-12-06_raspberry-pi-e1512540834201.png

源码

.. image:: ./2017-12-06_raspberry-pi-e1512540834201.png
  :width: 200px

表格

简单的表格

输入 输出
A B A or B
False False False
True False True
False True True
True True True

源码

=====  =====  ======
输入          输出
------------  ------
A      B      A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

复杂的表格

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 Cells may span columns.
body row 3 Cells may span rows.
  • Table cells
  • contain
  • body elements.
body row 4

源码

+------------------------+------------+----------+----------+
| 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             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

注解

参见:Sphinx rst 创建表格技巧 http://ramble.3vshej.cn/sphinx-rst-create-table-tips/

引用

本文档参考自 [赵子清的技术文章]

[赵子清的技术文章]《使用Sphinx + reST编写文档》 https://www.cnblogs.com/zzqcn/p/5096876.html

源码

本文档参考自 [赵子清的技术文章]_。

.. [赵子清的技术文章] 《使用Sphinx + reST编写文档》 https://www.cnblogs.com/zzqcn/p/5096876.html

脚注

当然,也参考了 seayxu [1] 的 reStructuredText(rst)快速入门语法说明 [2]

脚注

[1]seayxu 简书 http://www.jianshu.com/u/3462d3ed1acd
[2]reStructuredText(rst)快速入门语法说明 http://www.jianshu.com/p/1885d5570b37

源码

当然,也参考了 seayxu [#简书]_ 的 reStructuredText(rst)快速入门语法说明 [#地址]_ 。

脚注

.. [#简书] seayxu |苹果| 简书 http://www.jianshu.com/u/3462d3ed1acd
.. [#地址] reStructuredText(rst)快速入门语法说明 http://www.jianshu.com/p/1885d5570b37

替换

|release|

被项目文档的发布版本替换. 这时版本字符串包含完整的标签 alpha/beta/release ,例如 2.5.2b3

|version|

被项目文档的版本替换. 版本字符串仅有主要和次要两部分组成,例如版本2.5.1会表示为 2.5

|today|

替换今天的日期 (文档被读取的日期), 或者配置文件设置的日期

我非常喜欢吃 橘子 。

源码

我非常喜欢吃 |苹果| 。

.. |苹果| replace:: 橘子

注解

替换是全文替换的(我非常喜欢吃 橘子 )。

块引用

下面是引用的内容:

“真的猛士,敢于直面惨淡的人生,敢于正视淋漓的鲜血。”

—鲁迅

“人生的意志和劳动将创造奇迹般的奇迹。”

—涅克拉索

源码

下面是引用的内容:

    “真的猛士,敢于直面惨淡的人生,敢于正视淋漓的鲜血。”

    --- 鲁迅

..

      “人生的意志和劳动将创造奇迹般的奇迹。”

      — 涅克拉索

Python会话

>>> print "Hello World!"
Hello World!

源码

>>> print "Hello World!"
Hello World!

选项列表

选项列表是一个类似两列的表格,左边是参数,右边是描述信息。当参数选项过长时,参数选项和描述信息各占一行。

选项与参数之间有一个空格,参数选项与描述信息之间至少有两个空格。

-a command-line option “a”
-b file options can have arguments and long descriptions
--long options can be long also
--input=file long options can also have arguments
/V DOS/VMS-style options too

源码

-a            command-line option "a"
-b file       options can have arguments
              and long descriptions
--long        options can be long also
--input=file  long options can also have
              arguments
/V            DOS/VMS-style options too

分隔符

分隔符就是一条水平的横线,是由 4 个 - 或者更多组成,需要添加换行。

上面部分


下面部分

源码

上面部分

------------

下面部分

这篇文章来自我的Github,请参考 reference

注释

注释以 .. 开头,后面接注释内容即可,可以是多行内容,多行时每行开头要加一个空格。

源码

..
 我是注释内容
 你们看不到我

函数

这里的函数定义,并不是 python 中的方式,而是其他语言 如 PHP。在这里只是为了“高亮”显示。

clearEof($str);

清除换行符。

param string $str:
 待处理字符串
return:已经处理字符串
rtype:string

源码

.. py:function:: clearEof($str);

  清除换行符。

:param  string  $str: 待处理字符串
:return:      已经处理字符串
:rtype: string
Common.clearEof($str)
Common.getIp()

返回用户输入的一行文本.

源码

.. function:: clearEof($str)
              getIp()
   :module: Common

   返回用户输入的一行文本.

提示文本

注解

注解型提示。

源码

.. note::

   注解型提示。

警告

警告型提示。

源码

.. warning::

   警告型提示。

版本提示

新版本功能

2.5 新版功能: The spam parameter.

源码

.. versionadded:: 2.5
    The *spam* parameter.

版本中修改

在 2.6 版更改: The spam parameter.

与 versionadded 相似,但它描述的是该功能在版本中的更改(新参数,效果改变等)。

源码

.. versionchanged:: 2.6
   The *spam* parameter.

版本中移除

3.1 版后已移除: 使用 newFunc() 代替。

源码

.. deprecated:: 3.1
   使用 :func:`newFunc` 代替。

参见

参见

Common getIp
标准模块 Common 的文档.
段落级别的标记
创建简单的段落。

源码

.. seealso::

   Common :py:mod:`getIp`
      标准模块 :py:mod:`Common` 的文档.

   `段落级别的标记 <http://zh-sphinx-doc.readthedocs.io/en/latest/markup/para.html>`_
      创建简单的段落。

子目录

当文档很多时,那么,你需要用到 子目录 了。

根目录下 index.rst 加入 modelList/index ;在目录中,index.rst 文件,可以写为

源码

模块列表
----------

.. toctree::
        :glob:
        :titlesonly:

        *

创建索引

源码

.. index:: 创建, 索引, 测试