.rst 语法+简明教程

2023-05-16

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

reStructuredText入门

reStructuredText简明教程

一、行内样式

单星号: text 强调 (斜体),
双星号: text 重点强调 (粗体),以及
反引号: ``text`` 代码示例。

1. 子体

斜体: * ss *
粗体: ** ssss **
等宽 `` 行内文本(inline literal)通常显示为等宽文本,空格可以保留,但是换行不可以 ``

2. 章节标题

  • 章节头部由下线(也可有上线)和包含标点的标题 组合创建, 其中下线要至少等于标准文本的长度。
  • 可以表示标题的符号有 =、-、`、:、’、"、~、^、_ 、* 、+、 #、<、> 。
  • 对于相同的符号,有上标是一级标题,没有上标是二级标题。
  • 标题最多分六级,可以自由组合使用。
  • 全加上上标或者是全不加上标,使用不同的 6 个符号的标题依次排列,则会依次生成的标题为H1-H6。
=========
一级标题
=========
二级标题
=========

一级标题
^^^^^^^^
二级标题
---------
三级标题
>>>>>>>>>
四级标题
:::::::::
五级标题
'''''''''
六级标题
""""""""

3.段落

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

4. 列表

4.1 符号列表(Bullet Lists)

符号列表可以使用 -、 *、+ 来表示。
不同的符号结尾需要加上空行,下级列表需要有空格缩进。

- 符号列表1
- 符号列表2

  + 二级符号列表1

  - 二级符号列表2

  * 二级符号列表3

* 符号列表3

+ 符号列表4

4.2 枚举(顺序)列表(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

4.3 定义列表(Definition Lists)

定义列表可以理解为解释列表,即名词解释。
条目占一行,解释文本要有缩进;多层可根据缩进实现。

定义1
 这是定义1的内容

定义2
 这是定义2的内容

定义1
这是定义1的内容  

定义2
这是定义2的内容

4.4 字段列表(Field Lists)

:标题: reStructuredText语法说明

:作者:
 - Seay
 - Seay1
 - Seay2

:时间: 2016年06月21日

:概述: 这是一篇
 关于reStructuredText

 语法说明。

标题: reStructuredText语法说明
作者:

Seay
Seay1
Seay2

4.5 选项列表(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

二、超链接

1. 超链接

介绍各类带有链接性质的超链接

1.1 自动超链接

reStructuredText会自动将网址生成超链接。

https://github.com/SeayXu/

https://github.com/SeayXu/

1.2 外部超链接(External Hyperlink)

引用/参考(reference),是简单的形式,只能是一个词语,引用的文字不能带有空格。
这篇文章来自我的Github,请参考 reference_。

.. _reference: https://mp.csdn.net/mdeditor/100424467

引用/参考(reference),行内形式,引用的文字可以带有空格或者符号。
这篇文章来自我的Github,请参考

`mayun<https://mp.csdn.net/mdeditor/100424467>`_。

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

1.3 内部超链接|锚点(Internal Hyperlink)

更多信息参考 引用文档_

这里是其他内容

.. _引用文档:

这是引用部分的内容

更多信息参考 引用文档
这里是其他内容

这是引用部分的内容

1.4匿名超链接(Anonymous hyperlink)

词组(短语)引用/参考(phrase reference),引用的文字可以带有空格或者符号,需要使用反引号引起来。

这篇文章参考的是:`Quick reStructuredText`__。
.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html

这篇文章来自我的Github,请参考 Quick reStructuredText。

1.5 间接超链接(Indirect Hyperlink)

间接超链接是基于匿名链接的基础上的,就是将匿名链接地址换成了外部引用名_。

SeayXu_ 是 `我的 GitHub 用户名`__。

.. _SeayXu: https://github.com/SeayXu/

__ SeayXu_

SeayXu 是 我的 GitHub 用户名。

1.6 隐式超链接(Implicit Hyperlink)

小节标题、脚注和引用参考会自动生成超链接地址,使用小节标题、脚注或引用参考名称作为超链接名称就可以生成隐式链接。

第一节 介绍
===========

其他内容...

隐式链接到 `第一节 介绍`_,即可生成超链接。

<h6 id="id2">第一节 介绍</h6>
其他内容...
隐式链接到 第一节 介绍,即可生成超链接。

2. 替换引用(Substitution Reference)

替换引用就是用定义的指令替换对应的文字或图片,和内置指令(inline directives)类似。

|build| |docs| |license|
.. |build| image:: https://travis-ci.org/googlecartographer/cartographer_ros.svg?branch=master
    :alt: Build Status
    :scale: 100%
    :target: https://travis-ci.org/googlecartographer/cartographer_ros

3.脚注引用(Footnote Reference)

可以使用 [#name]_ 标注在脚注的位置,在文档的最后的 … rubric:: Footnotes 后添加脚注的内容,像这样:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

脚注引用,有这几个方式:有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。

手工序号可以和#结合使用,会自动延续手工的序号。

#表示的方法可以在后面加上一个名称,这个名称就会生成一个链接。

脚注引用一 [1]_
脚注引用二 [#]_
脚注引用三 [#链接]_
脚注引用四 [*]_
脚注引用五 [*]_
脚注引用六 [*]_

.. [1] 脚注内容一
.. [2] 脚注内容二
.. [#] 脚注内容三
.. [#链接] 脚注内容四 链接_
.. [*] 脚注内容五
.. [*] 脚注内容六
.. [*] 脚注内容七

脚注引用一 [1]<a id="id9"></a>
脚注引用二 [3]<a id="id10"></a>
脚注引用三 [4]<a id="id11"></a>
脚注引用四 [*]<a id="id12"></a>
脚注引用五 [†]<a id="id13"></a>
脚注引用六 [‡]<a id="id14"></a>
[1]<a id="id3"></a> 脚注内容一
[2]  脚注内容二
[3]<a id="id4"></a> 脚注内容三
[4]<a id="id5"></a> 脚注内容四 链接  
[*]<a id="id6"></a> 脚注内容五
[†]<a id="id7"></a> 脚注内容六
[‡]<a id="id8"></a> 脚注内容七

3. 嵌入程序代码+注释

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

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

3.1 嵌入式代码

  • 如果需要嵌入大段的程序代码(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);
  • 如果没有合适的段落添加 ::, 也可以在一个空行上添加, 这个双冒号行被忽略:
::

#
# 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,中文标点,. "

4. 表格

普通表格

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

简单表格
注意: 表格包含中文时,基本无法对齐,

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
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!

5 排版

5.1跨章节指引

行文中,经常要对其它章节进行指引,在 html 中对应的就是 锚点链接
rST 中提供了非常优雅的解决:
使用通用元素定义
比如説:

各个章节的首页一般是 index.rst
头一行,习惯性加个聲明:
.. _chapter6index:

那么,在其它任意文本中,随时可以使用:
:ref:`构建 buzz <chapter6index>`
来生成一个指向第二章 首页的链接!

5.2插图/表格指代

行文中,经常对指定插图/表格 进行指代
rST 中提供了非常优雅的解决:
进行通用元素定义
比如说

.. _fig_0601:
.. figure:: ../_static/figs/magic-2.png

   插图 6-1 神奇的2

然后,就可以在任意地方使用 插图 6-1 神奇的2 来指代, 实际输出的就是 “插图 6-1 神奇的2”

本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)

.rst 语法+简明教程 的相关文章

  • evo评测VINS-MONO---TUM数据集

    为了想测试室外场景下VINS MONO定位情况 xff0c 室外环境的KITTY数据集因无时间戳 xff0c EVO测评较困难 故选择TUM数据集 xff0c outdoors1 8 户外 xff1a 在校园内的室外场景拍摄 xff0c 但
  • ROS编译错误:Could not find a package configuration file provided by “XXX“

    解决 xff1a 系统提示缺少什么包 xff0c 就安装什么包即可 xff1a sudo apt get install ros noetic xff0c 依据自己的系统和出错提示更改相关内容 示例 xff1a 1 xff09 CMake
  • ZED2运行VINS-MONO初试

    上篇博客 xff0c 已经完成ZED2的标定 xff0c 获取相关标定参数 xff0c 将在此基础上进行VINS的相关修改 xff0c 实现使用ZED2运行VINS MONO 一 VINS MONO环境搭建 因为系统环境从ubuntu18
  • ZED2双目相机运行VINS-FUSION初试

    基于ZED2运行VINS MONO的经验 xff0c 在运行VINS FUSION前有几点tips想跟大家分享 xff0c 应该能在运行的过程中避免一些踩坑吧 TIPs 1 xff09 关于zed2标定 开始使用Kalibr进行相机单目 双
  • VINS Fusion GPS融合部分

    概述 VINS Fusion在VINS Mono的基础上 xff0c 添加了GPS等可以获取全局观测信息的传感器 xff0c 使得VINS可以利用全局信息消除累计误差 xff0c 进而减小闭环依赖 局部传感器 如相机 xff0c IMU x
  • STM32烧录一次后无法再次烧录

    STM32烧录一次后无法再次烧录 本人是使用cubemx配置stm32 xff0c 在配置sys时没有配置Debug xff0c 所以会导致程序只可以烧录一次的情况 xff0c 再次烧录会发生无法找到芯片的情况 解决方法是将单片机reset
  • Vins-fusion gps融合 KITTY数据集测试

    下载kitti数据集 下载kitti数据集和真值poses的00 txt以及sequences文件00序列的times txt xff0c xff08 全网找了好久 xff0c 最后不得已翻墙从官网down下来的 xff09 代码修改 xf
  • Vins-fusion GPS融合部分测试(自己的数据ZED+RTK)

    经过前一段时间的积累 xff0c 目前暂时成功实现了用自己的数据测试实现Vins fusion 43 GPS融合 xff0c 其实放在数据采集处理上的时间比较多 xff0c 踩了很多坑 xff0c 效果在一些部分还不是很好 xff0c 后期
  • Ceres Solver实例分析

    ceres简介 Ceres solver 是谷歌开发的一款用于非线性优化的库 xff0c 在谷歌的开源激光雷达slam项目cartographer中被大量使用 本篇博客结合相关实例介绍一下 Ceres库 的基本使用方法 xff1a 使用Ce
  • MSCKF算法简介

    感谢 xff1a 紫薯萝卜 https zhuanlan zhihu com p 76341809 论文 xff1a https arxiv org abs 1712 00036 代码 xff1a https github com Kuma
  • API函数详解:CreateSemaphore函数

    Windows API函数 Visual Basic 语法格式声明Declare Function CreateSemaphore Lib 34 kernel32 34 Alias 34 CreateSemaphoreA 34 lpSema
  • java 专业英语词汇

    abstract 关键字 抽象 39 bstr kt access vt 访问 存取 39 kses n 入口 使用权 algorithm n 算法 39 lg riem annotation java 代码注释 n u 39 tei n
  • 自动控制原理(1)-典型环节的传递函数

    构成线性定常控制系统的七个环节 xff1a 比例环节 xff0c 微分环节 xff0c 一阶微分环节 xff0c 二阶微分环节 xff0c 积分环节 xff0c 惯性环节 xff0c 振荡环节 1 比例环节 K为比例系数比例环节又称无惯性环
  • ESP8266从入门到入门系列(一) 你好,ESP8266

    0 前言 转载自我的古月居频道 距离我签约古月居已经过去了一个月了 xff0c 博主因为在这一个月的时间里琐碎的事情非常的多 xff0c 所以也推迟了我发博客的时间 古月居这个平台是以ROS起家的 xff0c 但是我们不能局限于软件 xff
  • BearPi-HM_Nano 鸿蒙os学习笔记(一)-在Windows下搭建开发环境

    BearPi HM Nano 鸿蒙os学习笔记 一 在Windows下搭建开发环境 0 前言 最近HarmonyOS2 0发布了 xff0c 就想着跟上时代的脚步 xff0c 后来在度娘上搜索相关信息 xff0c 发现了一款比较便宜的鸿蒙开
  • 普通数组如何转换成json数据格式

    我们都知道json有很多种格式 xff0c 而开发过程中经常遇到格式转换的问题 xff0c 特别是接口调用的时候 xff0c 如何将普通数组转成我们需要的json格式呢 xff0c 下面我提供了一种方法 xff0c 也是一种思路 xff0c
  • github常用命令(收藏版)

    目录 创建仓库 x1f30f 初始化仓库 x1f30f 查看仓库状态 x1f30f 设置用户信息 x1f30f 创建钥匙 x1f30f 验证钥匙 x1f30f 与远程仓库建立连接 x1f30f 重新设置仓库url地址 x1f30f 初次拉取
  • Android中Parcelable接口用法

    1 Parcelable接口 Interface for classes whose instances can be written to and restored from a Parcel Classes implementing t
  • STM32开发笔记(四)——FreeRTOS

    STM32开发笔记 xff08 四 xff09 FreeRTOS 小狼 64 http blog csdn net xiaolangyangyang 一 FreeRTOS调度原理 FreeRTOS调度分为时间片调度和抢占调度两种 时间片调度
  • 硬件学习之为什么三相电机不需要电容?

    1 单项电机 一个单相电机里一共有两个线圈 xff0c 主线圈和副线圈 当单相正弦电流通过主线圈时 xff0c 主线圈就会产生一个交变脉动磁场 xff0c 这个磁场的强弱随时间作正弦电流变化而变化 xff0c 但在它的方向一直是1 3这个方

随机推荐

  • Orb-slam2+win7+VS2015+USB双目摄像头

    Orb slam2 43 win7 43 VS2015 43 USB双目摄像头 本文将介绍如何在win7上使用USB双目摄像头实现Orb slam2 主要硬件 我们以USB双目摄像头 43 VS2015 43 win7来实现功能 xff1a
  • win7+opencv-2.4.13安装教程

    win7 43 opencv 2 4 13安装教程 本文将介绍如何在win7上安装opencv 2 4 13 一 安装过程 1 下载OpenCV 安装包 xff0c 以opencv 2 4 13 为例 2 双击 opencv 2 4 13
  • WIN7+Visual Studio 2013安装配置教程

    WIN7 43 Visual Studio 2013安装配置 本文将介绍如何在win7上安装Visual Studio 2013 一 xff1a 安装过程 1 下载Visual Studio 2013 安装包 下载之后的文件是 iso 格式
  • Ubuntu18.04 + Orb-Slam3 + USB双目摄像头

    Ubuntu18 04 43 Orb slam3 43 USB双目摄像头 本文将介绍如何在Ubuntu18 04上使用USB双目摄像头实现Orb slam3 主要硬件 我们以USB双目摄像头在Ubuntu18 04上来实现功能 xff1a
  • 树莓派结合Pixhawk飞控实现四轴双目视觉避障

    无人机双目视觉避障的实现 本文将介绍如何使用树莓派结合PIX飞控实现无人机双目视觉避障的功能 主要硬件 我们以双目摄像头 43 树莓派 43 Pixhawk飞控来实现功能 xff1a 双目摄像头与树莓派通过USB接口来连接 xff0c 树莓
  • TypeScript 终极初学者指南

    大家好 xff0c 我是 ConardLi xff0c 在过去的几年里 TypeScript 变得越来越流行 xff0c 现在许多工作都要求开发人员了解 TypeScript xff0c 各大厂的大型项目基本都要求使用 TypeScript
  • STM32——STM32库结构详解

    STM32库是由ST公司针对STM32提供的函数接口 xff0c 即API xff08 application program interface xff09 xff0c 开发者可以调用这些函数接口来配置STM32的寄存器 xff0c 脱离
  • 监控树莓派Raspberry Pi的CPU/GPU的温度

    监控树莓派Raspberry Pi的CPU GPU的温度 树莓派Raspberry Pi的CPU GPU的温度对于Pi的温度 高效运行非常重要 xff0c 所以我们要实时监控树莓派Raspberry Pi的CPU GPU的温度 1 运行环境
  • 【嵌入式系统】二、初识 Tiva TM4C123G系列开发板

    大二电赛小白 思考 主要偏向于嵌入式的应用 xff0c 请大家多多指教 xff01 TM4C123x系列是TI公司推出的一款32位基于ARM Cortex M4的处理器 1 TM4C123GH6PM的M4内核 超低功耗 耗电量370 A M
  • fdisk用法

    NAME fdisk Partition table manipulator for Linux SYNOPSIS fdisk u b sectorsize C cyls H heads S sects device fdisk l u d
  • 用策略模式优化代码的实例

    实例一 xff1a 利用利用策略模式实际开发中 if else 条件判断过多的问题 xff0c 条件少还好 xff0c 一旦 else if 过多这里的逻辑将会比较混乱 xff0c 并很容易出错 比如 xff1a 刚开始条件较少 xff0c
  • 灰度处理与二值化的关系

    当开始接触图像处理的童鞋可能跟我一样对这两个概念迷惑过 xff0c 在图像处理中 xff0c 用RGB三个分量 xff08 R xff1a Red xff0c G xff1a Green xff0c B xff1a Blue xff09 x
  • ucos2历程——信号量集

    信号量集 信号量集由两部分组成 xff1a 标识组和等待任务列表 xff1b 标识组由三部分组成 xff1a 1 OSFlagType 识别是否为信号量集的标志 2 OSFlagWaitList 指向等待任务列表的指针 3 OSFlagFl
  • 人体姿态估计资源大列表(Human Pose Estimation)

    基础 xff1a Human Pose Estimation人体姿态估计综述调研人体姿态估计数据集整理 xff08 Pose Estimation Keypoint xff09 姿态估计的两个数据集COCO和MPII的认识 Human Po
  • DIY小四轴之电路设计(一)

    DIY小四轴之电路设计 xff08 一 xff09 写在前面 前一阵时间一直在做四轴飞行器 xff0c 略有一点收获吧 xff0c 在这里分享出来 xff0c 一方面算是对自己的总结 xff0c 另一方面希望能给想做小四轴的读者一些思路 本
  • DIY小四轴之电路设计(二)

    DIY小四轴之电路设计 xff08 二 xff09 上次我分析了四轴电源的电路 xff0c 这次我们来看电机驱动与传感器电路 三 空心杯电机驱动电路 一般的小型四轴都选用空心杯电机来驱动旋翼 xff0c 空心杯电机不仅节能而且灵敏 xff0
  • ubuntu 18.04 vnc server开机自启动

    转自 xff1a https blog csdn net lixiaotao 1 article details 90140979 1 首先确定vncserver 以正确安装到linux系统 xff1b 2 设置vncserver随系统自启
  • vnc viewer灰屏的解决方法

    vnc能够连接上 xff0c 但是进入界面灰屏 先关闭当前打开的vnc xff1a vncserver kill 88 然后修改权限 xff1a chmod 43 x vnc xstartup 然后重新打开vnc vncserver geo
  • samba 常用命令

    没怎么修改配置 xff0c 但有时需要修改时 xff0c 又是搜索一番 xff0c 故将常用的在此备份一下 修改samba配置 xff1a span class token function sudo span span class tok
  • .rst 语法+简明教程

    reStructuredText 是扩展名为 rst的纯文本文件 xff0c 含义为 34 重新构建的文本 34 xff0c 也被简称为 xff1a RST或reST xff1b 是Python编程语言的Docutils项目的一部分 xff