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 > > > > >
signature.asc
Description: Digital signature
