使用单个 html 构建选项时如何包含目录？答案

【问题标题】：How to include table fo contents when using singlehtml build option?使用单个 html 构建选项时如何包含目录？
【发布时间】：2021-02-22 05:15:21
【问题描述】：

上下文

我正在使用 Sphinx 创建技术文档（与代码无关）。输入是几个 reStructuredText 和 SVG 文件。使用singlehtml 构建器创建输出（在后续步骤中使用 weasyprint 将其转换为 PDF）。

我想在最终文档中包含一个目录 (TOC)。 TOC（侧边栏）的默认位置不是一个选项。我必须禁用/隐藏侧边栏才能生成有用的 PDF。

toctree directive：不管我怎么尝试，似乎都只能使用侧边栏。
HTML Theming：我正在使用它来设置 HTML 输出的样式，但我不知道如何解决 TOC 问题。
Sphinx extensions：我自己写的，但不是很灵活，我仍然确定其他人已经解决了这个问题。
使用latexpdf builder：尝试过，它解决了 TOC 问题，但它产生了一些其他问题，并且使用 CSS 对文档进行样式设置变得非常容易。
Sphinx 以外的其他工具：这是 XY 问题的典型案例吗？我想使用 reStructuredText 和 SVG 来生成 PDF，但我愿意使用 Sphinx 以外的其他东西。

【问题讨论】：

有趣的问题。如果所有其他选项都不起作用，则应保证起作用的最后手段是手动创建嵌套的交叉引用列表。最后一个选项意味着失去一些自动化，但您可以微调 TOC 的构建和呈现方式。

【解决方案1】：

使用contents directive。

这是最简单形式的指令：
.. contents::
将使用依赖于语言的样板文本作为标题。英文默认标题文本为“Contents”。

可以指定明确的标题：
.. contents:: Table of Contents

【讨论】：

这真的有用吗？ .. contents:: 只为当前文件生成一个目录，但在问题中它说输入由几个 reStructuredText 文件组成。
我没试过。我正在等待查看 OP 尝试并报告的内容。
感谢@StevePiercy 的提示。我之前尝试过.. contents..，但没有想到其中的含义。我会接受你的回答并发布另一个显示我当前解决方案的答案。
@TomPohl 我没有立即提出这个建议，尽管我怀疑它可能会起作用。 .. contents:: 为其放置的文件创建一个目录，因此因为您正在生成 1 个单个文件，它应该适用于所有内容。 toctree 不起作用是有道理的，因为您引用的所有外部文件现在都集中在一个文件中。您对.. include:: 的使用之所以有效，是因为它本质上是一种替换（包含），然后由.. contents:: 处理。

【解决方案2】：

正如@mzjn 已经怀疑的那样，.. contents:: 只列出了当前文件的内容，但是如果我使用.. include:: 而不是.. toctree:: 来包含其他文件，它仍然可以工作。所以我目前使用的是这样的：

.. sectnum::
.. contents:: Table of Contents
   :depth: 2

.. include:: intro.rst
.. include:: processes.rst

【讨论】：