当我运行sphinx-apidoc,然后运行make html时,它会在目录(TOC)中的每个模块/包名称的末尾生成“子包”和“子模块”部分以及“模块”和“包”的文档页面。在不编辑Sphinx源代码的情况下,如何防止编写这些额外的标题?
下面是我想要制作的一个文档页面示例(注意TOC):
http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation
据我所知,这是由于sphinx源代码中的apidoc.py文件(第88行):
我可以手动编辑每个单独的.rst文件来删除这些标题,或者只是从脚本中删除这些代码行,但是接下来我必须编译Sphinx源代码。在不手动编辑Sphinx源代码的情况下,是否有一种自动完成此操作的方法?
发布于 2016-02-07 06:27:33
当我发现这个问题的时候我自己也在挣扎..。给出的答案并没有完全实现我想要的结果,所以我发誓当我想出来的时候会回来的。:)
为了从自动生成的标题中删除“包”和“模块”,并拥有真正自动的文档,您需要在几个地方进行更改,所以请容忍我。
首先,您需要处理sphinx-apidoc选项。我用的是:
sphinx-apidoc -fMeET ../yourpackage -o api假设您在docs目录中运行该文件,这将为文档提供yourpackage源代码,并将生成的文件放在docs/api中。我在这里使用的选项将覆盖现有文件,将模块文档放在子模块文档之前,将每个模块的文档放在自己的页面上,避免创建模块/包标题(如果您的docstring已经拥有它们),并且不会创建目录文件。
这是很多要记住的选项,所以我只是将它添加到我的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”标题的yourpackage.rst文件,所以我们需要最后一段配置。在conf.py文件中,找到exclude_patterns选项并将该文件添加到列表中。它应该是这样的:
exclude_patterns = ['_build', 'api/yourpackage.rst']现在,您的文档应该与您在模块文档字符串中设计的文档完全一样,您不必担心Sphinx文档和您的代码文档不同步!
发布于 2014-06-11 10:36:21
现在可能已经很晚了,但maxdepth或titlesonly的选项应该能做到这一点。
发布于 2016-12-21 13:26:32
answer by Jen Garcia提供了很多帮助,但它需要将重复的包名称放在docstring中。我使用Perl一行程序删除Makefile中的“模块”或“包”后缀:
docs:
rm -rf docs/api docs/_build
sphinx-apidoc -MeT -o docs/api wdmapper
for f in docs/api/*.rst; do\
perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
done
$(MAKE) -C docs htmlhttps://stackoverflow.com/questions/21003122
复制相似问题