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

[Glynn Clements]

Jachym Cepicky 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
> 
> 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?

I only care about man pages (i.e. nroff). Other formats only matter
insofar as decent man pages can be generated from them.

-- 
Glynn Clements <glynn at gclements.plus.com>