A Sphinx Book Template

文档构建时间: 2022-09-13, 08:35:47

GitHub issues GitHub issues closed GitHub repo size GitHub last commit (branch) GitHub Documentation Status

MyST Markdown

本文章推荐使用 MyST Markdown 作为编写文档的语言。

为什么使用 MyST Markdown

虽然 Markdown 无处不在,但它的功能还不足以编写现代的、功能齐全的文档。为此需要一些 Markdown 支持功能,但没有围绕这些功能的各种语法选择的社区标准。

而 Sphinx 是一个用 Python 编写的文档生成框架。它大量使用了 reStructuredText 语法,这是另一种用于编写文档的标记语言。特别是,Sphinx 定义了两个非常有用的扩展点: 内联角色和块级指令。

MyST 试图将 Markdown 的简单性和可读性与 reStructuredText 和 Sphinx 平台的强大功能和灵活性相结合。它以 CommonMark 降价规范为基础,并有选择地添加了一些额外的语法片段以利用 reStructuredText 最强大的部分。

MyST MarkdownreStructuredTextSphinx 之间的关系

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 CodeMyST 扩展语法高亮

  • reStructuredText : 这个扩展为 Visual Studio Code 提供了丰富的 reStructuredText 语言支持。现在,您可以使用 VS Code 提供的优秀的 IDE-like 接口编写 reStructuredText 脚本。

  • reStructuredText Syntax highlighting :这个扩展为 reStructuredText 提供了丰富的语法高亮显示和非侵入式节导航。

  • Markdown All in OneVisual Studio CodeMarkdown 支持

运行和预览

在配置完本地的项目运行环境后,我们就可以运行此项目。由于现有的 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.yamlrequirements/requirements.txt 文件中,这些文件的配置会覆盖 Read The Docs 平台中的项目的配置。