问题标签 [sphinx-apidoc]

所以目前我正在使用 apidoc 为我的文档生成 .rst 文件，然后在它们上使用 autodoc。问题是我的包将代码分成许多不同的文件，这导致了这种嵌套混乱（我的目录树的最大深度为 4）：

我们将所有相关类导入__init__.py包的基础。

举个例子：我们有一个 public class package.submodule1.SubModule1Class。作为包用户，我可以通过from package import SubModule1Class) 导入类。

我想从我们在这个__init__.py平面层次结构中导入的所有类中自动生成文档，如下所示：

我可以使用 apidoc 上的哪些配置设置来实现此目标状态？我尝试了各种各样的东西，但没有任何东西与此类似。

我有以下目录结构：

我不想在我的文档中使用 mock_run，所以在conf.py我有：
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store','mock', '**/mock_*', '*/mock_*','mock_run.py']

我运行sphinx-apidoc -o docs/ project_name -f -M（我还清理了make docsmakefile 中的所有内容）。

该文件仍然出现在文档中。我究竟做错了什么？

正如你所看到的，我已经尝试了许多不同的版本来捕获正则表达式，所以我相信这不是问题。

我在包含但似乎没有任何效果的rst文件上运行 Sphinx。automodule

以下是详细信息：我有一个 Python 项目，其中agent.py包含一个包含类的文件Agent。我还有一个子目录，里面apidoc有一个文件agent.rst（由 生成sphinx-apidoc）：

sphinx-build -b html apidoc apidoc/_build我以项目目录作为当前工作目录运行 sphinx 。

为了确保找到 Python 文件，我在 中包含以下内容apidoc/conf.py：

它运行没有错误，但是当我打开生成的 HTML 文件时，它只显示“代理模块”并且一切都是空白的。为什么不显示班级Agent及其成员？

更新：原来的问题很可能是我没有包含sphinx.ext.autodoc在conf.py. 不过，既然我这样做了，我会收到如下警告：

好吧，我一直在努力解决 Sphinx 无法从我在此示例代码中编写的文档字符串生成任何文档的问题。它是 Python 中堆栈的简单实现。

您可能不需要阅读所有这些内容：

src/stack.py

conf.py

stack.rst

我尝试使用 Sphinx 用命令记录这段代码$ sphinx-autodoc -o docs/source src/。这将输出文件modules.rst, stack.rst。然后我sphinx-build从我的makefile输出到HTML。

我的输出是空白页面上的标题：堆栈模块

像这个截图

这里应该发生一些自动的事情吗？如何通过使用 Sphinx autodoc 获得任何有意义的输出？

2020-1-31 更新：我还是遇到了一些麻烦，所以我按照 Masklinn 的建议创建了一个Github 存储库，除了上面提到的更改路径的其他建议，但是文档输出仍然不能令人满意。

2020-2-11 更新：我正在处理的文件结构

回复：sphinx-apidoc用于通过扩展从文档字符串自动生成 API 引用autodoc...

我将全局/site-packages/sphinx/templates/apidoc/package.rst_t模板复制到本地文件夹，并进行了无意义的编辑。当我构建 API 文档时，无意义的编辑不可见，即。本地模板似乎没有覆盖全局模板。

这是我的本地docs/source目录：

conf.py包含此指令：

我使用以下命令构建了 API 文档：

谁能看到出了什么问题？

问题

我正在尝试为包含许多子目录的 Python 项目构建文档。我正在尝试使用sphinx-apidoc使过程无缝。然而，尽管我尽了最大努力，我还是无法处理子目录中的代码。我在这里遵循了 YouTube 上的一个很棒的简短教程，并且效果很好。为了模拟我一直遇到的问题，我将其中一个文件放在一个can_it_handle_folders目录中，如下所示。

我转到docs目录并运行sphinx-apidoc -o . ..以根据根spamfilter目录生成 .rst 文件。我已将以下行添加到conf.py：

我生成的modules.rst看起来像：

目录中任何内容的 htmlcan_it_handle_folders都不会生成。如果我尝试添加can_it_handle_folders/test_spamfilter到目录树，我会得到一个toctree contains reference to nonexisting document 'can_it_handle_folders/test_spamfilter'错误。

问题

我希望test_spamfilter模块显示在生成的 html 中。我该怎么做呢？设置它的最佳方法是什么？

更新：它是初始化文件

我已经隔离了这个问题，它似乎__init__.py在根目录中（上面标有**）。我不知道该如何处理。如果我删除它，狮身人面像会完全按照我想要的方式工作。如果我保留它，问题就变成了这里。看来这一定是sys.path. 对于每个文件，这是我得到的错误：

我在conf.py文件中尝试了以下内容：

• sys.path.insert(0, os.path.abspath(os.path.join('..')))
• sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
• sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..')))

所有这些都导致了上述相同的错误消息。sphinx-apidoc -o ./source ../..除了sphinx-apidoc -o ./source ..上面的每个路径之外，我还尝试过运行。可能是什么问题？我知道这一定是一些小的配置。

语境

我是 Sphinx 的绝对初学者。我试图阅读文档，但它没有解决这个问题。我尝试了许多我认为显然不正确的事情。如果没有简单的答案，我会在这里添加我的尝试。我知道还有其他关于此的堆栈溢出问题，但它们不是最近的并且没有帮助。

• 使用 PowerShell 执行命令的 Windows 10 计算机

包含的文件：

• 索引.rst

• 配置文件

• 第一个不起作用，spamfilter-py.rst：

这是文档的样子：

我正在尝试为我的库生成文档。由于库目录结构很大，我希望 Sphinx 将.rst文件生成为反映包和模块结构的嵌套目录。

库结构：

到目前为止，我一直在使用在文件夹sphinx-apidoc -e -o ...中生成文档。docs/source/但这并没有按预期工作。

预期成绩：

作为嵌套目录生成的文档。这些文件已被删除以仅保留主干。

实际结果：

保留整个模块名称。

有没有办法将文档生成为目录树？

我正在使用带有autodoc扩展名的 Sphinx 为 Python 包自动生成文档。我面临的问题是autodoc跳过任何带有下划线的模块。

一些模块被强调以阻止用户导入它们。但是，这些带下划线的文件中的类没有下划线。

当我将带下划线的模块手动添加到package_name.rst并运行make html时，它会显示。所以我的问题是如何从autodoc.

我试图避免package_name.rst通过脚本解析来添加它们。我希望有一个 autodoc 标志或一个 hack！

我正在尝试使用 sphinx 为我的项目创建文档，它是一组功能划分为项目内部的模块。

我只需要在文档中公开一小部分功能，所以我过去常常autodoc-skip-member通过标记文档字符串来过滤掉不需要的功能，它似乎可以通过不列出不需要的功能来工作，但我最终得到了一堆空模块和子模块。

有没有办法告诉 sphinx 不列出空模块？我假设我可以使用该exclude功能，但添加新代码不会是一个自动化过程，我将不得不一直维护排除列表。

我正在使用这个流程来生成 HTML 文档：

这是过滤掉文件中函数的代码conf.py，即使它返回True一个模块，它也会在最终的 HTML 文档中列出。

我有一个 git 存储库，其中包含多个遵循命名空间的包（即PEP 420。

我正在尝试使用 Sphinx 创建 ReadTheDocs 文档。

git 存储库看起来像这个 repo：https ://github.com/pypa/sample-namespace-packages

为了在我的本地机器上进行测试，我使用了 Sphinx 的 docker image sphinxdoc/sphinx。

我尝试使用不同的方法为我的所有包生成文档，但每种方法最终都会遇到不同的问题。

狮身人面像-apidoc

docker run -it -v 密码:/repo --rm rtd bash -c 'make clean && rm -rf /repo/docs/_source/* && sphinx-apidoc -F -o /repo/docs/_source /repo && make html'

这样做的问题是它会生成错误的包，因为sphinx-apidoc它使用子文件夹来生成包，这是错误的。这最终会pkg_resourcespkg_a.example_pkg.a是不存在的，实际上应该是example_pkg.a

autoapi.extension

我也试过这个，但不幸的是，这最终没有在 HTML 中显示任何关于我的包的信息，同时还抛出以下警告：

所以，我的问题是是否可以使用 sphinx-apidoc 在同一个 git 存储库中为多个包创建文档？