带有 toctree 的自动摘要不为方法创建文档答案

【问题标题】：Autosummary with toctree not creating documentation for methods带有 toctree 的自动摘要不为方法创建文档
【发布时间】：2016-11-11 15:42:14
【问题描述】：

我正在使用带有 numpydoc 扩展和自动摘要的 sphinx。经过一些实验，我在我的 conf.py 文件中添加了以下选项。

autosummary_generate = True
numpydoc_show_class_members = False

这为每个引用的类提供了一个新文件，如下所示，它还创建了所有属性和方法的汇总表。

.. autosummary::
   :toctree: generated/
   :nosignatures:

   MyClass

问题在于，虽然在文档字符串的第一行有一个方法的汇总表，但方法的名称并没有链接到任何东西。如何获取方法的文档字符串以创建自己的文件（或至少在与类相同的文件中生成文档）？

【问题讨论】：

1) 只是没有链接，还是缺少应该作为链接目标的文件？ 2) 我希望看到autosummary 指令中列出的类的汇总表，而不是方法的汇总表。我是不是误会了什么？
它正在为 MyClass 生成一个文件，其中包含一个带有所有属性和方法的 autoclass 指令，但这就是它结束的地方。生成的 HTML 文件包含类文档字符串以及属性和方法的汇总表，但不会为这些方法生成文档。似乎该文件中需要另一个 :toctree: 来生成完整的树。
请参阅我在 2013 年 1 月 31 日 20:01 在此答案中的评论：stackoverflow.com/a/14621772/407651。这可能会有所帮助。
好的，这确实有帮助。我在我的 conf.py 中使用了 autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'inherited-members'] ，我更接近我的需要。所以我在想，如果我只想为一个类使用生成的文档，我可以使用带有 toctree 的 autosummary，它将所有文档放在一个文件中。但是，如果我想将方法文档拆分为一个大类的单独文件，那么我必须使用自动摘要指令手动创建一个类 rst 文件，并让它为方法生成存根文件，对吗？
我刚刚注意到 Pandas 是这样做的。他们有一个 api.rst 是手写的，并且明确地引用了类方法。然后他们使用 :toctree: 创建存根。

【解决方案1】：

首先，确保在您的 conf.py 文件中，字符串 'sphinx.ext.autodoc' 和 'sphinx.ext.autosummary' 在 extensions 列表中。

其次，您可以在 generate/ 目录中手动创建名称为 mymodule.MyClass.rst 的文件，可以是这样的：

mymodule.MyClass
================

.. currentmodule:: mymodule

.. autoclass:: MyClass

或者，如果你有很多类，你可以使用 sphinx-autogen 自动化它。您可以从终端运行它（cd 与 conf.py 文件相同）：

sphinx-autogen *.rst

【讨论】：