Blog of Rob Galanakis (@robgalanakis)

Building Sphinx documentation for unfriendly code

Some Twitter friends were discussing how to get Sphinx to work with mayapy to build documentation for code that runs in Autodesk Maya. I’ve had to do this sort of thing extensively, for both Maya and editor/game code, and have even run an in-house Read The Docs server to host everything. I’ve learned a number of important lessons, but most relevant here is:

Always generate your documentation using vanilla Python. Never a custom interpreter.

There’s no philosophical reason for this*. I’ve just found it, by far, the path of least resistance. All you have to do is some mocking in conf.py:

import mock
for mod in ['maya.cmds', 'pymel.core']: # and whatever else you need
    sys.modules[mod] = mock.MagicMock()

(I do not have the code in front of me so this may be slightly wrong. Perhaps an ex-colleague from CCP can check what used to be in our conf.py.)

Now when Sphinx tries to import your module that has import pymel.core as pmc, it will work fine. That is, assuming your modules do not have some nasty side effects or logic on import requiring correctly functioning modules, which you should definitely avoid and is always unnecessary.

When your documentation generation breaks, it’s now a simple matter of adding a string in one place, rather than a several hour debugging session.

Don’t say I didn’t warn you!


* If anything, I’m philosophically more inclined to use mayapy. So that should tell you what sort of bogeymen await!

One thought on “Building Sphinx documentation for unfriendly code

  1. Paul says:

    Thanks for this it really helped me out, and definitely helped me avoid the custom interpreter route!
    For anyone else who stumbles upon this, I just wanted to say that newer versions of Sphinx allows you to add mock objects more easily with just one line of code in your conf.py

    autodoc_mock_imports = [‘pymel.core’, ‘maya.cmds’]

Leave a Reply