python - 递归地使用 Sphinx autosummary 生成 API 文档

Question

我想使用 Sphinx 的 autosummary extension和 templates从文档字符串递归生成 API 文档。我想为每个模块、类、方法、属性和函数创建单独的页面。但它根本没有检测到我的模板。事实上，如果我只是从 _templates/autosummary/ 中删除 module.rst 文件，它会以与以前完全相同的方式呈现整个文件。我关注了this SO question不折不扣。如果您有兴趣，the full repository is on GitHub .

编辑:它似乎确实生成了一个不同的文件，我必须删除 docs/_autosummary 才能读取新模板。但是，现在它会生成一个带有 sparse header 和 description header 的文件。它不会进入 {% if classes %} 和 {% if functions %} 指令。

我的目录结构如下:

• 稀疏
• 文档
  • 配置文件
  • index.rst
  • modules.rst
  • _templates/autosummary/module.rst

目前为止的相关文件如下:

index.rst:

.. sparse documentation master file, created by
   sphinx-quickstart on Fri Dec 29 20:58:03 2017.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sparse's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

modules.rst:

API Reference
=============

Modules
-------

.. autosummary::
   :toctree: _autosummary

   sparse

_templates/autosummary/module.rst:

{{ fullname | escape | underline }}

Description
-----------

.. automodule:: {{ fullname | escape }}

{% if classes %}
Classes
-------
.. autosummary:
    :toctree: _autosummary

    {% for class in classes %}
        {{ class }}
    {% endfor %}

{% endif %}

{% if functions %}
Functions
---------
.. autosummary:
    :toctree: _autosummary

    {% for function in functions %}
        {{ function }}
    {% endfor %}

{% endif %}

Answer 1

从 Sphinx 3.1 版(2020 年 6 月)开始，您可以使用新的 :recursive: 选项获取 sphinx.ext.autosummary 以自动检测包中的每个模块，无论嵌套有多深，都会自动为该模块中的每个属性、类、函数和异常生成文档。

在这里查看我的回答:https://stackoverflow.com/a/62613202/12014259