[Proj] proj4.org, documentation, and documentation maintenance
howard at hobu.co
Thu Mar 3 11:56:06 EST 2016
The documentation for the proj.4 project has always been in flux, mostly due to proj.4's shared history as a friendly fork. The current situation is a difficult challenge for users looking for information. There's stuff in PDFs, stuff in two different wikis, and stuff in man pages. All of it can be a little bit different, and users are left to figure out what is the top of the heap on their own.
I know that adding *yet another* website by itself to this mix might not really solve the problem, but I think part of the issue has been that it was difficult to maintain a single, streamlined documentation set. To that end, at the Paris Code Sprint , I implemented a documentation system based on Sphinx , which has stabilized the management of documentation for many other projects in the open source geo space like OpenLayers, MapServer, and GeoTools.
I then adapted work of Even Rouault and Thomas Bonfort from the MapServer project and applied it in proj.4's situation to close the loop on the documentation system. What this means is every pull request that updates documentation will cause the website to be regenerated and refreshed (you can even edit on the GitHub website and make a PR if you want). Combined with the Sphinx organization, it will be easier for the proj.4 project to maintain and deliver coherent documentation.
It is my hope that this approach will allow documentation contributions to easily make it to the canonical website, allow the documentation to be organized more thoroughly, and it will allow multiple documentation output types (HTML, PDF, man, etc) to be easily generated from a central documentation set. There is still plenty of work to do, including organizing things, porting over and merging up docs from the various locations, and deciding on possible output types.
PS, are the original Latex files for the various PS/PDF files available somewhere? It would be really nice to port all of that stuff into a single organized documentation set without having to copy/paste out of PDFs.
More information about the Proj