[Adonthell-devel] API docs for Python code

[Kai Sterker]

Since we're now starting to implement stuff on Python side, I have
been wondering how why might generate API documentation for that code.
It turns out that doxygen does have some support for Python, but it
appears to be a bit limited. I.e. it will parse Python docstrings, but
won't recognize any special doxygen keywords in them:

http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks


Searching a bit further brought up this, however

http://internetducttape.com/2007/03/20/automatic_documentation_python_doxygen/

The author describes how to use a tool called doxypy as filter for
doxygen to convert python docstrings into what doxygen would normally
expect. This makes it possible to use standard doxygen syntax in
Python docstrings. doxypy is available here:

http://code.foosel.org/doxypy

In a footnote, there's also a link to another interesting piece. This
should allow to pass the doxygen documentation of C++ code through
SWIG into the generated Python wrappers. Not sure how well it works,
but if it works, it would be a very nice feature indeed! Especially
when we write more and more Python code

http://www.enricozini.org/2007/tips/swig-doxygen-docstring.html


Of course, there are plenty more tools around to create HTML
documentation for Python code. I'd like to stick to doxygen, however
as it will mean that our C++ and Python API is presented in a
consistent way.

I will play around with those tools as time permits and let you know
about the results.

Kai