[PyQt] Custom docstrings and complete signature

[Phil Thompson]

On 2 Dec 2017, at 12:52 am, Denis Rouzaud <denis.rouzaud at gmail.com> wrote:
> 
> 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?

Sorry, no.

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

I am working on documentation improvements, including better auto-generation from .sip files. This is part of the reason for separating the docs from the PyQt sources. It's a work-in-progress and subject to lots of API changes (which is why the code - sphinx extensions etc - isn't publically available yet). The next lot of major development on it will be some time in the first quarter next year.

Phil