Generate module doc from pybind11

[youliangtan]

Hi, I was trying to generate a simple api doc from a pybind11 implementation. After multiple attempts, the issue seems to be related to the signature while generating the module function arguments.

ValueError: no signature found for builtin <built-in method test_clone_ptr of PyCapsule object at 0x7f1ef5783b70>

On the second attempt, i managed to generate the html docs successfully, after adding this into the code within my pybind11 impl

PYBIND11_MODULE(module, m) {
    py::options options;
    options.disable_function_signatures();

During the docs generation, the terminal is prompted with:

_html_mako:326: UserWarning: Error handling return annotation for <Function

The resulted html doc is generated with missing args description within the class function. On the other hand, I managed to generate the doc with pydoc3, without issue.

Here I would hope to seek help in getting the right method to generate a doc from a pybind11 python module.

Let me know again if my description is unclear, I can provide you with the code for this issue. Thanks a lot!

Additional info

• ubuntu 20.04
• pdoc version: 0.9.2

[kernc]

Since PR https://github.com/pdoc3/pdoc/pull/148, we parse signatures from builtins' docstrings, if available. https://github.com/pdoc3/pdoc/blob/bec63077a03b2136e6982825d327073ed76cc20a/pdoc/init.py#L1442-L1475 Do your built-in functions feature signatures like the example in https://github.com/pdoc3/pdoc/issues/237?

[youliangtan]

I dont think is similar to that. I will try to further illustrate the issue. I am trying to generate my docs from this repo

An example:

when I try to generate rmf_adapter.geometry, I am getting Error msgs (for both finalize and make_final_convex_circle):

    return _signature_from_callable(obj, sigcls=cls,
  File "/usr/lib/python3.8/inspect.py", line 2296, in _signature_from_callable
    return _signature_from_builtin(sigcls, obj,
  File "/usr/lib/python3.8/inspect.py", line 2107, in _signature_from_builtin
    raise ValueError("no signature found for builtin {!r}".format(func))
ValueError: no signature found for builtin <built-in method make_final_convex_circle of PyCapsule object at 0x7fa6fc40d600>

which is related to the module function here

This is the doc generated from pydoc3

Hopefully I can get some guidance on this. Appreciate it.

[kernc]

This is pydoc, not pdoc! :sweat_smile:

https://github.com/osrf/rmf_fleet_adapter_python/blob/5f7776c314f3a360786a405435b10d7933fbd8a7/docs/gen_docs.sh#L1

[youliangtan]

Srry typo at the description above.😅😅 I meant to mention this to show that it works on pydoc, unfortunately not on pdoc.

[kernc]

Can you provide a full traceback? It's hard for me to locate where this leaves pdoc3 module space, and I don't feel like compiling your code. :stuck_out_tongue:

[kernc]

Or at least a larger chunk of the traceback, which contains pdoc3 exit-point? :grin: Thanks!