2

如果我需要同时支持 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()
 + ...

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

4

1 回答 1

3

您应该创建包含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
于 2015-12-14T23:22:54.957 回答