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

There's some mileage in %feature("autodoc") with SWIG 2.0, which I think is as far is it goes currently.

For example:

%module test

%feature("autodoc", "3");

void foo (int *a, void *bar, double epsilon);

causes some vaguely sane documentation to be inserted.

If that isn't sufficient I think the next easiest step would be to use %pythonprepend to make a marker that's unique enough sed or similar can be used to insert documentation into the interface after SWIG has run automatically:

%pythonprepend foo "MARKER"

and then:

sed -ei 's/MARKER/some documentation' test.py

Where you could find the functions to %pythonprepend by looking over the Doxygen output using a (Python?) script to generate the markers and substitute them after running SWIG.

Answer 2

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.