Automatic documentation for boost python.

[jmirabel]

Although not related to CMake, I post this issue here because the problem was encountered in many packages and the best place to provide a solution is this package.
This is mostly for reporting as I have no time to allocate to this at the moment.

Problem

A C++ library can be easily exposed in Python, using for instance boost python. If the C++ library is already documented using Doxygen, documenting the Python bindings in somewhat tedious as it duplicates the already written documentation.

Solution

1. make Doxygen generate XML documentation for your project. There is no need to install it if all the bindings are in the same package.
2. using a Python script similar to https://github.com/jmirabel/hpp-python/tree/master/doc, generate a C++ file containing the documentation for all the functions of your C++ code. There are two possible formats, one using templates, the other using a std::map. At the moment, I am not able to say which one is preferable.

Format using templates

template <typename FunctionPrototype> struct doxygen_doc
{
inline static const char* docstring() { static const char* ds = "undocumented function"; return ds; }
}
// A template specialization for each C++ function that Doxygen knows.

3. in the Python bindings code, use the file generated above to fill the documentation of your classes, methods, (attributes?)...

[jcarpent]

typename FunctionPrototype you meant a pointer on the function?

[jmirabel]

typename FunctionPrototype you meant a pointer on the function?

I meant the type of this function, i.e. return_type (ClassName::*) (args) but I realize now that it is not sufficient because the type does not include the function name... It may be necessary to use a pointer to the function.

Assuming there are no ambiguities, the idea is to use it as
.def ("func", &Class::func, doxygen_doc<&Class::func>::docstring())

If this works well, this could even become
.def (documented_method<&Class::func> ("func"))

[jcarpent]

Another issue concerns Majax equations. Do you know how to handle them?

[jmirabel]

Maybe http://asciitex.sourceforge.net/

[jcarpent]

This would be indeed a nice and expected feature.

[jmirabel]

Eventually this: https://www.ctan.org/pkg/tex2mail

[jmirabel]

Some links that may be useful:

• https://github.com/m7thon/doxy2swig
• https://xdress.github.io/libref/doxygen.html
• https://enteropia.wordpress.com/2012/06/09/ascii-art-math/

[jmirabel]

I played a bit on this topic. A first working version can be found by pulling branch python_doc of https://github.com/jmirabel/hpp-fcl.
To make it work, you must add my fork as remote of the submodule:

cd cmake
git remote add -f jmirabel https://github.com/jmirabel/jrl-cmakemodules

[jmirabel]

Some usage can be seen in:

• https://github.com/jmirabel/hpp-fcl/blob/python_doc/python/math.cc
• https://github.com/jmirabel/hpp-fcl/blob/python_doc/python/collision-geometries.cc

[jmirabel]

For the conversion from TeX formulas to ASCII, I found this very helpful package: https://pylatexenc.readthedocs.io/en/latest/