www.bijishequ.com


关注社区微信公众号: PMvideo

reStructuredText(rst)快速入门语法说明

作者:seayxu 2017-03-15 收录到我的专题

标签 列表 脚注 引用 枚举 标题




图片来自网络/图文无关

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),在下一篇中专门做语法说明。

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



登录 后发表评论

0条评论或问题

社区邀请

笔记社区是一个面向中高端IT开发者、程序员的知识共享社区,通过网络抓取与文章分类总结,由专家为用户提供高质量的专题文章系列。 邀请您成为社区专家 >>

原文链接:http://www.jianshu.com/p/1885d5570b37

声明:所有文章资源均从网络抓取,如果侵犯到您的著作权,请联系删除文章。联系方式请关注微信公众号PMvideo【锤子视频-程序员喜欢的短视频】,笔记社区开发者交流群 628286713。

16

December


相关文章

.Eclipse快捷键大全(收藏)

.手把手教你把基于 eclipse 的项目转换为基于 idea 的项目

.Eclipse 常用快捷键

.最好用的 IntelliJ 插件 Top 10

.我最常用的Intellij IDEA快捷键

.【码云周刊第 48 期】Eclipse 常用的高效插件

.【码云周刊第 50 期】6款国产 IntelliJ IDEA 优秀插件!

.我看过的最全的 LaTeX 零基础入门安装教程( LaTeX + sublime Text + Sumatra PDF反向搜索 + bib格式文件:参考文献引用(及国标化配置))

.Myeclipse 中jQuery代码提示

.IntelliJ IDEA 2017 入门篇


相关专题

300x200

Myeclipse 2017 安装与破解

安装详细步骤省略,仅仅是一路下一步即可,博主默认安装到了C盘,注意:安装完成后不要打开软件,不要打开软件,不要打开软件(安装完成记得取消勾选打开选项),重要的事情说三遍!

1 篇文章
300x200

将eclipse项目转idea

手把手教你把基于 eclipse 的项目转换为基于 idea 的项目

1 篇文章
300x200

Sublime安装与使用技巧-码农进阶必备神器

本专题主要对Sublime Text这款前端开发工具中的非常优秀的特性进行介绍,命令模式、Goto anything、多行游标等这些能极大提高你的生产力,不愧是码农进阶必备神器。

17 篇文章
300x200

消息中间件之Kafka

Kafka是一种高性能的开源消息中间件,目标是提供尽可能高的吞吐量,主要用于日志和分析类业务场景。

0 篇文章
300x200

Docker源码分析

《Docker源码分析》系列文章通过分析解读Docker源码,来让读者了解Docker的内部实现,以更好的使用Docker

10 篇文章
300x200

Android NDK学习笔记

初学者快速掌握Android NDK开发,包括NDK环境搭建、工具使用、调试、JNI和Java相互调用。

15 篇文章
300x200

PHP设计模式

常见的面向对象设计模式大约有23种,但是自从接触PHP后,渐渐发现常见的设计模式好像少了很多,网络上的资料也比较少

20 篇文章
300x200

EasyNetQ

EasyNetQ是一个易于使用的RabbitMQ的.Net客户端API。RabbitMQ是由 LShift 提供的一个 Advanced Message Queuing Protocol(AMQP)的开源实现由以高性能、健壮以及可伸缩性出名的Erlang写成,因此也是继承了这些优点

4 篇文章
300x200

java虚拟机学习

jvm运行时所管理的内存将会分为如下几个区域:程序计数器、虚拟机栈、本地方法栈、方法区、堆区.

3 篇文章
300x200

Laravel入门指南

PHP Web开发框架(PHP Web Framework)它可以让你从面条一样杂乱的代码中解脱出来;它可以帮你构建一个完美的网络APP,而且每行代码都可以简洁、富于表达力。

17 篇文章

精选专题

spring系列 1893篇

ORM 1622篇

缓存 2346篇

分布式服务 1792篇

Nio框架 691篇

并发编程 2110篇

网络基础 18925篇

搜索引擎 962篇

设计模式 2941篇

其他arch 2837篇

计算机基础 2885篇

操作系统 11.2篇

开发工具 3575篇

Nginx 1095篇

JVM虚拟机 1239篇

系统监控 968篇

日志分析 830篇

Hadoop 5091篇

Mongodb 666篇

Android开发 18345篇

IOS开发 640篇

移动游戏 1935篇

React-Native 465篇

前端基础 11854篇

HTML5 12402篇

ReactJs 102篇

AngularJs 354篇

大数据 18102篇

人工智能 9530篇