Sphinx 可以先发出 'module contents' 而最后发出 'submodules' 吗？

Question

我通常将 Python 包的高级文档放入其 __init__.py 文件的文档字符串中。这对我来说很有意义，因为 __init__.py 文件代表包与外界的接口。（而且，真的，你还会把它放在哪里？）

所以，当我第一次启动 Sphinx 并看到这个内容埋在包文档的最后，在所有子模块的内容之后时，我真的很惊讶。

这对我来说似乎很落后。用户将在访问包页面时看到的第一件事是恰好按字母顺序排在第一位的子模块的文档，而他应该首先看到的就是底部附近。

我想知道是否有办法解决这个问题，让 __init__.py 中的内容先出来，然后再子模块中的所有内容。如果我只是以错误的方式解决这个问题，我想知道这一点。谢谢！

Answer 1

有一段时间没有使用 Sphinx，但看起来他们在更新方面做得很好。过去，我不得不手动指定类，因为我不喜欢 autodoc 生成 methods/functions 的方式。现在看来您可以订购它们了：

.. autoclass:: YourClass
   :members: __init__, __getitem__

http://www.sphinx-doc.org/en/stable/ext/autodoc.html

Answer 2

更新的答案（谢谢 Donal Fellows）：

https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-M

原答案：

是的，有一个选项可以做到这一点，只是没有记录 here。在我的 Sphinx-1.3.3/sphinx/apidoc.py 副本中，我发现了这个：

parser.add_option('-M', '--module-first', action='store_true',
                  dest='modulefirst',
                  help='Put module documentation before submodule '
                  'documentation')

我试过了，效果很好。

Answer 3

也可以在 conf.py 文件中添加此选项。

在 conf.py 中搜索包含 sphinx-apidoc 命令的字符串所在的行（位于 try 部分）并添加 "--module-first" 选项。

新行将如下所示：

cmd_line_template = "sphinx-apidoc --module-first -f -o {outputdir} {moduledir}"

Sphinx 可以先发出 'module contents' 而最后发出 'submodules' 吗？

Can Sphinx emit the 'module contents' first and the 'submodules' last?

python-sphinx