从 Sphinx 切换到 MkDocs 文档 – 我得到了什么，失去了什么
?
由melanfolia在Unsplash上的照片
“一个项目的好坏取决于其文档” – 这是我之前 3 篇文章系列中强调文档重要性的引用。我后来了解到，存在不同类型的文档，其中更常见的是：
-
技术文档：描述项目内部运作的技术方面，可以是流程文档或产品文档
-
业务文档：描述它解决了哪些业务问题或实现了哪些业务目标
存在一种介于中间的文档类型，这些是手册、指南和教程。如果您希望技术用户使用或使用您的项目，或者商业用户理解您的项目并获得认可，这尤为重要。
随着文档内容的增加而变得更加复杂，以用户友好和可读的格式显示它可能会变得有些棘手。例如，教程不应嵌入在技术文档中，理想情况下，它们之间应有单独的导航标签或部分。
这激发了我探索更多的 Sphinx 主题，以使我的文档更美观，并能够处理更多信息。最终，我被 Sphinx-Material（https://bashtage.github.io/sphinx-material/）和 Sphinx-Immaterial（https://jbms.github.io/sphinx-immaterial/）主题所吸引，这些主题实现了来自 MkDocs（https://squidfunk.github.io/mkdocs-material/）的 Material 主题。经过多次调整，仍然没有得到我想要的结果，我最终切换到了 MkDocs，并终于理解了 MkDocs 的热潮。
在尝试了各种文档方法和主题后，我将尝试比较它们 – 重点关注从 Sphinx 切换到 MkDocs 所获得的功能和失去的功能。最后，这篇文章将以重要的 MkDocs 设置结束，以实现更优化的文档！
注意：如果您感兴趣，这是我用 Sphinx-Material 主题制作的文档的[链接](https://bigtree.readthedocs.io/en/0.15.7/)，这是用 MkDocs 制作的相同文档的链接 🙂
目录
Sphinx 与 MkDocs
MkDocs 获得的功能
MkDocs 失去的功能
相似的功能
重要的 MkDocs 设置
Sphinx 与 MkDocs：设置
两种方法都很相似——都需要安装一个 Python 包，并且有一个用于安装和随后的文档部署的一行命令
对于 Sphinx，以下分别是安装、设置和生成文档的命令。
$ pip install sphinx
$ mkdir docs
$ cd docs
$ sphinx-quickstart
$ make html
在docs文件夹中，有一个build文件夹，其中包含生成的 HTML 文件，还有一个source文件夹，其中包含文档的配置和源文件。配置是通过docs/source/conf.py Python 文件设置的。
对于 MkDocs，以下分别是安装、设置和生成文档的命令。
$ pip install mkdocs
$ mkdocs new .
$ mkdocs serve # deploy locally
$ mkdocs gh-deploy # deploy to GitHub Pages
在 docs 文件夹中，只有一个index.md文件，这是初始文档。在根文件夹中，有一个mkdocs.yml YAML 文件，它控制配置，生成的 HTML 文件存储在site文件夹中。
Sphinx 与 MkDocs：易用性
MkDocs 更容易使用——尤其是如果你还在设置各种配置
对于 Sphinx，任何对配置和代码文档字符串的更改都需要再次运行make html命令，这使得操作繁琐，等待时间可能会根据生成的 HTML 页面数量而变长。
MkDocs 更容易使用，因为配置和 Markdown 文件的更改会自动刷新，因为运行mkdocs serve时使用服务器托管文档。然而，代码文档字符串的更改需要重新启动服务器，因为这些文件不会被监视更改。
获得的功能：更佳的整体布局
MkDocs Material 经过一些调整后拥有更漂亮的布局
在详细阐述我的观点之前，我必须先说明，虽然“好”是主观的，但我将尝试更客观地定义它。此外，我提到的 MkDocs 具有而 Sphinx 没有的一些功能，可能在某些 Sphinx 主题或 Sphinx 扩展中实现——如果你有好的 Sphinx 替代方案，请评论！ 😃
文档的目的应该是让最终用户能够理解。考虑到这一点，拥有可读的布局是很重要的。
虽然可以使用 CSS 进行进一步的自定义（稍后会更详细地介绍），但某些布局很难用 CSS 修复。例如，在下面的图 1 中，MkDocs 与black集成以执行格式化，并以比 Sphinx 更易读的方式显示函数签名。
图 1：MkDocs（顶部）和 Sphinx（底部）上的代码参数显示 – 作者图片
仍然是在代码格式化的主题上，在 MkDocs 中，插件 mkdocstrings 允许解释 Python 代码，并通过在 mkdocs.yml 文件中进行配置来处理 Python 代码的显示和格式。我认为在 Sphinx 中这并不那么直接，我可能需要找到一个已经实现此功能的主题或扩展，或者修改 CSS 来满足我的需求。在我的经验中，我使用了多个扩展，如 autodoc 和 autodocsumm，每个扩展都有自己的设置，这可能会变得混乱和令人困惑。
虽然 Sphinx 有更大的用户基础和更多的社区支持，但我发现某些 Sphinx 主题和插件的文档（讽刺地）由于缺乏示例而难以理解，而且好的主题很难搜索，除非你已经知道你在寻找什么。
图 2：MkDocs 中的代码块（顶部）和代码动画（底部） – 作者图片
我喜欢 MkDocs 布局中的另一个特性是 代码块 和 代码动画！使用代码块，代码可以被分段到标签页中，从而减少滚动视觉空间。代码块被视为 Markdown 扩展，因此只需在 mkdocs.yml 文件中指定扩展，并遵循 Markdown 格式即可实现。
代码动画通过模拟输入或下载速度使代码更具吸引力。这是通过一个名为 Termynal 的插件实现的，同样，安装 Python 包，将其添加到配置文件中，并遵循 Markdown 格式。
在撰写这篇文章时，我试图寻找这些特性的 Sphinx 替代品（因为现在我知道我在寻找什么）并找到了一个名为 sphinx-term 的扩展，它可以为代码动画做同样的事情。对于代码块，它被渲染成如图 3 所示，看起来没有 MkDocs 那么精致。
图 3：Sphinx 中的代码动画 – 图片来自 文档
从这篇文章中可以看出，Sphinx 比 MkDocs 更成熟，拥有更多的追随者、主题和插件。我相信，如果我仔细寻找，也许我能找到我想要的 Sphinx 主题和插件。然而，它们可能不像我希望的那样可配置，或者看起来不是我想要的样子，我不得不额外花费时间来定制 CSS。一旦你更换了主题（就像我之前做的那样），定制 CSS 的努力可能会白费。MkDocs Material 主题减少了 CSS 调整的需求，使得文档过程更加轻松。此外，MkDocs 的大部分增强功能都可以通过配置文件进行调整，从而减少了 CSS 的需求。
获得的功能：更好的导航
MkDocs Material 导航位于顶部面板、左侧和右侧边栏
图 4：MkDocs 上的导航 - 作者图片
参考上图 4，顶部面板上不同页面的导航被认为是导航标签，左侧边栏的导航被认为是导航部分，右侧边栏的导航被认为是目录（或toc）。
导航标签使我能够将我的文档的不同类别分别放入不同的标签中，而导航部分则允许我的文档进一步分区和组织。我最喜欢的是，目录会随着用户滚动，一旦翻过早期部分，早期部分就会变灰。这个功能在 Sphinx Material 和 Immaterial 主题（不是所有主题！）中也可以实现，但我只是觉得这是一个非常酷的功能。
如果仍然不满意，MkDocs Material 提供了信息文档，展示了可用的不同导航设置，例如，左侧边栏可以与右侧边栏集成，侧边栏可以在选择页面隐藏，或者侧边栏可以设置为可折叠的，等等。
话虽如此，这种导航布局在 Sphinx 和 MkDocs 上都是主题相关的——而且我对 Material 主题（在 Sphinx 和 MkDocs 上都有）的倾向可能会让我对这个导航形式产生偏见。
获得的功能：社交
链接到其他社交媒体平台！
图 5：MkDocs 上的社交 - 作者图片
尽管这取决于主题（再次强调），将 Sphinx 的 Material 主题升级到 MkDocs 使我能够指定链接到我的其他社交媒体平台，如 GitHub、LinkedIn 和 Medium。这可能是一个微不足道的特性，但我仍然非常欣赏它。
图 6：MkDocs 上的社交卡片 - 作者图片
另一个获得的功能是社交卡片，默认情况下是启用的。社交卡片是在分享你的文档 URL 时显示的大缩略图（图 6），而来自文档不同页面的社交卡片看起来不同，因为它从页面标题中推断出来！然而，在较小的缩略图中，图像将被裁剪，例如在下面的示例 URL 中。
话虽如此，这些被认为是 MkDocs 获得的功能，因为 Sphinx 上的 Material 主题不再维护。Sphinx 上的 Immaterial 主题仍在维护，并且具有更多功能（它有这个社交功能！）。然而，尽管 Immaterial 主题具有更多功能，但我尝试了 Sphinx 的 Material 和 Immaterial 主题后，感觉字体、对齐、布局或整体感觉还是 Material（功能较少）更好，而且我不想过度定制 CSS 以与 Immaterial 一起使用。各花入各眼，但我不喜欢这种 Sphinx 主题之间的权衡。
到目前为止，我一直对 MkDocs 赞不绝口，现在来说说它的缺点…
失去的功能：使用 RST 文件的能力
MkDocs 只支持 Markdown，Sphinx 可以支持 Markdown 和 RST 文件
这可能是 Sphinx 和 MkDocs 之间最大的区别——使用 RST 文件的能力。这并不是一个致命的问题，我也没有说 RST 文件比 Markdown 文件更好。由于我不得不将我的 .rst 文件重写为 .md 文件，从 Sphinx 到 MkDocs 的过渡比必要的更繁琐。这两种格式之间最大的区别在于我转换时：
-
表格（在 Markdown 中，表格的原始格式比 RST 更易读）
-
字体标题（在 Markdown 中，指定 H1/H2 等字体比 RST 占用的视觉空间更少）
-
链接和图像（
a和img标签表示不同） -
链接到代码模块（主要从
..RST 表示法切换到::Markdown 表示法）
这可能是我在从 Sphinx 切换到 MkDocs 时花费时间最多的部分。由于 Sphinx 也可以与 Markdown 文件一起工作（使用 myst_parser 插件），Markdown 文件更灵活，这使得这次切换值得。
失去的功能：Doctest 和覆盖率测试
只有 Sphinx 可以运行文档测试
Doctest 有助于测试文档字符串中的代码是否按预期工作，它类似于对代码进行单元测试，但这是对文档字符串的单元测试。例如，在下面的代码块中，doctest 将测试代码示例 func_add(1, 2) 是否返回结果 3。这很有用，因为它确保了在编写或修改代码后，文档示例仍然有效且相关。
def func_add(x, y):
"""Add two numbers
Examples:
>>> func_add(1, 2)
3
(other documentation below)
"""
return x + y
而代码覆盖率测试检查单元测试是否可以到达所有代码行，文档覆盖率测试检查每个类和函数是否有为其编写的文档字符串。这有助于确保所有模块都有文档（尽管质量无法确定）。
图 7：Sphinx 上的 Doctest（左）和覆盖率测试（右）的结果 – 作者图片
在 Sphinx 上启用 Doctest 和覆盖率测试分别使用扩展 sphinx.ext.doctest 和 sphinx.ext.coverage。运行相应的测试命令后，结果如图 7 所示。尽管这些 doctest 和覆盖率测试是独立的命令，并且不会在 make html 上自动运行，但它们仍然有助于快速检查是否有任何模块缺少或无效的文档字符串。
我找不到任何适用于这些测试的正在工作的 MkDocs 替代品。考虑到 Python 模块替代品，docstr-coverage 可以以 Sphinx 的方式运行覆盖率测试。doctest 可以运行 doctest，然而，它不能从命令行调用以一次性运行整个项目。目前，我只是在项目中保留 Sphinx 设置，以便利用这些测试。
相似功能：托管在 Read the Docs 和 GitHub Pages 上
Read the Docs 和 GitHub Pages 都支持两种类型的文档
Read the Docs 是一个免费托管文档的平台。在切换之前，我担心 Read the Docs 只支持 Sphinx，但我意识到修改 .readthedocs.yml 文件中的两行就可以让我在部署 Sphinx 和 MkDocs 之间切换！
# For Sphinx
sphinx:
- configuration: docs/source/conf.py
# For MkDocs
mkdocs:
- configuration: mkdocs.yml
对于我的项目，我还启用了在 GitHub Pages 上构建文档的功能，通过 GitHub Actions 自动化。以下记录了 GitHub 工作流程 步骤 的更改。
# For Sphinx
- name: Install dependencies
run: |
pip install -r docs/requirements.txt
- name: Sphinx build
run: |
sphinx-build docs/source docs/build
- name: Deploy to GH Pages
uses: peaceiris/actions-gh-pages@v3
with:
publish_branch: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/build/
force_orphan: true
# For MkDocs
- name: Install dependencies
run: |
pip install -r docs/requirements.txt
git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
- name: Deploy to GH Pages
run: mkdocs gh-deploy
奖励：搜索引擎优化
使用元标签使您的文档更容易被搜索引擎发现
元标签是提供有关页面额外信息的 HTML 标签，以便搜索引擎使用。MkDocs 文档提到，可以通过 HTML 文件形式的 页面覆盖 来修改或注入自己的 HTML 元素，在这种情况下，是元标签，将其注入布局中。
下面是我对 main.html 覆盖文件和 mkdocs.yml 配置文件所做的更改，这些更改使我能够向我的网站添加元标签。这些更改在文档中并不立即直观，我从 这个 GitHub 问题评论中进行了调整。
<!-- In docs/overrides/main.html -->
{% extends "base.html" %}
{% block site_meta %}
<meta name="..." content="...">
<meta property="..." content="...">
{{ super() }}
{% endblock %}
# In mkdocs.yml
theme:
custom_dir: docs/overrides
良好的文档可以走得很远，而像 Sphinx 和 MkDocs 这样的工具可以使文档更易于阅读，而像 GitHub pages 和 Read the Docs 这样的平台可以使文档更容易访问。我希望这篇文章为您采用 MkDocs 并提高您的文档水平提供了一个良好的开端！
相关链接
Sphinx
-
官方文档：
www.sphinx-doc.org/ -
Immaterial 文档（主题）：
jbms.github.io/sphinx-immaterial/ -
代码块示例：
sublime-and-sphinx-guide.readthedocs.io/en/latest/code_blocks.html
MkDocs
-
官方文档：
www.mkdocs.org/ -
Material 文档（主题）：
squidfunk.github.io/mkdocs-material/getting-started/ -
mkdocstrings 文档（Python 文档字符串）：
mkdocstrings.github.io/python/ -
Termynal 文档（代码动画）：
mkdocs-plugins.github.io/termynal/
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
3
0- 0
已为社区贡献264条内容
所有评论(0)