FWIW, I added the aggregate javadocs and each project should now have a findbugs report in addition to the RAT report. Unfortunately, several of the findbugs reports aren't empty.
Ralph On Jun 19, 2012, at 1:09 AM, Ralph Goers wrote: > The issue with Sphinx appears to be that it is creating a new Python > environment in every module. This is in service to generate exactly 2 > documentation files. > > As far as I know xdoc is more powerful than APT and is the format I've always > used. However, Maven supports quiet a few template formats - > http://maven.apache.org/doxia/modules/index.html. > > From what I could see RST is very similar to APT. I only converted the RST to > xdoc because a) I'm quite familiar with it and b) I found a tool to convert > it from RST to xdoc so I didn't need to do much. > > The problem with Sphinx is that when it builds the user guide and dev guide > it isn't integrated with the rest of the documentation built by the site > plugin - assuming you want a multi-module site as I've done in flume-1262. > If you don't want a multi-module site then I would suggest not using Maven to > build the site at all. We are mandated to start using the Apache CMS by the > end of the year. Using the site I've built will require updating it with the > maven-scm-publish-plugin - > http://maven.apache.org/sandbox/plugins/asf-svnpubsub-plugin/, which is going > to be somewhat painful. If all you have are a bunch of static pages and > don't really want the maven generated reports then the CMS is a much better > way to go as you can directly edit the pages there. > > As for flume-1262, the only way for you to understand what a multi-module > site would look like was to build it and then let you take a look. To do > that check out the branch and then run > > mvn site > mvn site:deploy -DsiteUrlDeployment=file:///Users/xxxx/flume > > where xxxx is your userid. Then browse to ~/flume/index.html to see the site. > Note that it isn't actually generating many reports right now. Normally each > project would include findbugs, pmd, clover or cobertura, etc, although some > of these may also be on a CI server. > > Ralph > > > On Jun 19, 2012, at 12:32 AM, Mike Percy wrote: > >> Hi Devs, >> I noticed the work going on in branch "flume-1262", which appears to involve >> porting the existing RST docs to xdoc. I guess this is in response to a >> couple of concerns some people have raised: (1) Maven 2 isn't compatible >> with the way Sphinx is integrated with the build currently >> <https://issues.apache.org/jira/browse/FLUME-1282>, and (2) it appears that >> invoking Jython to run Sphinx takes more than the default amount of memory >> allocated to Maven (requires setting MAVEN_OPTS to increase the memory for >> the build) <https://issues.apache.org/jira/browse/FLUME-1256>. >> >> Since these issues have clear workarounds, I haven't set aside the time to >> try to fix them myself. However, I thought it might be a good idea to >> discuss openly on the dev list whether switching to another format makes >> sense (and if so, which one). It seems that xdoc was mostly replaced by APT >> (almost plain text) in Maven 2 (according to >> https://maven.apache.org/doxia/references/xdoc-format.html ). I wonder if >> there is a reason why Maven rewrote all their documentation in APT. >> >> While I'm sure RST and Jythonized Sphinx have some drawbacks, they also have >> the following benefits: >> - RST is meant to be very readable in source form >> - Even tables are readable in source form and are easy to maintain >> - Sphinx is skinnable / themeable and widely used in Python land >> - Can output to HTML and PDF >> >> I'm certainly not against moving to something else, but it might be a good >> idea to get consensus on a direction before going and independently >> reformatting all the documentation. Since the existing docs are already >> editable by the community, and people have been submitting patches to them >> (while the previous HTML was totally unmaintainable), let's make sure we end >> up with something better if we decide to replace it. >> >> Regards, >> Mike >> >> >
