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

[Paolo Cavallini]

Thanks a lot Denis!

Il 19 dicembre 2018 18:30:21 CET, Denis Rouzaud <denis.rouzaud at gmail.com> ha scritto:
>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

-- 
Sorry for being short
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20181219/fb5bad26/attachment.html>