如何自动递归引用App目录下RST文件生成Sphinx文档

项目结构 #

App
├───2023
│    ├───JULLY
│    │   ├───WEEK26.rst
│    │   └───WEEK27.rst
│    └───JUNE
│        └───WEEK25.rst
├───2022
│    ├───JULLY
│    │   ├───WEEK26.rst
│    │   └───WEEK27.rst
│    └───JUNE
│        └───WEEK25.rst
Doc
├───conf.py
├───modules.rst
├───index.rst

需求 #

在Doc/index.rst中无需硬编码，自动递归引用App目录下所有层级的RST文件，生成「年份→月份→周文档」的层级化HTML结构。

现有问题 #

用户尝试的toctree配置：

Documentation Sections
======================

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

      ../app/2023/JUNE/*.rst

出现报错：

WARNING: toctree glob pattern '../app/2023/JUNE/*.rst' didn't match any documents

报错原因 #

1. 路径大小写不匹配：项目中目录名为App，但配置里写的是../app/，在大小写敏感的系统（如Linux、macOS）中会导致文件查找失败。
2. glob模式范围有限：仅指定单个月份目录，无法实现递归匹配所有层级的RST文件。

解决步骤 #

1. 修正路径大小写 #

将配置中的路径改为正确的大小写形式：../App/2023/JUNE/*.rst，可解决单个目录的匹配报错，但无法满足递归需求。

2. 实现递归匹配所有RST文件 #

要自动递归引用所有层级的文件，结合Sphinx的glob通配符和足够的深度设置：

Documentation Sections
======================

.. toctree::
   :maxdepth: 3  # 对应年份→月份→周的三层结构
   :glob:

   ../App/**/*.rst

• **表示递归匹配所有子目录
• *.rst匹配所有RST文件
• :maxdepth: 3确保层级结构完整展示

3. 生成规范的层级标题结构 #

仅用上述配置会直接显示文件名作为条目，若要生成需求中的层级标题，需为每个目录添加index.rst来组织内容：

3.1 给年份目录添加index.rst

在App/2023/和App/2022/下分别创建index.rst（以2023为例）：

2023
====

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

   */index.rst

3.2 给月份目录添加index.rst

在所有月份目录（如App/2023/JUNE/、App/2023/JULLY/）下创建index.rst（以JUNE为例）：

JUNE
====

.. toctree::
   :maxdepth: 1
   :glob:

   WEEK*.rst

3.3 更新根目录的toctree配置

修改Doc/index.rst的配置，只引用年份目录的index.rst，让层级结构自动嵌套：

Documentation Sections
======================

.. toctree::
   :maxdepth: 3
   :glob:
   :caption: 归档文档

   ../App/*/index.rst

这样生成的HTML文档会自动呈现「年份→月份→周」的层级结构，且无需硬编码所有文件路径。

内容的提问来源于stack exchange，提问作者ravishankar chavare