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 2010/08/09 22:37:20 UTC
svn commit: r983811 - in
/maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples:
creating-content.apt moduleexcludes.apt siterun.apt templatefile.apt
Author: dennisl
Date: Mon Aug 9 20:37:20 2010
New Revision: 983811
URL: http://svn.apache.org/viewvc?rev=983811&view=rev
Log:
Restore content that was removed in r806386.
Modified:
maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/creating-content.apt
maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/moduleexcludes.apt
maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/siterun.apt
maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/templatefile.apt
Modified: maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/creating-content.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/creating-content.apt?rev=983811&r1=983810&r2=983811&view=diff
==============================================================================
--- maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/creating-content.apt (original)
+++ maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/creating-content.apt Mon Aug 9 20:37:20 2010
@@ -0,0 +1,215 @@
+ ------
+ Creating Content
+ ------
+ Dennis Lundberg
+ ------
+ 2009-03-08
+ ------
+
+ ~~ 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 structured by format, as there are several formats supported.
+
+ Here's an example of a directory structure for a site:
+
+-------------------
++- src/
+ +- site/
+ +- apt/
+ | +- index.apt
+ |
+ +- fml/
+ | +- general.fml
+ | +- faq.fml
+ |
+ +- xdoc/
+ | +- other.xml
+ |
+ +- site.xml
+--------------------
+
+ You notice the <<<$\{basedir\}/src/site>>> directory which contains a site
+ descriptor along with various directories corresponding to the supported
+ document formats. 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. After running '<<<mvn site:site>>>'
+ on the example above you will end up with this in your <<<target>>> directory:
+
+-------------------
++- target/
+ +- site/
+ +- css/
+ |
+ +- images/
+ |
+ +- index.html
+ +- general.html
+ +- faq.html
+ +- other.html
+--------------------
+
+ The <<<css>>> and <<<images>>> directories contains stylesheets and images
+ from the skin being used. You can read more about skins in
+ {{{sitedescriptor.html}the site descriptor documentation}}.
+
+
+* 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</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,
+ create a subdirectory with that locale's name in your site directory and
+ create a new site descriptor with the name of 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.
Modified: maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/moduleexcludes.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/moduleexcludes.apt?rev=983811&r1=983810&r2=983811&view=diff
==============================================================================
--- maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/moduleexcludes.apt (original)
+++ maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/moduleexcludes.apt Mon Aug 9 20:37:20 2010
@@ -0,0 +1,71 @@
+ ------
+ Excluding Document Formats
+ ------
+ Maria Odea Ching
+ ------
+ 2009-03-08
+ ------
+
+ ~~ 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
+
+
+Excluding Document Formats
+
+ To exclude specific document formats from the generated site, you can use the <<<excludeModules>>> parameter.
+
+ For example, you have the following site content in your POM
+
++-----+
+Module1
+|-- src
+| |-- main
+| `-- site
+| |-- apt
+| | `-- sample-apt.apt
+| `-- fml
+| `-- sample-fml.fml
+`-- pom.xml
++-----+
+
+ and you want to exclude all the documents in the fml format from the
+ generated site, you need to set the following in your POM and then execute
+ "<<<mvn site>>>".
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0</version>
+ <configuration>
+ <excludeModules>fml</excludeModules>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ You will see that no <<<sample-fml.html>>> will be present in the generated site.
\ No newline at end of file
Modified: maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/siterun.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/siterun.apt?rev=983811&r1=983810&r2=983811&view=diff
==============================================================================
--- maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/siterun.apt (original)
+++ maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/siterun.apt Mon Aug 9 20:37:20 2010
@@ -0,0 +1,59 @@
+ ------
+ Configuring Site Run
+ ------
+ Maria Odea Ching
+ ------
+ 2009-03-08
+ ------
+
+ ~~ 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 Site Run
+
+ For the <<<{{{run-mojo.html}site:run}}>>> goal, you can configure which port to use to start up the site as well as the directory where
+ the pages for the site will be rendered.
+
+ For example, you can have the following configuration in your POM:
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0</version>
+ <configuration>
+ <port>9000</port>
+ <tempWebappDirectory>${basedir}/target/site/tempdir</tempWebappDirectory>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ When you execute "<<<mvn site:run>>>", you will see in the command line that the Jetty server is started at port 9000.
+ To access the site, type <<<http://localhost:9000>>> in your browser. You will also see that the dummy web application is
+ generated in the <<<$\{basedir\}/target/site/tempdir>>> directory as specified by the <<<tempWebappDirectory>>> parameter.
Modified: maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/templatefile.apt
URL: http://svn.apache.org/viewvc/maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/templatefile.apt?rev=983811&r1=983810&r2=983811&view=diff
==============================================================================
--- maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/templatefile.apt (original)
+++ maven/plugins/branches/maven-site-plugin-3.x/src/site/apt/examples/templatefile.apt Mon Aug 9 20:37:20 2010
@@ -0,0 +1,98 @@
+ ------
+ Changing the Template File
+ ------
+ Vincent Siveton
+ <vi...@gmail.com>
+ Maria Odea Ching
+ ------
+ 2009-03-08
+ ------
+
+ ~~ 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
+
+
+Changing the Template File
+
+ It is possible to change the Velocity template used for creating the site.
+ Save your custom template in a directory of your choice and configure the
+ Site Plugin accordingly.
+
+ <<Note:>> If you use this method then skins and the default templates, CSS
+ and images are disabled. It is therefor highly recommended that you package
+ this as a {{{creatingskins.html}skin}} instead.
+
+ For version 2.0-beta-5 and later you would add something like this to your
+ <<<pom.xml>>>:
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0</version>
+ <configuration>
+ <templateFile>${basedir}/maven-site.vm</templateFile>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ For version 2.0-beta-4 and earlier it was done by adding this to your
+ <<<pom.xml>>>:
+
++-----+
+<project>
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-site-plugin</artifactId>
+ <version>2.0-beta-4</version>
+ <configuration>
+ <templateDirectory>${basedir}</templateDirectory>
+ <template>maven-site.vm</template>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+ ...
+</project>
++-----+
+
+ Then you execute the site goal from your project:
+
++-----+
+mvn site
++-----+
+
+ If you do not want to start from scratch you can start with the
+ {{{https://svn.apache.org/repos/asf/maven/doxia/doxia-sitetools/trunk/doxia-site-renderer/src/main/resources/org/apache/maven/doxia/siterenderer/resources/default-site.vm}default template}}
+ that is used by the Site Plugin.
+
+ For more information about Velocity, see
+ {{{http://velocity.apache.org/}http://velocity.apache.org/}}.
\ No newline at end of file