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

[Ralf W. Grosse-Kunstleve]

--- Martin Reddy <reddy at pixar.com> wrote:

> 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?

This must have been addressed since it works for me.

Ever since last summer I am dragging a local patch around with me which
automatically adds the C++ signatures to the doc strings. E.g. for a function
(to prove it works):

Help on built-in function min in scitbx.array_family.flex:

scitbx.array_family.flex.min = min(...)
    C++ signatures:
    min(scitbx::af::versa<double, scitbx::af::flex_grid<scitbx::af::small<long,

10ul> > >) -> d
    min(scitbx::af::versa<float, scitbx::af::flex_grid<scitbx::af::small<long,
1
0ul> > >) -> f
    min(scitbx::af::versa<long, scitbx::af::flex_grid<scitbx::af::small<long,
10
ul> > >) -> l
    min(scitbx::af::versa<int, scitbx::af::flex_grid<scitbx::af::small<long,
10u
l> > >) -> i
    min(scitbx::af::versa<unsigned long,
scitbx::af::flex_grid<scitbx::af::small
<long, 10ul> > >) -> m


Or for a class:

Help on class histogram in scitbx.array_family.flex:

scitbx.array_family.flex.histogram = class histogram(Boost.Python.instance)
 |  Method resolution order:
 |      histogram
 |      Boost.Python.instance
 |      __builtin__.object
 |  
 |  Methods defined here:
 |  
 |  __init__(...)
 |      C++ signatures:
 |      __init__(_object*, scitbx::histogram<double, long> other,
scitbx::af::co
nst_ref<double, scitbx::af::trivial_accessor> data) -> v
 |      __init__(_object*, scitbx::histogram<double, long> other,
scitbx::af::co
nst_ref<double, scitbx::af::trivial_accessor> data, d
relative_tolerance=0.0001)
 -> v
 |      __init__(_object*, scitbx::af::const_ref<double,
scitbx::af::trivial_acc
essor> data) -> v
 |      __init__(_object*, scitbx::af::const_ref<double,
scitbx::af::trivial_acc
essor> data, m n_slots=1000) -> v
 |  


This is output from gcc 3.4 compiled code which has some bug in the name
demangler. With other compilers the output contains full type names (e.g.
"bool" instead of just "b").

You have to update just two files in the boost tree to get the doc signatures
feature:

wget
http://cci.lbl.gov/~rwgk/boost_python/doc_signatures/function.hpp_2006_01_04_0620
wget
http://cci.lbl.gov/~rwgk/boost_python/doc_signatures/function.cpp_2006_01_04_0620

Copy these files to

boost/boost/python/object/function.hpp
boost/libs/python/src/object/function.cpp

The modified files are based on the current CVS. There are older files from
last summer in the same web directory (omit the file names from the URL). They
probably work with the latest boost release. In the worst case, take the diffs
from the same web directory and use the patch command to backport to your boost
version.

Sorry I never found the time to check the changes in. Unfortunately my changes
break some unit tests and it takes more time than I can affort right now to
adjust them.

Cheers,
        Ralf



		
__________________________________________ 
Yahoo! DSL – Something to write home about. 
Just $16.99/mo. or less. 
dsl.yahoo.com