Hi all, At the risk of overly spamming the dev list with JIRA and Reviewboard traffic, I wanted to bring up the issue of Flume documentation.
Right now, the Flume user guides are checked in as XHTML here: https://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-doc/xhtml/ That XHTML source is not great from a maintainability perspective because it was originally exported from some other format. The other end of the spectrum is ReStructuredText, which was designed to be readable in source form as well as easily convertible to other formats. There is an RST rendering engine called Sphinx <http://sphinx.pocoo.org/contents.html> which is BSD-licensed (written in Python) that has a maven plugin <https://github.com/tomdz/sphinx-maven> which is also BSD-licensed. The Maven plugin uses Jython to run the thing. Some sites have really nice documentation written using Sphinx including Bazaar <http://doc.bazaar.canonical.com/bzr.2.5/en/> and Celery <http://celery.readthedocs.org/en/latest/>. Over the past couple of weeks, I've been playing with Sphinx off and on. I finally got to the point that I thought it would work for our use case so I went ahead and converted the docs from XHTML to RST (using a variety of tools and scripts, as well as some hand editing). While the current Sphinx theme could use some stylistic love, I think it's a huge improvement in terms of ongoing maintenance of the docs. You can see the results here: https://people.apache.org/~mpercy/flume/flume-1.2.0-incubating-SNAPSHOT/docs/ Here is what the source code for the User Guide looks like (as an example): https://people.apache.org/~mpercy/flume/flume-1.2.0-incubating-SNAPSHOT/docs/_sources/FlumeUserGuide.txt The related JIRA is here: https://issues.apache.org/jira/browse/FLUME-1242 (review board patch is linked from the JIRA). I hope that others in the community will agree that this is an improvement. :) Would like to hear your thoughts. Best, Mike
