Sphinx LaTeX Table of Contents - avoid toctree nesting of included rst files

Question

I have a Sphinx documentation with the following structure:

My chapter title
=====================

Chapter intro part 1
--------------------------
Brief introduction that I would like to have in the start of this chapter...

Chapter intro part 2
--------------------------
Another short section ...


.. toctree::
   :hidden:
   :maxdepth: 2

   folder/subchapter1
   folder/subchapter2

When I render the HTML based on this, things work as intended - I have a starting page for this chapter and my sub chapters are available from the side menu.

However, when I build my LaTeX/PDF output, the hierarchy is structured as follows in the Table of Contents and numbering:

0.2 My chapter title
- 0.2.1 Chapter intro part 1
- 0.2.2 Chapter intro part 2
  - 0.2.2.1 subchapter1
  - 0.2.2.2 subchapter2

What I wanted to have was below:

0.2 My chapter title
- 0.2.1 Chapter intro part 1
- 0.2.2 Chapter intro part 2
- 0.2.3 subchapter1 title
- 0.2.3 subchapter2 title

Or alternatively:

0.2 My chapter title
0.2.1 subchapter1 title
0.2.2 subchapter2 title

I realize this is probably an attempt to "hack" the toctree concept a bit, but I'm trying to both satisfy my hierarchy requirements for HTML and LaTeX with the same code.

I'm using Sphinx 1.8.5 and default LaTeX build settings.

Your `toctree` is under the heading `Chapter intro part 2` and will inherit its numbering. IMO a more correct structure would be to move the intros into their own chapter index files—`chapter1/index` and `chapter2/index`—each with their own sub `toctree`, and the subchapter files into the correct `chapterN` folder. Thus your root `index` file is exactly what it should be used for, an index. Alternatively you can create a separate `latexindex.rst` and use that for latex builds, like in [Pyramid's docs](https://github.com/Pylons/pyramid/tree/master/docs). — Steve Piercy, Apr 16 '20 at 08:16

score 1 · Accepted Answer · answered Apr 22 '20 at 11:39

I ended up using a structure as below:

Hardware
=============================

.. only:: html

  .. include:: hardware/intro.rst


.. toctree::
   :hidden:
   :maxdepth: 2

   hardware/intro
   hardware/installation
   hardware/connector

In the conf.py I added:

if tags.has("output_html"):
    exclude_patterns.append("*/intro.rst")

And in my build process I add the tag output_html as the standard html tag is not accessible in the conf.py. With this I got what I wanted.

Sphinx LaTeX Table of Contents - avoid toctree nesting of included rst files

1 Answers1