[Qgis-developer] Call for applications: QGIS API Documentation Improvement

[Alessandro Pasotti]

2015-08-18 23:19 GMT+02:00 Tim Sutton <tim at qgis.org>:

> Hi all
>
> In the last few years we have been steadily improving the amount of
> funding we are able to accumulate in the QGIS project. Our goal in
> obtaining funding is always to 'make QGIS better'. Up until now we have
> focussed funding on high profile aspects of the project: Funding regular
> hackfests, paying for bug fixing work prior to releases, funding
> infrastructure such as servers, domain name registrations etc.
>
> With improved funding levels we now have the opportunity to also start
> addressing some of the many less obvious components of QGIS that badly need
> attention, but often don't attract volunteers. In our July 2015 PSC meeting
> it was agreed that we would start this initiative by funding one or more
> developers to improve the python documentation in QGIS. If you are
> interested in working on this, please be so kind as to visit the form [1]
> that we have set up for this.
>
>
> [1] http://goo.gl/forms/WRGSvWHkBb
>
> Regards
>
> Tim
>
>

Hi Tim,

Thank you for writing this proposal:  QGIS developer documentation really
needs some more love :)

While reading the form, I noticed that one of the goals is

* port the cookbook content over to the API documentation

Does this mean the end of the cookbook? I hope not!

IMHO the purpose of the cookbook is not to be a full API reference but a
collection of small tutorials (recipes), with some introductory material.

I've spent quite some time lately trying to update the cookbook by
proofreading and testing the examplesand adding new recipes and I think
that the cookbook is an invaluable source of informations for PyQGIS
programmers, the biggest problem is that it is not routinely updated when
the underlying API changes, for instance there are no recipes for
QgsMapSettings or QgsMapRendererCustomPainterJob and a few examples use
deprecated methods.

I liked a lot the idea we discussed in Denmark about adding tests directly
in the rst sphynx code, this would be a nice improvement for the code
examples and snippets.

I think that the cookbook must continue to exist, it would be awesome if
the process of writing code examples could be automated to transfer them to
the cookbook, adding the snippets to travis would be a nice start but we
all should definitely dedicate more resources for keeping the cookbook in
sync with the source code changes.

Generally speaking I like a lot how the Django project team handles their
(very high quality) documentation [1],  the policy is also a bit strict but
definitely worth reading [2]:

Long live the cookbook :)


https://docs.djangoproject.com/en/1.8/
*http://tinyurl.com/okburu3 <http://tinyurl.com/okburu3>*
-- 
Alessandro Pasotti
w3:   www.itopen.it
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20150819/c5e7b425/attachment.html>