将所有 :glob:-discovered 文件折叠到一个 TOC 条目中答案

【问题标题】：Collapse all :glob:-discovered files into one TOC entry将所有 :glob:-discovered 文件折叠到一个 TOC 条目中
【发布时间】：2020-12-15 17:40:31
【问题描述】：

我有这样的东西：

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

   docs
   frontend
   backend
   tools/*

我希望在tools 目录中找到的所有文档都折叠成一个可展开的侧边栏 TOC 条目。应该可以，但我找不到线索。

我使用sphinx_rtd_theme。

换句话说：假设我有一个很长的文档，像这样 (tools.rst)：

Section 1
*********

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

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

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

我应该如何按小节拆分它并保留文档结构，而不求助于包含，无论如何它都不适合 Sphinx。

【问题讨论】：

您的“超长文档”在哪里？是tools/example.rst吗？您是说这些小节没有出现在侧边栏导航中吗？你试过:maxdepth: 3吗？
没有。我有一个很长的tools.rst，在我的source 目录中有一个部分标题；我想将其拆分为source/tools 并保留结构（单个部分标题）。我没有管理它。
tools.rst 和 tools 都不在 toctree 中。这就是它没有出现在导航中的原因。您必须在 toctree 列表中拥有其中之一才能显示。
哦，这只是编辑后的index.rst。当然，tools.rst 最初出现在 index.rst 中。我没有设法将其拆分并移动到source/tools 并且保留外观和层次结构。 Section 不再是 Subsections 的根。顺便说一句，include 指令可以工作，但它们丑陋且麻烦。
请用文件的当前状态更新您的问题，以及您在当前状态下遇到的问题。我根本追不上你。

标签： python-sphinx toctree

【解决方案1】：

source/index.rst:

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

   tools/_tools
   docs
   frontend
   backend
   tmp/*

老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

新source/tools/_tools.rst:

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

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

   *

新版本的渲染与旧版本完全一样，并且更加通用且更简洁。

【讨论】：