使用Sphinx为每个函数自动生成单独的文档

Question

我一直在构建一个具有许多不同功能的 Python 模块。

我正在使用 Sphinx 和 readthedocs 来提供文档。我取得了不错的进展，但目前我有 one massive page 提供了我所有功能的文档（按字母顺序排列）。

我看过其他项目，每个功能都有一个单独的页面。在查看它们的源代码时，我发现每个都创建了一个单独的 .rst 文件。我认为这是自动完成的，this page 关于生成自动文档摘要似乎描述了其中的一些内容，但我就是无法理解它。

sphinx-apidoc 有一个选项 (-e) 可以为每个模块创建一个页面，但我想为每个功能创建一个页面。

如何使用Sphinx为每个功能自动生成单独的页面？

补充信息

要为以下答案之一添加信息，我已将以下内容放入我的 EoN.rst 文件中，该文件位于 docs.

子目录中

EON documentation
=================

.. automodule:: ../EoN
   :members:

.. currentmodule:: ../EoN

.. autosummary::
   :toctree: functions

   fast_SIR
   fast_SIS

我收到错误消息

$ sphinx-autogen -o docs/generated docs/*.rst

[autosummary] generating autosummary for: docs/index.rst, docs/methods.rst, docs/quickstart.rst

[autosummary] writing to docs/generated

WARNING: [autosummary] failed to import u'fast_SIR': no module named fast_SIR

WARNING: [autosummary] failed to import u'fast_SIS': no module named fast_SIS

fast_SIS 和 fast_SIR 坐在 ../EoN.py

内

Answer 1

在对 Sorting display by class using sphinx with 'autodoc'? it is explained how to generate documentation for classes with one page per class, using autosummary 的回答中使用 autosummary_generate=True。

这个机制也适用于函数。使用这样的东西：

EoN API documentation
=====================

.. currentmodule:: EoN

.. autosummary::
   :toctree: functions

   my_function1
   my_function2
   my_function3
   ...

您必须在autosummary 指令中枚举每个函数，但会自动生成相应的*.rst 文件（在functions 子目录中）。

Answer 2

我认为 sphinx-automodapi Sphinx 扩展可以满足您的需要。本质上要记录一个模块，您只需执行以下操作：

.. automodapi:: mypackage.mymodule

它会为每个函数生成 table 和单独的页面。

免责声明：我是 sphinx-automodapi 的作者

使用Sphinx为每个函数自动生成单独的文档

Using Sphinx to automatically generate a separate document for each function

python

python-sphinx

read-the-docs