带注释的狮身人面像树

Question

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

.. 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

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