Python Sphinx Autosummary：导入模块失败

Question

我正在尝试使用 sphinx-autosummary 为我的 python 代码创建自动摘要，如下所示：

\n\n

main\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modA\n|   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80__init__.py\n|   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modA.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modB\n|   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80__init__.py\n|   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modB.py\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80docs\n|   \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80build\n|   \xe2\x94\x94\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80source\n|       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80refs\n|       |   |\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80_autosummary\n|       |   |\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80index.rst\n|       |   |\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modA.rst\n|       |   |\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80modB.rst\n|       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80index.rst\n|       \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80\xe2\x94\x80conf.py\n

\n\n

正如 Sphinx 文档中提到的，我插入了工作目录的绝对路径，添加sphinx.ext.autodoc到扩展列表中，并autosummary_generate在conf.py.

\n\n

import os\nimport sys\nsys.path.insert(0, os.path.abspath(\'../..\'))\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named \'sphinx.ext.*\') or your custom\n# ones.\nextensions = [\n    \'sphinx.ext.autodoc\',\n    "sphinx.ext.autosummary", \n    \'sphinx.ext.coverage\', \n    \'sphinx.ext.napoleon\'\n]\n\nautosummary_generate = True\n

\n\n

接下来，在 中docs/index.rst，我添加了对该文件夹的引用refs/。

\n\n

.. toctree::\n   :maxdepth: 2\n\n   refs/index\n

\n\n

参考refs/index.rst了modA.rst和modB.rst。

\n\n

.. toctree::\n   :maxdepth: 2\n\n   modA\n   modB\n

\n\n

在modA.rst和 中modB.rst，我正在尝试创建自动摘要。

\n\n

modA.rst

\n\n

Attributes\n~~~~~~~~~~\n.. autosummary::\n   :toctree: _autosummary\n\n   modA.modA.create_job\n

\n\n

modB.rst

\n\n

Attributes\n~~~~~~~~~~\n.. autosummary::\n   :toctree: _autosummary\n\n   modB.modB.get_jobs\n

\n\n

虽然代码适用于modA.rst，但对于 则失败modB.rst。错误说，

\n\n

failed to import \'modB.modB.get_jobs\': no module named modB.modB.get_jobs\n

\n\n

我尝试将.. currentmodule::modBand放在.. currentmodule::main自动摘要之前，但没有成功。我什至尝试.. module::modB把.. module::main放在自动摘要之前，但即使这样也不起作用。我在互联网上搜索了很多，但无法理解为什么它不起作用。

\n\n

Edit-1：添加__init__.py到两个文件夹中。

\n

Answer 1

我在使用 Sphinx 时遇到了类似的问题。

经过一番实验，我怀疑类似的错误信息failed to import XXX: no module named XXX并不一定意味着找不到模块XXX。相反，在我的实验中，导入XXX时出现了一些错误。

就我而言，模块 XXX 本身正在导入一些尚未安装的包 YYY。由于 Sphinx 导入 XXX 是为了提取文档字符串，因此在这次导入尝试中发现了错误。删除该import YYY语句后，我可以成功构建文档。

Answer 2

似乎当 Sphinx 无法处理 python 导入时，它会显示通用模块导入警告（“.. 没有名为 ... 的模块”），正如您提到的。似乎当所有导入的 python 包都正确安装在环境中时，甚至会出现此警告，它只是意味着无法导入某些内容。

消除此警告的解决方法是使用 Sphinx 的 conf.py 文件中的 autodoc_mock_imports 来模拟外部 python 库。

例如：

import flask
import mongoengine
...
# your python code

带有模拟烧瓶的 conf.py 示例： autodoc_mock_imports = ["flask", "mongoengine"]

在这种情况下，Sphinx 将忽略这些导入，并且自动摘要可能能够正确构建摘要而不会出现任何错误。

更具体地说，您的情况：可能是您的 python 文件“modB.modB”包含 Sphinx 无法处理的导入语句，您要么需要正确安装 python 包，要么模拟在modB.modB 文件。

Answer 3

我有类似的问题。

我失败的导入错误的原因是指令modA.modA下指定的module.. autosummary::导入了未安装的库。

Attributes
~~~~~~~~~~
.. autosummary::
   :toctree: _autosummary

   modA.modA.create_job

但一般来说，failed to import错误的原因可能不同，因为从指令导入模块的函数.. autosummary::会捕获所有错误并自动摘要打印以输出相同的错误消息。

这是github上的相关问题https://github.com/sphinx-doc/sphinx/issues/7989

我建议导入你的模块modA.modA，modB.modB看看导入过程中是否有任何错误。