Hi Ralph, I wasn't aware of that but thanks for letting me know. For now, I just wanted to provide example output for people to see without having to apply the patch and build the site.
Mike On Wednesday, May 30, 2012 at 10:29 PM, Ralph Goers wrote: > As you may or may not know, infra has mandated that all projects switch to > using the Apache CMS by the end of the year (vs the old mechanism of > publishing to p.a.o). The CMS system does provide support for sites built > with Maven so the mechanism you are looking at might work depending on how > complicated the site gets. > > Ralph > > > On May 30, 2012, at 5:38 PM, Mike Percy 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 >
