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
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
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!