GSIP 25 - New Documentation Framework

Formalizing GeoServer documentation process and tools

Overview

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.

Proposed By

Mike Pumphrey
Justin Deoliveira
Ivan Willig

Assigned to Release

1.7.x

State

Accepted

Motivation

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:

Page Hierarchies

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.

Versioning

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.

Proposal

Sphinx

Sphinx is a nice documentation tool which addresses many of the limitations presented above. From the site:

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created to translate the new Python documentation, and it has excellent support for the documentation of Python projects, but other documents can be written with it too. Of course, this site is also created from reStructuredText sources using Sphinx!

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.

Version Control

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.

Confluence Wiki

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:

  • Community contributed documentation
  • GeoServer improvement proposals
  • R&D pages

And more. Basically the plan is to have all "manual" like documentation managed with Sphinx. This includes the user guide and the developer guide.

Feedback

Please enter in any any comments and suggestions.

Backwards Compatibility

Voting

Andrea Aime: +1
Alessio Fabiani: +1
Justin Deoliveira: +1
Simone Giannecchini: +1
[~jgarnett]:
[~roba]:

Added by Mike Pumphrey, last edited by Ben Caradoc-Davies on Jun 05, 2009  (view change) show comment
View Attachments (0) Info