-
Notifications
You must be signed in to change notification settings - Fork 4
GSIP 25 New Documentation Framework
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.
Mike Pumphrey Justin Deoliveira Ivan Willig
1.7.x
Accepted
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: {quote} 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! {quote}
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:
- 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.
Please enter in any any comments and suggestions.
Andrea Aime: +1 Alessio Fabiani: +1 Justin Deoliveira: +1 Simone Giannecchini: +1 Jody Garnett: Rob Atkinson: