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

[Andreas Neumann]

Hi Tim,

In the budget we have 2500 Euro allocated for API documentation - see 
https://docs.google.com/spreadsheets/d/197JVYgDqkKOAGy_zmxL25Lk4ntjJJLmEGQ6MuCmBjnE/edit#gid=0

However - we can be a bit flexible - if we require a bit more. I'd say 
at the very maximum up to 4000.

Andreas

On 17.08.2015 11:45, Tim Sutton wrote:
> 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
>
>
>
>
> _______________________________________________
> Qgis-psc mailing list
> Qgis-psc at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-psc

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