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

[Denis Rouzaud]

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