python - 带有 mkdocstrings 的 MkDocs 无法提供 "Could not collect"错误

Question

我正在使用 Python MkDocs 工具构建 API 文档，使用 MkDocs mkdocstrings 扩展直接从源代码中提取。

当我在我的项目中(在包含 mkdocs.yml 文件的目录中)运行 mkdocs serve 命令时，命令失败并显示 ERROR -无法收集“cpinotify” 错误。

aUser@aMachine:~/notify2nats$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
ERROR    -  mkdocstrings.extension: Error while loading JSON:

            Traceback (most recent call last):
              File
            "/home/aUser/.local/pipx/venvs/mkdocs/lib/python3.9/site-packages/mkdocstrings/handlers/python.py",
            line 206, in collect
                result = json.loads(stdout)
              File
            "/home/aUser/.asdf/installs/python/3.9.6/lib/python3.9/json/__init__.py",
            line 346, in loads
                return _default_decoder.decode(s)
              File
            "/home/aUser/.asdf/installs/python/3.9.6/lib/python3.9/json/decoder.py",
            line 337, in decode
                obj, end = self.raw_decode(s, idx=_w(s, 0).end())
              File
            "/home/aUser/.asdf/installs/python/3.9.6/lib/python3.9/json/decoder.py",
            line 355, in raw_decode
                raise JSONDecodeError("Expecting value", s, err.value) from None
            json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
ERROR    -  Error reading page 'API.md':
ERROR    -  Could not collect 'cpinotify'

Aborted with a BuildError!

我的包含 MkDocs mkdocstrings 命令的 docs/API.md 文件是:

# Test

::: cpinotify

(其中 cpinotify 是要从中提取 mkdocstrings 文档的 Python 包的名称)。

---

版本:

• Python v3.9.6
• MkDocs v1.2.2
• mkdocstrings v0.15.2
• Ubuntu 20.04
• asdf v0.8.1-a1ef92a(虚拟化 Python 版本)
• pipx v0.16.3(虚拟化已安装的 Python 包/命令)

Answer 1

TL;DR 不要在任何模块中顶层使用 Python argparser。

---

经过一些工作(破解 mkdocstrings 代码以了解发生了什么)...我发现(在我的例子中)问题是我的 cpinotify 代码使用了 Python argparse 库 在 cpinotify/cpinotify.py 模块中的顶层。

mkdocstrings 代码使用 pytkdocs 命令从相关的 Python 代码中提取将用于构建文档的信息。 mkdocstrings 代码将 pytkdocs 作为外部进程运行，在 pytkdocs stdin 上以 JSON 形式提供所需的包信息，并期望在 pytkdocs 上以 JSON 形式提供结果标准输出。

pytkdocs 实际上导入 要记录的代码。由于我的 cpinotify 代码和 pytkdocs 都使用了 argparse 库，所以我们的两种使用是冲突的，导致出现错误消息并且没有 JSON要加载的 mkdocstrings 扩展。

虽然 Python argparse 文档显示了 argparser 是在顶层 创建的示例，但这种用法是在顶层 当 pytkdocs 导入时改变了 pytkdocs 预期的命令行选项，导致 pytkdocs 失败，没有输出。

---

解决方案:一旦我将 argparse 库的使用移到 inside cpinotify.cli 方法中，我的导入时不再调用 argparse，因此不再更改 pytkdocs 预期的命令行参数。

对我的代码进行此更改后，pktdocs 命令开始按预期工作，并且 mkdocs serve 命令没有错误地生成我预期的文档。

---

注意:我的问题(以上)中的实际错误来自于 pytkdocs 未能提供任何输出这一事实——因此 mkdocstrings 将提供类似的失败报告pytkdocs 失败且没有输出的时间。