如何为大量模块构建 Sphinx 文档答案

【问题标题】：How to structure Sphinx docs for lots of modules如何为大量模块构建 Sphinx 文档
【发布时间】：2015-12-11 22:13:35
【问题描述】：

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

有许多 (

另一方面，我的项目包含 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 以某种方式实现这一点吗？

【问题讨论】：

标签： python-sphinx read-the-docs

【解决方案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

【讨论】：