有关Python模块/包名称的Sphinx apidoc部分标题

2022-04-20 00:00:00 python python-sphinx title html api-doc

当我运行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文档和代码中的文档不同步!

相关文章