Jody Garnett ha scritto:
> Hi Andrea:
>
> Thanks for setting up the wiki page; if your module is ready meets the
> requirements you can move it over to supported status. I was kind of
> hoping it could be rolled into the existing renderer module - but it
> looks like a plugin is a sensible option in order to control
> dependencies.
Yep. Going forward I would like to split out the SVG handling classes
from the renderer into a plugin as well, the rationale is that the Batik
dependencies are big and now we're forcing them down the throat of
everyone that wants to use the renderer (ok, you can manually exclude
them, but that's tedious).
> My understanding is that once you meet the requirements very little is
> required for the work to be included as a supported module; did you
> want a code review or anything?
I was mostly trying to follow protocol and show respect for
fellow developers (as opposed to go down cowboy way and do my
stuff without telling anyone).
So, I did not ask for a review, but if you want to make one
please do, constructive feedback is always appreciated.
> I am also interested in your experience with the Sphinx documentation;
> our wiki is not really building up additional documentation beyond
> core contributors.
I actually did not contribute that much to the GeoServer Sphinx
documentation so far, so I have little hands on reports to make,
yet for the few things that I've done, I'm happy about it.
If we want to make a pro/cons detail, I would say pros are:
1) plain text format with very light syntax.
E.g., see this source:
http://svn.codehaus.org/geoserver/branches/1.7.x/doc/user/source/data/postgis.rst
and its rendered form:
http://docs.geoserver.org/1.7.4/user/data/postgis.html
2) the sources are kept in svn, so they are at arm length from the
code you're working on
2) the PDF are generated going through Latex, meaning you get
very nice output
3) the documentation is good, and we provided more:
http://sphinx.pocoo.org/contents.html
http://docs.geoserver.org/1.7.x/docguide/
4) Everything runs locally, no long wait for Confluence
to render your stuff, and work on docs even disconnected
from the net, wherever you want
5) There is some pickup for Sphinx around. For example, Bruce
Perens used it to write his one "Python 3 patterns" book:
http://bitbucket.org/BruceEckel/python-3-patterns-idioms/src/
There are a few cons too:
1) you need some foreign tools installed on your machine to
build the docs.
In particular, you need python, python setup-tools,
sphinx itself, and Make to generate the HTML output.
If you want to generate the PDF, you need latex as well.
I know we have working installs of the above on Windows,
Linux and Mac OSX, so it's doable, but certainly odd
when you come from a pure Java background
2) the syntax is minimal, yet it's hard to find editors
that do syntax highlighting for .rst.
For Linux there is vim and I cooked up some modifications
to Gedit. For windows, I know Mike uses Notepad++ but
afaik that has no syntax highlight. There's an older
editor that has support for rst, called Ulipad.
See also this thread:
http://groups.google.com/group/sphinx-dev/browse_thread/thread/ffd99304f4f9903d
3) I don't know if it supports modular documentation
(write per module, aggregate later), but I did not look
very hard.
All in all I like Sphinx better that the other alternatives
I've seen so far, the home page citation:
"Cheers for a great tool that actually makes programmers want to write
documentation!"
is in fact true enough.
I mean, I don't see it as the holy grail, but better than
confluence, it is, imho.
The plan Mike suggested for GeoServer was to have official
documentation in Sphinx, and keep the wiki for user provided
docs instead, for R&D, for proposals and so on.
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.
------------------------------------------------------------------------------
The NEW KODAK i700 Series Scanners deliver under ANY circumstances! Your
production scanning environment may not be a perfect world - but thanks to
Kodak, there's a perfect scanner to get the job done! With the NEW KODAK i700
Series Scanner you'll get full speed at 300 dpi even with all image
processing features enabled. http://p.sf.net/sfu/kodak-com
_______________________________________________
Geotools-devel mailing list
Geotools-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geotools-devel
