[Qgis-psc] Work on PyQGIS docs

[Denis Rouzaud]

Le mer. 16 oct. 2019 à 20:46, Tim Sutton <tim at kartoza.com> a écrit :

> Hi
>
> Hurrah! Thank you so much for this Denis!
>

thanks :)


> If we move to Qt for Python one day will we have a massive job porting the
> API docs?
>

I believe not. Maybe, some work I did here (the links) could be dropped to
use some existing tool (sphinx-auto-typehints), but I left some
explanations in the code, so it would be quite straightforward.

Regarding moving to Qt for Python, there is 2 concerns:

1) Are we able to correctly create the bindings similarly as we do today. I
have no reason to think not, but it would require further investigations.

2) For the creation of the bindings files, the main issue is that sipify
won't work to create the xml files (replacing the sip files). We would have
3 options:
* move back to manual synchronization of files (like in the old days)
* adapt sipify to produce xml
* create a proper tool based on clang-parser to produce the xml based on
the same macros we use today in header files (SIP_*)

The required amount of work is quite large but:
1) we should take a wise decision regarding the future of our Python
bindings from what we know today (bus factor with PyQt/sip, awful sip, risk
of migrating)
2) sipify, while being very handy, is definitely the worst code I have ever
written and a very fragile tool. There's also some bus factor involved
here. Either moving to Qt for Python or not, I think we should try to move
away from it.

Cheers,
Denis


> Regards
>
> Tim
>
> On 16 Oct 2019, at 08:39, Denis Rouzaud <denis.rouzaud at gmail.com> wrote:
>
> Dear PSC,
>
> I have spent the 3 days on improving the PyQGIS docs.
> Here is what has been done:
>
> * refactoring of the build scripts (much clearer now)
> * updating the forked theme (to support versioning) with upstream
> * added processing to the documentation (still some work to be done here)
> * remove empty sections (enum, signal, attributes) in pages
> https://github.com/qgis/pyqgis/pull/40
> * add return types and param rtype (and links within the API docs)
> https://github.com/qgis/pyqgis/pull/41
>
> The last one was a tricky one. We currently cannot use existing tools
> (like sphinx-auto-typehints) since SIP does not fill the __annotations__
> dictionary. Maybe another reason to look towards Qt for Python. Anyway, I
> added custom event handler around autodoc to manually process the docstring.
>
> I believe this was a good shot for the docs, and I guess we would benefit
> from having such maintenance and small improvements sponsored work each
> year. Of course, I'm blowing my own horn, and I'd like to propose my
> application for next year.
>
> Thanks for your confidence.
> Denis
>
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
> —
>
>
>
>
>
>
>
>
> *Tim Sutton*
>
> *Co-founder:* Kartoza
> *Ex Project chair:* QGIS.org
>
> Visit http://kartoza.com to find out about open source:
>
> Desktop GIS programming services
> Geospatial web development
> GIS Training
> Consulting Services
>
> *Skype*: timlinux
> *IRC:* timlinux on #qgis at freenode.net
>
> I'd love to connect. Here's my calendar link
> <https://calendly.com/timlinux> to make finding time easy.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20191016/08ed612e/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: KartozaNewLogoThumbnail.jpg
Type: image/jpeg
Size: 6122 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20191016/08ed612e/attachment.jpg>