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
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.
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@gclements.plus.com>
On Tue, Feb 17, 2009 at 7:38 PM, Patton, Eric
<Eric.Patton@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