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

From: Neal D. Becker (ndbecker2_at_verizon.net)
Date: 09/30/04 

To: python-list@python.org
Date: Thu, 30 Sep 2004 13:15:12 -0400

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?

Relevant Pages

  • Re: Best way to document Python code...
    ... documentation in HTML format, and/or serve it over web with its built-in ... The HTML generated by pydoc doesn't link to standard modules properly. ... modification for generating docs for a web page about a python package. ...
    (comp.lang.python)
  • Re: Python "header" files
    ... Thanks to you and others for suggesting pydoc. ... calculations before producing HTML. ... I think the HTML documentation for a main program should have (in ...
    (comp.lang.python)
  • RE: pydoc does not like this file
    ... I'm not trying to run py2exe ... I'm trying to generate a html file with documentation (hence pydoc -w) ... hmmm guess -w should be after python and not after pydoc: ...
    (comp.lang.python)
  • pydoc, best practices, and Data class
    ... I have a python program that I am trying to generate documentation for. ... But in one of my files I have a class called "Data", when pydoc gets to ... of the classes, plus it doesn't create the standard header, Package ...
    (comp.lang.python)
  • Re: Tried Ruby (or, "what Python *really* needs" or "perldoc!")
    ... I was under the impression that pydoc already interpreted ... documentation sets -- that's where epydoc (which I suppose ... would be cool is if some of happydoc's unique features were ... ported to epydoc (such as getting information from comments ...
    (comp.lang.python)