Question

当我运行sphinx-apidoc然后make html时，它会生成doc子页面，其中包含“Subpackages”和“Submodules”部分以及每个模块/包名称末尾的“module”和“package”目录（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源的方法吗？

Answer 1

当我发现这个问题时，我正在努力解决这个问题......给出的答案并没有完全符合我的要求，所以当我想出来时，我发誓要回来。：）

为了删除＆＃39; package＆＃39;和＆＃39;模块＆＃39;从自动生成的标题中获得真正自动的文档，你需要在几个地方进行更改，所以请耐心等待。

首先，您需要处理sphinx-apidoc个选项。我用的是：

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

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

要记住很多选项，所以我只是将其添加到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文件，其中包含一个丑陋的你的套餐包＆＃39;标题，所以我们需要最后一个配置。在conf.py文件中，找到exclude_patterns选项并将此文件添加到列表中。看起来应该是这样的：

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

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

Answer 2

answer by Jen Garcia帮助了很多，但它需要在文档字符串中放置重复的包名称。我使用了Perl单线程来移除＆＃34;模块＆＃34;或＆＃34;包＆＃34;我的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 html

Answer 3

可能会迟到，但选项maxdepth或titlesonly应该可以解决问题。

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

Answer 4

我不确定我是100％回答你的问题，但我有类似的经历，我发现我每次都在运行sphinx-apidoc -f标志，每次创建.rst个文件。

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

所以你必须更改第一个文件，但只需更改一次。

Answer 5

我不想在我的文档字符串中使用标题，因为我遵循 numpy 样式指南。所以我首先生成 rst 文件，然后运行以下 python 脚本作为后处理步骤。

from pathlib import Path


src_dir = Path("source/api")
for file in src_dir.iterdir():
    print("Processed RST file:", file)
    with open(file, "r") as f:
        lines = f.read()

    junk_strs = ["Submodules\n----------", "Subpackages\n-----------"]

    for junk in junk_strs:
        lines = lines.replace(junk, "")

    lines = lines.replace(" module\n=", "\n")

    with open(file, "w") as f:
        f.write(lines)

此脚本与 makefile 保存在同一目录中。我还将以下几行添加到 makefile 中。

html:
    # rm -r "$(BUILDDIR)"
    python rst_process.py
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

现在运行 make html 以我想要的方式构建文档。

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

5 个答案: