[PyQt] Custom docstrings and complete signature

[Denis Rouzaud]

Hi Phil,

Thanks a lot for your prompt reply -- as usual!

What would you suggest to do in the meantime?

We have an automated process to create SIP files from the headers, I could
introduce the signature in there.
Does it sound like the most sensible approach to you?

Cheers,
Denis

Le sam. 2 déc. 2017 à 06:47, Phil Thompson <phil at riverbankcomputing.com> a
écrit :

> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://www.riverbankcomputing.com/pipermail/pyqt/attachments/20171202/69d06f5b/attachment.html>