如何使用 Sphinx 生成 Python 包文档答案

【问题标题】：How to generate Python package documentation with Sphinx如何使用 Sphinx 生成 Python 包文档
【发布时间】：2018-04-15 09:34:13
【问题描述】：

目前我这样做：

conf.py：

autosummary_generate = True

reference.rst:

package_1
---------
.. autosummary::
   :toctree: _generated

   package_1.module_1
   package_1.module_2
   package_1.module_3
   ...

这将为每个模块生成一个概览表，其中包含每个模块的条目很好地链接到详细信息页面。

我有两个问题：

广告 1：我想做这样的事情（目前不起作用）：

.. autosummary:: package_1
   :toctree: _generated
   :members:

（或者也许是一个新的autopackage 命令。）

广告 2：我想传递automodule 或autoclass 期望的选项，例如：

.. autosummary::
   :toctree: _generated
   :undoc-members:
   :private-members:

这似乎是一项显而易见的任务，所以我可能遗漏了一些信息。有没有简单的替代方法来实现这一点？

【问题讨论】：

查看sphinx-autogen 以在 rST 中生成存根页面，您可以从中生成文档。 sphinx-apidoc 和 autodoc 有一个类似的工具链。
类似问题：stackoverflow.com/q/48074094/407651
@StevePiercy 据我了解，autosummary_generate = True 是等价的 (sphinx-doc.org/en/master/ext/…)
@mzjn 你是对的：你链接到的问题是相似的。它为“广告 2”提供了解决方案。我的问题的一部分。您是否建议创建自定义模板是可行的方法（对我来说看起来有点复杂，但无论如何）？
@mar10 我不知道两者之间可能存在什么差异（如果有的话），所以我不知道它们是否等效。建议尝试比较和对比，因为从阅读文档中判断差异是乏味的。 TBH，这是我第一次看到 sphinx-autogen。

【解决方案1】：

感谢所有评论者！

广告 1：
我手动列出模块。

广告 2：
我终于采用this 和this 提出的解决方案回答类似问题：

创建模板文件（_templates/autosummary/module.rst 和 _templates/autosummary/class.rst）并将其添加到
api_doc.rst：

Package ``wsgidav``
-------------------
.. autosummary::
   :toctree: _autosummary

   wsgidav._version
   wsgidav.compat

【讨论】：