[Qgis-psc] Python cookbook revision final report
apasotti at gmail.com
Mon Apr 6 05:59:08 PDT 2020
first of all I would like to thank you all and all the QGIS sponsors
and donors together with the documentation team for making this review
process possible. I also wish to thank Martin Dobias for his help in
spotting out an issue in one snippet with Plugin Layers
To be completely honest, this task took me quite a bit more time than
planned, so consider the additional time that I spent on it as a
voluntary contribution by me (or QCooperative as you prefer :)
As it was initially planned I was able to review all the code snippets
in the cookbook and to put them under automated test in CI.
Before I started there were 62 tests over ~300 code snippets, we are
now at 303 tested snippets (302 on 3.10). Despite my efforts (where I
probably lost most of my time) I had to skip a handful of snippets
that were running perfectly well when tested manually but failing on
the doctest CI process:
- task manager tests (1 out of 3 on master, 2 out of 3 on 3.10)
- all standalone application tests (because the mocked application is
already started globally and it cannot be re-initialized)
Note that for a few of the most complex snippets the test coverage is
not 100% because the test does not really cover all execution paths.
I didn't have time to go through a reorganization of the text contents
but I did quickly read all the texts and I made some small
modifications to update the contents where the API had substantially
changed from the original texts.
A few snippets had to be updated because of changes in the QGIS API or
because of the deprecation of a the methods, CRS handling in
particular due to the proj6 switch, but there were also other places
where I had to make small changes.
I've found just 1 syntax error in the whole code!
The changes have been backported to the 3.10 branch.
Last but not least, I couldn't resist to add a few sections and to do
an more in-depth review of the server Python cookbook section, I
reorganized the material about plugins and I added snippets and short
introductory texts about the new modules and OGC APIs architecture.
A final personal consideration:
I think that the cookbook is a great source of information, not only
for PyQgis begginers or plugin developers but also for C++ developers:
it contains a lot of information about the internals of the QGIS API
that you cannot really find anywhere else.
It could probably benefit from a reorganization of a few sections but
it is already a great resource as it is.
More information about the Qgis-psc