python-sphinx - Sphinx RST 在 html 输出中展开子页面

Question

我正在使用 sphinx 文档系统生成 HTML 和 Latex 输出格式的报告。所以有一个层次结构，其中我有一个阅读 index.rst，其中包含一个按出现顺序引用所有章节的 toctree。然后一章是一个文件夹，其中还包含一个仅包含标题的 index.rst 和一个包含该章所有部分的 toctree。

举个例子，我的结构是这样的:

root
    - index.rst <- Contains only a toctree that references other chapters index.rst.
    - SomeChapter
        - index.rst <- Contains heading and toctree that references actual content
        - section1.rst <- actual content
        - section2.rst <- actual content
        ....

这与 latex 呈现精美，因为你会字面上得到 someChapter 和下面的部分，但在 html 中，这些都是单独的页面，对于一些较小的小节来说很快就会变得无聊，因为你必须不断点击。有没有一种方法可以指示 html 生成器在某些情况下它应该在同一页面中显示它们在 toctree 中的子页面而不是为其创建子页面？

我知道 singlehtml 但它确实为它构建了一个完整的单个 html 页面，我想部分地做它，因为很多时候不同的章节适合不同的页面，但部分可以很容易地在同一页面上。

感谢任何帮助。

Answer 1

未经测试的答案。

有两个不同的索引页面，一个用于 HTML (index.rst) 和一个用于 LaTeX (indexlatex.rst)，其中后者是前者的副本，然后前者被修改。

然后在您的 conf.py 中，将 indexlatex.rst 指定为入口目录树。来自 Pyramid 的示例:

latex_documents = [
  ('latexindex', 'pyramid.tex',
  ...
  )

最后要修改 index.rst，您将使用一系列 include 指令并删除 toctree 指令。

.. include:: section1.rst
.. include:: section2.rst

您可能还需要使用 :orphan: metadata在 latexindex 文件上禁止关于它未包含在 index 的 toctree 中的警告。