PyQGIS Developer Cookbook update and maintenance

Date 2016/09/15
Author Germán Carrillo (@gacarrillor)
Contact carrillo.german at gmail dot com
Maintainer @gacarrillor
Version QGIS 2.16.x and QGIS 3.0

Proposal details

The PyQGIS Cookbook is a very important document for both new PyQGIS users and developers. However, it is not rare to read in forums or other community websites that something could not be found in the PyQGIS Cookbook or that a code snippet taken from there does not work. It can be because the user has no previous experience with Python and cannot resolve basic error messages, but it can also be due to lack of maintenance of the code snippets.

I work with PyQGIS almost on a daily basis, which has allowed me to realize that there are confusing parts in the Python API. Things that simply do not work, things that do not work as expected, as documentation states, etc. Just to name some topics that could get into the PyQGIS Cookbook: how to run QGIS Processing algorithms from standalone PyQGIS scripts (I consider this to be very useful), a more detailed Function Editor explanation and examples, and how to access and make use of plugins' methods from the PyQGIS console.

One example of user misunderstanding is how to run a standalone PyQGIS script on Windows, which is in fact covered, but not clear enough for people learning PyQGIS because we still find questions about it. I think "Hello World!" examples need to be given to users, and such initial step should not represent an obstacle for them but an invitation to keep learning.

I am particularly interested in helping people to get started with PyQGIS, I would like to show new users/devs how simple scripts can make a difference in their workflows or in the QGIS GUI itself. Nonetheless, I can also understand and make improvements to more complex PyQGIS uses. For instance, I have answered questions related to QGIS-Processing that cannot be found in documentation, but require reading QGIS Processing code structure.

I propose to:

• Check every code snippet and, if necessary, make changes to it, e.g., remove deprecated function calls, add comments, add alternatives, among others.
• Check every code snippet and notify QGIS devs (via issue tracker, mailing list, Gitter, etc.) and/or GeoAPI maintainers (direct e-mail) about any issue I find (e.g., non-working method, missing classes/functions, and the like).
• Present self-contained (ready to run) code examples. I think there could be a collapsible button (collapsed by default) that displays fully working code (with necessary imports, variable definitions, using perhaps its own memory layers, etc.). As an alternative, we could just show a link to a Gist page, to a file in a GitHub repository, or any other platform you consider. In principle, there would not be a self-contained code example for each code snippet, but I could aim to have one or two per section.
• Find a place for and document 20 (to say something) of the most-voted PyQGIS answers on GIS.SE (or the ones that QGIS community considers) into the PyQGIS Cookbook.
• Find a place for and document 5 (to say something) blog posts from QGIS devs into the PyQGIS Cookbook (QGIS devs could point me to those resources).
• Complete Spanish translation of the PyQGIS Cookbook (for QGIS v.2.x).
• Keep an eye on API changes for QGIS 3.0 and replace/adjust code snippets with the new Python API.

It is unknown to me how different PyQGIS Cookbook versions are managed. I can maintain:

1. A master version (pointing towards QGIS 3.0), and
2. A '2.x' version that you choose between the latest 2.x release (e.g., 2.16.x) or the latest LTR (2.14.x).

I'm aware of the API Documentation Guidelines QEP by Martin Dobias, which I find both necessary and complementary. Even though code snippets would be added to the API docs (according to that QEP), I still think the PyQGIS Cookbook is the documentation resource new users will want to read when starting to learn PyQGIS, and sooner or later will be guided (e.g., by the PyQGIS Cookbook itself) to the API docs.

I am open to discuss about the scope of this proposal. If it is selected, I would like to get feedback about it before starting to work.

What is your implementation schedule / plan?

• Mid-October to mid-December (2 months):

  • PyQGIS Cookbook for QGIS v2.x (you would choose between QGIS 2.16.x or 2.14.x):
    • Reviewed.
    • Updated.
    • With self contained code examples.
    • With the chosen 20 code snippets from GIS.SE included.
    • With the chosen 5 blog posts included.
    • Translated into Spanish.

• January, February, and March (3 months):

  • PyQGIS Cookbook for QGIS v3.0.
  • Sections and code snippets updated.

Notes:

• I would expect to stop working on the 2.x version by mid-December and start working on the 3.0 (master branch) in January.
• If, for any reason, anything cannot be added to PyQGIS Cookbook for QGIS v.3.0, I will leave a list of missing things, so that after the grant programme, the community (and I'm there) can complete it.
• I would not expect to translate PyQGIS Cookbook for QGIS 3.0 because I will be focused on covering the new API.

How am I qualified to do this?

I hold a MSc. in Geoinformatics from the University of Münster (Germany), I'm a QGIS contributor (due to bug fixes sent years ago as C++ patches), I'm an active member of GIS StackExchange, particularily in PyQGIS-related questions, I'm one of the administrators of GeoTux (a website to promote and share knowledge on FOSS4G), I'm the author of four QGIS plugins and have contributed to QGIS WPS and Simplipy plugins. I enjoy helping people to discover how powerful PyQGIS is (and have the patience for that), I enjoy sharing my work with the community, I enjoy learning from other people's code (even if it's C++ code). I once even met QGIS core devs at the Linux Hotel in Essen, 2012 (unfortunately couldn't met Martin nor Anita there). I use QGIS every time I can, even as a platform for a couple of experiments. And finally, and most important, I would love to work for QGIS!