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

[Jachym Cepicky]

Hi,

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

How the demo works:
I tried to convert (hand-made) the vectorintro file, as well as v.buffer
documentation. You can see, that there are some internal links in the
file (some references where not found, so there are red-boxes with
errors). Do not try to look after anything else, then vectorintro or
v.buffer, nothing else was done.

What do you think about it?

Jachym

[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
-- 
Jachym Cepicky
e-mail: jachym.cepicky gmail com
URL: http://les-ejk.cz
GPG: http://les-ejk.cz/pgp/JachymCepicky.pgp