python-sphinx - Sphinx：如何排除自动模块中的导入？

Question

我有一个使用 RPi.GPIO 模块的 Python 编写的 Raspberry Pi 项目。代码上的所有工作都是在不会安装 RPi.GPIO 的 Windows 机器上完成的，每次我尝试运行 autodoc 时它都会崩溃，说它无法导入 RPi.GPIO。

D:\cube\docs\ledcube.rst:4: WARNING: autodoc: failed to import module u'ledcube'
; the following exception was raised:
Traceback (most recent call last):
  File "C:\Python27\lib\site-packages\sphinx-1.2b1-py2.7.egg\sphinx\ext\autodoc.
py", line 326, in import_object
    __import__(self.modname)
  File "D:\cube\ledcube.py", line 2, in <module>
    import RPi.GPIO as GPIO
ImportError: No module named RPi.GPIO

有什么办法吗？

Answer 1

没有办法告诉 Sphinx 排除某些导入。使用 autodoc 时，所有文档化的模块都必须是完全可导入的。

你也许可以通过做一些mocking来解决这个问题。这是一篇描述与您的问题非常相似的问题的解决方案的文章：http: //blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using -numpy 和 scipy/。这是一个小代码示例（旨在添加到 conf.py）：

import mock

MOCK_MODULES = ['numpy', 'matplotlib', 'matplotlib.pyplot']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

您可能需要安装 python-mock 才能使上述工作：sudo apt-get install python-mock

更新

从 Sphinx 1.3 开始，设置模拟变得更加容易。只需将要模拟的模块添加到autodoc_mock_imports配置值即可。

Answer 2

有一个模拟的解决方案：

http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports

只需将以下行添加到 conf.py （RPi 和串行是示例）：

autodoc_mock_imports = ["RPi", 'serial']

Answer 3

除了模拟模块之外，我还必须模拟仅在我的嵌入式系统中有意义的调用（例如，模拟从通过 SPI 从 FPGA 读取寄存器read_reg()的模块中对函数的调用）。examplemod

import mox as mox 
import examplemod
m = mox.Mox()
m.StubOutWithMock(examplemod, 'read_reg')

请注意，您需要 python-mox：sudo apt-get install python-mox

参考：如何为在嵌入式系统中运行的 python 代码生成 sphinx 文档