[C++-sig] Using python doc tools on boost-generated functions

[Neal Becker]

Martin Reddy wrote:

> 
> Hey there,
> 
> We are using boost.python to create Python bindings to C++ code. We'd like
> to produce automatic Python API docs using a tool like epydoc or pydoc.
> However, we've been running into a number of problems, such as epydoc not
> picking up any free functions that are generated by boost.python.
> 
> Checking the C++-sig archives, I found a message from Sep 2004 saying that
> boost.python functions are not generated with the same set of attributes
> on them as built-in python functions, and the doc tools like epydoc rely
> on those attributes.
> 
>    http://mail.python.org/pipermail/c++-sig/2004-September/008137.html
> 
> It looks like this is still an issue today. I'm just wondering if anyone
> has come up with any workarounds for using tools like epydoc or pydoc with
> boost.python functions, or what would be involved to fix this in
> boost.python?
> 
> Cheers,
> 

I did explore a few approaches.  Probably the simplest is something like
this:
This is an excerpt from some of my code:

  scope().attr("__doc__") = 
    "Module for Block Interleavers\n";

  class_<BlockInterleaver<int> > ("block_interleaver",  "Block Interleaver", 
                                  init<int, int, int>((arg ("size"), arg ("rows"), arg ("cols")),
                                                      "__init__(size,rows,cols)\n"
                                                      "Construct a Block Interleaver.\n"
                                                      "Only full arrays are supported.\n"
                                                      "@param size: array size\n"
                                                      "@type size: int\n"
                                                      "@param rows: rows\n"
                                                      "@type rows: int\n"
                                                      "@param cols: cols\n"
                                                      "@type cols: int\n"
                                                      )
                                  )
    .def ("v", &BlockInterleaver<int>::GetV)
    .def ("vinv", &BlockInterleaver<int>::GetVinv)
    //    .def_readonly ("v", &BlockInterleaver<int>::v)
    //    .def_readonly ("vinv", &BlockInterleaver<int>::vinv)
    ;

  def ("interleave", &interleave_block<ublas::vector<int>,
ublas::vector<int> >,
       "interleave(inter,x)\n"
       "Interleave input I{x} using interleaver I{inter}"
       "@param inter: stuff\n"
       );

Then running PYTHONPATH=./ epydoc <modulename> seems to work OK.