python-sphinx - 带注释的 Sphinx 目录树

Question

toctree在 Sphinx 中的常用用法如下所示：

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

例如，如果foo.rst标题以“Being Foo”bar.rst开头，以“Doing Bar”开头，并baz.rst以“Thinking Baz”开头，那么您将得到一个看起来像这样的漂亮目录：

• 成为 Foo
• 做酒吧
• 思考巴兹

带有从每个链接到相应页面的链接。

我的问题：有没有办法注释一个目录树？例如，如果我想用“W. Robert Foo 在 1857 年创建了第一个元句法变量，我们一直在使用它”之类的东西来注释“Being Foo”标题，那么我可以把那个文本放在某个地方（希望在 的顶部foo.rst，但如果不是，则在 toctree 指令中），并且 toctree 输出将如下所示：

• 成为 Foo — W. Robert Foo 在 1857 年创建了第一个元句法变量，从那时起我们就一直在使用它。
• 做酒吧
• 思考巴兹

Answer 1

您可以使用以下语法覆盖页面标题：

.. toctree::
   :maxdepth: 2

   Being Foo - W. Robert Foo created the first metasyntactic variable in 1857 <foo>
   bar
   baz

http://www.sphinx-doc.org/en/stable/markup/toctree.html?highlight=entries

但是，您会丢失自动标题，这可能是您问题的主要部分？