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 ...

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

这可能吗，怎么做？

Answer 1

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

然后查看包含您的文件的 docs 文件夹.rst。编辑.rst包的 - 最后带有模块内容的包。

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

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