如何为大量模块结构化Sphinx文档

Question

如果我需要支持“常规”散文文档和30多个模块的API文档，则如何最好地构建Sphinx文档（用于Read the Docs）？其中有一些（<10）常规散文文档页面，例如“入门”，“构建代码”，“常见问题解答”，“支持”等。我知道如何处理这些。另一方面，我的项目包含30多个模块，其中API文档不能从代码（非Python）中提取，而必须手动编写。每个模块都有n个函数，并且每个函数都必须使用相同的结构进行记录。我想每个模块都有一个.rst文件。因此，我希望拥有的目录结构如下：

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

在Read the Docs侧边导航（即目录）中，我希望看到以下表示方式：

+ 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来实现这一点？

- Marcel Stör

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

- devin_s