latexpython-sphinxtableofcontentstoctree

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


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.


Solution

  • 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.