Sphinx：为每个方法创建目录条目答案

【问题标题】：Sphinx: create toc entries for each methodSphinx：为每个方法创建目录条目
【发布时间】：2021-01-20 12:55:38
【问题描述】：

我正在使用 sphinx-autodoc 来记录一个类。我希望该类的方法与 Sphinx TOC 中的各个条目相对应，以便它们各自在“本地 TOC”侧边栏中生成一个链接。

我怎样才能做到这一点？

AFAICT，autoclass 指令不支持这一点。我尝试使用autosummary，但我也无法使用它：它需要单独的.rst 文件中的各个方法。我宁愿将它们都放在同一个页面上。

我想我可以像这样为每个成员手动创建一个部分：

Foo.bar()
---------

.. automethod:: Foo.bar

但这感觉很奇怪，而且不必要地复杂。

【问题讨论】：

我们是在谈论 Sphinx .. toctree:: 指令还是 reST .. contents:: 指令？您显示的代码没有指令，因此无法区分两者，两者有时都称为“目录”。
两者都不是。我希望内部文档层次结构为每个函数包含一个单独的节点。我知道的 2 种方法是 1. 通过 .. toctree:: 包含另一个文件或在单个 reST 源文件中包含额外部分。然而，我正在寻找一种适用于单个文件的方法，但不需要我手动创建部分。
所以主要要求只是“侧边栏目录”在您到达文档的给定页面后每个方法有 1 个链接？您是否希望仅在该特定页面上使用该方法？你想要类下一级的方法吗？你想在同一个页面中有几个类吗？与“侧边栏目录”相关的给定页面应该有什么？
是的，确切地说，侧边栏应该列出方法，并链接到它们。我并不特别关心类与方法的层次结构，因为我打算每个类有一页。不知道我是否理解你的最后一个问题。侧边栏包含本地 TOC，即当前页面的内容（节、小节……）（与整个文档的内容相反）。感谢您的帮助。
好的，这需要澄清，否则贡献者可能会发布一个结果不是你想要的答案。我自己还没有使用过autosummary，但你是对的，为了避免在每种方法上方写一个部分，这可能是最好的选择。（我现在很忙，今天不能回答这个问题，但我想同时澄清一下。）

标签： python documentation python-sphinx autodoc

【解决方案1】：

我编写了一个名为 autoclasstoc 的 sphinx 插件，它的功能与您想要的类似。该插件提供了一个指令，该指令为特定类的每个方法创建指向文档的链接表。这些链接不会出现在 TOC 侧边栏中，但它们仍然使类文档更易于浏览。还值得一提的是，这些链接可以组织成组（例如公共方法、私有方法等），并且继承方法的链接按超类分组并默认折叠。

尽管这不能完全回答您的问题，但它是实现类似效果的好方法。

【讨论】：

整洁，这绝对是一个进步！您似乎熟悉 docutils 的内部工作原理。有没有一种简单的方法可以扩展 autoclasstoc 以同时发出文档 TOC 条目？
这是个好问题。我不知道，因为我不知道 TOC 中的最终结果如何，但它可能非常简单。如果您想在错误跟踪器中打开有关此问题的问题，那将是继续此对话的好地方。