python-sphinxtoctree

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

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.

Solution

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