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

Question

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

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源代码？

- ecoe

1

类似问题：https://dev59.com/v10b5IYBdhLWcg3wR_fe。 - mzjn

6个回答

4

也许有点晚了，但选项 maxdepth 或 titlesonly 可以解决问题。

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

- user2623495

3

我和 @ecoe 一样有同样的问题，我已经在我的 index.rst 的 toctree 中尝试过 :maxdepth: 2 和 :titlesonly:，但仍然会出现这些标题。问题是 sphinx-apidoc 会将这些标题放入生成的 .rst 文件中。你有什么解决方法吗？像 @ocoe 所说，可以通过编辑.rst文件来移除这些标题，但这样做失去了让sphinx-apidoc为你自动生成这些文件的意义，因为每次都要进行编辑/后处理。 - estan

3

Jen Garcia的回答帮了很大的忙，但需要在文档字符串中重复包名。我使用Perl one-liner在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

- Jakob

你有类似的修复方法可以用于 make.bat 吗？ - mr.bjerre

@mr.bjerre 抱歉，我不在Windows下开发。Perl代码可以被一个小的Python脚本替换，但是我对Unix下的当前解决方案感到满意。 - Jakob

当我使用perl脚本时，出现了语法错误： `syntax error at -e line 1, near ". ==" Execution of -e aborted due to compilation errors. - Eddy

@Eddy，你使用的是哪个操作系统和Perl版本？看起来你漏掉了一个$符号（？） - Jakob

2

我不想在我的文档字符串中使用标题，因为我遵循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可以按照我想要的方式构建文档。

- TrigonaMinima

0

我不确定我是否完全回答了你的问题，但我有过类似的经历，我意识到每次都在使用-f标志运行sphinx-apidoc，这会每次创建新的.rst文件。

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

所以你确实需要改变rst文件，但只需要改变一次。

- A.Wan

0

在新版本的Apidoc中，您可以使用自定义Jinja模板来控制生成的输出。

默认模板在这里：https://github.com/sphinx-doc/sphinx/tree/5.x/sphinx/templates/apidoc

您可以使用相同的名称（例如source/_templates/toc.rst_t）创建每个模板的本地副本，并使用--templatedir选项调用sphinx-apidoc（例如sphinx-apidoc --templatedir source/_templates）。

一旦您使用自己的模板文件，就可以按照自己的喜好进行自定义。例如，您可以删除在此阶段添加的丑陋的“package”和“module”后缀。

- shadowtalker

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Jen Garcia · Accepted Answer

当我发现这个问题时，我自己也很苦恼...提供的答案并没有完全做到我想要的，所以我决定在我找到答案后再回来。:)

为了从自动生成的标题中删除“包”和“模块”，并获得真正自动化的文档，你需要在几个地方进行更改，请耐心阅读。

首先，你需要处理你的sphinx-apidoc选项。我的使用方法如下:

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

假设您正在docs目录中运行此命令，它将为文档引用yourpackage并将生成的文件放置在docs/api中。我所使用的选项将覆盖现有文件，在子模块文档之前添加模块文档，在单独页面上为每个模块提供文档，并且如果您的docstrings已经包含了它们，就不要创建模块/包标题，并且它也不会创建目录文件。

这是需要记住的许多选项，因此我只需将其添加到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 package”标题的 yourpackage.rst 文件，因此我们需要进行最后一步配置。在你的 conf.py 文件中找到 exclude_patterns 选项并将该文件添加到列表中。它应该看起来像这样：

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

现在你的文档应该与你在模块docstrings中设计的完全相同，您无需担心Sphinx文档和代码内部文档不同步的问题！