[Qgis-psc] PyQgis Cookbook revision

[ElPaso]

Il 19/03/20 10:39, Richard Duivenvoorde ha scritto:
> On 3/19/20 10:34 AM, Alessandro Pasotti wrote:
>> The main goal is to put code snippets under CI test and to make the
>> tests pass, secondary goal it to update the text content to reflect
>> changes in the API when necessary.
> Hi Alessandro, just to be sure: If I'm correct the code snippets are
> already under CI test now isn't it?


Hi Richard,


The CI system to test the snippets is in place (I'm well aware of it and 
I've also recently improved it to make the test ignore the Python 
internal object ID).

But ....

... only a few snippets are under test but the vast majority of the 
snippets are NOT under test, and that is exactly the purpose of my work: 
to put ALL snippets under test so that when some example breaks due to 
API changes we know that it must be fixed.


When I made the proposal, this was my estimate (copy pasting my first 
email):

-----



I've done a quick research, the current cookbook situation appears to be:

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

So, I think that the plan would be to:
1. check all the cookbook text for 3.10 API changes and update it 
accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the 'outofdate' 
directive:

./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to 
achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

So, what I would like to propose is to start with 5 days of work and see 
where we
can get with that, there are probably some APIs that haven't changed much
between releases (authentication is an example).

Btw, when looking at this, I've added this small improvement: 
https://github.com/qgis/QGIS-Documentation/pull/4651 
<https://github.com/qgis/QGIS-Documentation/pull/4651>


-- 
Alessandro Pasotti
w3: www.itopen.it