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?
Cheers, Will On May 31, 2012, at 3:02 PM, Eric Sammer <[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]>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
