<div dir="ltr"><div>Dear PSC,</div><div><br></div><div>Finally, I have finalized phase 2 of PyQGIS API docs project.</div><div>It was again a tedious job with again unexpected issues.</div><div><br></div><div>Here is what has been done:</div><div><br></div><div>1) Automatic building of QGIS docker images in Travis</div><div>These are used to later build the PyQGIS doc in another Travis job in QGISPythonAPIDocumentation repo.</div><div><br></div><div>2) Multi-version support</div><div>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].</div><div><br></div><div>3) Support for signal signatures</div><div>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.</div><div><br></div><div>4) Table of contents and grouping</div><div>In previous version, table of content was full of inherited class methods which were not bringing useful info (all methods from Qt parent classes).</div><div>Now, these are removed. </div><div>Moreover, there is a fine tuning in grouping and signals have their own dedicated category.</div><div>These is made possible by using a custom version of autoautosummary [4,5]</div><div><br></div><div>5) Online building of the Python API Docs</div><div>Everything has been setup in Travis to automatically build the docs using QGIS docker image (see pt 1).</div><div>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).</div><div>Hence last published version of the docs has been built on my computer, and server API is missing.</div><div>The logic is ass follows:</div><div>- master docs follows QGIS master branch and is built once a day</div><div>- release versions docs are built using tags on the main repo and hence will strictly correspond to the last point release of each branch</div><div><br></div><div>Original allocated time has again been largely overrun (mainly due to SIP modifications and trying to bring them in the build chain).</div><div>Since I considered signal for signatures was a first priority feature (although not mentionned before Gary's mail [6]), some were again left apart:</div><div>- Adapt sipify to move /Out/ parameters from parameters list to returns group</div><div>- Sipify doc</div><div><br></div><div>I think that the documentation is now in a much more accomplished state.</div><div><br></div><div>As far as I see it, here are the main remaining issues:</div><div><br></div><div>I1) as pointed by Richard [7], we need to fix redirections properly</div><div><br></div><div>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).</div><div><br></div><div>I3) list of parameters still showing output only parameters, and the /Out/ arguments are not mentionned as output. This is a sipify enhancement.</div><div><br></div><div>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).</div><div><br></div><div>I think someone from the PSC holding the info of the provider can easily handle I1.</div><div><br></div><div>I would propose QGIS.org to sponsor a phase 3 for the remaining issues with the following estimate:</div><div>I2) 8h</div><div>I3) 16h</div><div>i4)  24h</div><div><br></div><div>At the usual rate for QGIS.org sponsored project, the proposal is of 6 days.</div><div><br></div><div>Would you like to have this as grant proposal or shall we proceed similarly to the 2 previous phases?</div><div><br></div><div>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.</div><div><br></div><div>And last, but definitely not least, here are the docs!!!!</div><div><a href="http://python.qgis.org/master">http://python.qgis.org/master</a></div><div><br></div><div>Best regards,</div><div>Denis</div><div><br></div><div><br></div><div>[0] <a href="https://github.com/rtfd/sphinx_rtd_theme/pull/574">https://github.com/rtfd/sphinx_rtd_theme/pull/574</a></div><div>[1] <a href="https://github.com/3nids/sphinx_rtd_theme.git">https://github.com/3nids/sphinx_rtd_theme.git</a></div><div>[2] <a href="https://www.riverbankcomputing.com/pipermail/pyqt/2018-February/040036.html">https://www.riverbankcomputing.com/pipermail/pyqt/2018-February/040036.html</a></div><div>[3] <a href="https://www.riverbankcomputing.com/hg/sip/rev/34a94ca0260d">https://www.riverbankcomputing.com/hg/sip/rev/34a94ca0260d</a></div><div>[4] <a href="https://github.com/qgis/QGISPythonAPIDocumentation/blob/master/autoautosummary.py">https://github.com/qgis/QGISPythonAPIDocumentation/blob/master/autoautosummary.py</a></div><div>[5] <a href="https://stackoverflow.com/a/30783465/1548052">https://stackoverflow.com/a/30783465/1548052</a></div><div>[6] <a href="https://lists.osgeo.org/pipermail/qgis-developer/2018-February/052148.html">https://lists.osgeo.org/pipermail/qgis-developer/2018-February/052148.html</a></div><div>[7] <a href="https://lists.osgeo.org/pipermail/qgis-developer/2018-April/052976.html">https://lists.osgeo.org/pipermail/qgis-developer/2018-April/052976.html</a></div><div><br></div></div>