当我运行sphinx-apidoc 然后运行make html 时，它会生成包含“子包”和“子模块”部分以及“模块”和“包”在目录中每个模块/包名称末尾的文档页面（目录）。在不编辑 Sphinx 源代码的情况下，如何防止编写这些额外的标题？
这是我想做的一个示例文档页面（注意 TOC）：
http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation
我知道这是由于 sphinx 源代码中的 apidoc.py 文件（第 88 行）：
我可以手动编辑每个单独的 .rst 文件以删除这些标题，或者只是从脚本中删除这些代码行，但是我必须编译 Sphinx 源代码。有没有一种无需手动编辑 Sphinx 源代码的自动方法？
【问题讨论】：
标签： python html title python-sphinx api-doc
我不想在我的文档字符串中使用标题，因为我遵循 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 以我想要的方式构建文档。
【讨论】：
answer by Jen Garcia 有很大帮助，但它需要在文档字符串中放置重复的包名称。我使用 Perl 单线删除 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
【讨论】：
syntax error at -e line 1, near ". ==" Execution of -e aborted due to compilation errors.
$ (?)
当我发现这个问题时，我自己也在为此苦苦挣扎......给出的答案并没有完全达到我想要的效果，所以我发誓当我弄清楚时会回来。 :)
为了从自动生成的标题中删除“包”和“模块”并拥有真正自动的文档，您需要在几个地方进行更改，所以请耐心等待。 p>
首先，您需要处理您的sphinx-apidoc 选项。我用的是：
sphinx-apidoc -fMeET ../yourpackage -o api
假设您从docs 目录中运行它，这将获取yourpackage 的文档并将生成的文件放在docs/api。我在这里使用的选项将覆盖现有文件，将模块文档放在子模块文档之前，将每个模块的文档放在自己的页面上，如果您的文档字符串已经有它们，则不要创建模块/包标题，并且它不会创建目录文件。
要记住的选项很多，所以我将其添加到 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']
现在您的文档应该看起来与您在模块文档字符串中设计的完全一样，并且您不必担心您的 Sphinx 文档和您的代码内文档不同步！
【讨论】：
sphinx-apidoc 默认不使用-E 选项创建标题。启用此选项后，如果您的模块具有正确的文档字符串标头，Sphinx 将使用它而不是生成一个。
我不确定我是否 100% 回答了您的问题，但我有类似的经历，我意识到我每次都在运行 sphinx-apidoc 并带有 -f 标志，这会创建 .rst 文件每个都是新鲜的时间。
现在我允许sphinx-apidoc 生成一次.rst 文件，但不会覆盖它们，因此我可以修改它们以更改标题/等。然后运行make html 传播更改。如果我想重新生成.rst 文件，我可以删除我想重新生成的文件或传入-f 标志。
因此您必须更改第一个文件，但只需更改一次。
【讨论】：
可能为时已晚，但选项 maxdepth 或 titlesonly 应该可以解决问题。
【讨论】：
index.rst toctree 中尝试了:maxdepth: 2 和:titlesonly:，我仍然得到这些标题。问题是sphinx-apidoc 将这些标题放入生成的.rst 文件中。关于如何解决它们的任何想法？就像@ocoe 说的那样，人们总是可以在远离.rst 的地方编辑它们，但是这样你就失去了让sphinx-apidoc 为你生成这些文件的全部意义，因为你每次都必须编辑/后处理它们:(