使用 toctree 时防止 Python Sphinx 中的子部分嵌套答案

【问题标题】：Prevent sub-section nesting in Python Sphinx when using toctree使用 toctree 时防止 Python Sphinx 中的子部分嵌套
【发布时间】：2014-10-06 05:42:04
【问题描述】：

我在构建 Sphinx 用户指南时遇到了问题。我想通过一个包含章节标题和概述的主登录页面 (index.rst) 来形成一个章节，然后将包含在不同文件中的子部分分开 (part1.rst, part2.rst)。我正在尝试使用“toctree”来插入单独的小节，但是我遇到了嵌套问题，我的 toctree 被吸入了我的概述部分。（注意：我没有使用..include:: 指令，因为我希望在不同网页上显示的子部分按顺序链接。我还希望结构正确，以便它们在 UG 的 pdf 呈现版本中很好地布局）。

index.rst

Chapter 3                                                
===============================                                                 

Overview                                                                        
--------                                                                        

Yadda yadda yadda.

.. toctree::                                                                    
   :hidden:                                                                     

   part1                                                                        
   part2

part1.rst

Part 1
------

This part is all about yadda.

part2.rst

Part 2
------

More yadda.

我希望得到的结构是：

Chapter 3
  - overview
  - part 1
  - part 2

但我得到的是

Chapter 3
  - overview
    - part 1
    - part 2

我在文件底部包含的目录树似乎属于“概述”部分，而不是在主要章节上下文中运行。我尝试在文件顶部插入目录树，但后来我得到了这个顺序：

Chapter 3
  - part 1
  - part 2
  - overview

似乎必须有一种方法可以正确执行此操作，但我无法在 Sphinx 网站或 SO 上找到任何内容。任何帮助表示赞赏。

【问题讨论】：

这是一个 RST/docutils 问题，不是狮身人面像问题。除了创建一个新的标题之外，似乎没有办法在 rst 中指定“现在回到上一个标题级别”。按照设计，sphinx 通过在目录树所在的位置插入标题来构造目录树。所以斯芬克斯在这里并没有错。
我做了一个 PR 让 sphinx 解决这个问题：github.com/sphinx-doc/sphinx/pull/3622

标签： python python-sphinx restructuredtext toctree

【解决方案1】：

有一个很好的指导如何Create a custom landing page in Sphinx。

这个想法是您为目录创建一个单独的页面 (contents.rst)，并让您的目标网页 index.rst (或 index.html)。然后你改变

master_doc = '内容'

在conf.py 中（默认为index）。

【讨论】：

【解决方案2】：

对于 Latex pdf 生成器，您可以像这样在概述中作为同级标题：

.. raw:: latex

    \chapter{Overview}

【讨论】：

【解决方案3】：

我遇到了完全相同的问题，但找不到好的解决方案。唯一的选择似乎是删除子标题（上例中的“概述”）或将其标记为标题，例如

.. rubric:: Overview

这意味着它不包含在 TOC 中。应该可以将样式应用于量规，使其看起来像一个子标题，但这样做感觉有点像 hack。

【讨论】：