forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject Re: basic forrest plugin for maven
Date Thu, 05 Jun 2003 19:25:30 GMT
= 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



Mime
View raw message