如何将单个部分中的Sphinx章节分成不同的文件？

Question

我正在使用精彩的Sphinx工具来创建一些文档，我试图通过将同一部分的章节分成单独的文件来保持代码库的模块化形式。 （See here for definitions of 'chapter' and 'part'.）

我尝试使用两个文件test1.rst执行此操作：

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

和test2.rst：

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

它们包含在index.rst中，如下所示：

.. toctree::
   :maxdepth: 2

   test1
   test2

但是，在构建时，第2章没有嵌套在第1部分中。为什么会这样？有没有办法这样做而无需创建脚本将它们附加到单个文件中，如下例所示？

示例：

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

*********
Chapter 2
*********

Section 2
=========
Test Content 2.

Answer 1

似乎include指令正是您所寻找的。包含文件的内容将被解析并包含在指令中。

test1.rst：

######
Part 1
######

*********
Chapter 1
*********

Section 1
=========
Test Content 1.

.. include:: test2.rst