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

[Régis Haubourg]

Hi Denis, 

that's an awesome work you have been doing here. Congratulations for that, I imagine patching SIP was not expected at
start!

About the sponsoring part to have it fully completed, that would be a +1 for me if we vote. 
A good python documentation is a real priority and a something constantly raised in training sessions. 

Regards

RégisLe jeudi 12 avril 2018 à 15:20 +0000, Denis Rouzaud a écrit :
> 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
> 
> Best regards,
> Denis
> 
> 
> [0] https://github.com/rtfd/sphinx_rtd_theme/pull/574
> [1] https://github.com/3nids/sphinx_rtd_theme.git
> [2] https://www.riverbankcomputing.com/pipermail/pyqt/2018-February/040036.html
> [3] https://www.riverbankcomputing.com/hg/sip/rev/34a94ca0260d
> [4] https://github.com/qgis/QGISPythonAPIDocumentation/blob/master/autoautosummary.py
> [5] https://stackoverflow.com/a/30783465/1548052
> [6] https://lists.osgeo.org/pipermail/qgis-developer/2018-February/052148.html
> [7] 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