Generally speaking sister projects should have site
documentation alongside the code artifacts for each Maven module (so
that there is a src/site directory alongside
src/main/java and
src/test/java).
The parent module is the top-level module that contains the main
index.html entry page along with a hierarchy of
subsites corresponding to the submodules defined in the
<modules> element of the
POM, for example:
<modules>
<module>fixtures</module>
<module>documentation</module>
</modules>The child modules are then the modules referenced by the parent module.
Some sister projects may have separate standalone modules that just contain site content (typically with no code artifacts of their own). These can be thought of as parent modules with no children modules.
The customization required depends on whether the site is a parent/standalone module or a child module.
The project name should use
${project.name}, being taken from the
pom.xml.
<project name="${project.name}">
...
</project>The name will appear in any child modules sites linking back to the parent module (see Section 8.3.2.2, “Body and Menu Items”). It must be short enough to fit in the space provided.
The version should be positioned to the right, and the logo
should use a version of
hal-logo-for-maven-site.jpg customised for
the sister project (there is a
hal-logo-for-maven-site.pdn Paint.NET master available in
the Star Objects umbrella project):
<project name="${project.name}">
<version position="right"/>
<bannerLeft>
<name>HAL</name>
<src>images/hal-logo-for-maven-site.jpg</src>
<href>.</href>
</bannerLeft>
...
</project>The <poweredBy> element (which adds
a logo at the bottom of the menu bar) should be specified to use
the NO-powered-by-logo.png:
<project name="${project.name}">
...
<poweredBy>
<logo name="Naked Objects" href="http://nakedobjects.org"
img="images/NO-powered-by-logo.png"/>
</poweredBy>
...
</project>Note that the theme expects that the
.png image should be scalable to 100 x 62
(see maven-theme.css in Star Objects'
trunk/skin/src/main/resources/css).
The skin should be specified as the corporate Maven skin:
<project name="${project.name}">
...
<skin>
<groupId>org.starobjects.star</groupId>
<artifactId>skin</artifactId>
<version>1</version>
</skin>
...
</project>Note that section Chapter 13, The Maven Skin of this document describes how this skin is deployed. Sister projects should be able to take it for granted that this skin is available.
The <body> element defines menu
items (and optionally links)
<project name="${project.name}">
...
<body>
...
</body>
</project>(For parent modules), link item (appearing in the top border) should reference Naked Objects and other sister projects:
<body>
<links>
<item name="Naked Objects" href="http://www.nakedobjects.org/"/>
<item name="Sister Projects" href="http://starobjects.sourceforge.net"/>
</links>
...
</body>(For parent modules), a menu item should reference child modules, providing navigability to the subsites of these modules:
<body>
...
<menu ref="modules" inherit="top"/>
...
</body>If there is any specific content (such as overview pages, screencasts, FAQ pages and so on) then they should be referenced here. At the time of writing none of the sister projects had this requirement, but the Naked Objects site, also built with Maven, does show how:
<body>
...
<menu name="Developing with Naked Objects">
<item name="Forums" href="http://sourceforge.net/projects/nakedobjects/forums/" />
<item name="Blog/News" href="http://blog.nakedobjects.org/" />
<item name="Manual" href="manual.html" collapse="true">
<item name="Tutorial" href="tutorial.html" />
<item name="Application manual" href="application.html" />
<item name="Filename conventions" href="file-nameconvention.html" />
<item name="Installing NOF" href="installing-nof.html" />
</item>
</menu>
...
</body>Neither parent sites nor standalone sites are expected to include source code. If they do, though, then a menu item to reference generated reports should be added:
<body>
...
<menu ref="reports"/>
...
</body>Many parent modules will have a documentation (sub)module which is used to create DocBook documentation (as discussed in Chapter 7, Writing DocBook Documentation). The following links allow the generated documentation to be referenced directly from the parent site:
<body>
...
<menu name="Documentation">
<item name="User Guide (PDF)"
href="documentation/docbkx/pdf/user-guide.pdf"/>
<item name="User Guide (HTML)"
href="documentation/docbkx/html/user-guide/user-guide.html"/>
<item name="Developers Guide (PDF)"
href="documentation/docbkx/pdf/developers-guide.pdf"/>
<item name="Developers Guide (HTML)"
href="documentation/docbkx/html/developers-guide/developers-guide.html"/>
</menu>
...
</body>These links pick up generated documentation that is copied
from each the documentation project's
target/docbkx directory into its
target/site/docbkx directory. The copying
itself is defined in the corporate POM, as part
of the <postProcess> configuration of the
docbkx-maven-plugin plugin:
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.8</version>
...
<executions>
<execution>
<id>html-docs</id>
...
<configuration>
...
<postProcess>
<copy todir="target/site/docbkx/html" failonerror="false">
<fileset dir="target/docbkx/html">
<include name="**/*"/>
</fileset>
</copy>
</postProcess>
</configuration>
</execution>
...
</executions>
</plugin>There's a similar <postProcess>
element for PDF documents too.
Note that some sister projects may only have user guide and/or documentation guide. For example, Star Objects umbrella project only provides a developers guide (this guide!). In such cases, only add the links required.
Project resources provide pointers to resources hosted elsewhere (typically SourceForge). For example, Tested Objects has:
<body>
...
<menu name="Project Resources">
<item name="SF Trac Wiki" href="http://sourceforge.net/apps/trac/testedobjects"/>
<item name="SF Project Page" href="http://sourceforge.net/projects/testedobjects"/>
</menu>
...
</body>The "Maven Repo" link perhaps needs a little more explanation. Each of the sister projects has its own staging Maven repository on SourceForge. The "Maven Repo" link allows this repository to be browsed.
All sister projects should have a set of menu items pointing to other sister projects (home page, and the Maven repo):
<body>
...
<menu name="Sister Projects">
<item name="Home" href="http://starobjects.sourceforge.net"/>
<item name="Maven Repo" href="http://sourceforge.net/projects/starobjects/m2-repo"/>
</menu>
...
</body>Other resources provide pointers to related projects, blogs and so forth, also hosted elsewhere. The standard set for all sister projects are:
<body>
...
<menu name="Other Resources">
<item name="Dan Haywood's blog" href="http://danhaywood.com"/>
<item name="Naked Objects" href="http://www.nakedobjects.org/"/>
<item name="Naked Objects for .NET" href="http://www.nakedobjects.net/"/>
<item name="Naked Objects blog" href="http://blog.nakedobjects.org/"/>
<item name="Scimpi" href="http://www.scimpi.org/" />
</menu>
</body>Child modules inherit site definitions from the parent, but
override the <body> element to customize
the contents of the menu items. Pretty much everything else (such as
the logo and skin definition) is unchanged.
The project name should use
${project.name}, being taken from the
pom.xml.
<project name="${project.name}">
...
</project>The name will appear in any child sites linking back to the parent module (see Section 8.3.1, “Parent Module and Standalone Modules”), so it must be short enough to fit in the space provided.
The <body> element defines menu
items (and optionally links)
<project name="${project.name}">
...
<body>
...
</body>
</project>The child modules should reference the parent module, providing navigability back from the child's subsite to the parent's site:
<body>
<menu ref="parent"/>
...
</body>If there is any specific content for the child module then they should be referenced here. At the time of writing none of the sister projects had this requirement, but the Naked Objects site, also built with Maven, does show how:
<body>
...
<menu name="Developing with Naked Objects">
<item name="Forums" href="http://sourceforge.net/projects/nakedobjects/forums/" />
<item name="Blog/News" href="http://blog.nakedobjects.org/" />
<item name="Manual" href="manual.html" collapse="true">
<item name="Tutorial" href="tutorial.html" />
<item name="Application manual" href="application.html" />
<item name="Filename conventions" href="file-nameconvention.html" />
<item name="Installing NOF" href="installing-nof.html" />
</item>
</menu>
...
</body>All child modules are expected to contain source code. They should therefore include a reference to generated reports from that source code:
<body>
...
<menu ref="reports"/>
</body>Since all sister projects should have a documentation module, this module should also link to the documentation. The text for this is similar to that on the parent module, but one level deeper in the directory (ie remove the "documentation/" from the path):
<body>
...
<menu name="Documentation">
<item name="User Guide (PDF)"
href="docbkx/pdf/user-guide.pdf"/>
<item name="User Guide (HTML)"
href="docbkx/html/user-guide/user-guide.html"/>
<item name="Developers Guide (PDF)"
href="docbkx/pdf/developers-guide.pdf"/>
<item name="Developers Guide (HTML)"
href="docbkx/html/developers-guide/developers-guide.html"/>
</menu>
...
</body>