python - Python 模块/包名称的 Sphinx apidoc 部分标题

Question

当我运行 sphinx-apidoc 然后 make html 时，它会生成包含“Subpackages”和“Submodules”部分以及“module”和“package”的文档页面目录 (TOC) 中每个模块/包名称的末尾。如何在不编辑 Sphinx 源代码的情况下防止编写这些额外的标题？

这是我想制作的示例文档页面(注意目录):

http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation

我理解这是由于 sphinx 源中的 apidoc.py 文件(第 88 行):

https://bitbucket.org/birkenfeld/sphinx/src/ef3092d458cc00c4b74dd342ea05ba1059a5da70/sphinx/apidoc.py?at=default

我可以手动编辑每个单独的 .rst 文件以删除这些标题或只是从脚本中删除这些代码行，但随后我必须编译 Sphinx 源代码。是否有一种无需手动编辑 Sphinx 源代码即可自动执行此操作的方法？

Answer 1

当我发现这个问题时，我自己也在努力解决这个问题……给出的答案并没有完全满足我的要求，所以我发誓要在弄清楚后回来。 :)

---

为了从自动生成的标题中删除“包”和“模块”并拥有真正自动的文档，您需要在几个地方进行更改，请耐心等待。 p>

首先，您需要处理您的sphinx-apidoc 选项。我使用的是:

sphinx-apidoc -fMeET ../yourpackage -o api

假设您从 docs 目录中运行它，这将获取 yourpackage 的文档并将生成的文件放在 docs/api .我在这里使用的选项将覆盖现有文件，将模块文档放在子模块文档之前，将每个模块的文档放在其自己的页面上，如果您的文档字符串已经有它们，则放弃创建模块/包标题，并且它不会创建目录文件。

有很多选项需要记住，所以我只是将其添加到我的 Makefile 的末尾:

buildapi:
    sphinx-apidoc -fMeET ../yourpackage -o api
    @echo "Auto-generation of API documentation finished. " \
          "The generated files are in 'api/'"

有了这个，您可以运行 make buildapi 来构建您的文档。

接下来，在您的文档的根目录下创建一个 api.rst 文件，内容如下:

API Documentation
=================

Information on specific functions, classes, and methods.

.. toctree::
   :glob:

   api/*

这将创建一个目录，其中包含 api 文件夹中的所有内容。

不幸的是，sphinx-apidoc 仍会生成一个带有难看的“yourpackage package”标题的yourpackage.rst 文件，因此我们需要最后一项配置。在您的 conf.py 文件中，找到 exclude_patterns 选项并将此文件添加到列表中。它应该看起来像这样:

exclude_patterns = ['_build', 'api/yourpackage.rst']

现在您的文档应该看起来与您在模块文档字符串中设计的完全一样，您永远不必担心您的 Sphinx 文档和代码内文档不同步!