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

Posted 2023-02-19

【中文标题】Sphinx：如何排除自动模块中的导入？

【英文标题】：Sphinx: how to exclude imports in automodule?

【发布时间】：2013-03-31 03:44:35

【问题描述】：

我有一个使用 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

有什么办法吗？

【参考方案1】：

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

您可以通过执行一些mocking 来解决此问题。这是一篇描述与您的问题非常相似的问题的解决方案的文章：http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-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 配置值即可。

【讨论】：

从 Sphinx 1.3 开始，您可以使用配置值 autodoc_mock_imports 排除导入。

【参考方案2】：

有一个模拟的解决方案：

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

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

autodoc_mock_imports = ["RPi", 'serial']

【讨论】：

使用 autodoc_mock_imports 行更可取！对于任何来这里的人来说，Python 或一般开发经验有限，将 import 语句放在函数或方法中严重违反了基本的干净代码原则，可能会产生副作用！除非您真的知道自己在做什么，否则不要这样做，如果您知道自己在做什么，那么几乎可以肯定无论如何都不需要这样做！

你说得对，我已经删除了函数内部导入的解决方案。感谢您的评论！

【参考方案3】：

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

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

注意你需要python-mox：sudo apt-get install python-mox

参考：How to generate sphinx documentation for python code running in an embedded system