You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by de...@apache.org on 2008/03/23 17:57:27 UTC
svn commit: r640220 - in /maven/plugins/trunk/maven-site-plugin/src/site:
apt/examples/configuring-reports.apt apt/examples/creating-content.apt
apt/examples/creatingskins.apt apt/examples/sitedescriptor.apt
apt/usage.apt site.xml
Author: dennisl
Date: Sun Mar 23 09:57:24 2008
New Revision: 640220
URL: http://svn.apache.org/viewvc?rev=640220&view=rev
Log:
o Copy content from "Guide to creating a site" into the appropriate pages, to have all info in one place.
o Reorder the examples in the menu to get a better flow of events.
Added:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/configuring-reports.apt (with props)
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt (with props)
Modified:
maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creatingskins.apt
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/configuring-reports.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/configuring-reports.apt?rev=640220&view=auto
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/configuring-reports.apt (added)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/configuring-reports.apt Sun Mar 23 09:57:24 2008
@@ -0,0 +1,94 @@
+ ------
+ Configuring Reports
+ ------
+ Dennis Lundberg
+ ------
+ 2008-03-23
+ ------
+
+ ~~ 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
+
+
+Configuring Reports
+
+ Maven has several reports that you can add to your web site to display the
+ current state of the project. These reports take the form of plugins, just
+ like those used to build the project.
+
+ There are many standard reports that are available by gleaning information
+ from the POM. Currently these are provided by default:
+
+ * Continous Integration
+
+ * Dependencies
+
+ * Issue Tracking
+
+ * License
+
+ * Mailing Lists
+
+ * Project Team
+
+ * Source Repository
+
+ []
+
+ To find out more please refer to the
+ {{{http://maven.apache.org/plugins/maven-project-info-reports-plugin/}Project Info Reports Plugin}}.
+
+ To add these reports to your site, you must add the plugin to a special
+ <<<\<reporting\>>>> element in the POM. The following example shows how to
+ configure the standard Project Info Reports that display information from the
+ POM in a friendly format:
+
+-------------------
+<project>
+ ...
+ <reporting>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.0.1</version>
+ </plugin>
+ </plugins>
+ </reporting>
+ ...
+</project>
+-------------------
+
+ If you have included the appropriate <<<\<menu ref="reports"/\>>>> tag in your
+ {{{sitedescriptor.html}site descriptor}}, then when you regenerate the site
+ those items will appear in the menu.
+
+ <<Note:>> Many report plugins provide a parameter called <<<outputDirectory>>>
+ or similar to specify the destination for their report outputs. This parameter
+ is only relevant if the report plugin is run standalone, i.e. by invocation
+ directly from the command line. In constrast, when reports are generated as
+ part of the site, the configuration of the Maven Site Plugin will determine
+ the effective output directory to ensure that all reports end up in a common
+ location.
+
+ Check out the <reporting> section of the {{{http://maven.apache.org/plugins/}plugins page}},
+ for a list of available reporting plugins.
+
+ ~~TODO: explain report sets
Propchange: maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/configuring-reports.apt
------------------------------------------------------------------------------
svn:eol-style = native
Added: maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt?rev=640220&view=auto
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt (added)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt Sun Mar 23 09:57:24 2008
@@ -0,0 +1,196 @@
+ ------
+ Creating Content
+ ------
+ Dennis Lundberg
+ ------
+ 2008-03-23
+ ------
+
+ ~~ 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
+
+
+Creating Content
+
+ Now it's time to create some content for your site. In Maven 2, the site
+ content is separated by format, as there are several formats supported.
+
+ Here's an example of a directory structure for a site:
+
+-------------------
++- src/
+ +- site/
+ +- apt/
+ | +- index.apt
+ |
+ +- xdoc/
+ | +- other.xml
+ |
+ +- fml/
+ | +- general.fml
+ | +- faq.fml
+ |
+ +- site.xml
+--------------------
+
+ You notice the <<<$\{basedir\}/src/site>>> directory which contains a site
+ descriptor along with various directories corresponding to the supported
+ document formatss. Let's take a look at examples of the various document
+ formats.
+
+ The APT format, "Almost Plain Text", is a wiki-like format that allows you to
+ write simple, structured documents (like this one) very quickly. A full
+ reference of the
+ {{{http://maven.apache.org/doxia/references/apt-format.html} APT Format}} is
+ available.
+
+ The FML format is the FAQ format. This is the same that were used in Maven 1.x.
+ For more info about the
+ {{{http://maven.apache.org/doxia/references/fml-format.html}FML Format}}
+ check the {{{http://maven.apache.org/doxia/}Doxia}} site.
+
+ The XDoc format is the same as
+ {{{http://maven.apache.org/maven-1.x/using/site.html} used in Maven 1.x}}.
+ A reference for the
+ {{{http://maven.apache.org/doxia/references/xdoc-format.html} XDoc Format}}
+ is available.
+
+ Other formats are available, but at this point these 3 are the best tested.
+ There are also several possible output formats, but currently only XHTML is
+ available.
+
+ Note that all of the above is optional - just one index file is required in
+ one of the input trees. The paths under each format will be merged together
+ to form the root directory of the site.
+
+
+* Adding Extra Resources
+
+ You can add any arbitrary resource to your site by including them in a
+ <<<resources>>> directory as shown below. Additional CSS files can be picked
+ up when they are placed in the <<<css>>> directory within the <<<resources>>>
+ directory.
+
+-------------------
++- src/
+ +- site/
+ +- resources/
+ +- css/
+ | +- site.css
+ |
+ +- images/
+ +- pic1.jpg
+--------------------
+
+ The file <<<site.css>>> will be added to the default XHTML output, so it can
+ be used to adjust the default Maven stylesheets if desired.
+
+ The file <<<pic1.jpg>>> will be available via a relative reference to the
+ <<<images>>> directory from any page in your site.
+
+
+* Filtering
+
+ <<Note:>> This feature is available in version 2.0-beta-6 or later of the
+ Site Plugin.
+
+ To filter properties into any supported documentation format, add a <<<.vm>>>
+ extension to the filename.
+
+ For example, the module for the Maven website contains a
+ {{{http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/download.apt.vm}<<<src/site/apt/download.apt.vm>>>}}
+ file, which uses the expression <<<$\{currentVersion}>>> to filter in a
+ property set in the
+ {{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.
+
+ <<Note:>> {{{http://velocity.apache.org/}Velocity}} is used to apply the
+ filtering. Because Velocity uses a dot-notation internally you can <<not>>
+ use dots in your properties.
+
+ If you declare these properties in your POM
+
++-----+
+ <properties>
+ <!-- This will not work because the name of the property has a dot in it -->
+ <my.property>My value</my.property>
+ <!-- This will work because the name of the property has no dot in it -->
+ <myProperty>My other value</myProperty>
+ </properties>
++-----+
+
+ and then use the expression <<<$\{my.property\}>>> in your document, it will
+ <<not>> work. If you instead use the expression <<<$\{myProperty\}>>> it will
+ work just fine.
+
+
+* Internationalization
+
+ Internationalization in Maven is very simple, as long as the reports you are
+ using have that particular locale defined. For an overview of supported
+ languages and instructions on how to add further languages, please see the
+ related article {{{../i18n.html} Internationalization}}.
+
+ To enable multiple locales, or languages, add a configuration similar to the
+ following to your POM:
+
+-------------------
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0-beta-6</version>
+ <configuration>
+ <locales>en,fr</locales>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
+-------------------
+
+ This will generate both an English and a French version of the site. If
+ <<<en>>> is your current locale, then it will be generated at the root of the
+ site, with a copy of the French translation of the site in the <<<fr/>>>
+ subdirectory.
+
+ To add your own content for that translation instead of using the default,
+ place a subdirectory with that locale name in your site directory and create
+ a new site descriptor with the locale in the file name. For example:
+
+-------------------
++- src/
+ +- site/
+ +- apt/
+ | +- index.apt (Default version)
+ |
+ +- fr/
+ | +- apt/
+ | +- index.apt (French version)
+ |
+ +- site.xml (Default site descriptor)
+ +- site_fr.xml (French site descriptor)
+--------------------
+
+ With one site descriptor per language, the translated site(s) can evolve
+ independently.
Propchange: maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creating-content.apt
------------------------------------------------------------------------------
svn:eol-style = native
Modified: maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creatingskins.apt
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creatingskins.apt?rev=640220&r1=640219&r2=640220&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creatingskins.apt (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/apt/examples/creatingskins.apt Sun Mar 23 09:57:24 2008
@@ -29,6 +29,14 @@
Creating Skins
+ If you want to tune the way your site looks, you can use a custom skin to
+ provide your own CSS styles. If that is still not enough, you can even tweak
+ the output templates that Maven uses to generate the site documentation.
+
+~~ TODO: The following link is currently unavailable. Restore it when it becomes available again
+~~ For an in-depth discussion of site customization, please have a look at the
+~~ {{{http://www.sonatype.com/book/site-generation.html} Maven User Guide, Chapter 9, "Site Generation"}}.
+
* About
A Maven 2 site skin contains the following elements:
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=640220&r1=640219&r2=640220&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 Sun Mar 23 09:57:24 2008
@@ -36,6 +36,10 @@
to be accessible in the generated site, you must configure your site descriptor. You create the site descriptor in
a file called <<<site.xml>>> which should be located in your <<<src/site>>> directory.
+ If you are migrating from Maven 1.x you will be interested to know that the
+ <<<navigation.xml>>> file has been replaced by the site descriptor in Maven 2.
+ The format is nearly the same, so you can probably reuse most of your old file.
+
* Title
The title of each generated page will be a combination of the <site title>
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=640220&r1=640219&r2=640220&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 Sun Mar 23 09:57:24 2008
@@ -44,29 +44,40 @@
mvn site
+-----+
+ By default, the resulting site will be in the <<<target/site/>>> directory.
+
* Deploying a Site
- The <<<{{{deploy-mojo.html}site:deploy}}>>> goal supports the <<<scp>>> and
- <<<file>>> protocols. To deploy the generated site, you first need to specify
- where the site will be deployed. This can be set in the
- <<<\<distributionManagement\>>>> section of the POM as shown below.
+ To be able to deploy the site, you must first specify where the site will be
+ deployed. This is set in the <<<\<distributionManagement\>>>> element of the
+ POM as shown below.
+-----+
<project>
...
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-site-plugin</artifactId>
<distributionManagement>
<site>
- <id>maven.apache.org</id>
- <url>scp://maven.apache.org/deploy/path</url>
+ <id>www.yourcompany.com</id>
+ <url>scp://www.yourcompany.com/www/docs/project/</url>
</site>
</distributionManagement>
...
</project>
+-----+
- Then execute the <<<{{{deploy-mojo.html}site:deploy}}>>> goal from your project.
+ The <<<\<id\>>>> element identifies the repository, so that you can attach
+ credentials to it in your <<<settings.xml>>> file using the
+ {{{http://maven.apache.org/settings.html#Servers}<<<\<servers\>>>> element}}
+ as you would for any other repository.
+
+ The <<<\<url\>>>> gives the location to deploy to. Currently, the <<<scp>>>
+ and <<<file>>> protocols are supported. In the example above we copy to the
+ host <<<www.mycompany.com>>> in the path <<</www/docs/project/>>>. If
+ subprojects inherit the site URL from a parent POM, they will automatically
+ append their <<<\<artifactId\>>>> to form their effective deployment location.
+
+ Now you can execute the <<<{{{deploy-mojo.html}site:deploy}}>>> goal from
+ your project.
<<Note:>> A site must be generated first before executing <<<site:deploy>>>.
@@ -123,30 +134,3 @@
The server will, by default, be started on <<<http://localhost:8080/>>>. See
{{{http://jetty.mortbay.org/}http://jetty.mortbay.org/}} for more information about
the Jetty server.
-
-* Filtering
-
- <<Note:>> This feature is available in version 2.0-beta-6 or later of the Site Plugin.
-
- To filter properties into any supported documentation format, add a <<<.vm>>>
- extension to the filename.
-
- For example, the module for the Maven website contains a
- {{{http://svn.apache.org/repos/asf/maven/site/trunk/src/site/apt/download.apt.vm}<<<src/site/apt/download.apt.vm>>>}}
- file, which uses the expression <<<$\{currentVersion}>>> to filter in a
- property set in the
- {{{http://svn.apache.org/repos/asf/maven/site/trunk/pom.xml}POM}}.
-
- <<Note:>> {{{http://velocity.apache.org/}Velocity}} is used to apply the filtering. Because Velocity uses a
- dot-notation internally you can <<not>> use dots in your properties. So if
- you declare a property like this
-
-+-----+
- <properties>
- <!-- This will not work because the name of the property has a dot in it -->
- <my.property>My value</my.property>
- </properties>
-+-----+
-
- in your <<<pom.xml>>> file and then use the expression <<<$\{my.property\}>>> in
- your document, it will <<not>> work.
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=640220&r1=640219&r2=640220&view=diff
==============================================================================
--- maven/plugins/trunk/maven-site-plugin/src/site/site.xml (original)
+++ maven/plugins/trunk/maven-site-plugin/src/site/site.xml Sun Mar 23 09:57:24 2008
@@ -32,11 +32,13 @@
</menu>
<menu name="Examples">
+ <item name="Creating Content" href="/examples/creating-content.html"/>
<item name="Configuring the Site Descriptor" href="/examples/sitedescriptor.html"/>
- <item name="Changing the Template File" href="/examples/templatefile.html"/>
- <item name="Excluding Modules" href="/examples/moduleexcludes.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"/>
<item name="Creating Skins" href="/examples/creatingskins.html"/>
+ <item name="Excluding Modules" href="/examples/moduleexcludes.html"/>
</menu>
</body>
</project>