[Geoprisma-dev] Documentation : wiki or sphinx ?

[Yves Moisan]

Le mardi 10 novembre 2009 à 10:05 -0500, Alexandre Dube a écrit :
> Hi devs,
> 
>   I'm currently writing some doc that can be classified as "general 
> doc".  With the our new trac now available, I was wondering if I should 
> use the wiki to store this new documentation ( like OpenLayers [1] ) or 
> should I use Sphinx ?

Well OpenLayers does both :-).  Here's the Sphinx docs :
http://docs.openlayers.org/

About a year ago, Chris moved the OL docs away from the wiki to Sphinx
(http://www.mail-archive.com/dev@openlayers.org/msg03422.html).  

> 
>   Since not much seems to be currently in Sphinx right now, could we 
> consider using the wiki instead ?  Would it be better  / easier ?  What 
> are the pros/cons of each solutions ?  Please, I'd like to know your 
> thoughts about that.

IMO, styling (and eventually generating a PDF or LaTeX doc) is the key
"plus" for Sphinx.  Styling can be done with templating (Jinja).  We
barely scratched the styling possibilities of Sphinx.  Wiki styling,
well we pretty much know its limits ...  

I'd rather build a nice Sphinx docs and point to it in the wiki (which
I've already done) than start punching in the wiki only to find out
several KB later that we really need a "real" docs generation tool like
Sphinx.  I meant to write a "the files" doc that would server as a
general "what-file-does-what" technical intro to GP.  I hope I can get
around to doing it soon.

The wiki I would use to discuss issues, develop use cases, etc.  I like
Trac a lot better than other SCM tools because of its wiki.  At one
point, when use cases or other Trac doc artifacts are polished enough,
they can make it in the Sphinx docs.

What others say : "Integrated wikis (like Trac) are nice; but I prefer
to keep the documentation together with the source code. Sphinx is
perfect for that. It also looks like a million
bucks." (http://www.proven-corporation.com/2008/03/27/sphinx-templates/)

I haven't found a quote of someone hating Sphinx, but I haven't really
looked for that kind of thing ;-)

HTH,

Yves

> 
> Many thanks,
> 
> [1] http://trac.openlayers.org/wiki/Documentation
>