Work on PyQGIS docs

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

Work on PyQGIS docs

3nids
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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Work on PyQGIS docs

Andreas Neumann-3
Hi Denis,

Thanks a lot for your work.

I will put something in next years budget for maintenance/development of PyQGIS docs. I agree that this work is important and useful to our devs and users. If I forget about this in next year's budget, please remind me.

Budget will be up to discussion next year anyway.

Thanks,
Andreas

On Wed, 16 Oct 2019 at 09:40, Denis Rouzaud <[hidden email]> 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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--

--
Andreas Neumann
QGIS.ORG board member (treasurer)

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Work on PyQGIS docs

Tim Sutton-6
In reply to this post by 3nids
Hi

Hurrah! Thank you so much for this Denis! If we move to Qt for Python one day will we have a massive job porting the API docs?

Regards

Tim

On 16 Oct 2019, at 08:39, Denis Rouzaud <[hidden email]> 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
[hidden email]
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 to make finding time easy.


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Work on PyQGIS docs

3nids


Le mer. 16 oct. 2019 à 20:46, Tim Sutton <[hidden email]> 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 <[hidden email]> 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
[hidden email]
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 to make finding time easy.


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: Work on PyQGIS docs

Tim Sutton-6
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 <[hidden email]> wrote:



Le mer. 16 oct. 2019 à 20:46, Tim Sutton <[hidden email]> 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 <[hidden email]> 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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc



<KartozaNewLogoThumbnail.jpg>






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 to make finding time easy.










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 to make finding time easy.


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc