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]> 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 -- Arun C. Murthy Hortonworks Inc. http://hortonworks.com/
