Saturday, April 27, 2013

Sphinx domains for MATLAB

[UPDATE 2013-06-20] sphinxcontrib-matlabdomain is now at the cheese factory, so you should be able to install it using Pip or easy_install, or download the and unzip the source and use

>>> python setup.py install

Sphinx is a Python module that generates beautiful documentation using ReStructuredText. It is extensible to other "domains" other than Python. I've made a MATLAB domain that you can install on Bitbucket. Fork or clone it.

To use it you must have Sphinx and its dependencies. Then install the matlabdomain by cloning my fork of the sphinx-contrib repository from Bitbucket. Then run `python setup.py install` from inside the `matlabdomain` directory. If you run `pip freeze` you sill see it listed but there is a warning that the `dependency_links` are not in an svn repository - this is a known bug. After you've run sphinx-quickstart, edit conf.py to include `sphinxcontrib.matlab` in the list of `extensions` and also add the following line:

primary_domain = 'mat'

Voila! You can now document MATLAB in Sphinx, as in the example above. Do note the TODO in matlab.py - I have not added autodocs for MATLAB. It wouldn't make sense anyway, since MATLAB function and class definitions do not use ReStructuredText markup for their H1 and help comment lines.

Sphinx matlabdomain

I wrote a post on installing Sphinx with latex support. Also you will need a working make binary.

Old still shots of demo from before I added the iframe:

Fork me on GitHub