Author: ltheussl
Date: Tue Jan 18 10:26:21 2011
New Revision: 1060289
URL: http://svn.apache.org/viewvc?rev=1060289&view=rev
Log:
adding docs building mult-module sites
Added:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
Modified:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/sitedescriptor.apt
maven/plugins/trunk/maven-site-plugin/src/site/apt/usage.apt
maven/plugins/trunk/maven-site-plugin/src/site/site.xml
Added:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt?rev=1060289&view=auto
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
(added)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/multimodule.apt
Tue Jan 18 10:26:21 2011
@@ -0,0 +1,94 @@
+ ------
+ Multi-module Sites
+ ------
+ Vincent Siveton
+ <vincent.sive...@gmail.com>
+ Maria Odea Ching
+ Dennis Lundberg
+ Lukas Theussl
+ ------
+ 2011-01-18
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements. See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership. The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License. You may obtain a copy of the License at
+ ~~
+ ~~ http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied. See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
+
+
+Building multi-module sites
+
+ Running <<<mvn site>>> on a top level project, maven will build all sites
for every module
+ defined in the <<<modules>>> section of the pom individually. Note that each
site is
+ generated in each individual project's target location. As a result,
relative links between
+ different modules will NOT work. They will however work when you deploy or
stage the site.
+
+* Staging and deploying
+
+ To preview the whole tree of a multi-module site, you can use the
+ <<<{{{../stage-mojo.html}site:stage}}>>> goal. This will build the whole site
+ and copy individual sites to their proper place at the staging location.
+
+ <<<{{{../deploy-mojo.html}site:deploy}}>>> does the same thing as
<<<site:stage>>>
+ but uses the url defined in the <<<\<distributionManagement\>>>> element of
the pom
+ as deployment location. This is usually a remote url, but both <<<scp>>> and
<<<file>>>
+ protocols are supported.
+
+ Finally, <<<{{{../stage-deploy-mojo.html}site:stage-deploy}}>>> does the
same thing as
+ <<<site:deploy>>> but uses the <<<stagingDirectory>>> parameter as
deployment location.
+ This can be used to deploy the site to a remote staging area
(<<<site:stage>>> is always local).
+
+ <<Note:>> If subprojects inherit the site URL from a parent POM, they will
automatically
+ append their <artifactId> to form their effective deployment location.
+ This goes for both the project url and the url defined in the
+ <<<\<distributionManagement\>>>> element of the pom. If your multi-module
tree does not
+ follow the maven conventions, or if module directories are named differently
than
+ module artifacts, you have to specify the url's for <<each>> child project.
+ See also <<<{{{../faq.html#Use_of_url}How does the Site Plugin use the
\<url\> element in the POM?}}>>>.
+
+* Inheritance
+
+ Site descriptors are inherited along the same lines as project descriptors
+ are. If you want your project's site descriptor to be inherited, you need to
+ attach it to the project's main artifact. You use the
+ <<<{{{../attach-descriptor-mojo.html}site:attach-descriptor}}>>>
+ goal to attach the site descriptor to your project's main artifact.
+
+ In Maven 2 the site descriptor is attached automatically for projects with
+ packaging set to "pom".
+
+ By default, only the basic settings are inherited. From the body, <<only>>
+ the links and breadcrumbs are inherited, and these accumulate to contain all
the parents'
+ site descriptor links and breadcrumbs.
+
+ However, it is possible to inherit menus as well. To do so, use the
<<<inherit>>> attribute in the site descriptor. This can
+ be either <<<top>>> or <<<bottom>>>, indicating where the inherited menu
will be placed. For example:
+
++-----+
+<project>
+ ...
+ <body>
+ ...
+ <menu name="My Inherited Menu" inherit="top">
+ ...
+ </menu>
+ ...
+ </body>
+ ...
+</project>
++-----+
Modified:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/sitedescriptor.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/sitedescriptor.apt?rev=1060289&r1=1060288&r2=1060289&view=diff
==============================================================================
---
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/sitedescriptor.apt
(original)
+++
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/sitedescriptor.apt
Tue Jan 18 10:26:21 2011
@@ -147,35 +147,7 @@ Configuring the Site Descriptor
* Inheritance
- Site descriptors are inherited along the same lines as project descriptors
- are. If you want your project's site descriptor to be inherited, you need to
- attach it to the project's main artifact. You use the
- <<<site:attach-descriptor>>> goal to attach the site descriptor to your
- project's main artifact.
-
- In Maven 2 the site descriptor is attached automatically for projects with
- packaging set to "pom".
-
- By default, only the basic settings are inherited. From the body, <<only>>
- the links are inherited, and these accumulate to contain all the parents'
- site descriptor links.
-
- However, it is possible to inherit menus as well. To do so, use the
<<<inherit>>> attribute in the site descriptor. This can
- be either <<<top>>> or <<<bottom>>>, indicating where the inherited menu
will be placed. For example:
-
-+-----+
-<project>
- ...
- <body>
- ...
- <menu name="My Inherited Menu" inherit="top">
- ...
- </menu>
- ...
- </body>
- ...
-</project>
-+-----+
+ See {{{./multimodule.html} Building multi-module sites}}.
* Including Generated Content
Modified: maven/plugins/trunk/maven-site-plugin/src/site/apt/usage.apt
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/usage.apt?rev=1060289&r1=1060288&r2=1060289&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/usage.apt (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/usage.apt Tue Jan 18
10:26:21 2011
@@ -118,6 +118,15 @@ mvn site-deploy
project and its modules.
Just execute the <<<{{{./stage-mojo.html}site:stage}}>>> goal from your
project
+
++-----+
+mvn site:stage
++-----+
+
+ <<Note:>> Since version 2.3, a site must be generated first before executing
<<<site:stage>>>.
+
+ By default, the site will be staged in a directory <<<target/staging/>>>.
+ A different staging location can be chosen
with the <<<stagingDirectory>>> parameter as shown below:
+-----+
@@ -135,10 +144,11 @@ mvn site:stage -DstagingDirectory=C:\ful
for more information on this.
+-----+
-mvn site:stage-deploy -DstagingDirectory=C:\fullsite \
- -DstagingSiteURL=scp://www.mycompany.com/www/project/
+mvn site:stage-deploy -DstagingSiteURL=scp://www.mycompany.com/www/project/
+-----+
+ <<Note:>> Since version 2.3, a site must be generated first before executing
<<<site:stage-deploy>>>.
+
<<Note:>> Due to a bug in Wagon, the password is not always picked up when
you run the <<<site:stage-deploy>>> goal. The bug has been fixed, but the
version of Wagon that is used by the Site Plugin is determined by the version
Modified: maven/plugins/trunk/maven-site-plugin/src/site/site.xml
URL:
http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/site.xml?rev=1060289&r1=1060288&r2=1060289&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/site.xml Tue Jan 18 10:26:21
2011
@@ -37,6 +37,7 @@ under the License.
<menu name="Examples">
<item name="Creating Content" href="/examples/creating-content.html"/>
<item name="Configuring the Site Descriptor"
href="/examples/sitedescriptor.html"/>
+ <item name="Building a multi-module site"
href="/examples/multimodule.html"/>
<item name="Configuring Reports"
href="/examples/configuring-reports.html"/>
<item name="Configuring Site Run" href="/examples/siterun.html"/>
<item name="Changing the Template File"
href="/examples/templatefile.html"/>
