一文学会Rst文档撰写（使用VS Code）

Rst文档撰写（使用VS Code）

一、基本介绍

reStructuredText

Python社区的相关帮助文件是用rst文档编写的。很多人可能都听过markdown文档，但是大部分人可能都没听过rst文档。
RST（reStructuredText）是一种使用简单标记语法编写文档的文本文件格式。它被广泛应用于编写技术文档、软件说明文件、报告等。RST文件使用一些特定的符号和结构来表示文档的各个部分，比如标题、列表、链接、引用等。RST文件通常以.rst为扩展名。
RST最早由David Goodger于2002年创造并开发。它最初是为了Sphinx文档生成工具而设计的，Sphinx是一个用于创建文档的工具，常用于Python开发者社区，实际上RST文档比Markdown出现的更早。

Sphinx

要编写RST文档，我们需要使用Sphinx工具。Sphinx是Python文档生成器，它基于reStructuredText标记语言，可自动根据项目生成HTML，PDF等格式的文档。新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。

二、环境配置

1.先决环境：已安装Python（我使用的是Python 3.12）
查看Python安装情况：Win+R 运行cmd-> 输入Python
2.通过Python3安装Sphinx
cmd中输入命令并敲击回车：

	pip install sphinx sphinx_intl sphinx_rtd_theme recommonmark

如下所示是顺利安装的状态（篇幅所限没有全部截屏）

三、使用前配置

选择你要作为项目存放位置的文件夹，对其右键，选择“在终端中打开”，进入cmd：

1.输入以下命令打开快速配置工具：

sphinx-quickstart

后续配置如下图所示：

2.Separate source and build directories (y/n) [n] :选择是否将源文件和结构文件分离，这里我们输入y
3.Project name :项目名，自定义即可
4.Author name(s) :作者名，同上
5.Project release [] :自定义版本号，同上
6.Project language [en] :使用的语言，这里我们使用verilog；
以上所有配置都可以在conf.py文件中重新修改。
项目框架如下：
**build：**存放最终生成的文档
**source：**存放Rst文件等，以及引用数据
**Makefile：**批处理指令，使用make命令时用来构建文档输出
conf.py : 一个python文件，存放Sphinx的配置参数
**index.rst ：**文档项目的root目录。多个文件时可用于连接其余文件。

四、编写工具配置（基于VS Code）

在VS Code中安装：Python reStructuredText RST Preview三个插件。

五、编写

在刚才项目结构的source目录下，新建一个rst文件，使用VS Code打开，编写文档即可。

RST 基本语法

标题格式

==============
一级标题
==============

二级标题
==============

三级标题
--------------

四级标题
^^^^^^^^^^^^^^

五级标题
""""""""""""""

六级标题
**************

·这里为了区分明显，我将各级标题的代码之间加了空行。但事实上，连续的标题行间可以没有空行
·标题行下可以直接接正文，但是正文下不能直接接标题行，会报错，例如：

123456789
六级标题
**************

这样的写法就是错误的，应该在正文和新的标题行间加空行。
·各级标题的符号样式不止这一种，RST语言支持许多特殊符号用于划分标题等级
·各级标题的使用要连续，不能随意串用，例如：

二级标题
==============
四级标题
^^^^^^^^^^^^^^

上述情况，在二级标题后直接接一个四级标题，这种用法也会遭遇报错
·关于标题符号写多长的问题
对于分隔号的具体个数，并没有明确的规定，只是必须要比你的标题字符长度略长一些：

二级标题
=========
//如上，就会出现分隔符过短的报错

四级标题
^^^^^^^^^^^^^^^^^^
//如上情况就大致够用了

图片格式

值得一提的是，RST语言不像Markdown可以直接拖拽图片到指定位置插入，而是需要输入特定的代码。
建议在项目目录的source文件夹下建立一个image文件夹。插入图片举例如下：

.. image:: image/1.png

表格格式

我认为表格格式是RST语言比较令人讨厌的一部分语法。它对各单元格的对齐要求极其苛刻。尤其是在表格中中英文字符混杂的时候，输入的代码看起来就并不整齐了。
表格格式也有多种，我本人比较爱用的是这一种，并举范例如下：

+------------------+----------------+----------------+----------+
|      规范号      |主要起草部门专家|主要评审部门专家|  修订情况|
+==================+================+================+==========+
|                  |                |                |          |
+------------------+----------------+----------------+----------+
|                  |                |                |          |
+------------------+----------------+----------------+----------+
|                  |                |                |          |
+------------------+----------------+----------------+----------+
|                  |                |                |          |
+------------------+----------------+----------------+----------+

// 这竟然是能够正常输出表格的，然而代码看起来并不整齐，可笑可笑~

实际效果：

代码格式

代码块的格式相对规整。举范例如下：

::

 #include <stdio.h>
 #include <stdlib.h>
 

·开头要顶格写英文格式的两个冒号::
·两个冒号::后要空一行，否则报错！！
·代码块结尾与其他正文之间也要空一行
·除了两个冒号::顶格，其余所有代码部分都要空一格再写，极其容易出错

六、html文件生成

在项目根目录运行cmd，输入：

sphinx-build -b html source build 

make html

以最终出现下面结果为准：

下面一个命令亦是如此：

以最终出现下面结果为准：

经以上操作，即可生成html文件供预览了。