python-sphinx - 带注释的 Sphinx toctree

Question

toctree的常用用法在 Sphinx 中看起来像这样:

.. toctree::
   :maxdepth: 2

   foo
   bar
   baz

如果，例如， foo.rst以标题“Being Foo”开头， bar.rst以“Doing Bar”开头，以及 baz.rst以“Thinking Baz”开头，然后你会得到一个漂亮的目录，如下所示:

Being Foo

Doing Bar

Thinking Baz

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

我的问题: 有没有办法注释 toctree？ 例如，如果我想用类似“W. Robert Foo 在 1857 年创建第一个元句法变量并且从那时起我们一直在使用它。”来注释“Being Foo”标题，那么我可以将该文本放在某处(希望如此)在 foo.rst 的顶部，但如果不是，则在 toctree 指令中)并且 toctree 输出将如下所示:

Being Foo — W. Robert Foo 于 1857 年创建了第一个元句法变量，此后我们一直在使用它。

Doing Bar

Thinking Baz

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

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