Menu
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.
909
All other toctree entries can then be eliminated by the “hidden” option. In the end, all documents in the source directory (or subdirectories) must occur in some toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.
Since reST does not have facilities to interconnect several documents, or split documents into multiple output files, Sphinx uses a custom directive to add relations between the single files the documentation is made of, as well as tables of contents. The toctree directive is the central element.
In the end, all documents in the source directory (or subdirectories) must occur in some toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.
To enable Intersphinx, add the string 'sphinx.ext.intersphinx'to the extensionslist in your conf.pyfile. Then, add a variable to your conf.pyfile called intersphinx_mappingwhich contains a dict of module names to their API reference urls, like this:
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.
66
For the latex pdf generator, you could sneek in overview as a same-level heading like this:
.. raw:: latex
\chapter{Overview}
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
