python-sphinx - 一种让 Sphinx 文档小节开始新页面的方法？

Question

我需要一种方法来摆脱 Sphinx 的限制，即 HTML 输出每个级别 1 标题包含一个且只有一个页面。为了可读性，我的文档的一些内容必须在较低的标题级别分成页面。

我正在考虑是否可以通过操作左侧边栏中的目录来做到这一点，如下所示。

假设我有一个具有这种结构的文档：

Little section
    A subsection
    Another subsection
Big section
    Level 2 in a big section
    Another level 2 in a big section
Another little section

通常，文档会有三页，以“小部分”、“大部分”和“另一个小部分”开头。但我想要另外两页，从标题“大节中的第 2 级”和“另一个大节中的第 2 级”开始。我会这样做如下。

将每个 2 级部分放在一个单独的 reST 文件中，从 Sphinx 的角度来看，这使其初始标题成为 1 级标题。

将:orphan:选项添加到每个“2 级”reST 文件，使其不会自动出现在侧边栏目录中。

手动将 level-2 条目添加到“Big section”下的侧边栏 TOC，其中包含文本“Level 2 in a big section”和“Another level 2 in a big section”，并链接到孤立的“level 2”文件。

我在问这是否可能，因为我在 sphinx-doc.org Directives 页面上看到了以下声明。我已将相关部分用斜体表示：

您还可以为 [toctree] 指令提供“隐藏”选项，如下所示：

.. toctree::
   :hidden:

   doc_1
   doc_2

这仍然会通知 Sphinx 文档层次结构，但不会在指令所在的位置将链接插入到文档中 - 如果您打算自己插入这些链接，以不同的样式或在 HTML 侧边栏中插入这些链接，这是有意义的。

这似乎在说：是的，我的建议是可能的。但我找不到它是如何完成的线索。任何人都可以提供见解吗？

标签： python-sphinx