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

当我运行

sphinx-apidoc

然后

make-html

时，它生成的文档页面在目录（TOC）中的每个模块/包名称的末尾都有“子包”和“子模块”部分以及“模块”和“包”。在不编辑Sphinx源代码的情况下，如何防止编写这些额外的标题

下面是我想制作的文档页面示例（注意TOC）：

我理解这是由于sphinx源代码（第88行）中的apidoc.py文件造成的：

---

我可以手动编辑每个单独的.rst文件来删除这些标题，或者只是从脚本中删除那些代码行，但是我必须编译Sphinx源代码。有没有一种不用手动编辑Sphinx源代码就可以自动执行此操作的方法？

可能已经晚了，但是选项

maxdepth

或

titlesonly

应该可以做到这一点

更多详情：

---

我不确定我是否100%回答了你的问题，但我有过类似的经历，我意识到我每次都使用

-f

标志运行

sphinx apidoc

，这会创建每次都是新的

.rst

文件

现在我允许

sphinx-apidoc

一次生成

.rst

文件，但不覆盖它们，因此我可以修改它们以更改标题等，然后运行

make-html

来传播更改。如果我想新生成

.rst

文件，我可以删除我想重新生成的文件或传入

-f

标志

---

因此，您必须更改rst文件，但仅更改一次

当我发现这个问题时，我自己也在努力解决这个问题。。。给出的答案并不完全符合我的要求，所以我发誓在我找到答案后会回来

---

为了从自动生成的标题中删除“package”和“module”，并拥有真正自动的文档，您需要在多个地方进行更改，请耐心等待

首先，您需要处理

sphinxapidoc

选项。我使用的是：

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

假设您是从

docs

目录中运行此操作，这将为文档提供

yourpackage

，并将生成的文件放在

docs/api

中。我在这里使用的选项将覆盖现有文件，将模块文档放在子模块文档之前，将每个模块的文档放在自己的页面上，如果您的文档字符串已经有模块/包标题，则避免创建它们，并且不会创建目录文件

要记住的选项很多，所以我只需将其添加到我的

Makefile

的末尾：

buildapi:
sphinx apidoc-fMeET../yourpackage-o api
@echo“自动生成API文档已完成。”\
“生成的文件位于“api/”中”

有了它，您就可以运行

makebuildapi

来构建文档

接下来，在文档根目录下创建一个包含以下内容的

api.rst

文件：

API文档
=================
有关特定函数、类和方法的信息。
.. 目录树：：
：glob:
原料药/*

这将创建一个目录，其中包含

api

文件夹中的所有内容

不幸的是，

sphinx-apidoc

仍将生成一个带有难看的“yourpackage-package”标题的

yourpackage.rst

文件，因此我们需要最后一个配置。在

conf.py

文件中，找到

exclude_patterns

选项并将此文件添加到列表中。它应该是这样的：

exclude_patterns=[''构建''api/yourpackage.rst']

现在，您的文档应该与您在模块docstrings中设计的文档完全相同，而且您永远不必担心Sphinx文档和代码内文档不同步

这个方法帮助很大，但它需要在docstring中放置重复的包名。我使用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

---

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

从pathlib导入路径
src_dir=Path（“源/api”）
对于src_dir.iterdir（）中的文件：
打印（“已处理的RST文件：”，文件）
打开（文件“r”）作为f：
行=f.read（）
垃圾邮件\u strs=[“子模块\n------”，“子包\n------”]
对于垃圾桶中的垃圾：
行=行。替换（垃圾，“”）
行=行。替换（“模块”=，“\n”）
打开（文件“w”）作为f：
f、 写（行）

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

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

---

现在运行

makehtml

以我想要的方式构建文档。

我遇到了与@ecoe相同的问题，我在我的

index.rst

目录树中尝试了

：maxdepth:2

和

：titlesonly:

，我仍然得到了这些标题。问题是

sphinx-apidoc

将这些标题放入生成的

.rst

文件中。你知道如何解决这些问题吗？正如@ocoe所说，人们总是可以从

.rst

中编辑这些文件，但这样一来，你就失去了让

sphinx apidoc

为你生成这些文件的全部意义，因为你每次都必须对它们进行编辑/后处理：（类似的问题：。对我来说，这并没有达到OP想要的效果。您只是更改了TOC，但内部文档是相同的，因为生成的.rst默认具有这些标题。我正在指示

sphinx apidoc

在默认情况下不使用

-E

选项创建标题。启用此选项后，如果您的模块一个合适的docstring头，Sphinx将使用它而不是生成一个。事实上，我没有注意到区别，因为包中没有docstring，