首页
学习
活动
专区
圈层
工具
发布
社区首页 >问答首页 >Python模块/包名称的Sphinx apidoc节标题

问Python模块/包名称的Sphinx apidoc节标题
EN

Stack Overflow用户
提问于 2014-01-08 18:00:24
回答 6查看 7.3K关注 0票数 18

当我运行sphinx-apidoc,然后运行make html时,它会在目录(TOC)中的每个模块/包名称的末尾生成“子包”和“子模块”部分以及“模块”和“包”的文档页面。在不编辑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源代码的情况下,是否有一种自动完成此操作的方法?

EN

回答 6

Stack Overflow用户

回答已采纳

发布于 2016-02-07 06:27:33

当我发现这个问题的时候我自己也在挣扎..。给出的答案并没有完全实现我想要的结果,所以我发誓当我想出来的时候会回来的。:)

为了从自动生成的标题中删除“包”和“模块”,并拥有真正自动的文档,您需要在几个地方进行更改,所以请容忍我。

首先,您需要处理sphinx-apidoc选项。我用的是:

代码语言:javascript
复制
sphinx-apidoc -fMeET ../yourpackage -o api

假设您在docs目录中运行该文件,这将为文档提供yourpackage源代码,并将生成的文件放在docs/api中。我在这里使用的选项将覆盖现有文件,将模块文档放在子模块文档之前,将每个模块的文档放在自己的页面上,避免创建模块/包标题(如果您的docstring已经拥有它们),并且不会创建目录文件。

这是很多要记住的选项,所以我只是将它添加到我的Makefile末尾

代码语言:javascript
复制
buildapi:
    sphinx-apidoc -fMeET ../yourpackage -o api
    @echo "Auto-generation of API documentation finished. " \
          "The generated files are in 'api/'"

这样,您就可以运行make buildapi来构建您的文档。

接下来,在文档的根目录创建一个api.rst文件,内容如下:

代码语言:javascript
复制
API Documentation
=================

Information on specific functions, classes, and methods.

.. toctree::
   :glob:

   api/*

这将创建一个包含api文件夹中所有内容的目录。

不幸的是,sphinx-apidoc仍然会生成一个带有丑陋的“yourpackage”标题的yourpackage.rst文件,所以我们需要最后一段配置。在conf.py文件中,找到exclude_patterns选项并将该文件添加到列表中。它应该是这样的:

代码语言:javascript
复制
exclude_patterns = ['_build', 'api/yourpackage.rst']

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

票数 23
EN

Stack Overflow用户

发布于 2014-06-11 10:36:21

现在可能已经很晚了,但maxdepth或titlesonly的选项应该能做到这一点。

更多细节:http://sphinx-doc.org/latest/markup/toctree.html

票数 4
EN

Stack Overflow用户

发布于 2016-12-21 13:26:32

answer by Jen Garcia提供了很多帮助,但它需要将重复的包名称放在docstring中。我使用Perl一行程序删除Makefile中的“模块”或“包”后缀:

代码语言:javascript
复制
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 html
票数 3
EN
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://stackoverflow.com/questions/21003122

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档