Call for applications: QGIS API Documentation Improvement

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Call for applications: QGIS API Documentation Improvement

Tim Sutton-5
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.



Regards

Tim



Tim Sutton
QGIS Project Steering Committee Member





_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

Alessandro Pasotti-2
2015-08-18 23:19 GMT+02:00 Tim Sutton <[hidden email]>:
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.



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
--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

ginetto
cut&paste error

this link
> http://tinyurl.com/okburu3

probably was:
https://docs.djangoproject.com/en/1.8/internals/contributing/writing-code/submitting-patches/#patch-review-checklist

regards,
Luigi Pirelli

**************************************************************************************************
* LinkedIn: https://www.linkedin.com/in/luigipirelli
* Elance: https://www.elance.com/s/edit/luigipirelli/
* GitHub: https://github.com/luipir
* Stackexchange: http://gis.stackexchange.com/users/19667/luigi-pirelli
* Mastering QGIS:
https://www.packtpub.com/application-development/mastering-qgis
**************************************************************************************************
_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

Alessandro Pasotti-2
2015-08-19 12:05 GMT+02:00 Luigi Pirelli <[hidden email]>:
cut&paste error

this link
> http://tinyurl.com/okburu3

probably was:
https://docs.djangoproject.com/en/1.8/internals/contributing/writing-code/submitting-patches/#patch-review-checklist

 

Sorry..
 
Thanks Luigi for signaling the error!


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

Tim Sutton-5
In reply to this post by Alessandro Pasotti-2
Hi Ale
On 19 Aug 2015, at 09:41, Alessandro Pasotti <[hidden email]> wrote:

2015-08-18 23:19 GMT+02:00 Tim Sutton <[hidden email]>:
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.



Regards

Tim



Hi Tim,

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

Yes it does!


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.




I also really like the cookbook, though I worry about the maintenance of it - if we can do the tests in ret to make sure that it remains current that would be one good motivation for keeping it current. An alternative approach would be to move the content of the cookbook into doxygen documentation (you can add arbitrary pages there - they don’t all need to be generated from header files. 

But let me rather step back and say that my intention in the proposal was more that we sponsor someone to really look into these things and come up with a well established standard - something like the django folks have done in your link below. We obviously don’t currently have funding for a complete revision of every single source file, but I think if the person we hire can establish a good working system, it will be easier to point others to when they submit patches, telling them ‘we need docs with that!’ - and pointing the to examples and instructions on how to document their code nicely.

Regards

Tim

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
--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer



Tim Sutton
QGIS Project Steering Committee Member





_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

Alessandro Pasotti-2
2015-08-19 21:38 GMT+02:00 Tim Sutton <[hidden email]>:
Hi Ale
On 19 Aug 2015, at 09:41, Alessandro Pasotti <[hidden email]> wrote:

2015-08-18 23:19 GMT+02:00 Tim Sutton <[hidden email]>:
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.



Regards

Tim



Hi Tim,

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

Yes it does!


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.




I also really like the cookbook, though I worry about the maintenance of it - if we can do the tests in ret to make sure that it remains current that would be one good motivation for keeping it current. An alternative approach would be to move the content of the cookbook into doxygen documentation (you can add arbitrary pages there - they don’t all need to be generated from header files.
 

But let me rather step back and say that my intention in the proposal was more that we sponsor someone to really look into these things and come up with a well established standard - something like the django folks have done in your link below. We obviously don’t currently have funding for a complete revision of every single source file, but I think if the person we hire can establish a good working system, it will be easier to point others to when they submit patches, telling them ‘we need docs with that!’ - and pointing the to examples and instructions on how to document their code nicely.


Ok, agreed.

The Django folks are very picky about "Have documentation" and "Have tests" before accepting any patch, and the documentation always have examples.

Doxygen also accepts RST and we could place python documentation into .sip  files, maybe a solution would be to include snippets and examples from doxygen (.sip is preferred) into the cookbook, leaving the introductory material in the cookbook itself interleaved with included examples and snippets.

I don't know about QT but most of the (not API) documentation I've seen is made with sphinx, I might be wrong (maybe is just that I know sphinx better than doxygen) but I suspect that moving the whole cookbook into doxygen and outside from the rest of the documentation (user manual, tutorial etc.) is not a good idea.


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer
Reply | Threaded
Open this post in threaded view
|

Re: Call for applications: QGIS API Documentation Improvement

Jürgen E. Fischer
Hi Ale,

On Thu, 20. Aug 2015 at 11:42:06 +0200, Alessandro Pasotti wrote:
> Doxygen also accepts RST and we could place python documentation into .sip
> files, maybe a solution would be to include snippets and examples from
> doxygen (.sip is preferred) into the cookbook, leaving the introductory
> material in the cookbook itself interleaved with included examples and
> snippets.

The .sip are maintained by comparing them with the header files
(scripts/sipdiff).  So IMHO they should be kept as close to them as possible -
at least in the section with the actual interfaces.  

But more verbose sections above or below the actual code shouldn't be a problem
(that part is mostly not in synced anyway).


Jürgen

--
Jürgen E. Fischer           norBIT GmbH             Tel. +49-4931-918175-31
Dipl.-Inf. (FH)             Rheinstraße 13          Fax. +49-4931-918175-50
Software Engineer           D-26506 Norden             http://www.norbit.de
QGIS release manager (PSC)  Germany                    IRC: jef on FreeNode                        

_______________________________________________
Qgis-developer mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/qgis-developer

signature.asc (844 bytes) Download Attachment