1. 准备部分¶
备注
Sphinx 项目需要 Python 环境来支持,在此不对如何安装 Python 进行说明. 有需要的可以通过 Python官网 单独下载.
1.1. 安装 Sphinx 并下载必要的包¶
安装 Sphinx 库以及 sphinx-rtd-theme 主题库。
pip install sphinx
pip install sphinx-rtd-theme
1.2. 在项目根目录运行生成文档命令 sphinx-quickstart¶
Eugene-Forest@DESKTOP-4BMMHQP MINGW64 ~/workspace-vscode/ReadTheDocs/NewDocs
$ sphinx-quickstart
欢迎使用 Sphinx 4.3.2 快速配置工具。
请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。
已选择根路径：.
有两种方式来设置 Sphinx 输出的创建目录：
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]:
项目名称将会出现在文档的许多地方。
> 项目名称: newbooks
> 作者名称: eugene
> 项目发行版本 []: 0.1
如果用英语以外的语言编写文档，
你可以在此按语言代码选择语种。
Sphinx 会把内置文本翻译成相应语言的版本。
支持的语言代码列表见：
http://sphinx-doc.org/config.html#confval-language。
> 项目语种 [en]: zh_CN
创建文件 C:\Users\qaz22\workspace-vscode\ReadTheDocs\NewDocs\conf.py。
创建文件 C:\Users\qaz22\workspace-vscode\ReadTheDocs\NewDocs\index.rst。
创建文件 C:\Users\qaz22\workspace-vscode\ReadTheDocs\NewDocs\Makefile。
创建文件 C:\Users\qaz22\workspace-vscode\ReadTheDocs\NewDocs\make.bat。
完成：已创建初始目录结构。
你现在可以填写主文档文件 C:\Users\qaz22\workspace-vscode\ReadTheDocs\NewDocs\index.rst 并创建其他文档源文件了
。 用 Makefile 构建文档，例如：
make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。
最后生成的项目结构如下：
build 、 _build 文件夹: 用来存放通过make html生成文档网页文件
source 文件夹: 存放用于生成文档的源文件
conf.py 文件: Sphinx的配置文件
index.rst 文件: 主文档
_static 、 _template 文件夹: 用来存放静态文件或模板html
图 1.2.1 非独立的源文件和构建目录¶
图 1.2.2 独立的源文件和构建目录¶
1.3. 配置主题¶
在conf.py文件中配置以下属性以替换主题：
# 头部添加导入
import sphinx_rtd_theme
# 找到主题属性更改如下
html_theme = 'sphinx_rtd_theme'
备注
更多主题配置点击查看 HTML Theme 笔记.
1.4. 通过vscode的git插件创建存储库¶
创建完之后，添加.gitignore文件以及README.md文件
本项目的.gitignore文件代码如下：
/.vscode
/source/_build/*
/build/*
*.class
本项目的README.md文件代码如下：
# 一个用于快速创建 `Sphinx` 文档的模板
[](https://a-sphinx-book-template.readthedocs.io/zh/latest/?badge=latest)
## `MyST Markdown`
推荐使用 MyST Markdown 作为编写文档的语言。
### 为什么使用 `MyST Markdown`
虽然 Markdown 无处不在，但它的功能还不足以编写现代的、功能齐全的文档。为此需要一些 Markdown 支持功能，但没有围绕这些功能的各种语法选择的社区标准。
而 Sphinx 是一个用 Python 编写的文档生成框架。它大量使用了 reStructuredText 语法，这是另一种用于编写文档的标记语言。特别是，Sphinx 定义了两个非常有用的扩展点： 内联角色和块级指令。
MyST 试图将 Markdown 的简单性和可读性与 reStructuredText 和 Sphinx 平台的强大功能和灵活性相结合。它以 CommonMark 降价规范为基础，并有选择地添加了一些额外的语法片段以利用 reStructuredText 最强大的部分。
### `MyST Markdown` 、 `reStructuredText` 和 `Sphinx` 之间的关系
MyST Markdown 提供了与 reStructuredText 语法等效的 Markdown，这意味着您可以在 MyST 中做任何可以用 reStructuredText 做的事情。
Sphinx 文档引擎支持多种不同的输入类型。默认情况下，Sphinx 读取reStructuredText ( .rst) 文件。Sphinx 使用解析器将输入文件解析为它自己的内部文档模型（由核心 Python 项目 docutils 提供）。
MyST 解析器是用于 MyST 降价语言的 Sphinx 解析器。当您使用它时，Sphinx 将知道如何解析包含 MyST Markdown 的内容文件（默认情况下，Sphinx 会假设任何以 结尾的文件.md都是用 MyST Markdown 编写的）。一旦文档被解析为 Sphinx，无论它是用 rST 还是 MyST Markdown 编写的，它的行为都是一样的。
```
myst markdown (.md) ------> myst parser ---+
|
+-->Sphinx document (docutils)
|
reStructuredText (.rst) --> rst parser ----+
```
## 本地运行环境推荐配置
[`Sphinx`](https://www.sphinx-doc.org/zh_CN/master/index.html) 项目需要 `Python` 环境来支持,在此不对如何安装 `Python` 进行说明。 有需要的可以通过 [Python官网](https://www.python.org/) 单独下载。
### 本机安装 `Sphinx` 和其他必要的包
本机要运行需要向 `Python` 环境中添加一些必要的包，以及提高编写效率的插件包如：`sphinx-autobuild` 。
```powershell
pip install sphinx
pip install myst-parser
pip install sphinx-rtd-theme
pip install sphinx-design
pip install sphinx-autobuild
pip install sphinx-copybutton
```
### 在 `VS Code` 中安装推荐插件
笔者使用 VS Code 编写此项目的，因为 VS Code 提供了我们所需的语法高亮和提示功能。
* `MyST-Markdown VS Code` ： `MyST` 扩展语法高亮
* `reStructuredText` ： 这个扩展为 `Visual Studio Code` 提供了丰富的 `reStructuredText` 语言支持。现在，您可以使用 `VS Code` 提供的优秀的 IDE-like 接口编写 `reStructuredText` 脚本。
* `reStructuredText Syntax highlighting` ：这个扩展为 `reStructuredText` 提供了丰富的语法高亮显示和非侵入式节导航。
* `Markdown All in One` ：`Visual Studio Code` 的 `Markdown` 支持
### 运行和预览
在配置完本地的项目运行环境后，我们就可以运行此项目。由于现有的 `VS Code` 中没有支持 `MyST Markdown` 的预览插件，所以我们选需要通过 `Python` 环境安装 `sphinx-copybutton` 包来支持 `Sphinx` 文档工具的热部署功能。
> 需要注意的是，`sphinx-copybutton` 插件对文档索引的更新没办法做到动态更新，所以如果在对项目文档的目录修改后，会出现不同页面的左侧边栏目录不同的情况。
### 通过 `bash` 终端执行自动构建工具
我们可以通过命令行来执行 autobuild.sh 文件，打开 bash 终端然后直到此项目的根目录( `source` 目录的父目录)，然后执行命令 `$ ./autobuild.sh`。
### 通过 `powershell` 终端执行自动构建工具
我们可以通过命令行来执行 autobuild.bat 文件，打开 bash 终端然后直到此项目的根目录( `source` 目录的父目录)，然后执行命令 `> .\autobuild.sh`。
> 需要优化，即在运行前判断 source 文件夹下是否存在 _build 文件夹，若存在则删除自动构建或预览产生的html等文件
## `Read The Docs` 运行环境推荐配置
我们对 Read The Docs 的配置全部在 `.readthedocs.yaml` 和 `requirements/requirements.txt` 文件中，这些文件的配置会覆盖 Read The Docs 平台中的项目的配置。
## 样板主目录文件 `source/index.md` 和语法运行结果示例文件夹 `source/syntax/..`
参考样板目录文件 `source/index.md` ，我们可以新建一个自定义的目录文件，然后参考示例文件夹编写笔记；当然，也可以使用自己的方式来编写。至于此模板的语法，可以参考示例文件有选择地适用。
1.6. 不同文件下的 tab 键行为控制¶
这个功能配置可选择性添加，如果不使用 rst 文件编写笔记，那么这个功能也没有用；但是如果你打算使用 rst 文件编写笔记，甚至打算使用 rst 和 md 文件混合编写笔记，那么就有必要控制 tab 键的行为，因为 RestructureText 语法中的指令的内容和可选项都需要缩进 3个空格。，虽然可以连击三个 space，但是显然直接使用 tab 键更快捷。
由于笔者使用 VsCode 编写笔记，然后发现通过分别设置 用户、工作区、文件夹的 settings.json 文件中的 "editor.tabSize": 3 属性都没有很好的设置到 tab 的空格数。所以笔者索性通过插件 EditorConfig for Visual Studio Code 使用 .editorconfig 文件来格式化不同文件下的 tab 键。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | # EditorConfig is awesome: https://EditorConfig.org
# top-most EditorConfig file 表示是最顶层的配置文件，发现设为true时，才会停止查找.editorconfig文件
root = true
# Set default charset
[*.{rst,py,md,txt,html,xml,java}]
charset = utf-8
# Unix-style newlines with a newline ending every file 对于所有的文件 始终在文件末尾插入一个新行
[*]
end_of_line = lf
insert_final_newline = true
# 4 space indentation 控制py文件类型的缩进大小
[*.{py,md,java}]
indent_style = space
indent_size = 4
[*.rst]
indent_style = space
indent_size = 3
|