Place minor pages in the right place in the TOC

Question

In my sphinx documentation, I have some minor pages that (of course) need to be part of the toctree, but I can't get them listed in the right place.

If my "section 3" page looks like so:

.. toctree::
   3.3
   3.4

3
=====



3.1
-----


3.2
---

Then 3.3 and 3.4 are listed before 3.

I've tried other permutations, but none seem to work.

1. If I put the toctree after the 3 heading then 3.3 and 3.4 are listed between 3 and 3.1.
2. If I put the toctree at the end of the page, everything is in the right order, but 3.3 and 3.4 become third-level sections, children of section 3.2.

---

I've put up a concrete example, here:

• http://sphinx-problem.readthedocs.org/en/latest/
• https://github.com/bukzor/sphinx-problem

Answer 1

To get the general structure right, you can user the include directive as follows:

3
=====

3.1
-----

3.2
---

.. include:: 3_3.rst

.. include:: 3_4.rst

Still, there is no good way to have these sections listed in a toctree on the same page. Listing self in the toctree will only show the first level heading and a direct self-reference - in your example to further-detail-1 - will work for html (although it will cause a warning), but mess up the latexpdf build.

As a workaround, you could simply hard-code your own toctree using a list of references.