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

[Patton, Eric]

>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

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 would argue that the documents already do have a pretty consistent look and feel. That being said, I will admit that the mock ups you created look pretty nice. Another issue to consider in changing is that the html pages might require quite a bit of cleaning and pruning in order to be consistent enough to mash through a conversion script - and that could mean a lot of html to clean.

I feel a more pressing need is that the existing documentation needs improvement more in the area of additional examples where there are none, or more expanded examples for different module flags and parameters. I have been trying to do this as my work schedule allows, but it has been difficult as of late. 

I would welcome feedback and comments from others on the list, maybe I'm off the mark.

~ Eric.