使用 Sphinx 创建文档时如何修复 DLL 错误？

Question

我正在尝试为我的包创建 HTML 文档，但我一遍又一遍地收到相同的错误。

我在 Windows 机器上，使用 Python 3.7 和 Sphinx 3.2.1。

我的包裹结构如下：

[package]
 |
 |__ [package]
 |   |
 |   |__ module1.py
 |   |__ module2.py
 |   |__ __init__.py
 |
 |__ setup.py

我在第二个 [package] 文件夹中创建了一个 docs 文件夹，并且运行 sphinx-quickstart 产生了这个结构：

[package]
 |
 |__ [package]
 |   |
 |   |__ module1.py
 |   |__ module2.py
 |   |__ __init__.py
 |   |
 |   |__ [docs]
 |       |
 |       |__ [_build]
 |       | ...
 |       |__ conf.py
 |__ setup.py

我取消注释并更改 conf.py:

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

之后我做了 sphinx-apidoc -o . ..，当我运行 make html 时，我得到以下输出：

Running Sphinx v3.2.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
C:\Users\username\.conda\envs\cera\lib\importlib\_bootstrap.py:219: RuntimeWarning: numpy.ufunc size changed, may indicate binary incompatibility. Expected 192 from C header, got 216 from PyObject
  return f(*args, **kwds)

WARNING: autodoc: failed to import module 'module1' from module 'package'; the following exception was raised:
DLL load failed: The specified module could not be found.
WARNING: autodoc: failed to import module 'module2' from module 'package'; the following exception was raised:
DLL load failed: The specified module could not be found.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] modules
generating indices...  genindex py-modindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in _build\html.

HTML 文件已创建，但除了模块列表之外绝对没有任何文档。为什么我会收到 DLL 错误？

如果您需要任何其他信息，请告诉我！

Answer 1

可能是 PYTHONPATH / sys.path 设置不正确的问题。这可能是因为 os.path.abspath('..') 语句相对于当前工作目录（脚本执行的目录）。

要获取模块的可移植路径，或相对于模块的路径，请始终使用 __file__:

# package/docs/conf.py
# Use pathlib for a better path API.
# Available since Python 3.4
from pathlib import Path
import sys

THIS_DIR = Path(__file__).absolute().parent
PROJ_ROOT = THIS_DIR.parent
sys.path.insert(0, PROJ_ROOT)

Answer 2

通过将我的 conda 环境中的一些软件包升级到最新版本，问题得到解决。我通过从上面的错误中导入模块 module1 和 module2 来发现错误在 conf.py 文件中分析出现的错误消息。
似乎 sphinx 版本与旧的 numpy 和 sklearn 版本不兼容，因为那些是我必须升级的包。

使用 Sphinx 创建文档时如何修复 DLL 错误？

How do I fix an DLL Error when creating documentation with Sphinx?

python

python-sphinx