mirror of
https://github.com/apache/maven.git
synced 2025-02-08 11:05:37 +00:00
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
@ -35,3 +35,7 @@ the JDK configuration equivalent.
|
|||||||
.
|
.
|
||||||
.
|
.
|
||||||
</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 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>
|
<version>3.8.1</version>
|
||||||
<scope>test</scope>
|
<scope>test</scope>
|
||||||
</dependency>
|
</dependency>
|
||||||
<!-- New external dependency -->
|
<!--
|
||||||
|
|
|
||||||
|
| New external dependency
|
||||||
|
|
|
||||||
|
-->
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.apache.codehaus.plexus</groupId>
|
<groupId>org.apache.codehaus.plexus</groupId>
|
||||||
<artifactId>plexus-utils</artifactId>
|
<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?
|
<settings>
|
||||||
~~ o Explain the different formats APT/xdoc/docbook/FAQML
|
.
|
||||||
|
.
|
||||||
|
<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
|
~~http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix
|
||||||
|
|
||||||
|
|||||||
@ -7,3 +7,10 @@
|
|||||||
------
|
------
|
||||||
|
|
||||||
Introduction to Archetypes
|
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…
x
Reference in New Issue
Block a user