Having findbugs in the build would be great. I think most people would want the following docs: - Tutorial - Cookbook / examples - Configuration reference - Plugin dev guide
I am sure there is room for more types of docs but I'm unsure what is being achieved by splitting everything up on a per-Maven-module basis (that's what Javadoc is for, right?). In cases like core, configuration, and node - what docs would someone expect from those? Regarding the CMS - I'm not sure we would want this stuff integrated with CMS. We should be able to check in a doc snapshot from the release tarball every time there is a release. CMS is for maintaining content that changes over time. Mike On Tuesday, June 19, 2012 at 1:43 AM, Ralph Goers wrote: > 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 > > >
