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

[Denis Rouzaud]

Dear PSC,

A small mail to announce that phase 3 of the PyQGIS API doc has reached its
goal.
Mainly, the docs are automatically build and published on Travis using the
docker images also built on Travis.
Former sub-categories has been removed and all classes lie in their package
(core/gui/server/analysis).
The docs are pushed daily for master: https://qgis.org/pyqgis/master

Best wishes to you all,

Denis

Le jeu. 12 avr. 2018 à 11:20, Denis Rouzaud <denis.rouzaud at gmail.com> 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
>
> --

Denis Rouzaud
denis at opengis.ch  <denis at opengis.ch>
+41 76 370 21 22
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20181219/d4be0165/attachment.html>