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

When I run sphinx-apidoc and then make html it produces doc pages that have "Subpackages" and "Submodules" sections and "module" and "package" at the end of each module/package name in the table of contents (TOC). How might I prevent these extra titles from being written without editing the Sphinx source?

当我运行sphinx-apidoc然后生成html时,它会生成doc页面,其中包含“Subpackages”和“Submodules”部分以及目录(TOC)中每个模块/包名称末尾的“module”和“package”。如何在不编辑Sphinx源的情况下阻止编写这些额外的标题?

here's an example doc pages I would like to make (notice TOC):

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

http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation

I understand it is due to the apidoc.py file in the sphinx source (line 88):

据我所知,这是由于sphinx源代码中的apidoc.py文件(第88行):

https://bitbucket.org/birkenfeld/sphinx/src/ef3092d458cc00c4b74dd342ea05ba1059a5da70/sphinx/apidoc.py?at=default

I could manually edit each individual .rst file to delete these titles or just remove those lines of code from the script but then I'd have to compile the Sphinx source code. Is there an automatic way of doing this without manually editing the Sphinx source?

我可以手动编辑每个单独的.rst文件来删除这些标题,或者只是从脚本中删除那些代码行,但是我必须编译Sphinx源代码。有没有手动编辑Sphinx源的自动方式?

4 个解决方案

#1

I was struggling with this myself when I found this question... The answers given didn't quite do what I wanted so I vowed to come back when I figured it out. :)

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

In order to remove 'package' and 'module' from the auto-generated headings and have docs that are truly automatic, you need to make changes in several places so bear with me.

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

First, you need to handle your sphinx-apidoc options. What I use is:

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

sphinx-apidoc -fMeET ../yourpackage -o api

Assuming you are running this from inside the docs directory, this will source yourpackage for documentation and put the resulting files at docs/api. The options I'm using here will overwrite existing files, put module docs before submodule docs, put documentation for each module on its own page, abstain from creating module/package headings if your docstrings already have them, and it won't create a table of contents file.

假设您从docs目录中运行它,这将获取文件的包,并将生成的文件放在docs / api中。我在这里使用的选项将覆盖现有文件,将模块文档放在子模块文档之前,将每个模块的文档放在自己的页面上,如果你的文档字符串已经拥有它们,则不会创建模块/包标题,并且它不会创建目录文件。

That's a lot of options to remember, so I just add this to the end of my Makefile:

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

buildapi:
    sphinx-apidoc -fMeET ../yourpackage -o api
    @echo "Auto-generation of API documentation finished. " \
          "The generated files are in 'api/'"

With this in place, you can just run make buildapi to build your docs.

有了这个,你可以运行make buildapi来构建你的文档。

Next, create an api.rst file at the root of your docs with the following contents:

接下来,使用以下内容在文档的根目录下创建api.rst文件:

API Documentation
=================

Information on specific functions, classes, and methods.

.. toctree::
   :glob:

   api/*

This will create a table of contents with everything in the api folder.

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

Unfortunately, sphinx-apidoc will still generate a yourpackage.rst file with an ugly 'yourpackage package' heading, so we need one final piece of configuration. In your conf.py file, find the exclude_patterns option and add this file to the list. It should look something like this:

不幸的是,sphinx-apidoc仍会生成一个带有丑陋的'yourpackage包'标题的yourpackage.rst文件,因此我们需要最后一个配置。在conf.py文件中,找到exclude_patterns选项并将此文件添加到列表中。它应该看起来像这样:

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

Now your documentation should look exactly like you designed it in the module docstrings, and you never have to worry about your Sphinx docs and your in-code documentation being out of sync!

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

#2

The answer by Jen Garcia helped a lot but it requires to put repeat package names in docstrings. I used a Perl one-liner to remove the "module" or "package" suffix in my Makefile:

Jen Garcia的答案帮了很多,但它需要在文档字符串中添加重复的包名。我使用Perl单行删除了Makefile中的“module”或“package”后缀:

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

It's probably late, but the options maxdepth or titlesonly should do the trick.

它可能已经晚了,但选项maxdepth或titlesonly应该可以解决问题。

More details : http://sphinx-doc.org/latest/markup/toctree.html

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

#4

I'm not sure I'm 100% answering your question, but I had a similar experience and I realized I was running sphinx-apidoc with the -f flag each time, which created the .rst files fresh each time.

我不确定我是100%回答你的问题,但我有类似的经历,我意识到我每次都使用-f标志运行sphinx-apidoc,每次创建.rst文件。

Now I'm allowing sphinx-apidoc to generate the .rst files once, but not overwriting them, so I can modify them to change titles/etc. and then run make html to propagate the changes. If I want to freshly generate .rst files I can just remove the files I want to regenerate or pass the -f flag in.

现在我允许sphinx-apidoc生成一次.rst文件,但不会覆盖它们,所以我可以修改它们来更改标题/等。然后运行make html来传播更改。如果我想重新生成.rst文件,我可以删除我想要重新生成的文件或传递-f标志。

So you do have to change the rst files but only once.

因此,您必须更改第一个文件,但只需更改一次。

#1