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文件代码如下：
# NoteBook
[![GitHub last commit][github-badge]][github-link]
[![Documentation Status][rtd-badge]][rtd-link]
这是笔者在学习过程中的一些笔记，可能包括软件的安装配置、技术的知识点、技术的使用技巧、软件的使用方法、以及学习过程当中的感悟、学习过程中出现的疑问以及疑问的解决。
本项目是通过 [Sphinx](https://www.sphinx-doc.org/zh_CN/master/index.html) 工具来实现的，使用了并涉及了 [reStructureText](https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/index.html) 、 Markdown 、[MyST](https://myst-parser.readthedocs.io/en/latest/index.html) 标记语言以及其他基于这些语言的 Sphinx 插件扩展语法来编写文档，并托管与 [Read the Docs](https://readthedocs.org/) 平台运行。
项目分为三个分支。其中， **main** 分支是主分支，是 **k-doc** 和 **builder-doc** 分支的结合；而 **k-doc** 分支记载笔者的工作、学习的笔记和感悟；而 **builder-doc** 分支主要是介绍本项目的相关编写语法和工具，涉及 [MyST](https://myst-parser.readthedocs.io/en/latest/index.html) 、 [reStructureText](https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/index.html) 和 [Sphinx](https://www.sphinx-doc.org/zh_CN/master/index.html) 文档工具和插件等。
## 关于 `MyST`
*MyST* (*Markedly Structured Text*) 建立在 *markdown-it* 定义的标记之上，所以 *MyST* 遵守 [CommonMark 规范](https://spec.commonmark.org/)。为此，它使用了 [markdown-it-py 解析器](https://github.com/executablebooks/markdown-it-py)，这是一个结构良好的 *Python* 降价解析器，符合 *CommonMark* 规范且可扩展。
*MyST* 向 *CommonMark* 添加了几个新的语法选项，以便与 *Sphinx* 一起使用，而 *Sphinx* 是 *Python* 生态系统中广泛使用的文档生成引擎。
## 为什么使用 `MyST`
虽然 *Markdown* 无处不在，但它的功能还不足以编写现代的、功能齐全的文档。为此需要一些 *Markdown* 支持功能，但没有围绕这些功能的各种语法选择的社区标准。
*Sphinx* 是一个用 *Python* 编写的文档生成框架。它大量使用了 *reStructuredText* 语法，这是另一种用于编写文档的标记语言。特别是， *Sphinx* 定义了两个非常有用的扩展点： 内联角色和块级指令。
*MyST* 试图将 *Markdown* 的简单性和可读性与 *reStructuredText* 和 *Sphinx* 平台的强大功能和灵活性相结合。它从 *CommonMark* 降价规范开始，并有选择地添加了一些额外的语法片段以利用 *reStructuredText* 最强大的部分。
## `MyST` 、 `reStructuredText` 和 `Sphinx` 之间的关系
*MyST* 提供了与 *reStructuredText* 语法等效的 *Markdown* ，这意味着您可以在 *MyST* 中做任何可以用 *reStructuredText* 做的事情。
*Sphinx* 文档引擎支持多种不同的输入类型。默认情况下， *Sphinx* 读取 *reStructuredText* ( `.rst`) 文件。 *Sphinx* 使用解析器将输入文件解析为它自己的内部文档模型（由核心 *Python* 项目 `docutils` 提供）。
开发人员可以扩展 *Sphinx* 以支持其他类型的输入文件。任何内容文件都可以读入 *Sphinx* 文档结构，前提是有人为该文件编写了 解析器。一旦内容文件被解析为 *Sphinx* ，它的行为与任何其他内容文件几乎相同，无论它是用什么语言编写的。
*MyST* 解析器是用于 *MyST* 降价语言的 *Sphinx* 解析器。当您使用它时， *Sphinx* 将知道如何解析包含 *MyST* 的内容文件（默认情况下， *Sphinx* 会假设任何以 结尾的文件.md都是用 *MyST* 编写的）。一旦文档被解析为 *Sphinx* ，无论它是用 `rST` 还是 *MyST* 编写的，它的行为都是一样的。
```
myst markdown (.md) ------> myst parser ---+
|
+-->Sphinx document (docutils)
|
reStructuredText (.rst) --> rst parser ----+
```
## 项目对应的电子书在线查看
本项目已经挂载在 [Read the Docs](https://readthedocs.org/) 中，点击下方链接即可在线查看项目的实现即电子书。链接如下： https://studynotes.readthedocs.io/zh/k-doc
## 关于免费的开源托管平台 Read the Docs
[Read the Docs](https://readthedocs.org/) 通过自动为您构建，版本控制和托管文档来简化软件文档。
[github-badge]: https://img.shields.io/github/last-commit/Eugene-Forest/NoteBook
[github-link]: https://img.shields.io/github/last-commit/Eugene-Forest/NoteBook
[rtd-badge]: https://readthedocs.org/projects/studynotes/badge/?version=main
[rtd-link]: https://studynotes.readthedocs.io/zh/main/?badge=main
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 |