Prevent sub-section nesting in Python Sphinx when

2019-02-16 14:17发布

问题:

I'm running into a problem in structuring my Sphinx users guide. I would like to form a chapter by having a main landing page (index.rst) that contains the chapter heading and an overview, and then separate sub-sections contained in different files(part1.rst, part2.rst). I am trying to use "toctree" to insert the separate subsections, but I am running into a nesting problem where my toctree is getting sucked into my overview section. (note: I am not using the ..include:: directive because I want the sub-sections displayed on different web pages sequentially linked. I also want the structured properly so they lay out nicely in the pdf rendered version of the UG).

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.

I would like the resulting structure to be:

Chapter 3
  - overview
  - part 1
  - part 2

But what I'm getting is

Chapter 3
  - overview
    - part 1
    - part 2

It seems like the toctree I include at the bottom of the file is falling under the "overview" section, instead of being run under the main chapter context. I tried inserting the toctree at the top of the file, but then I get this ordering:

Chapter 3
  - part 1
  - part 2
  - overview

It seems like there must be a way to do this properly, but I haven't been able to find anything on the Sphinx site or here on SO. Any help is appreciated.

回答1:

I had exactly the same problem, and couldn't find a nice solution. The only options seemed to be either remove the sub-heading ('Overview' in the example above) or mark it up as a rubric, e.g.

.. rubric:: Overview

which means it doesn't get included in the TOC. It should be possible to apply styling to the rubric so it looks like a sub-heading, but doing it this way feels like a bit of a hack.