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文件中手动记录所有内容(这不会发生,因为没有足够的文件)已知宇宙的生命周期中剩余的免费无偿志愿者秒数)?因为...
这不起作用。
精明的评论:
Sphinx 不会无法导入我愚蠢地认为对标准模块的交叉引用是内置的......因为
typing
或其他标准模块。所有警告都是关于缺少交叉引用目标的。为了获得对标准模块的工作交叉引用,请使用intersphinx
。
它绝对应该是。可悲的是,这样做需要配置另一个正交扩展。当然,Sphinx 并没有在其警告输出中暗示这可能是一个好主意——除非您明确地将秘密的 -n
选项传递给
sphinx-build
,否则 Sphinx 甚至不会发出警告。
</double_facepalm>