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

Question

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

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

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

当我发现这个问题时,我正在努力解决这个问题......所给出的答案并不完全符合我的要求,所以当我想出来时,我发誓要回来.:)

为了从自动生成的标题中删除"包"和"模块"并拥有真正自动的文档,您需要在几个地方进行更改,所以请耐心等待.

首先,您需要处理您的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.rst带有丑陋的'yourpackage包'标题的文件,因此我们需要最后一个配置.在您的conf.py文件中,找到该exclude_patterns选项并将此文件添加到列表中.它应该看起来像这样:

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

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