在使用toctree时防止Python Sphinx中的子节嵌套

Question

我在整理我的Sphinx用户指南时遇到了一些问题。我想创建一个章节，里面有一个主页面（index.rst），这个页面包含章节标题和概述，然后再有几个不同的文件（part1.rst, part2.rst）来放置各个子部分。我想用“toctree”来插入这些子部分，但我遇到了一个嵌套的问题，导致我的toctree被吸入了概述部分。（注意：我不使用..include::指令，因为我希望子部分在不同的网页上顺序链接显示。我还希望结构合理，这样在生成的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

看起来我在文件底部插入的toctree落在了“概述”部分下面，而不是在主章节的上下文中。我试着把toctree放在文件顶部，但这样我得到的顺序是：

Chapter 3
  - part 1
  - part 2
  - overview

似乎应该有办法正确做到这一点，但我在Sphinx网站或这里的StackOverflow上找不到相关信息。任何帮助都很感激。

Answer 1

对于latex PDF生成器，你可以像这样把概述放在同一级别的标题里：

.. raw:: latex

    \chapter{Overview}

Answer 2

我也遇到过完全一样的问题，找不到一个好的解决办法。看起来唯一的选择就是要么去掉副标题（上面例子中的“概述”），要么把它标记为一个规则，比如：

.. rubric:: Overview

这样的话，它就不会被包含在目录里。其实应该可以给这个规则加点样式，让它看起来像个副标题，但这样做感觉有点像是变通的办法。