如何为MicroPython构建Sphinx文档

Question

如何配置Sphinx以记录用于MicroPython解释器的模块？

我面临的根本问题是，Sphinx获取其文档信息来自所导入的模块。因此，用于记录模块的Python解释器必须可在该解释器中导入。

第一个问题

我正在使用pyboard，自然地

import pyb

无法找到模块pyb... 所以我添加了到conf.py

from unittest.mock import MagicMock
sys.modules['pyb'] = MagicMock()  # and many more

第二个问题

我的MicroPython库之一叫做cmd

Exception occurred:
  File "/usr/lib/python3.5/pdb.py", line 135, in <module>
    class Pdb(bdb.Bdb, cmd.Cmd):
AttributeError: module 'cmd' has no attribute 'Cmd'

所以这很有道理...我将模块的名称更改为ucmd，并且似乎工作正常...但它非常不稳定。

问题

是否有一种正确的方法来做到这一点？ 对于未设计用于运行sphinx-build命令的平台的模块进行sphinx文档记录？

更实际地说：如果我想要记录一个名为collections、subprocess或io（所有这些都被sphinx库使用）的MicroPython模块，是否可以使用sphinx来完成？

还是我只能满足于分别将它们命名为ucollections、usubprocess和uio？

- FraggaMuffin

---

除了Sphinx之外，如果您可以“直接导入”大多数（而不是全部）MicroPython标准库模块，您会得到帮助吗？ - Jos Verlinde

@JosVerlinde 问题出在导入冲突上，以 cmd 为例，我有两个选择：1）导入 micropython 的 cmd 模块，但 sphinx 就无法加载；2）记录系统的 cmd 模块，但这不是重点。 因此，“只需导入”会引发其中之一的问题……而使用抽象语法树（ast）方法进行自动文档化则不会有这个问题，但我不认为 sphinx 支持该方法。 我已经成功地在一个系统上工作了两年，我应该在这里回复我的经验和我发现的最佳实践。 - FraggaMuffin

Answer 1

以下不是sphinx解决方案，但在大多数现代编辑器中提供了部分自动完成。

要为（自定义）MicroPython模块生成存根，您可以使用MicroPython-Stubber

有关自定义模块的配置，请参见第4.4节

或者在同一资料库中，我在各种测试中导入MicroPython-CPython stubs（源自micropython-lib和pycopy-lib），通过将其插入到CPython的sys.path中实现。 对于我的测试目的，这非常有效，使我能够在CPython上运行和调试（与硬件无关的）MicroPython代码而无需或只需进行很小的更改。 也许它也适合您的文档需求。

- Jos Verlinde