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

Question

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

\n\n

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

\n\n

另一方面，我的项目包含 30 多个模块，这些模块的 API 文档无法从代码（非 Python）中提取，而必须手动编写。每个模块都有 n 个功能，并且每个模块都必须使用相同的结构进行记录。我想要一个.rst每个模块。

\n\n

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

\n\n

docs\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 building.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 faq.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 index.rst\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 modules\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 node.rst\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n

\n\n

在阅读文档侧导航（即目录）中，我希望看到它表示为

\n\n

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

\n\n

可以/应该通过将另一个index.rst放在modules？

\n

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