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?

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.

Answer 2

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

Answer 3

Just a few minutes ago I've found another solution: Do not place "import RPi.GPIO" at the beginning of the file. Place it inside the function / method (maybe not a good style). So sphinx will not see it and a documentation will be build.

But the solution with mocking is better, here is a link: 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']