带有mkdocstrings的MkDocs无法服务，出现“无法收集”错误

Question

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

当我在项目中（在包含mkdocs.yml文件的目录中）运行mkdocs serve命令时，该命令失败，并出现ERROR - Could not collect '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代码在cpinotify/cpinotify.py模块的顶层使用Python argparse库

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

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

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

---

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

对我的代码进行此更改后，pktdocs命令开始按预期工作，mkdocs serve命令工作正常，没有产生我预期的文档错误

---

注意：我的问题（上面）中的实际错误来自于pytkdocs未能提供任何输出的事实，因此当pytkdocs在没有输出的情况下失败时，mkdocstring将提供类似的失败报告