python - 如何从代码自动在 sphinx 中创建顶级文档？

Question

我有一个 python 包，我可以使用 python 代码自动创建 sphinx 文档

sphinx-apidoc -f -o source --full path_to_package
make html

这很好用，html 列出了所有子模块及其文档。

但在 html 中我看到以下部分/文本:

Package name
  Submodules
  First module
    docu...
  Second module
    docu ...

每个模块确实有它的文档，但是如何将 tom 文档文本直接放在包名称下面？我想要具有以下结构:

Package name
  General package documentation...
  Submodules
  First module
    docu...
  Second module
    docu ...

如何生成文档以显示在 sphinx 生成文档的顶层，描述整个包，仅通过更改 python 包中的代码？我不想更改/添加/修改 sphinx 生成的任何文件。

这可能吗，如何实现？

Answer 1

首先将文档作为文档字符串放入包__init__.py文件中。

然后查看包含您的 .rst 文件的文档文件夹。 编辑包的 .rst - 最后是模块内容的那个。

然后剪切模块内容部分并将其粘贴到子包上方的顶部。 然后运行 ​​make html。

我意识到该操作在原始问题中只声明更改 python 代码，但鉴于他后来的评论，这似乎确实是答案。