python - 使用 toctree 时防止 Python Sphinx 中的子部分嵌套

Question

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

索引.rst

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

Overview                                                                        
--------                                                                        

Yadda yadda yadda.

.. toctree::                                                                    
   :hidden:                                                                     

   part1                                                                        
   part2

第 1 部分.rst

Part 1
------

This part is all about yadda.

第 2 部分.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 上找到任何东西。任何帮助表示赞赏。

Answer 1

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

.. rubric:: Overview

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

Answer 2

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

.. raw:: latex

    \chapter{Overview}

Answer 3

关于如何在 Sphinx 创建自定义登录页面有一个很好的指南。

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

master_doc = '内容'

在conf.py（index默认情况下）。