简介

本模块包启发自 Sphinx。通常将 Sphinx 视为用来自动生成 Python 文档的“官方”解决方案。根据 Sphinx 的文档，其“自动生成”功能大致可以视为：

为Python、C++和其他软件域手动或从docstrings自动生成生成API文档，轻松让您的代码文档保持最新。

——Sphinx

大体上，该模块包提供了类似Sphinx的功能。通过完整遍历某个指定的模块包，其中的内容将重新组织成自动生成的 API 文档。不过，不可以将 pyDocusaurus 看作 Sphinx 的扩展，这是由于：

Sphinx 垂垂老矣。它诞生于 Python 标准库还不支持类型标记、提示的年代。是以，Sphinx 需要从文档字符串 (docstring) 本身来推断参数类型。在现代的 Python 代码中，这一功能已然多余。
Sphinx 主要是为 reStructuredText (rst) 格式设计的。诚然，它也可以通过某些扩展插件来支持 Markdown。然而，某些 Markdown 特性，特别是与变量类型相关的部分，并没有整合到自动生成的 API 文档中。它的用户还是需要在生成的文档中与大量的 rst 代码斗智斗勇。
由于积攒了许多老旧的模板，Sphinx 不适用于构建“现代”网站。

基本上，本模块包产出的是 Docusaurus 项目的补丁。与 Sphinx 相似的一点是，pyDocusaurus 将穷尽整个指定的模块包，并将其中的 docstring 转化为与 Docusaurus 兼容的 API 文档。 要将所生成的文档整合到某个已经存在的 Docusaurus 项目中（例如一个教程网站），只需要做一些微小的修改。

用法示范

命令行
Python

运行以下单行命令，就可以将一个已经存在的模块包转换成文档项目。

python -m pydocusaurus render-doc <package-name> -o <out-dir> -u <user-name>

要了解更多细节，请善用“帮助”功能：

python -m pydocusaurus render-doc --help

运行以下脚本，就可以将一个已经存在的模块包转换成文档项目。

convert_docs.py
from pydocusaurus import render_package_as_mdx
import any_package

if __name__ == "__main__":
    render_package_as_mdx(
        any_package, out_dir="./docs-output", package_info="yourname"
    )