通过添加 README 降价文件启用 Sphinx AutoAPI 扩展

如何解决通过添加 README 降价文件启用 Sphinx AutoAPI 扩展

Python 开发人员通常会将 README.md 文件添加到包含包的文件夹中。他们还希望将这些文件添加到由 Sphinx（在我的情况下为 3.2.1）和 sphinx_autoapi 扩展名（在我的情况下为 1.8.1）生成的 HTML 文档中。您能分享一下您对可能的解决方案的看法吗？

解决方法

在 conf.py 中，添加 myst_parser 扩展名，它将 Markdown 文件呈现为 HTML（我使用的是最新版本：0.15.0），并创建一个函数来检查所需文件（这将是 README.md) 存在于文件夹中。

 extensions = [
     'autoapi.extension','myst_parser',...
 ]

 def local_file(name):
     return os.path.exists(name.lstrip('/'))

 def _prep_jinja_env(jinja_env):
     jinja_env.tests['loc_file'] = local_file

 autoapi_prepare_jinja_env = _prep_jinja_env

autoapi_prepare_jinja_env 变量通过另一个名为“loc_file”的测试扩展了 Jinja 测试列表。这将在 Jinja 模板中用于检查当前文件夹中是否存在名为 name 的文件。

在 AutoAPI 模板中，例如在 module.rst 中，添加 toctree 指令，该指令引用与此类似的 README 页面：

 {% if 'loc_file' in obj.jinja_env.tests %}
    {% set readme = obj.url_root + '/' + obj.pathname + '/README.md' %}
    {% if readme is loc_file %}

 .. toctree::
    :maxdepth: 1

    README

    {% endif %}
 {% endif %}

如果当前文件夹中存在 README.md 文件，这将添加一个指向自述文件标题（第一级标题）的链接。

除此之外，您还需要一个预处理（步骤 #0），它收集源 Python 包中的所有 README.md 文件，并在主进程（Sphinx + autoapi) 开始。 autoapi 扩展不会触及其工作区中创建 *.rst 文件的任何文件。

在收集 README.md 文件时，您需要创建与 autoapi 扩展创建的目录结构相同的目录结构，该结构实际上重复了您记录的源 Python 包的结构。

就是这样。它按预期工作。我不得不深入研究 autoapi 代码才能找到它。希望这对其他人有帮助。