有关Python模块/包名称的Sphinx apidoc部分标题 [英] Sphinx apidoc section titles for Python module/package names

问题描述

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

以下是我要制作的示例文档页面(请注意TOC)：

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

我知道这是由于sphinx源代码(第88行)中的apidoc.py文件造成的：

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

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

推荐答案

我自己也在纠结这个问题，这时我发现了这个问题...给出的答案没有完全达到我想要的效果，所以我发誓当我弄清楚的时候一定会回来。：)

---

为了从自动生成的标题中删除"Package"和"MODULE"，并使文档真正自动，您需要在几个地方进行更改，因此请原谅我。

首先，您需要处理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文档和代码中的文档不同步！

这篇关于有关Python模块/包名称的Sphinx apidoc部分标题的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！