Collapse all :glob:-discovered files into one TOC entry

Question

I've got something like this:

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :hidden:
   :glob:

   docs
   frontend
   backend
   tools/*

I'd like all the documents found in the tools directory to collapse into one expandable sidebar TOC entry. Should be possible, but I can't find a clue.

I use sphinx_rtd_theme.

To put it another way: suppose I have a very long document like this (tools.rst):

Section 1
*********

Subsection 1
============

Subsection 2
============

Subsection 3
============

How am I supposed to split it by the subsection and preserve the document structure, without resorting to includes, which don't sit well with Sphinx anyway.

Monachism

Where is your "very long document"? Is it tools/example.rst? Are you saying that the subsections do not appear in the sidebar navigation? Did you try :maxdepth: 3? – Eudosia

No. I've got a very long tools.rst with one section heading in my source directory; I'd like to split it into source/tools and preserve the structure (a single section heading). I did not manage it. – Monachism

Neither tools.rst nor tools is in the toctree. That is why it does not appear in the navigation. You must have one of them in the toctree listing for it to appear. – Eudosia

Oh, It's just the edited index.rst. Of course, tools.rst initially was present in the index.rst. I did not manage to split and move it into source/tools and preserve the appearance and hierarchy. The Section no longer is root to Subsections. Include directives work, by the way, but they are ugly and cumbersome. – Monachism

Please update your question with the current state of your files and what problem you face with their current state. I cannot follow you at all. – Eudosia

Sorry. I discovered what I wanted, at last, and made an answer. – Monachism

Answer 1

source/index.rst:

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   :glob:

   tools/_tools
   docs
   frontend
   backend
   tmp/*

Old source/tools/_tools.rst:

Notes on tools
**************

.. include:: black.rst
.. include:: docker.rst
.. include:: git_hooks.rst
.. include:: github_webhooks.rst
.. include:: mypy.rst
.. include:: pipm.rst
.. include:: poetry.rst
.. include:: sphinx.rst
.. include:: uvicorn.rst

New source/tools/_tools.rst:

Notes on tools
**************

.. toctree::
   :maxdepth: 2
   :glob:

   *

The new one renders exactly like the old one, and is more versatile an a lot cleaner.

Monachism