[C++-sig] documenting boost::python - and now for something completely different

[Neal D. Becker]

Here is a completely different approach to documenting boost::python code.

The intended user of this documentation is a python programmer.  Therefore,
they want Python-ish documentation.

Doxygen can produce nice documents.  It doesn't know Python.  But wait! 
There is a script pythfilter.py that does a nice job of converting python
code, and can be run by doxygen as a filter.

So here's the deal.  You write python code inside a c++ comment.  This code
is marked up per doxygen markup.  You put a marker at the start and end of
each such comment.  A tiny python script I wrote strips everything not
between those markers and feeds it to pythfilter.  So, all you have to do
is in Doxyfile set INPUT_FILTER = todoxy.py.

The best way to do this is use emacs/xemacs.  (require 'mmm).  Write doc
blocks like this:

/* {%python%}
class IIR_double():
    """ \brief IIR filter class with float input and coefficients
    """
    def __init__(self, numerator, denominator):
 """Construct an IIR filter
 \param numerator vector
 \param denominator vector
 """
    
{%/python%} */

This will switch emacs into python mode inside the block, which makes it
really easy to edit the blocks.

Anyone interested I will supply the todoxy.py + modified pythfilter.py.