[GRASS-dev] proposal: new documentation for 7.x branch

[Markus Neteler]

On Tue, Feb 17, 2009 at 7:38 PM, Patton, Eric
<Eric.Patton at nrcan-rncan.gc.ca> wrote:
>>recently, I found Sphinx tool [1], which makes it really easy to
>>generate documentation for projects. I tried it on PyWPS project's home
>>page [2] and also, I created some Czech tutorial of GRASS with it [3]. I
>>have to say, I felt in love with this tool.
>>
>>I tried to prepare some *very* demo of possible GRASS GIS Documentation
>>system. [4][5]
>>
>>Why to move to Sphinx:
>>+ searchable documentation
>>+ easy for user usage - links to index page from everywhere,
>>indexes, ...
>>+ easy for developers - the reStructuredText[6] is really easy to use
>>+ migration should be relatively easy (script based)
>>+ all tutorial could have similar look&feel
>>----
>>+ I like the sphinx look & feel
>>
>>Why not to move to sphinx:
>>- never touch running system


Here recent Mapserver discussion about this, including
suggestions for manual translation (we are receiving
translated manual pages now but cannot handle them yet!):

http://lists.osgeo.org/pipermail/mapserver-dev/2009-April/008603.html

> I recall there was a discussion about possibly moving to a different system for the GRASS documentation pages about a year or so ago, but I can't seem to find the thread in the ML. The gist of it seemed to be that we should maintain the status quo because html was simple, well-known, easy to learn, and was already up and running.

I think that if we can obtain Sphinx'ed documentation from the
existing files - fine.


A conversion script could mean html to clean but that should not
harm (indeed, it's needed). This is a perfect power user task :)

Here the HTML to reST script (which is the Sphynx input):
http://sphinx.pocoo.org/intro.html
-> Conversion from other systems
     -> Gerard Flanagan...

Markus

from Jachym's email:
[1] http://sphinx.pocoo.org/
[2] http://pywps.wald.intevation.org/
[3] http://les-ej.cz/skoleni/grass/
[4] http://les-ejk.cz/tmp/grass-doc.tgz
[5] http://les-ejk.cz/tmp/grass/build/
[6] http://docutils.sourceforge.net/rst.html