[Qgis-psc] Work on PyQGIS docs

[Tim Sutton]

Ok thanks for the insights! So more than just a single grant proposal’s worth or work then I guess?

Regards

Tim

> On 16 Oct 2019, at 20:01, Denis Rouzaud <denis.rouzaud at gmail.com> wrote:
> 
> 
> 
> Le mer. 16 oct. 2019 à 20:46, Tim Sutton <tim at kartoza.com <mailto: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 <mailto: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 <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 <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 <mailto:Qgis-psc at lists.osgeo.org>
>> https://lists.osgeo.org/mailman/listinfo/qgis-psc <https://lists.osgeo.org/mailman/listinfo/qgis-psc>
> —
> 
> 
> <KartozaNewLogoThumbnail.jpg>
> 
> 
> 
> 
> 
> 
> Tim Sutton
> 
> Co-founder: Kartoza
> Ex Project chair: QGIS.org <http://qgis.org/>
> 
> Visit http://kartoza.com <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 <http://freenode.net/>
> 
> I'd love to connect. Here's my calendar link <https://calendly.com/timlinux> to make finding time easy.
> 

—









Tim Sutton

Co-founder: Kartoza
Ex Project chair: QGIS.org

Visit http://kartoza.com <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/63a29dae/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/63a29dae/attachment.jpg>