如何为许多模块构建Sphinx文档

Question

如果我需要同时支持30多个模块的"常规"散文文档和API文档，我如何最好地构建Sphinx文档（用于阅读文档）？

有许多（<10）常规散文文档页面，如"入门"、"构建代码"、"常见问题解答"、"支持"等。我知道如何处理这些页面。

另一方面，我的项目由30多个模块组成，API文档无法从代码（非Python）中提取，但也必须手动编写。每个模块有n个功能，每个模块都必须使用相同的结构进行记录。我希望每个模块有一个.rst。

因此，我想要的目录结构如下：

docs
├── building.rst
├── faq.rst
├── ...
├── index.rst
└── modules
    ├── node.rst
    ├── ...

在"读取文档"侧导航（即ToC）中，我希望将其表示为

+ Building (header 1)
 - chapter 1 (header 2)
 - ...
+ FAQ
 - question 1
 - ...
+ Modules
 + node (header 1 from `modules/node.rst`)
   - node.foo()
   - node.bar()
 + ...

可以/应该通过在modules目录中放置另一个index.rst来实现这一点吗？

Answer 1

您应该创建一个包含toctree指令的索引文件层次结构，这些指令引用包含自己的toctree指令的文件。下面是一个布局示例：

index.rst:

Index
=====
.. toctree::
   modules/index

modules/index.rst:

Modules
=======
.. toctree::
   node1
   node2

modules/node1.rst:

Node 1
======
Node 1 contents

modules/node2.rst:

Node 2
======
Node 2 contents