Sphinx LaTeX 目录 - 避免包含的 rst 文件的目录树嵌套答案

【问题标题】：Sphinx LaTeX Table of Contents - avoid toctree nesting of included rst filesSphinx LaTeX 目录 - 避免包含的 rst 文件的目录树嵌套
【发布时间】：2020-07-29 09:41:43
【问题描述】：

我有一个 Sphinx 文档，其结构如下：

My chapter title
=====================

Chapter intro part 1
--------------------------
Brief introduction that I would like to have in the start of this chapter...

Chapter intro part 2
--------------------------
Another short section ...


.. toctree::
   :hidden:
   :maxdepth: 2

   folder/subchapter1
   folder/subchapter2

当我基于此渲染 HTML 时，一切都会按预期工作 - 我有一个本章的起始页，我的子章节可以从侧面菜单中找到。

但是，当我构建我的 LaTeX/PDF 输出时，层次结构在目录和编号中如下所示：

0.2 My chapter title
- 0.2.1 Chapter intro part 1
- 0.2.2 Chapter intro part 2
  - 0.2.2.1 subchapter1
  - 0.2.2.2 subchapter2

我想要的如下：

0.2 My chapter title
- 0.2.1 Chapter intro part 1
- 0.2.2 Chapter intro part 2
- 0.2.3 subchapter1 title
- 0.2.3 subchapter2 title

或者：

0.2 My chapter title
0.2.1 subchapter1 title
0.2.2 subchapter2 title

我意识到这可能是在尝试“破解”toctree 概念，但我正在尝试使用相同的代码同时满足我对 HTML 和 LaTeX 的层次结构要求。

我正在使用 Sphinx 1.8.5 和默认的 LaTeX 构建设置。

【问题讨论】：

您的toctree 位于标题Chapter intro part 2 下，并将继承其编号。 IMO 更正确的结构是将介绍移动到它们自己的章节索引文件中——chapter1/index 和 chapter2/index——每个都有自己的子 toctree，子章节文件到正确的 chapterN 文件夹中。因此，您的根 index 文件正是它应该用于的，一个索引。或者，您可以创建一个单独的 latexindex.rst 并将其用于乳胶构建，例如 Pyramid's docs。

标签： latex python-sphinx tableofcontents toctree

【解决方案1】：

我最终使用了如下结构：

Hardware
=============================

.. only:: html

  .. include:: hardware/intro.rst


.. toctree::
   :hidden:
   :maxdepth: 2

   hardware/intro
   hardware/installation
   hardware/connector

在conf.py我加了：

if tags.has("output_html"):
    exclude_patterns.append("*/intro.rst")

在我的构建过程中，我添加了标签output_html，因为在conf.py 中无法访问标准html 标签。有了这个，我得到了我想要的。

【讨论】：