Re: Docstrings for signals

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

Re: Docstrings for signals

Denis Rouzaud
Hi Phil,

I've been looking a bit more, and it seems signals do have docstring.
At least I set them in my code and Sphinx seems to pick them up:

See SIP code:

Resulting doc:

Is this expected to you?

If yes, would there be a way to add the signature in the Docstring? Shall we modify the sip gen to achieve this?
In Python, doing QgsMapCanvas.currentLayerChanged returns:

<unbound PYQT_SIGNAL currentLayerChanged(QgsMapLayer*)>

Cheers,

Denis


Le mar. 20 févr. 2018 à 08:27, Phil Thompson <[hidden email]> a écrit :
On 20 Feb 2018, at 12:13 pm, Denis Rouzaud <[hidden email]> wrote:
>
> Hi Phil,
>
> Another issue for Docstrings...
> Would it be possible to get a signature for signals too?
> They are listed as attribute (and not method in sphinx).

Signals *are* attributes and attributes cannot have docstrings.

Phil

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

Re: Docstrings for signals

Denis Rouzaud

Digging a bit more...
Sorry, I mixed things.
Signals indeed do not have Python docstrings but there is a structure containing the documentation that is written under %Docstring in the SIP file.

So all in all, my question can be resumed as, is there a way in Sphinx to display this signature?

Le lun. 26 févr. 2018 à 13:23, Denis Rouzaud <[hidden email]> a écrit :
Hi Phil,

I've been looking a bit more, and it seems signals do have docstring.
At least I set them in my code and Sphinx seems to pick them up:

See SIP code:

Resulting doc:

Is this expected to you?

If yes, would there be a way to add the signature in the Docstring? Shall we modify the sip gen to achieve this?
In Python, doing QgsMapCanvas.currentLayerChanged returns:

<unbound PYQT_SIGNAL currentLayerChanged(QgsMapLayer*)>

Cheers,

Denis


Le mar. 20 févr. 2018 à 08:27, Phil Thompson <[hidden email]> a écrit :
On 20 Feb 2018, at 12:13 pm, Denis Rouzaud <[hidden email]> wrote:
>
> Hi Phil,
>
> Another issue for Docstrings...
> Would it be possible to get a signature for signals too?
> They are listed as attribute (and not method in sphinx).

Signals *are* attributes and attributes cannot have docstrings.

Phil

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

Re: Docstrings for signals

Phil Thompson-5
On 26 Feb 2018, at 5:36 pm, Denis Rouzaud <[hidden email]> wrote:
>
>
> Digging a bit more...
> Sorry, I mixed things.
> Signals indeed do not have Python docstrings but there is a structure containing the documentation that is written under %Docstring in the SIP file.

Yes that confused me as well which is why I gave a misleading answer.

> So all in all, my question can be resumed as, is there a way in Sphinx to display this signature?
>
> Le lun. 26 févr. 2018 à 13:23, Denis Rouzaud <[hidden email]> a écrit :
> Hi Phil,
>
> I've been looking a bit more, and it seems signals do have docstring.
> At least I set them in my code and Sphinx seems to pick them up:
>
> See SIP code:
> https://github.com/qgis/QGIS/blob/master/python/gui/qgsmapcanvas.sip.in#L912-L917
>
> Resulting doc:
> http://python.qgis.org/api/gui/Map/QgsMapCanvas.html#qgis.gui.QgsMapCanvas.currentLayerChanged
>
> Is this expected to you?
>
> If yes, would there be a way to add the signature in the Docstring? Shall we modify the sip gen to achieve this?
> In Python, doing QgsMapCanvas.currentLayerChanged returns:
> <unbound PYQT_SIGNAL currentLayerChanged(QgsMapLayer*)>

It should be possible, but may need changes in PyQt as well.

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

Re: Docstrings for signals

Denis Rouzaud


Le lun. 26 févr. 2018 à 13:43, Phil Thompson <[hidden email]> a écrit :
On 26 Feb 2018, at 5:36 pm, Denis Rouzaud <[hidden email]> wrote:
>
>
> Digging a bit more...
> Sorry, I mixed things.
> Signals indeed do not have Python docstrings but there is a structure containing the documentation that is written under %Docstring in the SIP file.

Yes that confused me as well which is why I gave a misleading answer.

> So all in all, my question can be resumed as, is there a way in Sphinx to display this signature?
>
> Le lun. 26 févr. 2018 à 13:23, Denis Rouzaud <[hidden email]> a écrit :
> Hi Phil,
>
> I've been looking a bit more, and it seems signals do have docstring.
> At least I set them in my code and Sphinx seems to pick them up:
>
> See SIP code:
> https://github.com/qgis/QGIS/blob/master/python/gui/qgsmapcanvas.sip.in#L912-L917
>
> Resulting doc:
> http://python.qgis.org/api/gui/Map/QgsMapCanvas.html#qgis.gui.QgsMapCanvas.currentLayerChanged
>
> Is this expected to you?
>
> If yes, would there be a way to add the signature in the Docstring? Shall we modify the sip gen to achieve this?
> In Python, doing QgsMapCanvas.currentLayerChanged returns:
> <unbound PYQT_SIGNAL currentLayerChanged(QgsMapLayer*)>

It should be possible, but may need changes in PyQt as well.

Wouldn't it be sufficient to extend generateSignalTableEntry, test if we have prepend/append Docstring option and parse the arguments (sig->cppsig->args) to write them down?
As far as I see it, we won't have optional argument names from a signal, but at least it's something.
What do you think? 

Phil

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

Re: Docstrings for signals

Phil Thompson-5
On 26 Feb 2018, at 6:22 pm, Denis Rouzaud <[hidden email]> wrote:

>
> Le lun. 26 févr. 2018 à 13:43, Phil Thompson <[hidden email]> a écrit :
> On 26 Feb 2018, at 5:36 pm, Denis Rouzaud <[hidden email]> wrote:
> >
> >
> > Digging a bit more...
> > Sorry, I mixed things.
> > Signals indeed do not have Python docstrings but there is a structure containing the documentation that is written under %Docstring in the SIP file.
>
> Yes that confused me as well which is why I gave a misleading answer.
>
> > So all in all, my question can be resumed as, is there a way in Sphinx to display this signature?
> >
> > Le lun. 26 févr. 2018 à 13:23, Denis Rouzaud <[hidden email]> a écrit :
> > Hi Phil,
> >
> > I've been looking a bit more, and it seems signals do have docstring.
> > At least I set them in my code and Sphinx seems to pick them up:
> >
> > See SIP code:
> > https://github.com/qgis/QGIS/blob/master/python/gui/qgsmapcanvas.sip.in#L912-L917
> >
> > Resulting doc:
> > http://python.qgis.org/api/gui/Map/QgsMapCanvas.html#qgis.gui.QgsMapCanvas.currentLayerChanged
> >
> > Is this expected to you?
> >
> > If yes, would there be a way to add the signature in the Docstring? Shall we modify the sip gen to achieve this?
> > In Python, doing QgsMapCanvas.currentLayerChanged returns:
> > <unbound PYQT_SIGNAL currentLayerChanged(QgsMapLayer*)>
>
> It should be possible, but may need changes in PyQt as well.
>
> Wouldn't it be sufficient to extend generateSignalTableEntry, test if we have prepend/append Docstring option and parse the arguments (sig->cppsig->args) to write them down?
> As far as I see it, we won't have optional argument names from a signal, but at least it's something.
> What do you think?

Possibly, but PyQt does some manipulation of the docstrings (as far as I can remember) to deal with a signal having overloads which are not signals.

Try it and send me a patch...

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