Custom docstrings and complete signature

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

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

[1] <a href="http://pyqt.sourceforge.net/Docs/sip4/directives.html#directive-%Docstring">http://pyqt.sourceforge.net/Docs/sip4/directives.html#directive-%Docstring



_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Custom docstrings and complete signature

Phil Thompson-5
On 2 Dec 2017, at 12:52 am, Denis Rouzaud <[hidden email]> 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
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> a écrit :
On 2 Dec 2017, at 12:52 am, Denis Rouzaud <[hidden email]> 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

_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Custom docstrings and complete signature

Phil Thompson-5
On 2 Dec 2017, at 11:43 am, Denis Rouzaud <[hidden email]> wrote:
>
> 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?

What is the problem with the current docstrings?

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Custom docstrings and complete signature

Denis Rouzaud
It doesn't integrate the signature because we provide our own docstrings from the c++ headers.

I was hoping for an automation of:
- getting the signature in the pythonic way
- getting all the overloaded methods listed



Le sam. 2 déc. 2017 à 07:48, Phil Thompson <[hidden email]> a écrit :
On 2 Dec 2017, at 11:43 am, Denis Rouzaud <[hidden email]> wrote:
>
> 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?

What is the problem with the current docstrings?

Phil

_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Custom docstrings and complete signature

Phil Thompson-5
On 2 Dec 2017, at 11:51 am, Denis Rouzaud <[hidden email]> wrote:
>
> It doesn't integrate the signature because we provide our own docstrings from the c++ headers.
>
> I was hoping for an automation of:
> - getting the signature in the pythonic way
> - getting all the overloaded methods listed

First off, docstrings are different to documentation. The former are only generated for objects that actually *do* exist. The latter is generated for all objects that *might* exist. For example, you want documentation to include platform-specific APIs but docstrings can only include the current platform. You need to take that into account when deciding how you are going to automate the documentation.

Just considering the docstrings for now you could provide a patch to sip that make the %Docstring directive work the way you want. For example, add a "generated" option that could have values of either "before", "after" or "discard". The default value would be "discard" (to maintain compatibility).

Phil
_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt
Reply | Threaded
Open this post in threaded view
|

Re: Custom docstrings and complete signature

Denis Rouzaud


Le sam. 2 déc. 2017 à 08:22, Phil Thompson <[hidden email]> a écrit :
On 2 Dec 2017, at 11:51 am, Denis Rouzaud <[hidden email]> wrote:
>
> It doesn't integrate the signature because we provide our own docstrings from the c++ headers.
>
> I was hoping for an automation of:
> - getting the signature in the pythonic way
> - getting all the overloaded methods listed

First off, docstrings are different to documentation. The former are only generated for objects that actually *do* exist. The latter is generated for all objects that *might* exist. For example, you want documentation to include platform-specific APIs but docstrings can only include the current platform. You need to take that into account when deciding how you are going to automate the documentation.

Thanks for the warning, that's something I did not pay attention to yet. I don't think there is a lot of concern here for our project, not sure though.

Just considering the docstrings for now you could provide a patch to sip that make the %Docstring directive work the way you want. For example, add a "generated" option that could have values of either "before", "after" or "discard". The default value would be "discard" (to maintain compatibility).

Hey, that would be awesome. Is that something you could achieve for us/me?
If fundings are needed, I could ask the project for some.
Let me know your thoughts.

Cheers,
Denis 

_______________________________________________
PyQt mailing list    [hidden email]
https://www.riverbankcomputing.com/mailman/listinfo/pyqt