Hi folks, thanks for your feedback. There is a maven plugin being used which I linked to in the original email.
The patch is up for review in FLUME-1242 and I would like to check this in unless there are any major issues with it. Thanks, Mike On Thursday, May 31, 2012 at 3:19 PM, Arun C Murthy wrote: > On May 31, 2012, at 3:08 PM, Will McQueen wrote: > > > I think one argument I heard once against APT is that it doesn't have a way > > to embed images. Is that your understanding to? > > Not true. > > Hadoop moved to apt and although, I'm not thrilled with apt, it's not that > bad: > > http://hadoop.apache.org/common/docs/r2.0.0-alpha/hadoop-yarn/hadoop-yarn-site/YARN.html > > Arun > > > Cheers, > > Will > > > > On May 31, 2012, at 3:02 PM, Eric Sammer <[email protected] > > (mailto:[email protected])> wrote: > > > > > I'm in favor of something that mvn can generate. There's APT and Velocity > > > based templates. This is not in opposition to Mike's suggestions, just > > > that > > > I *really* like the idea of generated docs (javadoc, dep tree stuff, rat, > > > etc.) being first class citizens. If we can make any of the others play > > > nice as part of the build, I'm happy. > > > > > > On Wed, May 30, 2012 at 11:50 PM, Jarek Jarcec Cecho <[email protected] > > > (mailto:[email protected])>wrote: > > > > > > > Hi Mike, > > > > it seems much more better to me than the original XHTML document. > > > > > > > > Jarcec > > > > > > > > On Wed, May 30, 2012 at 10:46:33PM -0700, Mike Percy wrote: > > > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > -- > > > Eric Sammer > > > twitter: esammer > > > data: www.cloudera.com (http://www.cloudera.com) > > > > > > -- > Arun C. Murthy > Hortonworks Inc. > http://hortonworks.com/
