问题描述
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
代码才能找到它。
希望这对其他人有帮助。