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

[Denis Bitouzé]

Hi,

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 depending on
the depth's levels of the folders they belong to?

Thanks.
--
Denis

[Luc Saffre]

Interesting idea.
This should be clearly optional because there are doctrees that rely precisely on the feature of having the logical structure independent from file system structure.
Luc

Denis --
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/3e00313f-3985-48b6-9c09-592daa0922b6n%40googlegroups.com.

[Denis Bitouzé]

Le 02/12/20 à 10h59, Luc Saffre a écrit :

> Interesting idea.

Thanks :)

> This should be clearly optional

Of course.

> because there are doctrees that rely precisely on the feature of
> having the logical structure independent from file system structure.

Agree.

But, meanwhile, do you see any way to temporarily active the feature I'm requesting?

Thanks!
--
Denis

[Luc Saffre]

On 02.12.20 11:26, Denis Bitouzé wrote:

But, meanwhile, do you see any way to temporarily active the feature I'm requesting?

No, sorry, I have no idea where to start with such a feature. I'm afraid that it isn't a quick win. But I don't know enough about the inner life of Sphinx, so my feeling isn't actually relevant.

Luc

[Komiya Takeshi]

Hi,

Sphinx does not mind the depth of the document itself. It only minds
how sections are "nested".

To make your subsections "nested", please append sub-toctree to
foo0.rst and subfolder1/foo1.rst like following:

```
# foo0.rst

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

.. toctree::

subfoloder1/foo1
```

```
# subfoloder1/foo1.rst

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

.. toctree::

subfoloder2/foo2
```

Then you'll see a ToC tree as expected.

Thanks,
Takeshi KOMIYA

2020年12月2日(水) 5:08 Denis Bitouzé <denis....@gmail.com>:

[Denis Bitouzé]

Le 12/12/20 à 18h11, Komiya Takeshi a écrit :

> Hi,

Hi,

> Sphinx does not mind the depth of the document itself. It only minds
> how sections are "nested".

OK.

> To make your subsections "nested", please append sub-toctree to
> foo0.rst and subfolder1/foo1.rst like following:
>
> ```
> # foo0.rst
>
> This a title
> ============
>
> .. toctree::
>
>    subfoloder1/foo1
> ```
>
> ```
> # subfoloder1/foo1.rst
>
> This a title
> ============
>
> .. toctree::
>
>    subfoloder2/foo2
> ```
>
> Then you'll see a ToC tree as expected.

Thanks!

Nevertheless, the trouble with this solution is, I have about a thousand
files that are currently included in the main index.rst file. So I would
have to edit all of them to write the toctree directive and the path of
the right subfile to include :$
--
Denis