mirror of https://github.com/apache/maven.git
o still need to do lots of plugin doco but have run out of stream ...
git-svn-id: https://svn.apache.org/repos/asf/maven/components/trunk@294981 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Jason van Zyl
parent
e9115a5ce2
commit
38a002fa1e
|
|
@ -34,4 +34,8 @@ the JDK configuration equivalent.
|
|||
</proxies>
|
||||
.
|
||||
.
|
||||
</settings>
|
||||
</settings>
|
||||
|
||||
+----+
|
||||
|
||||
Please note that urrently NTML proxies are not supported as they have not been tested.
|
||||
|
|
@ -200,4 +200,10 @@ example of generating sources
|
|||
|
||||
How to modify the manifest.
|
||||
|
||||
~~ * How do I deal with a dependency that is already supplied by my runtime?
|
||||
|
||||
~~* How do I deploy my jar in Ibiblio?
|
||||
|
||||
~~* How do I internationalize my site?
|
||||
|
||||
+-----+
|
||||
|
|
|
|||
|
|
@ -620,7 +620,11 @@ environment=${environment}
|
|||
<version>3.8.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<!-- New external dependency -->
|
||||
<!--
|
||||
|
|
||||
| New external dependency
|
||||
|
|
||||
-->
|
||||
<dependency>
|
||||
<groupId>org.apache.codehaus.plexus</groupId>
|
||||
<artifactId>plexus-utils</artifactId>
|
||||
|
|
@ -642,26 +646,335 @@ environment=${environment}
|
|||
|
||||
+----+
|
||||
|
||||
~~ * How do I deal with a dependency that is already supplied by my runtime?
|
||||
* How do I deploy my jar in my remote repository?
|
||||
|
||||
~~ o Explain the use of repositories, remote and local
|
||||
+----+
|
||||
|
||||
~~* How do I setup a proxy if I'm behind a firewall so I can get my external dependencies?
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<groupId>com.mycompany.app</groupId>
|
||||
<artifactId>my-app</artifactId>
|
||||
<packaging>jar</packaging>
|
||||
<version>1.0-SNAPSHOT</version>
|
||||
<name>Maven Quick Start Archetype</name>
|
||||
<url>http://maven.apache.org</url>
|
||||
<description>Killer App</description>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
<artifactId>junit</artifactId>
|
||||
<version>3.8.1</version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.apache.codehaus.plexus</groupId>
|
||||
<artifactId>plexus-utils</artifactId>
|
||||
<version>1.0.4</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
<build>
|
||||
<filters>
|
||||
<filter>src/main/filters/filters.properties</filter>
|
||||
</filters>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/resources</directory>
|
||||
<filtering>true</filtering>
|
||||
</resource>
|
||||
</resources>
|
||||
</build>
|
||||
<!--
|
||||
|
|
||||
|
|
||||
|
|
||||
-->
|
||||
<distributionManagement>
|
||||
<repository>
|
||||
<id>mycompany-repository</id>
|
||||
<name>MyCompany Repository</name>
|
||||
<url>scp://repository.mycompany.com/repository/maven2</url>
|
||||
</repository>
|
||||
</distributionManagement>
|
||||
</project>
|
||||
|
||||
~~* How do I deploy my jar in my remote repository?
|
||||
+----+
|
||||
|
||||
~~* How do I deploy my jar in Ibiblio?
|
||||
+----+
|
||||
|
||||
~~* How do I create documentation?
|
||||
~~ o Explain the different formats APT/xdoc/docbook/FAQML
|
||||
<settings>
|
||||
.
|
||||
.
|
||||
<servers>
|
||||
<server>
|
||||
<id>mycompany-repository</id>
|
||||
<username>jvanzyl</username>
|
||||
<!-- Default value is ~/.ssh/id_dsa -->
|
||||
<privateKey>/path/to/identity</privateKey> (default is ~/.ssh/id_dsa)
|
||||
<passphrase>my_key_passphrase</passphrase>
|
||||
</server>
|
||||
</servers>
|
||||
.
|
||||
.
|
||||
</settings>
|
||||
|
||||
~~* How do I use plug-ins?
|
||||
o Explain that a plug-in consists of one or more mojos
|
||||
~~* How do I control what version of plug-in I use?
|
||||
+----+
|
||||
|
||||
~~* How do I generate reports?
|
||||
* How do I create documentation?
|
||||
|
||||
~~* How do I internationalize my site?
|
||||
To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site
|
||||
for you without your existing project using the following command:
|
||||
|
||||
+----+
|
||||
|
||||
m2 archetype:create -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-site
|
||||
|
||||
+----+
|
||||
|
||||
If you take a look in your directory structure it should look like the following:
|
||||
|
||||
+----+
|
||||
|
||||
my-app
|
||||
|-- pom.xml
|
||||
`-- src
|
||||
|-- main
|
||||
| |-- filters
|
||||
| | `-- filters.properties
|
||||
| |-- java
|
||||
| | `-- com
|
||||
| | `-- mycompany
|
||||
| | `-- app
|
||||
| | `-- App.java
|
||||
| `-- resources
|
||||
| `-- META-INF
|
||||
| |-- application.properties
|
||||
| `-- application.properties~
|
||||
|-- site
|
||||
| |-- apt
|
||||
| | |-- format.apt
|
||||
| | `-- index.apt
|
||||
| |-- fml
|
||||
| | `-- faq.fml
|
||||
| |-- fr
|
||||
| | |-- apt
|
||||
| | | |-- format.apt
|
||||
| | | `-- index.apt
|
||||
| | |-- fml
|
||||
| | | `-- faq.fml
|
||||
| | `-- xdoc
|
||||
| | `-- xdoc.xml
|
||||
| |-- site.xml
|
||||
| |-- site_fr.xml
|
||||
| `-- xdoc
|
||||
| `-- xdoc.xml
|
||||
`-- test
|
||||
|-- java
|
||||
| `-- com
|
||||
| `-- mycompany
|
||||
| `-- app
|
||||
| `-- AppTest.java
|
||||
`-- resources
|
||||
`-- test.properties
|
||||
+----+
|
||||
|
||||
You will notice there is now a <<<${basedir}/src/site>>> directory within which is contained a site descriptor
|
||||
along with various directories corresponding to the supported document types. Let's take a look at site
|
||||
descriptor and the examples of the various document types.
|
||||
|
||||
The Xdoc format is the same as {{{http://maven.apache.org/using/site.html} used in Maven 1.0}}. However, <<<navigation.xml>>>
|
||||
has been replaced by the site descriptor (see below).
|
||||
|
||||
The APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this)
|
||||
very quickly. A full reference of the {{{apt-format.html} APT Format}} is available.
|
||||
|
||||
The FML format is the FAQ format, also used in Maven 1.0.
|
||||
|
||||
Other formats are available, but at this point these 3 are the best tested. There are also several possible output formats,
|
||||
but as of 2.0, only XHTML is available.
|
||||
|
||||
Note that all of the above is optional - just one index file is required in one of the input trees. Each of the paths will be merged
|
||||
together to form the root directory of the site.
|
||||
|
||||
* Generating The Site
|
||||
|
||||
Generating the site is very simple, and fast!
|
||||
|
||||
---------------
|
||||
m2 site:site
|
||||
---------------
|
||||
|
||||
The resulting site will be in <<<target/site/...>>>
|
||||
|
||||
* How do I deploy my site?
|
||||
|
||||
To be able to deploy the site, you must first declare a location to distribute to in your <<<pom.xml>>>, similar to the repository for
|
||||
deployment.
|
||||
|
||||
---------------
|
||||
<distributionManagement>
|
||||
<site>
|
||||
<id>website</id>
|
||||
<url>scp://www.mycompany.com/www/docs/project/</url>
|
||||
</site>
|
||||
</distributionManagement>
|
||||
---------------
|
||||
|
||||
The <<<id>>> element identifies the repository, so that you can attach credentials to it in your <<<settings.xml>>>
|
||||
file in the same way as you would for any other repository. The URL gives the location to deploy to. Currently,
|
||||
only SSH is supported, as above which copies to the host <<<www.mycompany.com>>> in the path <<</www/docs/project/>>>.
|
||||
|
||||
Deploying the site is done with the <<<site:deploy>>> goal. Note that you cannot just call the deployment goal on its own, however.
|
||||
You must presently run the <<<site:site>>> goal independantly.
|
||||
|
||||
---------------
|
||||
m2 site:site site:deploy
|
||||
---------------
|
||||
|
||||
<<Note:>> the trailing slash in the URL above indicates that any subprojects that inherit this value should append their artifact ID to
|
||||
the path instead of using it as is.
|
||||
|
||||
* Creating a Site Descriptor
|
||||
|
||||
The <<<site.xml>>> file is used to describe the layout of the site, and replaces the navigation file used in Maven 1.0.
|
||||
|
||||
A sample is given below:
|
||||
|
||||
--------------------
|
||||
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
<project name="Maven">
|
||||
<bannerLeft>
|
||||
<name>Maven</name>
|
||||
<src>http://maven.apache.org/images/apache-maven-project.png</src>
|
||||
<href>http://maven.apache.org/</href>
|
||||
</bannerLeft>
|
||||
<bannerRight>
|
||||
<src>http://maven.apache.org/images/maven-small.gif</src>
|
||||
</bannerRight>
|
||||
<body>
|
||||
<links>
|
||||
<item name="Apache" href="http://www.apache.org/" />
|
||||
<item name="Maven 1.0" href="http://maven.apache.org/"/>
|
||||
<item name="Maven 2" href="http://maven.apache.org/maven2/"/>
|
||||
</links>
|
||||
|
||||
<menu name="Maven 2.0">
|
||||
<item name="Introduction" href="index.html"/>
|
||||
<item name="Download" href="download.html"/>
|
||||
<item name="Release Notes" href="release-notes.html" />
|
||||
<item name="General Information" href="about.html"/>
|
||||
<item name="For Maven 1.0 Users" href="maven1.html"/>
|
||||
<item name="Road Map" href="roadmap.html" />
|
||||
</menu>
|
||||
|
||||
${reports}
|
||||
|
||||
...
|
||||
</body>
|
||||
</project>
|
||||
--------------------
|
||||
|
||||
~~TODO: deserves more explanation.
|
||||
|
||||
Note the <<<${reports}>>> string in the navigation. When building the site, this is replaced by menus for any reports
|
||||
that you have configured.
|
||||
|
||||
* Adding Extra Resources
|
||||
|
||||
You can add any arbitrary resources to you site by including them in a
|
||||
<<<resources>>> directory as shown below. Addition CSS will 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 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.
|
||||
|
||||
* 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.
|
||||
|
||||
To add these reports to your site, you must add the plugins to a special <<<reporting>>> section in the POM. The
|
||||
following example shows how to configure the standard project information 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>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</reporting>
|
||||
...
|
||||
-------------------
|
||||
|
||||
If you have included the appropriate <<<${reports}>>> tag in your <<<site.xml>>> descriptor, then when you regenerate
|
||||
the site those items will appear on the menu.
|
||||
|
||||
~~TODO: explain report sets
|
||||
|
||||
* Internationalisation
|
||||
|
||||
Internationalisation in Maven is very simple, as long as the reports you are using have that particular locale
|
||||
defined.
|
||||
|
||||
To enable multiple locales, add configuration similar to the following to your POM:
|
||||
|
||||
-------------------
|
||||
<project>
|
||||
...
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-site-plugin</artifactId>
|
||||
<configuration>
|
||||
<locales>en,fr</locales>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
...
|
||||
-------------------
|
||||
|
||||
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 by language, translated site can evolve independently.
|
||||
|
||||
* How do I use plug-ins?
|
||||
|
||||
* How do I control what version of plug-in I use?
|
||||
|
||||
~~http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix
|
||||
|
||||
|
|
|
|||
|
|
@ -7,3 +7,10 @@
|
|||
------
|
||||
|
||||
Introduction to Archetypes
|
||||
|
||||
What is Archetype?
|
||||
|
||||
In short, Archetype is a Maven project templating toolkit. Archetype
|
||||
will help authors create Maven project templates for users, and provides
|
||||
users with the means to generate parameterized versions of those templates.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue