RST 和 Markdown

RST 和 Markdown

关键词： vscode rst md sphinx 开发环境

无论是写博客还是相关技术文档，都或多或少会接触到文档文本的编辑，txt不足以满足我们的需求，rst和md文档就应运而生。
本博客系列文档主要使用rst文档编写，也有部分md文档，rst文档预览以及文档编译使用到Sphinx和ReadTheDocs，
编辑器使用vscode，vscode配置参考这里。

主要内容：

• sphinx 环境配置
• sphinx 基本使用
• 文档格式转换
• rst 语法
• md 语法

文档参考：

• Sphinx 使用手册 https://zh-sphinx-doc.readthedocs.io/en/latest/index.html
• Sphinx 主题 http://sphinx-themes.org
• readthedocs 在线托管平台 https://readthedocs.org
• pandoc 文档格式转换工具 https://pandoc.org/installing.html
• rst 转换为 markdown 格式 https://www.cnblogs.com/azureology/p/13438004.html
• rst 官方语法教程 https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html
• 野火 rst 语法教程 https://ebf-contribute-guide.readthedocs.io/zh_CN/latest/rest-syntax/base-syntax.html
• csdn博客模板-系列文章模板

最新地址： https://taotaodiy-linux.readthedocs.io/en/latest/env/rstRule.html

sphinx 环境配置

首先需要安装 vscode和安装插件reStructuredText

接着配置python环境

然后安装 sphinx

pip install sphinx

sphinx 使用

这里演示使用 sphinx 创建一个全新的sphinx工程。

sphinx-quickstart

新建目录 taotaodiy，新建一个 git 仓库，参考git使用。 当然也可以是空目录。然后在该目录下载执行sphinx-quickstart。

Windows可以使用cmd，先切换到该目录再执行sphinx-quickstart，也可以使用VSCode的终端。
Ubuntu就很容易了，命令行直接执行。输出如下：

root@bluseli:/home/share/taotaodiy# sphinx-quickstart
欢迎使用 Sphinx 3.2.1 快速配置工具。

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> 独立的源文件和构建目录（y/n） [n]: Y

The project name will occur in several places in the built documentation.
> 项目名称: taotaodiy
> 作者名称: bluseli
> 项目发行版本 []: 0

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

创建文件 /home/share/taotaodiy/source/conf.py。
创建文件 /home/share/taotaodiy/source/index.rst。
创建文件 /home/share/taotaodiy/Makefile。
创建文件 /home/share/taotaodiy/make.bat。

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

You should now populate your master file /home/share/taotaodiy/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

执行成功，则配置成功。检查目录如下，其中：

<