A Sphinx Book Template¶
文档构建时间: 2022-09-13, 08:35:47
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
项目需要 Python
环境来支持,在此不对如何安装 Python
进行说明。 有需要的可以通过 Python官网 单独下载。
本机安装 Sphinx
和其他必要的包¶
本机要运行需要向 Python
环境中添加一些必要的包,以及提高编写效率的插件包如:sphinx-autobuild
。
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
。
Read The Docs
运行环境推荐配置¶
我们对 Read The Docs 的配置全部在 .readthedocs.yaml
和 requirements/requirements.txt
文件中,这些文件的配置会覆盖 Read The Docs 平台中的项目的配置。