sphinx.ext.autodoc：外部包的 ModuleNotFoundError

Question

我想开始使用 Sphinx 记录我的基于 Flask 的应用程序。目前，我正在尝试弄清楚如何使用 autodoc 扩展。我的本地模块都找到了，但是外部库的导入在sphinx中不起作用。

我的所有需求都在一个

requirements.txt

文件中，所以我希望 sphinx 可以从那里提取包/模块。我正在环境中的本地计算机上测试 sphinx。因此我已经添加了：

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
sys.path.insert(0, os.path.abspath('~/envs'))

到

myproject/docs/source/config.py

。这适用于我的项目内部模块，但不适用于进一步的工作。

因此，运行

sphinx-build -M html docs/source/ docs/build/

会导致此错误：

WARNING: Failed to import myproject.errors.
Possible hints:
* ModuleNotFoundError: No module named 'flask'
* KeyError: 'myproject'
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] api
WARNING: autodoc: failed to import module 'errors' from module 'myproject'; the following exception was raised:
No module named 'flask' [autodoc.import_object]

作为一名 mwe，我创建了

myproject/docs/source/api.rst

:

API
===

.. autosummary::
   :toctree: generated

.. automodule:: myproject.errors
    :members:
    :imported-members:

为了仔细检查是否安装了所有依赖项，我运行了 `

(envs) user@machine:~/git/myproject$ pip freeze | grep -F "Flask"
Flask==2.3.3

为了排除任何可能是

flask

特定的问题，我尝试通过

autodoc_mock_imports=['flask']

来模拟它，但这将问题一一转移到所有其他外部模块。

Answer 1

非常感谢，mzjn！你的提示是正确的。我好奇地在 venv 中运行所有 python 命令，但

sphinx-build

除外。我通过添加

来证明这个假设

sys.path.append(os.path.abspath('../../'))
print('Sphinx runs with the following prefix:'+sys.prefix)

到我的

conf.py

，这是我从 wpercy 获得的，我将把这些行留在那里，以供以后调试。知道这一点后，我尝试按照 migonzalvar 的描述进行操作：

环境激活后：

$ source /home/migonzalvar/envs/myenvironment/bin/activate
$ pip install sphinx
$ which sphinx-build
/home/migonzalvar/envs/myenvironment/bin/sphinx-build

还是没用。只有在我停用 venv 并通过

pip uninstall sphinx

全局卸载 sphinx 后，sphinx-build 才开始使用 venv（如我所愿）。