在 sphinx 文档中生成目录的自动模块

Question

在 Sphinx 中，有没有办法让自动模块指令生成 class 中成员的目录？

现在我有

.. 内容::

.. topic:: Abstract

   bla bla bla

.. automodule:: ServerCommHandler
    :members:
    :private-members:
    :special-members:
    :show-inheritance:
    :inherited-members:

效果很好，但是这个模块中有很多方法，指向这些方法的目录会非常好。

Answer 1

toctree.

怎么样

.. toctree::

   ServerCommHandler

Answer 2

autodocsumm 扩展将允许 autodoc 指令（automodule、autoclass）自动添加像内置自动摘要扩展那样的汇总表。

可以这样使用：

pip install autodocsumm

然后编辑您的 conf.py 以添加扩展名：

extensions = [
    'sphinx.ext.autodoc',
    ...,
    'autodocsumm',
]

并在您的 autodoc 指令中添加一个 :autosummary: 选项，例如：

.. automodule: foo.bar
    :autosummary:

如果您想对所有 autodoc 指令启用自动摘要而不显式添加它们，您可以从 conf.py 执行此操作，如下所示：

autodoc_default_options = {
    'autosummary': True,
}

如果您使用 sphinx-apidoc 动态生成 API 页面，这将特别有用，而 sphinx-apidoc 不容易配置为添加 :autosummary:.

自动生成所有 API 页面的 conf.py 的完整示例：

def setup(app):
    from sphinx.ext import apidoc
    app.connect('builder-inited', lambda _: apidoc.main([
        '-o', './api', '-d2', '-feMT', '../src/PROJECT',
    ]))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'autodocsumm',
]


autodoc_default_options = {
    'autosummary': True,
}

autodata_content = 'both'

在 sphinx 文档中生成目录的自动模块

automodule to generate toc in sphinx documents

python

python-sphinx