vs code 中使用 reStructuredText

什么是reStructuredText 与 Sphinx

reStructuredText（RST、ReST或reST）是一种用于文本数据的文件格式，主要用于 Python 编程语言社区的技术文档。

它是Python Doc-SIG（Documentation Special Interest Group）的 Docutils 项目的一部分，旨在为 Python 创建一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation（pod）的工具。Docutils 可以从 Python 程序中提取注释和信息，并将它们格式化为各种形式的程序文档。
从这个意义上说，reStructuredText 是一种轻量级标记语言，其设计目的是（a）文档处理软件（如Docutils）可以处理它，（b）读和写 Python 源代码的程序员很容易读它

Sphinx是从reStructuredText文档生成HTML / PDF的工具。

安装Python，Sphinx和其他（0.0.14及更高版本）

下载python版本2.7.10或更高版本（建议使用版本3.4）。
如果要在Windows上安装，请确保将Python安装目录和Python脚本目录都添加到了PATH环境变量中。例如，如果将Python安装到c:\python34目录中，则将添加c:\python34;c:\python34\scripts到PATH环境变量中。
通过打开命令提示符并运行以下Python命令来安装Sphinx。（请注意，此操作可能需要几分钟才能完成。）

pip install sphinx sphinx-autobuild
安装restructuredtext-lint以启用linter支持。

pip install restructuredtext-lint

请注意，有关如何安装Python和sphinx的最新步骤，请参考本文。

开始sphinx和rst工作

sphinx-quickstart
欢迎使用 Sphinx 2.2.2 快速配置工具。

请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：.

布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]:

项目名称会出现在文档的许多地方。
> 项目名称: jon_doc
> 作者名称: jon
> 项目发行版本 []: 0.01

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 项目语种 [en]: zh_CN

创建文件 ./conf.py。
创建文件 ./index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

你现在可以填写主文档文件 ./index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
 make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

localhost:hippo200_doc jon$ tree -L 1
.
├── Makefile
├── _build   #  运行make命令后，生成的文件都在这个目录里面
├── _static
├── _templates  #  主题文件
├── conf.py        #  配置文件
├── index.rst      # index
└── make.bat    # 批处理命令

基本完成，使用 make html 命令就可以生成html形式的文档了
这里生成的是html格式的。当然可以生成dirhtml,singlehtml,epub,devhelp,latex,man,texinfo,text等多种格式。

预览
生成的htm目录在工程的_build/html目录
双击html目录下的index.html完成预览

vs code 配置

macos 的vs code配置python3 “Command + ,” 打开settings.json文件,添加以下配置：

找到settings.json

{
    # 输出到终端
    "code-runner.runInTerminal": true, 

    # 更换编辑器解析器路径(换成你自己的)
    "python.pythonPath": "/Library/Frameworks/Python.framework/Versions/3.8/bin/python3",

    # code runner使用python3运行
    "code-runner.executorMap": {
        "python": "python3 -u",
    }
}

VScode配置

安装插件 reStructuredText
点击预览
效果

效果

建立3个模块分别为「api」、「database」、「tool」，把主索引 index.rst 改为：

项目文档
========

.. toctree::
    :maxdepth: 2
    :glob:

    api/index
    database/index
    tool/index

创建 3个目录，每个目录下创建一个 index.rst 文件，也就是二级索引文件。

mkdir api database tool
touch api/index.rst database/index.rst tool/inde.rst

参照目录创建文件，如 api，则在 api 目录下创建如下文件：

cd api
touch 01_environs.rst  02_api.rst     03_slot.rst

每个文件里写上一级标题，然后检查下：

 cat  *.rst

环境说明
=========================
接口文档
=========================
预留
=========================

然后把文件名添加到二级索引 api/index 里

api 接口
==========

这一部分主要介绍 api 接口

.. toctree::
    :maxdepth: 2
    :numbered: 2

    01_environs
    02_api
    03_slot

结构

tree -L 2
.
├── Makefile
├── _build
│   ├── doctrees
│   └── html
├── _static
├── _templates
├── api              # 
│   ├── 01_environs.rst
│   ├── 02_api.rst
│   ├── 03_slot.rst
│   └── index.rst
├── conf.py
├── database          # 
│   ├── 01_detail.rst
│   └── index.rst
├── index.rst
├── make.bat
└── tool              #
    └── index.rst

效果

image.png