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]>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
