[Qgis-developer] PyQGIS cookbook

[Martin Dobias]

Hi all

I think we are still lacking a comprehensive resource for developers
using Python bindings to develop plugins and/or custom applications.
There are some resources in form of of blog posts and wiki pages, but
they are not well organized and sometimes outdated. Finally, existing
plugins contain a lot of useful (reusable) code, but going through a
plenty of source code of plugins is not a particularly good way to
learn QGIS API.

I've decided to start a PyQGIS cookbook that would introduce various
aspects of QGIS API in form of working code snippets. The cookbook
shouldn't replace the generated Doxygen documentation. Instead of
telling what a class can do, it should be task-oriented, i.e.
answering the questions "how do I?". Ideally, the cookbook should be
both a way how to learn QGIS API and a source of code for those
familiar with it, though not remembering the exact syntax/usage.

After reviewing possible documentation systems, sphinx [1] looked like
a suitable candidate (currently generator for Python documentation
[2]). It has plenty of features and supports various output formats.
It uses reStructured text syntax, which is quite similar to wiki
syntax.

As a start, I've combined Python_Bindings and
Developing_Python_Plugins wiki pages and added some new material, the
working draft is available here:
http://mapserver.sk/~wonder/qgis/html/

It is in early stages and covers only some parts of the API. If the
cookbook will get positive feedback, I'd like to move it to official
QGIS documentation page [3]. The source code for the cookbook could be
put into QGIS svn - either within the source tree or as a separate
branch in svn and the online docs could be regenerated daily as is the
case of Doxygen documentation.

I'd like to ask you for some feedback on the cookbook:
- do you like the idea?
- what parts of API should be documented - what is missing?
- do you know about any resources / useful code snippets that could be
integrated into the cookbook?

Any contributions to the cookbook would be highly welcome. I believe
after some time this could end up as a complete guide for all common
needs.

Regards
Martin

[1] http://sphinx.pocoo.org/
[2] http://docs.python.org/
[3] http://doc.qgis.org/