[PyQt] Docstrings for signals

[Phil Thompson]

On 26 Feb 2018, at 6:22 pm, Denis Rouzaud <denis.rouzaud at gmail.com> wrote:
> 
> Le lun. 26 févr. 2018 à 13:43, Phil Thompson <phil at riverbankcomputing.com> a écrit :
> On 26 Feb 2018, at 5:36 pm, Denis Rouzaud <denis.rouzaud at gmail.com> 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 <denis.rouzaud at gmail.com> 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