reStructuredText(rst)快速入门语法说明
2016-06-21 15:50
477 查看
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
由于格式原因,觉得这个不是很直观的话,可以到我的github上查看。
重点(emphasis)通常显示为斜体
重点强调(strong emphasis)通常显示为粗体
行内文本(inline literal)通常显示为等宽文本,空格可以保留,但是换行不可以。
可以表示标题的符号有 =、-、`、:、'、"、~、^、_ 、* 、+、 #、<、> 。
对于相同的符号,有上标是一级标题,没有上标是二级标题。
标题最多分六级,可以自由组合使用。
全加上上标或者是全不加上标,使用不同的 6 个符号的标题依次排列,则会依次生成的标题为H1-H6。
六级标题
缩进的段落被视为引文。
不同的符号结尾需要加上空行,下级列表需要有空格缩进。
符号列表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.", "A.", "a.", "I.", "i."。
() 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 后缀: "1)", "A)", "a)", "I)", "i)"。
枚举列表可以结合 # 自动生成枚举序号。
枚举列表1
枚举列表2
枚举列表3
I. 枚举列表1
II. 枚举列表2
III. 枚举列表3
A. 枚举列表1
B. 枚举列表2
C. 枚举列表3
条目占一行,解释文本要有缩进;多层可根据缩进实现。
定义1
定义2
标题: reStructuredText语法说明
作者:
Seay
Seay1
Seay2
时间: 2016年06月21日
概述: 这是一篇 关于reStructuredText
语法说明。
选项与参数之间有一个空格,参数选项与描述信息之间至少有两个空格。
由于格式问题,这里只是一个示例,实际上时没有上面的表头列和表格竖直线的。
文字块不能定顶头写,要有缩进,结束标志是,新的一段文本贴开头,即没有缩进。
下面是文字块内容:
这是新的一段。
| 前后各有一个空格。
下面是行块内容:
这是新的一段。
通常引用结尾会加上出处(attribution),出处的文字块开头是 --、--- 、—,后面加上出处信息。
块引用可以使用空的注释 .. 分隔上下的块引用。
注意在新的块和出处都要添加一个空行。
下面是引用的内容:
- 用来分隔行, = 用来分隔表头和表体行,| 用来分隔列,+ 用来表示行和列相交的节点。
效果请查看:这里
效果请查看:这里
上面部分
下面部分
https://github.com/SeayXu/
.rst 文件是轻量级标记语言的一种,被设计为容易阅读和编写的纯文本,并且可以借助Docutils这样的程序进行文档处理,也可以转换为HTML或PDF等多种格式,或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。
本文语法来自Quick reStructuredText
由于格式原因,觉得这个不是很直观的话,可以到我的github上查看。
行内样式
斜体
重点、解释文字*重点(emphasis)通常显示为斜体* `解释文字(interpreted text)通常显示为斜体`
重点(emphasis)通常显示为斜体
粗体
重点强调**重点强调(strong emphasis)通常显示为粗体**
重点强调(strong emphasis)通常显示为粗体
等宽
``行内文本(inline literal)通常显示为等宽文本,空格可以保留,但是换行不可以。``
行内文本(inline literal)通常显示为等宽文本,空格可以保留,但是换行不可以。
章节标题
章节头部由下线(也可有上线)和包含标点的标题 组合创建, 其中下线要至少等于标准文本的长度。可以表示标题的符号有 =、-、`、:、'、"、~、^、_ 、* 、+、 #、<、> 。
对于相同的符号,有上标是一级标题,没有上标是二级标题。
标题最多分六级,可以自由组合使用。
全加上上标或者是全不加上标,使用不同的 6 个符号的标题依次排列,则会依次生成的标题为H1-H6。
========= 一级标题 ========= 二级标题 ========= 一级标题 ^^^^^^^^ 二级标题 --------- 三级标题 >>>>>>>>> 四级标题 ::::::::: 五级标题 ''''''''' 六级标题 """"""""
一级标题
二级标题
一级标题
二级标题
三级标题
四级标题
五级标题六级标题
段落
段落是被空行分割的文字片段,左侧必须对齐(没有空格,或者有相同多的空格)。缩进的段落被视为引文。
列表
符号列表(Bullet Lists)
符号列表可以使用 -、*、+ 来表示。不同的符号结尾需要加上空行,下级列表需要有空格缩进。
- 符号列表1 - 符号列表2 + 二级符号列表1 - 二级符号列表2 * 二级符号列表3 * 符号列表3 + 符号列表4
符号列表1
符号列表2
二级符号列表1
二级符号列表2
二级符号列表3
符号列表3
符号列表4
枚举(顺序)列表(Enumerated Lists)
枚举列表算即顺序(序号)列表,可以使用不同的枚举序号来表示列表。可以使用的枚举有:
阿拉伯数字: 1, 2, 3, ... (无上限)。
大写字母: A-Z。
小写字母: a-z。
大写罗马数字: I, II, III, IV, ..., MMMMCMXCIX (4999)。
小写罗马数字: i, ii, iii, iv, ..., mmmmcmxcix (4999)。
可以为序号添加前缀和后缀,下面的是被允许的。
. 后缀: "1.", "A.", "a.", "I.", "i."。
() 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 后缀: "1)", "A)", "a)", "I)", "i)"。
枚举列表可以结合 # 自动生成枚举序号。
1. 枚举列表1 #. 枚举列表2 #. 枚举列表3 (I) 枚举列表1 (#) 枚举列表2 (#) 枚举列表3 A) 枚举列表1 #) 枚举列表2 #) 枚举列表3
枚举列表1
枚举列表2
枚举列表3
I. 枚举列表1
II. 枚举列表2
III. 枚举列表3
A. 枚举列表1
B. 枚举列表2
C. 枚举列表3
定义列表(Definition Lists)
定义列表可以理解为解释列表,即名词解释。条目占一行,解释文本要有缩进;多层可根据缩进实现。
定义1 这是定义1的内容 定义2 这是定义2的内容
定义1
这是定义1的内容
定义2
这是定义2的内容
字段列表(Field Lists)
:标题: reStructuredText语法说明 :作者: - Seay - Seay1 - Seay2 :时间: 2016年06月21日 :概述: 这是一篇 关于reStructuredText 语法说明。
标题: reStructuredText语法说明
作者:
Seay
Seay1
Seay2
时间: 2016年06月21日
概述: 这是一篇 关于reStructuredText
语法说明。
选项列表(Option Lists)
选项列表是一个类似两列的表格,左边是参数,右边是描述信息。当参数选项过长时,参数选项和描述信息各占一行。选项与参数之间有一个空格,参数选项与描述信息之间至少有两个空格。
-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 |
块(Blocks)
文字块(Literal Blocks)
文字块就是一段文字信息,在需要插入文本块的段落后面加上 ::,接着一个空行,然后就是文字块了。文字块不能定顶头写,要有缩进,结束标志是,新的一段文本贴开头,即没有缩进。
下面是文字块内容: :: 这是一段文字块 同样也是文字块 还是文字块 这是新的一段。
下面是文字块内容:
这是一段文字块 同样也是文字块 还是文字块
这是新的一段。
行块(Line Blocks)
行块对于地址、诗句以及无装饰列表是非常有用的。行块是以 | 开头,每一个行块可以是多段文本。| 前后各有一个空格。
下面是行块内容: | 这是一段行块内容 | 这同样也是行块内容 还是行块内容 这是新的一段。
下面是行块内容:
这是一段行块内容 这同样也是行块内容 还是行块内容
这是新的一段。
块引用(Block Quotes)
块引用是通过缩进来实现的,引用块要在前面的段落基础上缩进。通常引用结尾会加上出处(attribution),出处的文字块开头是 --、--- 、—,后面加上出处信息。
块引用可以使用空的注释 .. 分隔上下的块引用。
注意在新的块和出处都要添加一个空行。
下面是引用的内容: “真的猛士,敢于直面惨淡的人生,敢于正视淋漓的鲜血。” --- 鲁迅 .. “人生的意志和劳动将创造奇迹般的奇迹。” — 涅克拉索
下面是引用的内容:
“真的猛士,敢于直面惨淡的人生,敢于正视淋漓的鲜血。” —鲁迅 “人生的意志和劳动将创造奇迹般的奇迹。” —涅克拉索
文档测试块(Doctest Blocks)
文档测试块是交互式的Python会话,以 >>> 开始,一个空行结束。>>> print "This is a doctest block." This is a doctest block.
>>> print "This is a doctest block." This is a doctest block.
表格(Tables)
reStructuredText提供两种表格:网格表(Grid Tables),简单表(Simple Tables)。网格表(Grid Tables)
网格表中使用的符号有:-、=、|、+。- 用来分隔行, = 用来分隔表头和表体行,| 用来分隔列,+ 用来表示行和列相交的节点。
Grid table: +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
效果请查看:这里
简单表(Simple Tables)
简单表相对于网格表,少了 | 和 + 两个符号,只用 - 和 = 表示。Simple table: ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ======
效果请查看:这里
分隔符
分隔符就是一条水平的横线,是由 4 个 - 或者更多组成,需要添加换行。上面部分 ------------ 下面部分
上面部分
下面部分
超链接
介绍各类带有链接性质的超链接自动超链接
reStructuredText会自动将网址生成超链接。https://github.com/SeayXu/
https://github.com/SeayXu/
外部超链接(External Hyperlink)
引用/参考(reference),是简单的形式,只能是一个词语,引用的文字不能带有空格。这篇文章来自我的Github,请参考 reference_。 .. _reference: https://github.com/SeayXu/[/code] 引用/参考(reference),行内形式,引用的文字可以带有空格或者符号。这篇文章来自我的Github,请参考 `SeayXu <https://github.com/SeayXu/>`_。
这篇文章来自我的Github,请参考 SeayXu。内部超链接|锚点(Internal Hyperlink)
更多信息参考 引用文档_ 这里是其他内容 .. _引用文档: 这是引用部分的内容
更多信息参考 引用文档
这里是其他内容
这是引用部分的内容匿名超链接(Anonymous hyperlink)
词组(短语)引用/参考(phrase reference),引用的文字可以带有空格或者符号,需要使用反引号引起来。这篇文章参考的是:`Quick reStructuredText`__。 .. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html[/code] 这篇文章来自我的Github,请参考 Quick reStructuredText。间接超链接(Indirect Hyperlink)
间接超链接是基于匿名链接的基础上的,就是将匿名链接地址换成了外部引用名_。SeayXu_ 是 `我的 GitHub 用户名`__。 .. _SeayXu: https://github.com/SeayXu/ __ SeayXu_
SeayXu 是 我的 GitHub 用户名。隐式超链接(Implicit Hyperlink)
小节标题、脚注和引用参考会自动生成超链接地址,使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。第一节 介绍 =========== 其他内容... 隐式链接到 `第一节 介绍`_,即可生成超链接。
第一节 介绍
其他内容...
隐式链接到 第一节 介绍,即可生成超链接。替换引用(Substitution Reference)
替换引用就是用定义的指令替换对应的文字或图片,和内置指令(inline directives)类似。这是 |logo| github的Logo,我的github用户名是:|name|。 .. |logo| image:: https://help.github.com/assets/images/site/favicon.ico .. |name| replace:: SeayXu
这是
GitHub的Logo,我的github用户名是:SeayXu。脚注引用(Footnote Reference)
脚注引用,有这几个方式:有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。
手工序号可以和#结合使用,会自动延续手工的序号。
# 表示的方法可以在后面加上一个名称,这个名称就会生成一个链接。脚注引用一 [1]_ 脚注引用二 [#]_ 脚注引用三 [#链接]_ 脚注引用四 [*]_ 脚注引用五 [*]_ 脚注引用六 [*]_ .. [1] 脚注内容一 .. [2] 脚注内容二 .. [#] 脚注内容三 .. [#链接] 脚注内容四 链接_ .. [*] 脚注内容五 .. [*] 脚注内容六 .. [*] 脚注内容七
脚注引用一 [1]
脚注引用二 [3]
脚注引用三 [4]
脚注引用四 [*]
脚注引用五 [†]
脚注引用六 [‡]
[1] 脚注内容一
[2] 脚注内容二
[3] 脚注内容三
[4] 脚注内容四 链接
[*] 脚注内容五
[†] 脚注内容六
[‡] 脚注内容七引用参考(Citation Reference)
引用参考与上面的脚注有点类似。引用参考的内容通常放在页面结尾处,比如 [One]_,Two_ .. [One] 参考引用一 .. [Two] 参考引用二
引用参考的内容通常放在页面结尾处,比如 [One],Two注释(Comments)
注释以 .. 开头,后面接注释内容即可,可以是多行内容,多行时每行开头要加一个空格。.. 我是注释内容 你们看不到我
关于 指令(Directives),在下一篇中专门做语法说明。
如果有不正确的地方,希望你能指出。
相关文章推荐
- PHP Json格式化时间处理
- Qt5.7新特性
- MyEclipse2014导入web项目常见问题设置
- Spring中IOC和AOP的详细解释
- jsp页面动态展示list-使用<select>和<c:forEach>标签
- cin、cin.get()、cin.getline()、getline()、gets()等函数的用法
- vim 编辑器常用快捷命令用法
- go revel框架搭建
- TCP-IP 三次握手-四次挥手
- 如何查看linxu是32位的还是64位的
- 类成员变量和实例成员变量分别指什么有什么区别?
- decltype类型指示符
- serialVersionUID作用
- AFNetworking 3.0 https 报错问题 CFNetwork SSLHandshake failed (-9801)
- JHTP自测题_第五章_控制语句Part 2-逻辑运算符
- 堆排序
- KMP算法&next数组总结
- Qt5.7新特性
- Android系统编译与测试
- http://blog.csdn.net/mr_raptor/article/category/799879/3