Question

我在构建我的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

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

Chapter 3
  - part 1
  - part 2
  - overview

似乎必须有一种方法可以正确地做到这一点，但我无法在Sphinx网站或SO上找到任何东西。任何帮助表示赞赏。

Answer 1

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

.. rubric:: Overview

这意味着它不会包含在TOC中。应该可以在样式上应用样式，因此它看起来像一个小标题，但这样做就像是一个黑客。

Answer 2

对于乳胶pdf生成器，您可以像这样的同级标题浏览概览：

.. raw:: latex

    \chapter{Overview}

Answer 3

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

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

<块引用>

master_doc = '内容'

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

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

3 个答案: