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)通常显示为斜体*
`解释文字(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. 枚举列表1
  2. 枚举列表2
  3. 枚举列表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/

引用/参考(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

这篇文章来自我的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

[One] 参考引用一

[Two] 参考引用二

注释(Comments)

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

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

关于 指令(Directives),在下一篇中专门做语法说明。

如果有不正确的地方,希望你能指出。

reStructuredText(rst)快速入门语法说明的更多相关文章

  1. aardio 编程语言快速入门 —— 语法速览

    本文仅供有编程基础的用户快速了解常用语法.如果『没有编程基础』 ,那么您可以通过学习任何一门编程语言去弥补你的编程基础,不同编程语言虽然语法不同 -- 编程基础与经验都是可以互通的.我经常看到一些新手 ...

  2. HTML/CSS快速入门

    Web概念 JavaWeb 使用java语言开发基于互联网的项目 软件架构 C/S架构:Client/Server 客户端/服务器 用户本地有一个客户端程序,在远程有一个服务端程序 如QQ,英雄联盟. ...

  3. Objective-C基础语法快速入门

    Objective-C基础语法快速入门 2010-11-04 16:32 折酷吧 zheku8 字号:T | T 假如我们对面向对象的思维已经C语言都很熟悉的话,对于我们学习Objective-C将会 ...

  4. Hadoop生态圈-Hive快速入门篇之HQL的基础语法

    Hadoop生态圈-Hive快速入门篇之HQL的基础语法 作者:尹正杰 版权声明:原创作品,谢绝转载!否则将追究法律责任. 本篇博客的重点是介绍Hive中常见的数据类型,DDL数据定义,DML数据操作 ...

  5. python 基本语法速览,快速入门

    https://zhuanlan.zhihu.com/p/24536868 学习参考于这个博文. 我做一个笔记. 关于python一些常用的语法快速的预览,适合已经掌握一门编程语言的人.零基础,没有任 ...

  6. Vue 1-- ES6 快速入门、vue的基本语法、vue应用示例,vue基础语法

    一.ES6快速入门 let和const let ES6新增了let命令,用于声明变量.其用法类似var,但是声明的变量只在let命令所在的代码块内有效. { let x = 10; var y = 2 ...

  7. C#快速入门笔记(1)——基础语法

    C#快速入门笔记(1)——基础语法 总体框架:

  8. Scala快速入门 - 基础语法篇

    本篇文章首发于头条号Scala快速入门 - 基础语法篇,欢迎关注我的头条号和微信公众号"大数据技术和人工智能"(微信搜索bigdata_ai_tech)获取更多干货,也欢迎关注我的 ...

  9. Less 语法快速入门

    Less 语法快速入门 Less 是一门 CSS 预处理语言其可以运行在 Node 或浏览器端. 它将传统的 css 样式结构单一的排版顺序进行了优化,让我们可以通过层级嵌套的方式将 css 类名与H ...

随机推荐

  1. 【走过巨坑】android studio对于jni调用及运行闪退无法加载库的问题解决方案

    相信很多小伙伴都在android开发中遇到调用jni的各种巨坑,因为我们不得不在很多地方用到第三方库so文件,然而第三方官方通常都只会给出ADT环境下的集成方式,而谷歌亲儿子android studi ...

  2. 以向VS 程序打包集成自动写入注册表功能为例,介绍如何实现自由控制安装过程

    最近由于项目部署时需要更灵活的控制程序安装的流程以及自定义安装行为,特意研究了一下VS程序打包,把解决办法和大家分享一下. 以VS2010为例: 这是一个已经设置好最基本的Visual Studio ...

  3. c# Enumerable中Aggregate和Join的使用

    参考页面: http://www.yuanjiaocheng.net/ASPNET-CORE/asp.net-core-environment.html http://www.yuanjiaochen ...

  4. [修正] Firemonkey TFrame 存档后,下次载入某些事件连结会消失(但源码还在)

    问题:Firemonkey TFrame 存档后,下次载入某些事件连结会消失(但源码还在) 解决:(暂时方法) type TTestFrame = class(TFrame) public const ...

  5. Linux实战教学笔记08:Linux 文件的属性(上半部分)

    第八节 Linux 文件的属性(上半部分) 标签(空格分隔):Linux实战教学笔记 第1章 Linux中的文件 1.1 文件属性概述(ls -lhi) linux里一切皆文件 Linux系统中的文件 ...

  6. 高级渲染技巧和代码示例 GPU Pro 7

    下载代码示例 移动设备正呈现着像素越来越高,屏幕尺寸越来越小的发展趋势. 由于像素着色的能耗非常大,因此 DPI 的增加以及移动设备固有的功耗受限环境为降低像素着色成本带来了巨大的压力. MSAA 有 ...

  7. BZOJ 3110: [Zjoi2013]K大数查询 [树套树]

    3110: [Zjoi2013]K大数查询 Time Limit: 20 Sec  Memory Limit: 512 MBSubmit: 6050  Solved: 2007[Submit][Sta ...

  8. Lesson 17 Always young

    Text My aunt Jennifer is an actress. She must be at least thirty-five years old. In spit of this, sh ...

  9. 2000条你应知的WPF小姿势 基础篇<40-44 启动关闭,Xaml,逻辑树>

    在正文开始之前需要介绍一个人:Sean Sexton. 来自明尼苏达双城的软件工程师.最为出色的是他维护了两个博客:2,000Things You Should Know About C# 和 2,0 ...

  10. ASP.NET Web API WebHost宿主环境中管道、路由

    ASP.NET Web API WebHost宿主环境中管道.路由 前言 上篇中说到ASP.NET Web API框架在SelfHost环境中管道.路由的一个形态,本篇就来说明一下在WebHost环境 ...