[Qgis-psc] PyQgis Cookbook revision

[Alessandro Pasotti]

On Sun, Mar 1, 2020 at 1:13 PM Paolo Cavallini <cavallini at faunalia.it> wrote:
>
> Hi Harrissou,
> I think everybody agrees in improving documentation, both for devs and
> for users. Could you ask the proponents to put a formal proposal for
> funding?

The proponents is me, here is my proposal about the cookbook contents
revision (basically copied from my original email):

make a revision of the current cookbook text and code snippets in order to:
- update the text and the code snippets
- put ALL code snippets under the existing automated Python test CI
infrastructure.

The current situation (well, current when I wrote the original email
but I don't think it has changed):

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

My plan is:
1. check all the cookbook text for 3.10 (or whatever the LTR will be
when I will do the work) 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.

Total time required: 5 days at the standard QGIS hourly rate.

Note that in the original thread was discussed to move the cookbook
outside of the documentation, but that task is completely independent
from the text and code revision and it is not included in my proposal.

Regards.

--
Alessandro Pasotti
w3:   www.itopen.it