Help with boost::python and documentation tools (e.g. pydoc)

[Neal D. Becker]

I'm using boost::python to transform various C++ classes and functions to
python.  It is all working quite well, but now I'm having trouble with
documentation tools.

I hope someone can tell me if the problem is with the doc tools, such as
pydoc, or with boost::python implementation.

If I create a free function, this is what happens:
PyTypeObject function_type = {
    PyObject_HEAD_INIT(0)
    0,
    "Boost.Python.function",
    sizeof(function),
    0,
    (destructor)function_dealloc,               /* tp_dealloc */
    0,                                  /* tp_print */
    0,                                  /* tp_getattr */
    0,                                  /* tp_setattr */
    0,                                  /* tp_compare */
    0, //(reprfunc)func_repr,                   /* tp_repr */
    0,                                  /* tp_as_number */
    0,                                  /* tp_as_sequence */
    0,                                  /* tp_as_mapping */
    0,                                  /* tp_hash */
    function_call,                              /* tp_call */
    0,                                  /* tp_str */
    0, // PyObject_GenericGetAttr,            /* tp_getattro */
    0, // PyObject_GenericSetAttr,            /* tp_setattro */
    0,                                  /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT /* | Py_TPFLAGS_HAVE_GC */,/* tp_flags */
    0,                                  /* tp_doc */
    0, // (traverseproc)func_traverse,          /* tp_traverse */
    0,                                  /* tp_clear */
    0,                                  /* tp_richcompare */
    0, //offsetof(PyFunctionObject, func_weakreflist), /* tp_weaklistoffset
*/
    0,                                  /* tp_iter */
    0,                                  /* tp_iternext */
    0,                                  /* tp_methods */
    0, // func_memberlist,              /* tp_members */
    function_getsetlist,                /* tp_getset */
    0,                                  /* tp_base */
    0,                                  /* tp_dict */
    function_descr_get,                 /* tp_descr_get */
    0,                                  /* tp_descr_set */
    0, //offsetof(PyFunctionObject, func_dict),      /* tp_dictoffset */
    0,                                      /* tp_init */
    0,                                      /* tp_alloc */
    0,
    0                                       /* tp_new */
};

Notice the getset member is being set, so I guess this is using the new
descriptor protocol.

As an example:

dir (block_interleaver_wrap)
['__doc__', '__file__', '__name__', 'block_interleaver', 'deinterleave',
'deinterleave_c', 'interleave', 'interleave_c']

the latter 4 are free functions.  If I use pydoc, these functions don't
appear.

inspect.ismethoddescriptor(block_interleaver_wrap.interleave)
True

inspect.getdoc (block_interleaver_wrap.interleave)
'interleave(inter,x)\nInterleave input I{x} using interleaver I{inter}@param
inter: stuff'

This is the documentation I wanted.

Anyone know what needs to happen so that tools like pydoc, and especially
epydoc, will correctly find the documentation?