Sphinx“autodoc”扩展甚至无法找到保证存在的标准模块

Question

我正在尝试记录

beartype

的公共 API，这是一个用于 Python 的 berry 有趣的运行时类型检查器。我彻底失败了。 Sphinx 的

autodoc

扩展无法找到 标准纯 Python CPython 模块，这些模块既保证存在又可轻松导入。 这不应该... 但确实如此。

因此，这个问题与该主题的其他所有问题都不同。正如我手动注入到该项目的

print()

Sphinx 配置中的 doc/source/conf.py

 语句所示

，Sphinx 的运行时 sys.path

 已正确建立并且应该可以正常工作。

不顾理智，

autodoc

甚至无法解决对标准模块的交叉引用：

$ sphinx-build -M html doc/source/ doc/build/ -W -j auto --keep-going -n -a
Running Sphinx v4.4.0
sys.path (from "doc/source/conf.py"): ['/usr/lib/python-exec/python3.8', '/usr/lib/python38.zip', '/usr/lib/python3.8', '/usr/lib/python3.8/lib-dynload', '/usr/lib/python3.8/site-packages', '/home/leycec/py/beartype']
loading pickled environment... done
[autosummary] generating autosummary for: changes.rst, index.rst, reference.rst, tutorial.rst
building [mo]: all of 0 po files
building [html]: all source files
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
/usr/lib/python3.8/site-packages/beartype/__init__.py:docstring of beartype:3: WARNING: py:mod reference target not found: beartype.meta
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: beartype._data.datatyping.BeartypeableT
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: beartype._data.datatyping.BeartypeableT
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: beartype._data.datatyping.BeartypeableT
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: BeartypeableT
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: BeartypeConf
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: optional
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:class reference target not found: BeartypeReturn
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeConfException
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:68: WARNING: py:class reference target not found: BeartypeConf
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeDecorHintException
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:69: WARNING: py:mod reference target not found: typing
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeDecorHintPep563Exception
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeDecorParamNameException
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeDecorWrappeeException
/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:: WARNING: py:exc reference target not found: BeartypeDecorWrapperException

waiting for workers...
generating indices... genindex py-modindex done
highlighting module code... [100%] beartype._decor.cache.cachedecor                                                            
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 16 warnings.

忽略上面的所有内容，除了

autodoc

 未能找到标准 

typing

 模块的警告：

/usr/lib/python3.8/site-packages/beartype/_decor/cache/cachedecor.py:docstring of beartype._decor.cache.cachedecor.beartype:69: WARNING: py:mod reference target not found: typing

"/usr/lib/python3.8"

 位于 

sys.path

。 

"/usr/lib/python3.8/typing.py"

 存在，而且确实必须存在。然而

autodoc

什么也没找到。在这里插入双捂脸模因。

我越来越怀疑

autodoc

是地狱的化身。我们大多数人已经知道这一点。其余的人能够通过我微弱的天赋之外的奥术魔法，强行让斯芬克斯屈服于他们的背信弃义的意志。我属于前一类。

切线：是否有任何可行的替代方案autodoc

，我可以立即陷入一种工作状态，而不是在原始Sphinx特定的reStructuredText文件中手动记录所有内容（这不会发生，因为没有足够的文件）已知宇宙的生命周期中剩余的免费无偿志愿者秒数）？

因为...

这不起作用。

Answer 1

由狮身人面像向导 @mzjn 提供，作为上面

精明的评论：

Sphinx 不会无法导入

typing

 或其他标准模块。所有警告都是关于缺少交叉引用目标的。为了获得对标准模块的工作交叉引用，请使用 

intersphinx。

我愚蠢地认为对标准模块的交叉引用是内置的......因为

它绝对应该是。可悲的是，这样做需要配置另一个正交扩展。当然，Sphinx 并没有在其警告输出中暗示这可能是一个好主意——除非您明确地将秘密的 -n

 选项传递给 

sphinx-build

，否则 Sphinx 甚至不会发出警告。 

</double_facepalm>