Make the heading levels of documents automatically dependent of the depth's levels of the (sub(sub(...)))folders they belong to

Question

Suppose I have:

• a foo0.rst file at the root (source) of my sphinx-doc source folder,
• a foo1.rst file in a subfolder subfolder1 of source,
• a foo2.rst file in a subfolder subfolder2 of subfolder1,

that is:

$ tree source
source
├── foo0.rst
└── subfolder1
    ├── foo1.rst
    └── subfolder2
        └── foo2.rst

all with the same content:

This a title
============

Now, if the index.rst contains:

Welcome to Test's documentation!
================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   foo0
   subfolder1/foo1
   subfolder1/subfolder2/foo2

make html gives:

Welcome to Test’s documentation!

Contents:

    • This a title
    • This a title
    • This a title

that is all the headings are sections.

What I would like to get instead is the following:

Welcome to Test’s documentation!

Contents:

    • This a title
      ◦ This a title
        ▪ This a title

that is the heading of:

• foo0.rst being a section,
• subfolder1/foo1.rst being a subsection (and not a section),
• subfolder1/subfolder2/foo2.rst being a subsubsection (and not a section).

My question is therefore: is it possible to make the heading levels of documents belonging to (sub(sub(...)))folders automatically depend on the depth's levels of the folders they belong to?

Answer 1

The style applied to the toctree entries is dependent on the theme you are using. The theme's CSS will apply a style to the entries that Sphinx translated into <ul> and <li> depending both on their place within the "document hierarchy" given how you chain the toctrees and how your section structure in the individual .rst files is organized.

For example, inspect the HTML elements Sphinx generates. The toctree will be a div class="toctree-wrapper compound" with each level of sections being named <li class="toctree-l1"> then <li class="toctree-l2">, etc...

One way to achieve what you want would be to surround a given toctree using a .. class:: directive (as show here) and apply a custom style. But that would then impact the style of any other .rst files you want to include as entries in that toctree.

In any case, you will incur in extra work and potentially loose automatism if you refactor your project.

There is also one possible workaround, using the :hidden: option together with the :include: directive. If you declare a hidden toctree before a visible toctree the "document hierarchy" can fix the position of an entry for you in the hierarchy. Afterwards the visible toctree without the :hidden: option will render .rst file entries as a <li> element having a fixed position in the hierarchy. (A thorough example can be seen in this post).

It can be done, but you will be working against the characteristics of the toctree.

The prevalent solution is writing your .rst files and sections depending on how you want the toctree to display. (This approach has all the advantages with the only drawback of putting restrictions on how you write the .rst files). It's probably the preferable solution rather than trying to adapt the CSS styles or using workarounds.

---

EDIT:

What I wrote before is valid, but probably too general. So I'll give one possible solution to the example. If you want the following:

Contents:

    • This a title (foo0)
      ◦ This a title (foo1)
        ▪ This a title (foo2)

A simple option is using a chain of toctrees. You can hide the toctree's that are lower in the document hierarchy if you don't want to see them.

index.rst

.. toctree::
   :maxdepth: 3

   foo0

and in foo0.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/foo1

and in subfolder1/foo1.rst

.. toctree::
   :maxdepth: 3
   :hidden:

   subfolder1/subfolder2/foo2

The result will be as you specified.