[Qgis-psc] Sponsorship for improving the Python documentation of QGIS

[Tim Sutton]

Hi All

Please see below my draft message to send to the dev list and post as an
article on our blog. Can someone remind me on what the amount is that we
will commit for this?

--------------------

Dear QGIS Developers

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. Here, briefly, is
the vision:

Lets take our inspiration from Qt. As a foundational library for QGIS, I
have always loved the fact that Qt4 is so well documented. Take a look at
this for example - http://doc.qt.io/qt-4.8/qlabel.html#details

The Qt4 documentation provides a readable narrative explaining the purpose
(with images and illustrations if needed) of each class. It also provides a
code snippet, which in many cases you can simply cut and paste into your
code and then tweak to get started.

As a PyQGIS programmer you have two main resources: The QGIS Python
cookbook and the QGIS C++ API documentation. The cookbook is an excellent
resource, but it is hard to keep it synchronised with the code base - so
examples often run the risk of being out of date, or don't leverage new
functionality that makes its way into the code base. The C++ documentation
is good in terms of coverage, but it often lacks detail and as a python
programmer you may find it a bit off putting since the text is littered
with examples using pointers. Also, the C++ documentation isn't always a
one to one match for python users, and doesn't explain python specific
behaviour such as how ownership is passed around with returning objects.

Wouldn't it be nice if the C++ API documentation also included the content
that is in the python cookbook? And wouldn't it be nice if the C++
documentation became the C++ *and* Python API documentation - catering for
users of both programming languages and providing for a single point of
reference and maintenance? Even better the python documentation would live
right in the C++ code, so that anytime someone touches the code base they
can easily maintain the documentation without needing to jump through a lot
of hoops.

For this funded effort we are thus seeking one or more individuals to lay
the foundation for this work:

* establish norms and guidelines for improving the doxygen API docs so that
each documented resource can include both python and C++ documentation.
* port the cookbook content over to the API documentation
* create doxygen pages to provide a starting point for python programmers
to be able to carry out common activities they need
* populate the API docs with Python examples and improved descriptions
* do these in a nice clear and concise writing style, again taking
inspiration from the fine work that Qt has done
* perhaps do something really smart to generate docs from the SIP API and
incorporate it into our doxygen doctree?

If you think this is something you are able to do, please contact the QGIS
PSC using this form and let us know!

http://goo.gl/forms/WRGSvWHkBb

----------------------------


Any comments?

Regards

Tim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20150817/8ad3cbc8/attachment.html>