Is there a good way to produce documentation for swig interfaces?

Question

I'd like to know if there are any good techniques for constructing/maintaining documentation on the interface.

I'm building an interface from c++ code to python using swig; mostly I'm just %including the c++ header files. I'm dealing with at least dozens of classes and 100's of functions, so automated tools are preferred.

Ideally, I'd like to use the doxygen formatted comments in the c++ headers to populate the docstrings in the python classes/methods.

Alternately, generating separate documentation (in ascii, html...) would also be useful. It looks like this kind of functionality was supported in earlier versions of swig (1.3 and earlier) but I don't see a way to do it with 2.0.

Are there any useful (automated) techniques for documenting the interface?

Answer 1

To get your doxygen comments into the python files there exists a python tool called doxy2swig.py on the web as described here.

Create xml documentation from your code. Then use the tool:

doxy2swig.py index.xml documentation.i

and import documentation.i in you swig interface file via

%import "documentation.i"

And its done.