Sphinx: how to exclude imports in automodule?

Question

I have a Raspberry Pi project written in Python that uses RPi.GPIO module. All the work on the code is done on a Windows box where RPi.GPIO will not install and every time I try to run autodoc it crashes saying it cannot import 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

Any way around this?

Allogamy

Answer 1

There is no way to tell Sphinx to exclude some imports. When using autodoc, all documented modules must be cleanly importable.

You might be able to work around the problem by doing some mocking. Here is an article describing the solution to a problem that seems quite similar to yours: http://blog.rtwilson.com/how-to-make-your-sphinx-documentation-compile-with-readthedocs-when-youre-using-numpy-and-scipy/. Here is a small code sample (intended to be added to conf.py):

import mock

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

You might might need to install python-mock for the above to work: sudo apt-get install python-mock

Update

Since Sphinx 1.3, it is easier to set up the mocking. Just add the modules to be mocked to the autodoc_mock_imports configuration value.

Mestas

As of Sphinx 1.3, you can use config value autodoc_mock_imports to exclude imports. – Naamana

Answer 2

There is a solution with mocking:

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

Just add the following line to conf.py (RPi and serial are examples):

autodoc_mock_imports = ["RPi", 'serial']

Choriamb

Using autodoc_mock_imports line is much, much more preferable! For anyone coming here with limited experience of Python or development in general, putting import statements inside functions or methods is severely going against basic clean code principles, can create side-effects! Don't do it unless you really know what you're doing, and if you know what you're doing, you almost certainly won't need to do it anyway! – Lodmilla

You're right, I've removed the solutions with the imports inside the function. Thanks for Your comment! – Choriamb

Answer 3

Besides mocking modules, I also had to mock calls that only made sense in my embedded system (for example mocking a call to a function read_reg() from the module examplemod that reads a register from an FPGA via SPI).

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

Note that you need python-mox: sudo apt-get install python-mox

Reference: How to generate sphinx documentation for python code running in an embedded system

Permission