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

Question

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

有一些（＆lt; 10）常规散文文档页面，例如“入门”，“构建代码”，“常见问题”，“支持”等。我知道如何处理这些。

另一方面，我的项目包含30多个模块，无法从代码（非Python）中提取API文档，但也必须手动编写。每个模块都有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()
 + ...

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

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