从 Sphinx 页面中删除 toctrees

通过选择性地从页面中删除 TocTree 对象来提高 Sphinx 构建时间。如果您使用的文档使用了自动生成的 API 文档，这将生成大量的存根页面，这将非常有用。

此扩展可用于仅删除您指定的页面的侧边栏链接，从而显著加快构建速度。

这是为谁准备的？

此软件包是为使用 Sphinx 并拥有大量 API 文档的维护者准备的（或由于其他原因，有大量嵌套页面）。如果您使用包含整个目录表在每个页面上的 Sphinx 主题（例如，任何具有“可折叠”侧边栏部分的主题），这将大大减慢速度。使用此主题来加快您的构建。

安装

通过 pip 安装扩展

$ pip install sphinx-remove-toctrees

通过将其添加到 conf.py 中的 Sphinx 扩展来激活它

extensions.append("sphinx_remove_toctrees")

使用

在 conf.py 文件中，有一个顶级配置键 remove_from_toctrees，允许您指定从侧边栏中删除的页面。请提供一组相对于文档根目录的 类似 glob 的路径 列表。每个条目都应匹配应从侧边栏中删除的页面。

例如，以下配置将从文件夹 api/generated 中删除所有页面，以及特定页面 subfolder/page_two.rst。

remove_from_toctrees = ["api/generated/*", "subfolder/page_two.rst"]

这对于与 autosummary 指令结合使用尤其有用，该指令通常会生成大量的占位符页面，从而减慢了速度。

如果您在 myfolder/page1.rst 页面中有以下 autosummary 指令：

.. autosummary: datetime.datetime
   :toctree: api_gen

这将在 myfolder/api_gen/ 文件夹中生成占位符页面。要从侧边栏中删除这些页面，您需要像这样配置此扩展：

remove_from_toctrees = ["myfolder/api_gen/*"]

试用此文档

此扩展没有托管文档页面，但该仓库的 docs/ 文件夹中有一个。您可以使用该文件夹来预览此扩展的功能。

这是如何工作的

Sphinx 跟踪 toctree 对象以表示文档的结构。这些对象存在于 Sphinx 环境对象中的 env.tocs。在构建过程中有两个地方与此相关：

• 在构建早期，Sphinx 使用这些 tocs 确保您的文档中的文件在某个地方有链接，如果它发现不在任何一个 tocs 中的文件，将会发出警告。
• 在构建后期，Sphinx 使用这些 tocs 构建包含指向您文档中页面的链接的 HTML toctree。如果 tocs 中有很多元素，解析所有这些链接将需要很长时间！

此扩展在第一个步骤之后、第二个步骤之前运行。它删除您指定的所有 toctree 对象，因此不会发出关于缺失文件的警告，但它们将从侧边栏中删除，并且不会减慢您的构建速度。