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