python-sphinx - 如何将单个部分中的 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 指令是您正在寻找的。包含文件的内容在指令点被解析和包含。

测试1.rst:

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

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

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

.. include:: test2.rst