reStructuredtext快速入门

reStructuredText是一种reStructuredText是一种轻量级的文本标记语言,简单易读,所见即所得的文本标记语言。

其一般保存的文件以.rst为后缀。在必要的时候,.rst文件可以被转化成PDF或者HTML格式,也可以有Sphinx转化为LaTex,man等格式,现在被广泛的用于程序的文档撰写。

段落

段落是reST文档中最基础的部分,段落通过一个或者多个空行分隔开。左侧必须对齐(没有空格,或者有相同多的空格)。

内联标记

标准的reST内联标记包括:粗体、斜体以及引用。

  • *text*:使用一个星号包裹文本表示斜体
  • **text**:使用两个星号包裹文本表示粗体
  • ``text``:使用两个反引号包裹文本表示代码块

如果星号或反引号出现在文本会对行内标记分隔符引起混淆,他们必须用一个反斜杠进行转义。

标记需注意的一些限制:

  • 不能相互嵌套
  • 内容前后不能有空白: 这样写* text* 是错误的,
  • 如果内容需要特殊字符分隔. 使用反斜杠转义,如: this is\ *one*\ word

这些限制在未来版本可能会被改善.

列表与引用

顺序列表

1. 第 **一** 条

   段落

#. 第二条

   1. 小条

#. 第三条

第二条开始后续的条目用 # 开头。第一条的序号不必从 1 开始。

顺序列表包括如下符号样式:

1. 数字

a. 小写字母

A. 大写字母

i) 小写罗马数字

(I) 大写罗马数字

列表前后, 以及条目之间必须有空行隔开. 列表下面可以插入任意的内容, 段落, 图片都可以, 只要他们的左侧和列表的第一个文字左对齐。

无序列表

和顺序列表相似, 使用 “*” “+” “-” 代替数字:

* 列表第一级

  + 第二级

    - 第三级

  + 第二级的另一个项目

自定义列表

或者叫名词解释更确切:

*鸡*
  两条腿, 直立行走, 带翅膀, 有头冠的动物.

*鸭*
  鸡的崇拜者

嵌入程序代码

如果需要嵌入大段的程序代码(SQL, 业务逻辑设置, 配置文件等), 在段落末尾添加两个’:’, 并且代码块需要与周围文本以空行分隔,代码的左侧必须缩进, 代码引用到没有缩进的行为止. 例如:

如果数据库有问题, 执行下面的 SQL::

 # Dumping data for table `item_table`

 INSERT INTO item_table VALUES (
   0000000001, 0, 'Manual', '', '0.18.0',
   'This is the manual for Mantis version 0.18.0.\r\n\r\nThe Mantis manual is modeled after the [url=http://www.php.net/manual/en/]PHP Manual[/url]. It is authored via the \\"manual\\" module in Mantis CVS.  You can always view/download the latest version of this manual from [url=http://mantisbt.sourceforge.net/manual/]here[/url].',
   '', 1, 1, 20030811192655);

高亮代码

可以 用 .. code-block:: 追加各种语法高亮声明:

.. code-block:: python
    :linenos:

    def foo():
        print "Love Python, Love FreeDome"
        print "E文标点,.0123456789,中文标点,. "

引用外部代码:

.. literalinclude:: example.py
    :language: python

表格

普通表格

+------------+------------+-----------+
| 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. |
+------------+------------+-----------+

简单表格

有一些限制,需要有多行,且第一列元素不能分行显示,如下::

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

CSV表格

.. csv-table:: Frozen Delights!
 :header: "Treat", "Quantity", "Description"
 :widths: 15, 10, 30

 "Albatross", 2.99, "On a stick!"
 "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
 crunchy, now would it?"
 "Gannet Ripple", 1.99, "On a stick!"

列表表格

.. list-table:: Frozen Delights!
  :widths: 15 10 30
  :header-rows: 1

  * - Treat
    - Quantity
    - Description
  * - Albatross
    - 2.99
    - On a stick!
  * - Crunchy Frog
    - 1.49
    - If we took the bones out, it wouldn't be
      crunchy, now would it?
  * - Gannet Ripple
    - 1.99
    - On a stick!

超链接

外部链接

使用 链接文本 <http://example.com/>_ 可以插入网页链接。 链接文本是网址,则不需要特别标记,分析器会自动发现文本里的链接或邮件地址。

可以把链接和标签分开, 如下:

段落里包含 `a link`_.

.. _a link: http://example.com/

内部链接

章节

章节是文章的主体结构, 分为 标题 章 节 小节 等. 定义章节的方式是在行的下面添加 ‘=======’, 比如:

标题
====

章
--

节
~~

小节
####

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

# 及上划线表示部分
* 及上划线表示章节
=, 小章节
-, 子章节
^, 子章节的子章节
", 段落

显示标记

显式标用在那些需做特殊处理的reST结构中, 如尾注,突出段落,评论,通用指令.

显式标记以 .. 开始,后跟空白符,与下面段落的缩进一样. (在显示标记与正常的段落间需有空行,这听起来有些复杂,但是写起来会非常直观.)

指令

指令是显式标记最常用的模块。也是reST 的扩展规则, 在 Sphinx 经常被用到。

图像

reST 支持图像指令, 如下

.. image:: gnu.png
   (选项)

这里给出的文件名( gnu.png) 必须是源文件的相对路径,如果是绝对路径则以源目录为根目录. 例如,在文件 sketch/spam.rst 引用图像 images/spam.png ,则使用 ../images/spam.png 或者 /images/spam.png.

Sphinx 会自动将图像文件拷贝到输出目录的子目录里,( 输出HTML时目录为 _static )

注释

有明确标记块但又不是有效的结构标记的标记 (像上面的尾注)都被视为注释,例如:

.. 这是一个评论.

可以通过缩进产生多行注释:

..
   这整个缩进块都是
   一个评论.

   仍是一个评论.

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏雪地二货笔记库

vue学习笔记10-组件

之后就可以在html中<tagName></tagName>来使用它。 自定义组件也分为全局和局部两种,全局可以在任何实例中使用,而局部只有注册后才能使用。 全...

14010
来自专栏陈满iOS

iOS·枚举与整型转换

某项目组之前的小伙伴开发的模块:某页面行距大小根据枚举类型进行设置,现在本人接受项目后,需要添加两个功能,一个按钮增大字体大小,一个按钮缩小字体大小。

55710
来自专栏技术小讲堂

ASP.NET AJAX(13)__利用Microsoft AJAX Library开发客户端组件Sys.Component成员Sys.IDisposable成员Sys.INotifyDisposin

Microsoft AJAX Library定义了一个客户端组件的模型,它的基类是Sys.Component,它实现了三个接口Sys.IDisposable,S...

34450
来自专栏葡萄城控件技术团队

如何将第三方控件嵌入ToolStrip控件,并提供Design-Time支持

最近研究了一下如何将第三方控件嵌入到ToolStrip控件中,并能提供Design-Time下的支持. 下面将详细讲解如何把系统的MonthCalendar控件...

21880
来自专栏视觉求索无尽也

Markdown:技巧进阶参考资料:开始学习:

本文作者:keloli 本文说明:本文首发于2017.08.01,用于收集Markdown排版中的一些技巧,会不断更新。

21720
来自专栏谈补锅

开发中常用的JS知识点集锦

9920
来自专栏mySoul

jQuery(一)

jquery为一种库,属于最基础的一个库,伴随着h5的到来,很多jquery的规则直接融入到了规则本身了,直接使用原生的js也能达到相同的目的。虽然如此,不过依...

27640
来自专栏前端杂货铺

typeof的一些兼容性问题

typeof存在一些兼容性的问题,在IE6,7,8中的DOM和BOM元素及其对象上的方法的判定会出现误差,在safari上对NodeList实例 的判定,对Ex...

358150
来自专栏瓜大三哥

matlab GUI基础1

GUI编程开发 1.句柄图形 是一种面向对象的绘图系统。这些细节一般隐藏在图形M文件的内部,用户通过句柄图形可以定制图形的许多特性,这是使用高级绘图函数无法实现...

30580
来自专栏阮一峰的网络日志

IntersectionObserver API 使用教程

网页开发时,常常需要了解某个元素是否进入了"视口"(viewport),即用户能不能看到它。 ? 上图的绿色方块不断滚动,顶部会提示它的可见性。 传统的实现方法...

41160

扫码关注云+社区

领取腾讯云代金券