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