问题
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.
来源：https://stackoverflow.com/questions/25276415/prevent-sub-section-nesting-in-python-sphinx-when-using-toctree