GeoServer : GSIP 25 - New Documentation Framework
This page last changed on Jun 05, 2009 by bencaradocdavies.
Formalizing GeoServer documentation process and tools
This proposal outlines the use of new tool, Sphinx, and a new process for GeoServer project documentation. Porting the user guide and developer guide from Confluence to straight html built with Sphinx, while continuing to use Confluence for other project documentation.
For most of the life of GeoServer, the Confluence wiki has been used for all project documentation. The user guide is built by simple exporting the entire wiki as HTML.
While Confluence is a great wiki for Java projects, it has various limitations as a documentation tool:
The Hierarchical structure of pages in Confluence has some problems. Child pages are not ordered which makes generating good indexes and table of contents hard. Also every page in a Confluence space is uniquely named which means two pages under different page hierarchies can't have the same name.
While the system supports versioning, reverting to eariler versions and doing diffs is difficult.
And there are various others. To put it simply Confluence was not designed to be a document publishing system.
Sphinx is a nice documentation tool which addresses many of the limitations presented above. From the site:
An example has been put together at http://docs.opengeo.org/docs/geoserver. With sphinx, building documentation is more like building source code. Documentation is checked out of svn, and built using the sphinx tools executed via Makefile.
Being rst based makes documentation easy to version with a standard vcs like subversion. Documentation will be stored parallel to source code in the repository under a doc folder. This means that documentation is stored on a branch by branch basis.
Sphinx is not a wiki system and hence not a replacement for confluence. Confluence will still be used for content appropriate for the wiki. This includes:
And more. Basically the plan is to have all "manual" like documentation managed with Sphinx. This includes the user guide and the developer guide.
Please enter in any any comments and suggestions.
|Document generated by Confluence on May 14, 2014 23:00|