Tag Archives: language python

Getting Sphinx to work with Maya modules

Lets say you want to have your API look pretty. However, your API interfaces with another program such as Maya. The problem here is that maya comes with its own python interpreter. With a little bit of hacking you can get it working.

Required before you begin:

  • Maya 2011 or higher (I have not tested 2010 or below, but you will need at minimum mayapy working)
  • Sphinx 2.x.x or higher (again, ive only tested with the build 2.0.6)

Step-By-Step

% mkdir docs
% cd docs
% sphinx-quickstart
# follow instructions, mostly just letting it create the default stuff (smash the return key until its complete)
# edit the conf.py that was created, and insert your python source path after your import modules:
sys.path.insert(0, os.path.abspath(‘..’))
# you need to turn on extensions in the conf.py as well:
extensions=[‘sphinx.ext.autodoc]
# so now you should be able to auto-generate the rcs files
% sphinx-apidoc -F -o ‘install_dir’ ‘source_dir’
# python script used to build the docs

  • Take special note of the #!/usr/bin/env mayapy, the mayapy is the trick here. If you are windows it might be: #!/C:/maya2013/bin/mayapy (or where ever the mayapy is located. The file should be setting right next to maya.exe)

build_sphinx_mayadoc.py:

#!/usr/bin/env mayapy
 import maya.standalone
 maya.standalone.initialize(name='python')
 import sphinx
 import sys
 import os
 if __name__ == '__main__':
 argv = sys.argv[1:]
 cwd = os.getcwd()
 argv.insert(0, sphinx.__file__)
 sphinx.main(argv)

# I also updated my Makefile to point to this script ‘build_sphinx_mayadoc.py’ instead of ‘sphinx’. This allows me now to do “make install” and all my Maya related modules won’t complain that they do not exist.

References

Full instructions are a bit vague:
http://sphinx-doc.org/tutorial.html
http://sphinx-doc.org/ext/autodoc.html

Advertisements