使用Sphinx自动摘要递归生成API文档。

Question

我希望使用Sphinx的autosummary扩展和模板，从docstrings递归生成API文档。我想要为每个模块、类、方法、属性和函数生成单独的页面。但是它根本无法检测到我的模板。事实上，如果我只从_templates/autosummary/中删除module.rst文件，它会完全以与之前相同的方式呈现整个文件。我已经严格按照这个SO问题的说明进行操作了。如有兴趣，完整的存储库在GitHub上。

编辑：看起来它确实生成了一个不同的文件，我必须删除docs/_autosummary才能读取新模板。然而，现在它生成了一个带有sparse头和description头的文件。它不进入{% if classes %}和{% if functions %}指令。

我的目录结构如下：

• sparse
• docs
  • conf.py
  • 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 %}

- Hameer Abbasi

---

为什么不使用sphinx-apidoc呢？ - Steve Piercy

如果sphinx-apidoc可以做我想要的类似事情（使用模板和成员摘要），那么我会这样做。不幸的是，我对Sphinx不太熟悉，一个示例会很有用。但据我所知，sphinx-apidoc等效于使用autosummary_generate = True的autosummary。 - Hameer Abbasi

Answer 1

自Sphinx 3.1版本（2020年6月）起，您可以使用新的:recursive:选项来让sphinx.ext.autosummary自动检测您包中的每个模块（不管多深），并自动生成有关该模块中每个属性、类、函数和异常的文档。

请查看此处的答案：https://dev59.com/TXE85IYBdhLWcg3wl0rF#62613202。

- James Leedham

Answer 2

我需要以下文件： modules.rst:

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

.. rubric:: Modules

.. autosummary::
   :toctree: generated

   sparse

_templates/autosummary/module.rst:

{{ fullname | escape | underline }}

.. rubric:: Description

.. automodule:: {{ fullname }}

.. currentmodule:: {{ fullname }}

{% if classes %}
.. rubric:: Classes

.. autosummary::
    :toctree: .
    {% for class in classes %}
    {{ class }}
    {% endfor %}

{% endif %}

{% if functions %}
.. rubric:: Functions

.. autosummary::
    :toctree: .
    {% for function in functions %}
    {{ function }}
    {% endfor %}

{% endif %}

_templates/autosummary/class.rst:

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

   {% block methods %}
   {% block attributes %}
   {% if attributes %}
   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
      .. autosummary::
         :toctree:
      {% for item in all_attributes %}
         {%- if not item.startswith('_') %}
         {{ name }}.{{ item }}
         {%- endif -%}
      {%- endfor %}
   {% endif %}
   {% endblock %}

   {% if methods %}
   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
      .. autosummary::
         :toctree:
      {% for item in all_methods %}
         {%- if not item.startswith('_') or item in ['__call__'] %}
         {{ name }}.{{ item }}
         {%- endif -%}
      {%- endfor %}
   {% endif %}
   {% endblock %}

_templates/autosummary/base.rst:

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ objname }}

我还需要前往 sphinx/ext/autosummary/generate.py 并在函数 generate_autosummary_docs 中设置 imported_members=True。

如果你不像我一样使用 numpydoc，你可能需要移除 .. HACK 指令。

- Hameer Abbasi

---

我克隆了您的GitHub项目，它也对我有用。在 generate_autosummary_docs 函数中设置 imported_members=True 似乎是关键。但是修改Sphinx源代码才能使其正常工作并不理想。 - mzjn

我刚看到了https://github.com/sphinx-doc/sphinx/issues/4372。在`__init__.py`中，您有`__all__ = ["COO", "tensordot", "concatenate", "stack", "dot", "triu", "tril"]，我认为这应该足够了。据我所知，autosummary不考虑__all__`。 - mzjn

是的，它应该考虑__all__或提供一种包含导入成员的方法。 - Hameer Abbasi

非常好的答案，非常有帮助！您是否知道如何将文档化的模块属性（如常量定义）添加到modules.rst的输出中？ - mar10

@mar10 你需要添加一个类似于 _templates/autosummary/module.rst 中函数和类部分的属性部分。我自己没有尝试过，但我相信它会起作用。 - Hameer Abbasi

@HameerAbbasi attributes 似乎是空的，但 members 有内容。我可以像这样过滤掉 if item not in all_functions and item not in all_classes ... 并且得到我想要的大部分内容（除了导入的模块名称和符号，我还没有弄清楚如何排除它们）。 - mar10