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.

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`? — Steve Piercy, Dec 16 '20 at 08:53
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. — Alexey Orlov, Dec 16 '20 at 09:07
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. — Steve Piercy, Dec 16 '20 at 10:41
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. — Alexey Orlov, Dec 16 '20 at 11:05
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. — Steve Piercy, Dec 16 '20 at 11:41
Sorry. I discovered what I wanted, at last, and made an answer. — Alexey Orlov, Dec 16 '20 at 11:56

score 1 · Accepted Answer · answered Dec 16 '20 at 11:54

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.

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

1 Answers1

Linked