I have played with maven 1.0 and its xdoc plugin seems to provide decent value. I think the entire EMMA web site can eventually migrate to be maven-built. There is some ugliness in adding custom nav bar menu items in maven, but it's tolerable compared to my homegrown frameset/perl solution. (I have also looked into SF's docman but it seem inadequate for all but simplest doc needs)
xdocs seem fine for simple site content but docbook will remain the solution for user guide/reference manual generation.
It will take some time to migrate the current site body pages to xdocs. To this effect, I will start a new sub-site just for developers only and will start by publishing new docs on branch/trunk maint and EMMA build to get it going.
Finally, my experience so far has been that the doc content get large pretty quickly. I intend to start a new CVS module "docs" for all documentation as opposed to a new dir under "emma". This will include both the reference material and the web site content.
Let me know if you have comments on the direction I am taking.
Let me know if
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The only comment I have is that maven is a horrible tool. My current project has tried to use it, and it was just a mess. I had conversations with the contributors to Maven that made it very clear to me that the maven team didn't really care about backwards compatibility. Build scripts that work with maven 1.0 may not work with maven 2.0 because of how maven interacts with ant. They are completely changing the interaction between the two releases.
Also, maven pretty much requires you to do things its way. For example, in my project, we have our mainline code in one package, say net.rkbloom.javaproject, and the tests in a subpackage named test, net.rkbloom.javaproject.test. The test package is a subdirectory of the javaproject directory. Maven however wants the tests to be in the same package as the code, just in separate directory trees. Regardless of which way is better (and we really don't need to go into it), I want my tools to work for me, I don't want to work for my tools.
Finally, you don't need to use maven to use xdocs. Maven just uses velocity to generate the web site, the exact same effect can be had with pages written in xdocs, and processed using ant or even make to run the velocity tempalte engine over them. This would give you more control on the look and feel of the site. Notice that all maven sites look the exact same, that isn't a coincidence. Maven forces that look and feel on your site. I tried to replace the velocity config and templating files to get a different look and feel, and couldn't figure out how to do it.
If you really want to use xdocs (and I have no problem doing so at all), then please use ant to drive velocity, not maven.
Ryan
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Valid points. I have next to zero maven experience (the company I work for uses a custom uber-build system that has so many enterprise features it is unlikely to be replaced by maven ever), however I have to say that several early posters were very keen on maven, so I am giving in to that pressure.
I knew that maven was unstable. But so is ANT to some extent, even now (the classloading model changed in 1.6 in a way that would break JNDI and a few other things and I had to work around it for EMMA).
I will look at using raw velocity now. I just want a simple means of generating a simple site with a navigation bar and I don't want to change technology here every month. I don't know if navigation.xml is a maven or a velocity thing. Any pointers are welcome (HTML authoring is not my forte).
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I have played with maven 1.0 and its xdoc plugin seems to provide decent value. I think the entire EMMA web site can eventually migrate to be maven-built. There is some ugliness in adding custom nav bar menu items in maven, but it's tolerable compared to my homegrown frameset/perl solution. (I have also looked into SF's docman but it seem inadequate for all but simplest doc needs)
xdocs seem fine for simple site content but docbook will remain the solution for user guide/reference manual generation.
It will take some time to migrate the current site body pages to xdocs. To this effect, I will start a new sub-site just for developers only and will start by publishing new docs on branch/trunk maint and EMMA build to get it going.
Finally, my experience so far has been that the doc content get large pretty quickly. I intend to start a new CVS module "docs" for all documentation as opposed to a new dir under "emma". This will include both the reference material and the web site content.
Let me know if you have comments on the direction I am taking.
Let me know if
The only comment I have is that maven is a horrible tool. My current project has tried to use it, and it was just a mess. I had conversations with the contributors to Maven that made it very clear to me that the maven team didn't really care about backwards compatibility. Build scripts that work with maven 1.0 may not work with maven 2.0 because of how maven interacts with ant. They are completely changing the interaction between the two releases.
Also, maven pretty much requires you to do things its way. For example, in my project, we have our mainline code in one package, say net.rkbloom.javaproject, and the tests in a subpackage named test, net.rkbloom.javaproject.test. The test package is a subdirectory of the javaproject directory. Maven however wants the tests to be in the same package as the code, just in separate directory trees. Regardless of which way is better (and we really don't need to go into it), I want my tools to work for me, I don't want to work for my tools.
Finally, you don't need to use maven to use xdocs. Maven just uses velocity to generate the web site, the exact same effect can be had with pages written in xdocs, and processed using ant or even make to run the velocity tempalte engine over them. This would give you more control on the look and feel of the site. Notice that all maven sites look the exact same, that isn't a coincidence. Maven forces that look and feel on your site. I tried to replace the velocity config and templating files to get a different look and feel, and couldn't figure out how to do it.
If you really want to use xdocs (and I have no problem doing so at all), then please use ant to drive velocity, not maven.
Ryan
Valid points. I have next to zero maven experience (the company I work for uses a custom uber-build system that has so many enterprise features it is unlikely to be replaced by maven ever), however I have to say that several early posters were very keen on maven, so I am giving in to that pressure.
I knew that maven was unstable. But so is ANT to some extent, even now (the classloading model changed in 1.6 in a way that would break JNDI and a few other things and I had to work around it for EMMA).
I will look at using raw velocity now. I just want a simple means of generating a simple site with a navigation bar and I don't want to change technology here every month. I don't know if navigation.xml is a maven or a velocity thing. Any pointers are welcome (HTML authoring is not my forte).