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