Docs for members

[nyalldawson]

Looking into why https://qgis.org/pyqgis/3.4/core/Raster/QgsRasterHistogram.html has such poor docs, it's because the member variable documentation isn't transferred to sip docstrings.

This isn't currently supported by sip, but I think it should be possible. See https://stackoverflow.com/a/40488936/1861260

[3nids]

I think that SIP will return an error if you try to document a member, have you tested?
It might be possible to bring that to PyQt list and to see it fixed, but I guess this is not a trivial fix.

But anyway, this kind of class is not very common in the API. I have no strong opinion, but it seems we should try to stay coherent and offer setters/getters rather than making the members public. But it's maybe off-topic.

[nyalldawson]

Yes, sip errors. I guess there's a lot of parts involved here -- sipify, pyqt, sphinx,... I'd be inclined to agree with you that's it's too much effort, but then.. I don't like missing nice stuff :p

[3nids]

sipify and sphinx are the easy parts ;) I'll be happy to tackle them if you do the SIP part.
Or just refactor the class with setters and getters (a V2 and implicit conversion)?

[nyalldawson]

@3nids do you have a way to locally test the doc generation?

[3nids]

yes I do. There is also a build on any pull request on this repo, and the generated docs are accessible here https://qgis.org/pyqgis/master_temp/

[3nids]

I asked for enum on the list
https://www.riverbankcomputing.com/pipermail/pyqt/2019-March/041423.html

Another easier approach might be to create extra files with sipify and integrate them in sphinx.