= Reworked =
I've reworked the plugin so that forrest does not manage its own
classpath but lets maven download things. Since _a lot_ of the stuff
that forrest needs is snapshot jars not easily available, I've added
lots of stuff to a custom maven repository at
http://lsd.student.utwente.nl/repository/
it's my humble opinion that the dependency management for forrest is
rather horrible to figure out: the project.xml file has the largest list
of dependencies I've seen for any project!
I also got the impression there are some unused jars in the cvs, and
some unused projects referenced in the gump descriptor.
= wiki =
I like wikis. Contents of this e-mail up at
http://nagoya.apache.org/wiki/apachewiki.cgi?MavenForrestPlugin
= Intro =
Maven is a nice tool. For those who want more feature-rich documentation
generation than it offers and a rigid documentation format, with the
potential to easily scale up to a realtime webapp, it makes sense to
extend it with forrest. With the new forrest plugin, this is now easy to do.
= Install and usage =
== Installing the plugin ==
dead easy!
1) install maven-beta-9 or later, if you don't have it yet
2) install the plugin
wget \
http://lsd.student.utwente.nl/repository/forrest/jars/maven-forrest-plugin-1.0.jar
\
$MAVEN_HOME/plugins/
== Using the plugin ==
just as easy!
1) convert your maven-format docs to document-v11 format. Keep them in
src/xdocs/
2) optional: add a forrest.properties file to your project to customize
any forrest settings, if you want
3) use the 'forrest:generate' goal
cd $MY_PROJECT
maven forrest:generate
or add
<postGoal name="xdoc">
<attainGoal name="forrest:generate"/>
</postGoal>
to your project's maven.xml, so you can resume documentation generation
as normal using 'maven xdoc' and friends.
== Building the plugin yourself ==
1) checkout xml-forrest module
mkdir ~/cvs/
cd ~/cvs/
cvs -d anoncvs@cvs.apache.org:/home/cvspublic checkout \
xml-forrest
2) get plugin patch
wget
http://cvs.apache.org/~leosimons/maven-forrest-plugin-20030605.zip /tmp
mv /tmp/maven-forrest-plugin* ~/cvs/xml-forrest/src/resources
cd ~/cvs/xml-forrest/src/resources
rm -Rf maven-plugin
unzip maven-forrest-plugin-20030605.zip
3) build and install the plugin
cd maven-plugin
maven plugin # this is a target inside the maven-plugin-plugin, atm
# it just calls the jar:jar goal/target
maven plugin:install # this is another target inside that plugin;
# it just copies the generated jarfile into your local
# maven installation
== Example usage ==
1) install plugin as above
2) checkout avalon and avalon-excalibur modules
mkdir ~/cvs/
cd ~/cvs/
cvs -d anoncvs@cvs.apache.org:/home/cvspublic checkout \
avalon avalon-excalibur
cd ~/cvs/avalon-excalibur/compatibility
3) build excalibur-compatibility documentation using maven and forrest
maven xdoc
4) view the generated docs in
~/cvs/avalon-excalibur/compatibility/target/docs
= Things To Do =
== Devs wanted! ==
It should be pretty clear what it does (even if you don't know maven or
jelly, like me ;), basically the shbat distribution is generated,
patched, then jarred up along with some minimal script files.
The most tricky bit atm is figuring out how to get the oodles of
required jars on the proper classpaths. Which I seem to have succeeded in :D
- add plugin to forrest cvs
- figure out how to neatly replace the xdoc generation (right now the
forrest:generate target just overwrites any maven-generated files
which are in the way)
this is the most tricky part. A symbiotic relationship between maven and
forrest can exist to some extent, as you can have maven-generated files
easily reference files which will be generated later by forrest, and
vice versa (where I believe filterlinks.xsl should be modified in
forrest to not overwrite any stuff we know maven will generate).
<i>(I built a patch for that but its not operational yet.)</i>
I saw an anakia2document.xsl sheet and some auxillary files. How easy
would it be to detect whether a given xdoc file is in maven's format and
have forrest run this automatically? Where does one configure forrest to
do that? Is there docs on how to do that (I have a hunch there is some
kind of fancy dynamism in some kind of sitemap :D)?
<i>I took a look at how to do this and gave up rather quickly. The
mutual dislike between me and XSL is growing rapidly!</i>
- customize forrest skins to include a reference to the
maven-generated project reports if they exist
my current thinking is that for now a "reports" tab should be added to a
temporary tabs.xml file based on a test for existence of the
maven-reports.html file. Is that workable? Where would that test go; how
easy is it to modify the tabs.xml file conditionally like that?
I had a look at tabutils.xsl, tab2menu.xsl, etc. Can't figure out how to
do this. I think that all that needs to happen is to append
<div><a href="maven-reports.html">Reports</a></div>
somewhere in some way. How do you guys make sense out of the multitude
of XSL sheets? Is there some editor that makes it workable?
- write a project.xml (maven POM) -> status.xml (Forrest status file)
converter
- write a navigation.xml (maven site layout -> sitemap.xmap (Forrest
site layout) converter
cheers!
- Leo
|