Versions Compared

Old Version 7

changes.mady.by.user Brett Porter

Saved on

compared with

New Version Current

changes.mady.by.user Dennis Lundberg

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Sites and Inheritence

MavneMaven's support for sites that span multiple projects has generally been limited to date. The following are some features that will assist in this.

...

  • Inherited navigational elements
  • Using submenus
  • Ability to generate within the subproject, or at the top level and get the same results (with the exception of aggregated reports)
  • No strict requirements on filesystem layout other than those that already exist for Maven projects
  • Ability to aggregate reports (individual report technique out of scope here)
  • Breadcrumbing
  • Skinning
  • Separation of user and developer documentation
  • Separation of different releases in documentation

Proposed Solutions

Inherited Navigational Elements

The site descriptor will be deployed to the repository whenever the artifact is (through the deploy phase) or the site is (through the site-deploy phase). It will also be discoverable via the parent POM using ${basedir}/src/site/site.xml using the normal workspace location. When deployed to the repository, it will be located at /groupId/artifactId/version/artifactId-version-site.xml.

We can add inherit="truetop|bottom|falsenone" to the menu element, with true none as the default.

Code Block
xml
xml
<menu name="Commons Common">
  <item ... />
</menu>

<menu name="Commons Specifics" inherit="falsebottom">
  <item ... />
</menu>

Using Submenus

Including Generated Content

Currently there are elements like ${reports} and ${modules} in the site descriptor. These will be deprecated in favour of:

Code Block
xml
xml

  <!-- Include all info and reports -->
  <menu ref="reports" />

  <menu ref="modules" />

~~TODO: not happy with this yetWe have the collapse="true" element that can be added to a (sub)menu to indicate whether it is only expanded when inside that part of the navigation. We would need to add collapse="inherit" to use the parent behaviour.

Symmetric generation

When generating within the top level, content will be generated into the target/site location of the subproject, then copied into the right place within the target/site of the top level project, using the difference between the top level URL and the subproject's URL as the relative path to use (which will default to artifactId). It will not be possible to navigate between the sites on the filesystem - you must push to staging to achieve this.

When generated within the subproject, it is only generated into the subproject. The site will appear correctly, but navigating to upper levels will not be possible when previewing. However, it can be deployed from there directly into the right subdirectory on the site.

...

The location of site.xml relative to a project is determined by plugin configuration as normal, and defaults to src/site. When locating a parent project, this is done using the normal workspaces/USD technique (using relativePath in the POM, falling back to the repository. Parent project documents are not needed - only the site descriptor.

Report aggregation

Most of the work of this is covered in the individual plugins and the Maven Dashboard discussion, and is out of scope for this document. While the site mojo itself will not be an @aggregator, individual reports are free to do so and should behave correctly.

Breadcrumbing

Breadcrumbs will be stored in the <breadcrumbs /> element.

Code Block
xml
xml
<body>
  <breadcrumbs>
    <breadcrumb>Maven 1.x</breadcrumb><item href="http://www.apache.org/" name="Apache" />
    <item name="Maven"/> <!-- href is derived from project.url -->
  </breadcrumbs>

Note: Generally you'll only specify one breadcrumb, but it is a list to facilitate the root to have additional breadcrumbs that navigate back beyond the Maven hierachy.

By default, the name element of the project will be used as the breadcrumb.

Report aggregation

Most of the work of this is covered in the individual plugins and the Maven Dashboard discussion. When running the site from the top level, it behaves as an @aggregator so that it is repsonsible for generating all of the child projects, rather than using the reactor to do so. This will enable final aggregation.

Skinning

Skinning support will provided by a separate artifact that contains CSS, images and is unpakced over a siteunpacked over a site. It can optionally contain a replacement /META-INF/maven/site.vm velocity template for generating the final XHTML.

It is built as a normal JAR, using a custom packaging of "maven-skin". To configure the skin in the client, add it to the site plugindescriptor:

Code Block
xml
xml
<plugin>
  <artifactId>maven-site-plugin</artifactId><project>
...
  <configuration><skin>
    <skinArtifact>
      <groupId>org.apache.maven.maven<skins</groupId>
      <artifactId>maven-sitedefault-skin</artifactId>
      <version>1.0-SNAPSHOT<0</version>
 <!--   </skinArtifact>optional -->
  </configuration>
skin>
...

Separation of different releases in documentation

see http://jira.codehaus.org/browse/MNG-41