在 sphinx 中构建反映项目文件夹结构的目录

Question

我想为 python 项目自动生成文档。我设法获得了一个与 sphinx 一起使用的准系统管道，但输出不是很漂亮，我希望得到一些有关如何使输出更清晰和输入更易于维护的指导。

我的项目是这样组织的：

docs
   |-- build
   |-- index.rst
   |-- conf.py
app
   |-- main_app.py #entry point that intializes everything, internal imports in .py files are relative to here
   views
      |-- view1.py
      |-- view2.py
      |-- ...
   controllers
      |-- controller1.py
      |-- ...
   models
      |-- model1.py
      |-- ...
   utils
      |-- ...
   plugins
      |-- ...

生成的目录是扁平的，如下所示：

app
   app.controller.controller1
   app.models.model1
   app.utils.util1
   ...

我希望有一个具有多个嵌套级别的目录，以重现

app

文件夹的文件夹结构。我如何修改或重新分配我的

index.rst

（如下）以实现此目的？

.. automodule:: app.utils.MetaReader
    :members:
...
.. automodule:: app.models.main_model
    :members:
...more automodule statements ...

.. toctree::
   :maxdepth: 4
   :caption: Contents:

Answer 1

我将它们放在

docs/api/GROUP_NAME/*.rst

中，这样它就可以反映您的 API 文件目录结构。

在

docs/index.rst

中，您可以为每个

toctree

添加一个

api/GROUP_NAME/module.rst

条目。

您还可以在每个嵌套文件夹中包含索引文件。您可以遵循这个 2 级深度示例：https://github.com/Pylons/pyramid/tree/main/docs/api。