Another quick question about advantages / disadvantages about Sphinx. Is there a possibility for a spell check ?.
For the rest of the arguments, I agree to Andrea. One of the most import things is to have the documentation in sync with the source code. And for the WYSIWYG freaks, the following procedure works fine. 1) Open an editor and work on the rst file 2) Open a cmd line and change to the doc directory 3) Open a browser on result html The turn around is Edit the rst file, save it, invoke "make html", refresh the open browser and see the result. For me, the question is simple and the answer is "use sphinx" Andrea Aime writes: > 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 ------------------------------------------------------------------------------ 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
