[Qgis-psc] [PyQGIS API] end of phase 2

Fri Apr 13 02:35:22 PDT 2018

Hi Denis

Wow this is fantastic work! Thank you so much for all the effort you have put into this. Considering how critical good documentation is for building a vibrant collection of plugins and applications for QGIS, a big
 +1 from me too if the PSC can make more funding available for this.

One small feature request: Could you inject the class diagrams generated by doxygen into the py docs? The image urls seem to be predictable e.g.

https://qgis.org/api/classQgsVectorLayer__inherit__graph.png

and so you could just substitute the class name in the above string each time and insert the image at the top of the page. I find these diagrams really helpful in understanding the context of a given class.

Regards

Tim

> On 12 Apr 2018, at 17:20, Denis Rouzaud <denis.rouzaud at gmail.com> wrote:
> 
> Dear PSC,
> 
> Finally, I have finalized phase 2 of PyQGIS API docs project.
> It was again a tedious job with again unexpected issues.
> 
> Here is what has been done:
> 
> 1) Automatic building of QGIS docker images in Travis
> These are used to later build the PyQGIS doc in another Travis job in QGISPythonAPIDocumentation repo.
> 
> 2) Multi-version support
> To enable support several API versions on a custom website (not readthedocs, but we use readthedocs theme), it was required to fork the theme since support of multiple version was rejected in main repo [0]. The fork is here [1].
> 
> 3) Support for signal signatures
> Support for signal signatures in SIP was missing [2] and I provided a patch [3]. This patch is in the upstream SIP library (maintained by Phil Thomson) and jumping into this code is really not an easy task.
> 
> 4) Table of contents and grouping
> In previous version, table of content was full of inherited class methods which were not bringing useful info (all methods from Qt parent classes).
> Now, these are removed. 
> Moreover, there is a fine tuning in grouping and signals have their own dedicated category.
> These is made possible by using a custom version of autoautosummary [4,5]
> 
> 5) Online building of the Python API Docs
> Everything has been setup in Travis to automatically build the docs using QGIS docker image (see pt 1).
> Sadly, I was not able to set the dev version of SIP (upcoming 4.19.9) in the main docker. That means missing the nice signatures for signals. So, this is on hold (it's pushing to a temp folder) until new SIP is released (probably along new Qt version in may).
> Hence last published version of the docs has been built on my computer, and server API is missing.
> The logic is ass follows:
> - master docs follows QGIS master branch and is built once a day
> - release versions docs are built using tags on the main repo and hence will strictly correspond to the last point release of each branch
> 
> Original allocated time has again been largely overrun (mainly due to SIP modifications and trying to bring them in the build chain).
> Since I considered signal for signatures was a first priority feature (although not mentionned before Gary's mail [6]), some were again left apart:
> - Adapt sipify to move /Out/ parameters from parameters list to returns group
> - Sipify doc
> 
> I think that the documentation is now in a much more accomplished state.
> 
> As far as I see it, here are the main remaining issues:
> 
> I1) as pointed by Richard [7], we need to fix redirections properly
> 
> I2) also mentionned [7], the categorization of classes originally thought by Tim can be improved by creating categories on our own (instead of automatically by class names). Maybe take it down to 10-20 sucategories for each module (core, gui, analysis, server).
> 
> I3) list of parameters still showing output only parameters, and the /Out/ arguments are not mentionned as output. This is a sipify enhancement.
> 
> I4) Finalizing the auto build toolchain (integrate coming SIP version in dependency docker image, automatic triggering of API docs build from main QGIS travis jobs).
> 
> I think someone from the PSC holding the info of the provider can easily handle I1.
> 
> I would propose QGIS.org to sponsor a phase 3 for the remaining issues with the following estimate:
> I2) 8h
> I3) 16h
> i4)  24h
> 
> At the usual rate for QGIS.org sponsored project, the proposal is of 6 days.
> 
> Would you like to have this as grant proposal or shall we proceed similarly to the 2 previous phases?
> 
> I'd like to thanks again QGIS.org for sponsoring this. It is worth mentioning though that a lot of time has been freely invested there, on behalf of Opengis, roughly doubling the time.
> 
> And last, but definitely not least, here are the docs!!!!
> http://python.qgis.org/master <http://python.qgis.org/master>
> 
> Best regards,
> Denis
> 
> 
> [0] https://github.com/rtfd/sphinx_rtd_theme/pull/574 <https://github.com/rtfd/sphinx_rtd_theme/pull/574>
> [1] https://github.com/3nids/sphinx_rtd_theme.git <https://github.com/3nids/sphinx_rtd_theme.git>
> [2] https://www.riverbankcomputing.com/pipermail/pyqt/2018-February/040036.html <https://www.riverbankcomputing.com/pipermail/pyqt/2018-February/040036.html>
> [3] https://www.riverbankcomputing.com/hg/sip/rev/34a94ca0260d <https://www.riverbankcomputing.com/hg/sip/rev/34a94ca0260d>
> [4] https://github.com/qgis/QGISPythonAPIDocumentation/blob/master/autoautosummary.py <https://github.com/qgis/QGISPythonAPIDocumentation/blob/master/autoautosummary.py>
> [5] https://stackoverflow.com/a/30783465/1548052 <https://stackoverflow.com/a/30783465/1548052>
> [6] https://lists.osgeo.org/pipermail/qgis-developer/2018-February/052148.html <https://lists.osgeo.org/pipermail/qgis-developer/2018-February/052148.html>
> [7] https://lists.osgeo.org/pipermail/qgis-developer/2018-April/052976.html <https://lists.osgeo.org/pipermail/qgis-developer/2018-April/052976.html>
> 
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-psc

—

Tim Sutton

Co-founder: Kartoza
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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20180413/b629c6d6/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/20180413/b629c6d6/attachment.jpg>