[PyQt] Custom docstrings and complete signature

[Denis Rouzaud]

Hi all,

I am trying to build QGIS Pypthon API documentation using Sphinx.
The Python API is built using SIP and I'm wondering which approach I should
consider to get full signature (and hopefully from overloaded methods too)
in the doc.
I would like to try avoiding having to write down the signature myself in
the docstring, and get a full automatic method (with my overloaded methods
:) )

I have read here that introspection is possible (which apprently wasn't the
case before)
https://stackoverflow.com/a/41245451/1548052
It says you can do it automatically (via Argument Clinic [0]) or manually
(author's prefered way) via setting PyDoc_STRVAR.
This sounds a bit obscure to me, I tried to print __text_signature__ on my
objects/methods, and always get empty string.

I read from SIP %Docstring% documentation that as soon as you define a
docstrings, it *will* *prevent SIP from generating an automatic docstring
that describes the Python signature of a function or method overload* [1].

Now, is there a way of still automatically create the Python signature and
prepend it to the custom docstring?

The only thing I can think of is to build twice, once with and once without
argument -o [2] and to get a way to merge them in Sphinx or when creating
the rst templates.

Or is the Argument Clinic the approach?
Anything else?


Thanks a lot for any help or participation to the discussion.
Cheers,
Denis

[0] https://docs.python.org/3/howto/clinic.html
[1]
http://pyqt.sourceforge.net/Docs/sip4/directives.html#directive-%Docstring
[2] http://pyqt.sourceforge.net/Docs/sip4/command_line.html#cmdoption-sip-o
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://www.riverbankcomputing.com/pipermail/pyqt/attachments/20171202/b18d45fc/attachment-0001.html>