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

Wed Dec 19 13:35:02 PST 2018

Hi

Nice stuff!
Regards

Tim

On Wed, Dec 19, 2018 at 7:30 PM Denis Rouzaud <denis.rouzaud at gmail.com>
wrote:

> 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
>
>
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-psc

-- 
------------------------------------------------------------------------------------------

Tim Sutton
Visit 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
Tim is a member of the QGIS Project Steering Committee
-------------------------------------------------------------------------------------------
Kartoza is a merger between Linfiniti and Afrispatial
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20181219/d10e88d5/attachment.html>