Prevent sub-section nesting in Python Sphinx when using toctree

17
votes

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.

3
pythonpython-sphinxrestructuredtexttoctree
This is an RST/docutils problem, not a sphinx problem. It seems that there is no way to specify "now go back under the previous heading level" in rst, other than by creating a new heading. By design, sphinx constructs the toc-tree by inserting the headings in the location where the toctree is. So sphinx isn't really in the wrong here. – Eric
I've made a PR to let sphinx work around this: github.com/sphinx-doc/sphinx/pull/3622 – Eric

3 Answers

5
votes

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.

1
votes

For the latex pdf generator, you could sneek in overview as a same-level heading like this:

.. raw:: latex

    \chapter{Overview}
0
votes

There is a good guide on how to Create a custom landing page in Sphinx.

The idea is that you create a separate page for the toc (contents.rst), and make your landing page index.rst (or index.html). Then you change

master_doc = 'contents'

in conf.py (it was index by default).