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

问题描述

我一直在构建具有许多不同函数的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

[自动摘要]生成以下内容的自动摘要：docs/index.rst、docs/method s.rst、docs/ickstart.rst

[自动汇总]写入文档/生成

警告：[自动摘要]无法导入u‘Fast_SIR’：没有名为FAST_SIR的模块

警告：[自动摘要]无法导入u‘Fast_SIS’：没有名为FAST_SIS的模块

fast_SIS和fast_SIR位于../EoN.py

---

解决方案

在Sorting display by class using sphinx with 'autodoc'?的回答中介绍了如何使用autosummary和autosummary_generate=True为每个类生成一个页面的类的文档。

此机制也适用于函数。使用类似以下内容：

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

.. currentmodule:: EoN

.. autosummary::
   :toctree: functions

   my_function1
   my_function2
   my_function3
   ...

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