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 源的自动方法？

4

5 回答 5

23

当我发现这个问题时，我自己也在为此苦苦挣扎......给出的答案并没有完全符合我的要求，所以我发誓要在我弄清楚时回来。:)

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

首先，您需要处理您的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.rst带有难看的“yourpackage package”标题的文件，所以我们需要最后一个配置。在您的conf.py文件中，找到该exclude_patterns选项并将此文件添加到列表中。它应该看起来像这样：

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

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

于 2016-02-07T06:27:33.067 回答
4

可能为时已晚，但选项maxdepth或titlesonly应该可以解决问题。

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

于 2014-06-11T10:36:21.243 回答
3

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
于 2016-12-21T13:26:32.660 回答
0

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

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

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

于 2015-11-10T22:35:23.973 回答
0

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

于 2021-05-15T18:07:28.300 回答