介绍

我爱Python，我喜欢写文档。

实际上，我很幸运，在某个时候，I landed a job as Developer Advocate for Read the Docs，所以在2021年的大部分时间里，我能够与Sphinx社区深入互动，贡献了第一个实际的Sphinx教程，推动更广泛地采用Myst的方式来解决用于Python文档等等。

但是，尽管我喜欢狮身人面像的强大功能以及该项目在创建15年后仍在进行中，但让我们说狮身有时有些棘手。

最近，我开始担任Kedro的开发人员倡导者，这是一个有用的数据科学框架，我们正在做的一件事是exploring 什么是我们可以使用的最佳开源工具来创建我们的文档。

事实证明，这使我陷入了狮身人面像替代方案状态的有趣兔子孔，我开始连接一些点并想象未来派的工具链记录Python项目的样子是：

（link to original post on Mastodon）

最后，我设法进行了discuss with many smart folks，收集了相当多的链接，并形成了我想与更广泛的社区分享的体面思想。而且，为我重新开始写博客的完美借口！

在这篇文章的第一部分中，我将描述文档系统的更广泛背景，并特别关注Python与其他生态系统相比，并证明为什么我想要更强大的系统。在第二部分中，我将与Python中现有的当前文档系统遇到的一些具体问题，重点关注狮身人面像和MKDOC。在第三部分中，我将对如何在Myst上加倍并尝试扩大其受欢迎程度以及利用与特定文档系统无关的独立DocString解析来创建更好的工具链。<<<<<<<<<<<<<<<<< /p>

让我们走！

第1部分：目标更多

首先，我认为必须对文档系统是或做什么进行一些反思。在我看来，狮身人面像或mkdoc之类的工具基本上归结为这两件事：

1. docstring解析机制，
2. 静态站点发生器。

前者启用生成API引用，后者除了以连贯的方式组装所有内容外，还可以启用叙事文档。

（当然有一个单独的问题，即是什么使A good ssg用于技术文档 - 可扩展性，功能强大的交叉引用功能，用于代码块的良好语法，我们可以继续 - 但是让我们继续进行转储目前，所有这些都进入静态站点生成器。）

Python的文档系统如此有限的原因不是缺乏静态站点生成器（毕竟，只要SSG的语言是 ，只要它呈现标记），但由于两个主要原因：

1. 从历史上看，可用的Docstring解析系统与他们的同伴SSG相结合。换句话说：一个人不能简单地在狮身人面像之外使用sphinx-autodoc，也不能简单地使用mkdocs外的mkdocstrings。
2. Python选择重组文本（当时是绝对有意义的，因为Markdown甚至不存在）和Myst的后期开发（第一个真正可扩展和共同标记的Markdown的方言，它带来了所有强大的功能。狮身人面像以外的大多数SSG都发展了自己的刻痕方言，这些方言与Myst People所做的语法选择不兼容。例如，Hugo在Markdown内部使用shortcodes（实际上是一种模板语言）进行交叉引用，而Mkdocs使用Python-Markdown，这甚至不是共同标记的实现，因此已经进化了a bespoke extension mechanism。
。

这种历史发展的结果是，静态现场生成器的世界在过去几年中取得了惊人的进步，而Python生态系统尚未赶上它。如今，a rich ecosystem有不同的选项用于静态站点的生成，其中有些更倾向于服务器端的生成和简单性（例如Hugo），而其他人则利用单页应用程序框架（例如React.js或类似）（例如Docusaurus）。最重要的是，有一些“无头CMS”可以使用其中一些SSG作为后端，在将HTML输出生成卸载为其他组件（例如Decap CMS，Ghost，或Forestry）的同时，提供了更复杂的创作体验。

我要弄清楚的是：作为一个开发Python库的团队，如果我们可以使用我们喜欢的任何SSG来创建文档，同时保持Myst的低估功能和生成能力API参考？换句话说，是否可以使用Hugo或Docusaurus作为后端为Python项目创建文档网站？

等待这篇文章的第二部分！