通识

1. 得益于拥抱开源，微软 VSCode 成为了最热门的 IDE，广泛用于各种场景的编程，比如编辑 reStructuredText 文件。
2. reStructuredText 是 Python 官方文档的格式，属于 Sphinx 项目的一部分，Sphinx 是 Python 文档生成器。
3. 从 reStructuredText 的文件格式 rst，方便转化为各种文件格式。
4. MS Code 自带 reStructuredText 插件，类似于 Markdown，安装后可以用于预览 rst 格式。
5. 可安装后并不能直接预览，还需要配置一番，于是就有了下面的部分。

配置

1. 依据 reStructuredText 文档，先 pip 安装 doc8 和 sphinx

2. 再上 VSCode 配置:

   // Points to the doc8 exectuable.
   "restructuredtext.linter.executablePath": "doc8",
   // Extra arguments to doc8.
   "restructuredtext.linter.extraArgs": ["--max-line-length 1024"],
   // The full path of sphinx-build utility. This is an absolute path, and you can use ${workspaceRoot} to represent workspace root folder.
   "restructuredtext.sphinxBuildPath": "sphinx-build",
   // Flag to control whether text changed event triggers preview update.
   "restructuredtext.updateOnTextChanged": "true",
   

3. 在项目根目录下运行:

   sphinx-quickstart
   

4. 一路回车，即生成了如下文件:

   _build
   _static
   _templates
   conf.py
   index.rst
   make.bat
   Makefile
   

此时可以通过 Ctrl+Shift+R 来预览了

附录

快速参考 sphinx-rest