当我运行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源的自动方式?
当我发现这个问题时,我正在努力解决这个问题......所给出的答案并不完全符合我的要求,所以当我想出来时,我发誓要回来.:)
为了从自动生成的标题中删除"包"和"模块"并拥有真正自动的文档,您需要在几个地方进行更改,所以请耐心等待.
首先,您需要处理您的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文档和您的代码内文档不同步!