Thanks, Mike. This ties-in with Juhani's comment from the "Expanding contributors to Flume" thread 2 days ago:
>>One thing that could be good is having more documentation on developing plugins, >>as well as encouraging contribution of such plugins to get people involved? I believe this doc format change would make it easier for the community to provide doc patch contributions. Cheers, Will On Wed, May 30, 2012 at 5:38 PM, Mike Percy <[email protected]> wrote: > 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 > > >
