Wendy Smoak Wiki: MavenMultiProjectSite

Converting the Struts site

Copy everything from /struts/current/core/doc/ to /struts/current/site/xdocs/
Rename the project.xml files (which contain the menus) to navigation.xml
Change links in all navigation.xml files under 'build' to be relative to the root directory
Add the missing <body> tags to navigation.xml files
Add navigation.xml files to xdocs under each subproject
Change the <chapter> tags to <section> and <section> to <subsection> in the userGuide
Remove the <search> section from userGuide/index.xml and faqs/index.xml
Fix links to Taglib Package Descriptions in the User Guide
Fix links to Taglib API References in the User Guide

Draft site: http://svn.apache.org/builds/struts/maven/trunk/site-test/index.html

Discussion thread: http://www.mail-archive.com/dev%40struts.apache.org/msg10723.html

TODO List

Anchors aren't working: http://svn.apache.org/builds/struts/maven/trunk/site-test/using.html#Lists does not scroll to the 'Lists' section.
- XML source is: <section name="Joining the Mailing Lists" href="Lists">
- generated HTML is: <div class="section"><a name="Joining_the_Mailing_Lists"></a><h2>Joining the Mailing Lists</h2>.

Solution: put <a href="#Lists"> near the <section> tag. Otherwise, we would have to modify and maintain a site.jsl file for the XSLT.
Requested feature for xdoc plugin: http://jira.codehaus.org/browse/MPXDOC-159

Struts uses <chapter> tags, which aren't allowed in the [xdocs structure]. Will converting them to empty sections break anything? (Was this possibly for docbook?)

Developer Guide - Links to the Taglib API References are broken [example]. Those probably get built in the 'taglib' sub-project, need to find them and fix the links.

$ maven struts:generate-tlds puts tld files in target/classes/META-INF/tlds/
move these files to src/tld/
$ maven taglib:report builds html files from src/tld/*.tld into target/docs/tlddoc/
Descriptions are missing, see http://people.apache.org/~germuska/struts-taglib/docs/tlddoc/index.html
This is what generates the framed docs: https://taglibrarydoc.dev.java.net/

Struts Tiles navigation links to non-existent pages. (Where is the rest of the Tiles documentation?)

Deal with the changed site directory names: flow -> struts-flow, bsf -> struts-bsf and shale -> ??? when the docs move down under the subproject directories.

postGoal to rename the directory before the site is uploaded?
redirect or softlink on the server?
Just accept the new directory name? (Probably okay for bsf and flow, not Shale if its directory name changes.)

Add link to Javadoc back to the 'Documentation' menu

Problem with Maven PDF Plugin, related to duplicate section names from xdoc plugin
- http://jira.codehaus.org/browse/MPPDF-40

Add Dashboard reports: http://maven.apache.org/reference/plugins/dashboard/

Multiproject site for Sandbox

Multiproject site for Shale

Host the 1.2.7 docs at http://struts.apache.org/struts-1.2.7-doc/ (like Tomcat) Possibly move /api under struts-1.2.7-doc [will break links, so link or redirect from /api/].

Done

[DONE] Move the 'Projects' links to the top of the navigation menu.

Notes

When you add 'navigation.xml' to the xdocs directory, you take over responsibility for the entire menu.

If you add a directory under /current/build/xdocs/, be sure not to duplicate a directory name from one of the sub-projects.

Make sure not to delete/overwrite the 1.2.7 Javadocs living in the /api subdirectory.

References

http://maven.apache.org/reference/dirlayout.html
xdocs structure: http://jakarta.apache.org/site/jakarta-site2.html
Different multiproject directory structures http://technology.amis.nl/blog/index.php?p=490

Dashboard: http://maven.apache.org/reference/plugins/dashboard/

August 8, 2005 Problem with maven multiproject:site

$ maven multiproject:site > ../../mp-site.log

BUILD FAILED
File...... C:\Documents and Settings\wendy\.maven\cache\maven-xdoc-plugin-1.8\plugin.jelly
Element... j:include
Line...... 365
Column.... 54
file:/C:/Documents and Settings/wendy/.maven/cache/maven-xdoc-plugin-1.8/plugin-
resources/site.jsl:33:15: <jsl:stylesheet> file:/C:/Documents and Settings/wendy
/.maven/cache/maven-xdoc-plugin-1.8/plugin-resources/site.jsl:161:65: <jsl:apply
Templates> file:/C:/Documents and Settings/wendy/.maven/cache/maven-xdoc-plugin-
1.8/plugin-resources/site.jsl:239:50: <jsl:applyTemplates> file:/C:/Documents an
d Settings/wendy/.maven/cache/maven-xdoc-plugin-1.8/plugin-resources/site.jsl:25
4:48: <x:set> Property 'var' has no write method

wendy@imbrium-1 /cygdrive/e/svn/struts/current/build
$

Possible Solution

Visited http://maven.apache.org/reference/plugins/xdoc/ and determined that the xdoc plugin is now at version 1.9.1. Download maven-xdoc-plugin-1.9.1.jar and placed in $MAVEN_HOME/plugins, and re-run maven multiproject:site.

Different Problem

wendy@imbrium-1 /cygdrive/e/svn/struts/current/build
$ maven multiproject:site > ../../mp-site.log

BUILD FAILED
File...... C:\Documents and Settings\wendy\.maven\cache\maven-xdoc-plugin-1.9.1\plugin.jelly
Element... echo
Line...... 554
Column.... 75
java.lang.reflect.InvocationTargetException

wendy@imbrium-1 /cygdrive/e/svn/struts/current/build
$

Tried it in Windows (instead of Cygwin)

multiproject:projects-init:

multiproject:site-init:

multiproject:create-nav:
    [echo] Producing aggregate navigation...
    [echo] Producing user supplied navigation...

BUILD FAILED
File...... C:\Documents and Settings\wendy\.maven\cache\maven-multiproject-plugi
n-1.3.1\plugin.jelly
Element... velocity:merge
Line...... 169
Column.... 11
java.lang.OutOfMemoryError
Total time: 10 minutes 1 seconds
Finished at: Mon Aug 08 16:56:09 MST 2005

E:\svn\struts\current\build>

So close! Try this: http://swc.projects.semwebcentral.org/util/maven-setup/build-maven.html

there is currently a problem compiling all the plugin docs due to an OutOfMemoryError.
as a workaround, make the following change to MAVEN_HOME/bin/maven.bat
REM SET MAVEN_OPTS=-Xmx128m
SET MAVEN_OPTS=-Xmx1024m

The line in maven.bat is now

@REM Reaching here means variables are defined and arguments have been captured
:endInit
if "%MAVEN_OPTS%"=="" SET MAVEN_OPTS="-Xmx256m"

So it should respect an environment variable set before calling maven.

E:\svn\struts\current\build>set MAVEN_OPTS=-Xmx1024m

E:\svn\struts\current\build>echo %MAVEN_OPTS%
-Xmx1024m

E:\svn\struts\current\build>maven multiproject:site > ../../mp-site.log
Note: Some input files use or override a deprecated API.
Note: Recompile with -deprecation for details.
...
E:\svn\struts\current\build>

From mp-site.log

BUILD SUCCESSFUL
Total time: 9 minutes 30 seconds
Finished at: Mon Aug 08 17:16:58 MST 2005

Success!