[OSGeo-Discuss] Help authoring tools

[Howard Butler]

On Jun 1, 2010, at 12:34 PM, Stefan Steiniger wrote:
>> On 06/01/2010 10:00 AM, Daniel Ames wrote:
>>> Do any of you have a preferred open source help authoring tool? We're looking for something to document our projects on web pages - something better than wiki - and also to download and install with software. Must be cross platform, etc. I'd like to use whatever others are using in the OSGeo community for consistency... - Dan

Daniel,

MapServer, GeoTools, OpenLayers, GeoServer, Shapely, libLAS, and GeoDjango all use Sphinx <http://sphinx.pocoo.org/>.  In my opinion, Sphinx's great advantages in order of importance are:

- text-like markup (docbook is too much burden on documentation writers).  Restructured text is not too difficult to learn, but I wish the world would agree on a text-like markup (markdown, restructured text, wikitext, etc)
- variety of output.  Besides html, you can do ePub, PDF (multiple ways -- via latex or stand alone), windows compiled help, qthelp, man
- pretty output
- simple installation and management

I know there are some sphinx skeptics from the MapServer project on this list who might chime up one way or another about its level of success within the MapServer project, but I think its implementation has help our project immensely.  

GDAL is still using Doxygen for its documentation generation.

Howard