src/site/apt/examples/links-configuration.apt.vm

 ------
 Configuring links and offlineLinks Parameters
 ------
 Vincent Siveton
 ------
 2009-08-04
 ------

~~ 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 <<<links>>> Parameter

~~ Using anchor links produces a Velocity error.
  You can add cross reference links to external projects using the {{{../javadoc-mojo.html}\<links/\>}}
  parameter. For instance:

+-----+
<project>
  ...
  <reporting> (or <build>)
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <links>
            <link>http://commons.apache.org/dbcp/apidocs/</link>
            <link>http://commons.apache.org/fileupload/apidocs/</link>
          </links>
            ...
        </configuration>
      </plugin>
    </plugins>
  </reporting> (or </build>)
  ...
</project>
+-----+

  <<Important Note>>: according the
  {{{http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#package-list}Javadoc specifications}},
  all given links <<should>> have a fetchable <<</package-list>>> file.

  You can try to detect all Javadoc links for the project's dependencies. You need to use the
  {{{../javadoc-mojo.html#detectLinks}\<detectLinks/\>}} parameter. Detected links are based on the default Maven
  conventions. For instance, if your project has a dependency on
  {{{https://commons.apache.org/lang/}Apache Commons Lang}} such as:

+-----+
<project>
  ...
  <dependencies>
    <dependency>
      <groupId>commons-lang</groupId>
      <artifactId>commons-lang</artifactId>
      <versions>2.4</version>
    </dependency>
  </dependencies>
  ...
</project>
+-----+

  The added Javadoc link will be {{https://commons.apache.org/lang/apidocs}}.

  A Javadoc API link, depending the JDK version used by
  your project, will be added. The version of the Javadoc API is detected from the value of the
  {{{https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#source}\<source/\>}}
  parameter in the <<<{{{http://maven.apache.org/plugins/maven-compiler-plugin}org.apache.maven.plugins:maven-compiler-plugin}}>>>
  (defined in $\{project.build.plugins\} or in $\{project.build.pluginManagement\}), or computed via the Javadoc Tool
  executable. To skip this link, you need to configure
  {{{../javadoc-mojo.html#detectJavaApiLink}\<detectJavaApiLink/\>}} to <<<false>>>.

  <<Note>>: if you are using an unsupported JDK like 7.0, you can add its Javadoc API url using the
  {{{../javadoc-mojo.html#javaApiLinks}\<javaApiLinks/\>}} parameter, i.e.:

+-----+
<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>
+-----+

~~ Using anchor links produces a Velocity error.
  Refer to {{{../javadoc-mojo.html}\<links/>}} parameter for more information.

Configuring <<<offlineLinks>>> Parameter

  If your project has modules, you can add cross reference links to your modules when your goals are not aggregator
  goals. For instance, if your project has two modules i.e.:

+-----+
<project>
  ...
  <modules>
    <module>module1</module>
    <module>module2</module>
  </modules>
  ...
</project>
+-----+

  The offlineLinks for <<module1>> will be <<</absolute/path/to/>>><<module2>><<</target/site/apidocs>>> and
  the offlineLinks for <<module2>> will be <<</absolute/path/to/>>><<module1>><<</target/site/apidocs>>>.

  <<Important Note>>: all offlinelinks are based on the $\{project.url\} if present.

  You can disable the cross reference for <<<offlineLinks>>> using the
  {{{../javadoc-mojo.html#detectOfflineLinks}\<detectOfflineLinks/>}} parameter.

  Refer to {{{../javadoc-mojo.html#offlineLinks}\<offlineLinks/\>}} parameter for more information.