Sphinx 自动摘要在 toctree 中不使用标签

编程问答 2022-05-27

问题描述

在 sphinx-autosummary toctree 中是否有使用标签的选项？ Sphinx 可以构建一个 toctree 如：

.. toctree::

  Main page <module.main>

以上将在 HTML 文档的 TOC 中显示“主页”。 我想使用自动摘要目录树

.. autosummary::
  :toctree:
  
  Main page <module.main>

然而，上面的标签产生：module\main.rst: WARNING: document is not included in any toctree

这样做的目的，当生成 html 页面时，TOC 显示：

module package
   module.main module

我想看到的是：

module package
   main module

我什至不确定这是实现上述渲染的正确位置

解决方法

我已经找到了整个问题的来源。原因不在目录树中，而是在每个 rst 文件的标题中。我使用 apidoc 和自动摘要。 apidoc 有一个模板 pacakge.rst 来构建一个目录树，它使用生成的 .rst 文件的标题在 *.html 中显示名称。

我的意思是，如果你打开 autosummary/module.rst：

{{ 全名 |逃脱|下划线}}

python-sphinxtoctree