Maven 3:为定义的工件生成Javadoc [英] Maven 3: Generate Javadoc for defined artifacts

问题描述

我只想从专用的docs-project中为项目的某些工件生成javadocs.

I want to generate javadocs only for certain artifacts of my project from within a dedicated docs-project.

这意味着我想有一个名为"docs"的独立项目.在docs/pom.xml中，我想定义应包含在生成的javadocs中的工件.

That means that I would like to have an independent project called "docs" for example. In the docs/pom.xml I would like to define the artifacts that should be included in the generated javadocs.

到目前为止，我了解到必须为要包含的项目生成一个单独的sources.jar.但是我不知道该怎么做.

So far I learned that I have to generate a separate sources.jar for the projects I want to include. But I can't figure out how to go on from there.

现在我只能想象两种方法:

For now I can only imagine two approaches:

1. 获取要包含的工件(sources.jar)，解压缩它们，并以某种方式将Javadoc插件指向源目录.

1. Get the artifacts (sources.jar) I want to include, unpack them and somehow point the Javadoc plugin to the source directory.

将我感兴趣的工件定义为依赖项，并使用javadoc-plugin的"dependencySourceInclude"选项.但是我不确定这是否符合预期用途.

Define the artifacts I am interested as dependency and use the "dependencySourceInclude" option of the javadoc-plugin. But I am not sure if this is usage as intended.

任何建议如何解决此问题?

Any suggestions how to solve this problem?

推荐答案

我已经找到了解决方案.这是一个小技巧，但确实对我有用.我选择了第一个想法:

I have found a solution my self. It is a bit of a hack but it does work for me. I chose to go with my first idea:

获取要包含的工件(sources.jar)，解压缩它们，并以某种方式将javadoc插件指向源目录.

Get the artifacts (sources.jar) I want to include, unpack them and somehow point the javadoc plugin to the source directory.

此解决方案包含四个不同的部分，我将在后面详细解释:

This solution has four differents parts which I'll explain in more detail later:

1. 在我想包含的所有工件中生成sources.jars
2. 解压这些sources.jars
3. 通过将javadoc-plugin指向解压后的源代码来生成Javadoc
4. 将生成的apidocs打包为一个zip文件

现在更详细:

1.在我想包含的所有工件中生成sources.jars

要生成sources.jar，必须使用maven-sources-plugin，如下所示:

To generate sources.jars you have to use the maven-sources-plugin as follows:

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-source-plugin</artifactId>
      <version>2.1.2</version>
      <executions>
        <execution>
          <id>bundle-sources</id>
          <phase>package</phase>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

您必须在要包含在apidocs中的每个项目/模块/工件中执行此操作.

You have to do this in every project/module/artifact you want to include in your apidocs.

2.解压那些sources.jars

在pom.xml文件中，您需要使用它来生成javadocs，您必须添加以下插件来解压缩sources.jar文件.

In you pom.xml you use to generate the javadocs you have to add the following plugins to unpack the sources.jar files.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>unpack-artifact-sources</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>unpack</goal>
      </goals>
      <configuration>
        <artifactItems>
          <artifactItem>
            <groupId>${project.groupId}</groupId>
            <artifactId><!-- your artifact here --></artifactId>
            <version>${project.version}</version>
            <classifier>sources</classifier>
            <overWrite>true</overWrite>
          </artifactItem>
        </artifactItems>
        <outputDirectory>${project.build.directory}/unpack_sources</outputDirectory>
      </configuration>
    </execution>
    <!-- add more unpack-executions here -->
  </executions>
</plugin>

您可以根据需要添加任意数量的unpack-execution-blocks.

You can add as many unpack-execution-blocks as you like.

3.通过将javadoc插件指向未打包的源来生成Javadoc

现在棘手的部分.让javadoc-plugin知道在哪里寻找源文件.导入的定义为<sourcepath>定义.在本节中，我们定义在第2步中解压缩源文件的文件夹.

Now the tricky part. Letting the javadoc-plugin know where to look for the source files. The imported definition is the <sourcepath> definition. In this section we define the folder where we have unpacked the sources in step 2.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.7</version>
  <configuration>
    <sourcepath>${project.build.directory}/unpack_sources</sourcepath>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>javadoc</goal>
      </goals>
      <phase>process-resources</phase>
    </execution>
  </executions>
</plugin>

这时调用mvn clean install时，您将在target文件夹内最终找到一个site文件夹.在此站点文件夹中，您将找到apidocs.但是，要使此构建物更加闪亮，我们希望将apidocs组装成一个zip存档.

When you call mvn clean install at this point you will end up with a site folder inside your target folder. In this site folder you'll find your apidocs. But to make this build all shiny and stuff we want to assemble the apidocs into a zip archive.

4.将生成的apidocs打包为一个zip文件

要汇编文档，您必须使用maven-assembly-plugin和一个额外的汇编文件. 首先在pom内定义插件:

To assemble the docs you have to use the maven-assembly-plugin and a extra assembly-file. First the plugin-defintion inside your pom:

<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <executions>
    <execution>
      <id>docs-assembly</id>
      <phase>package</phase>
      <configuration>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/main/assembly/assemble.xml</descriptor>
        </descriptors>
      </configuration>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

assemble.xml:

assemble.xml:

<?xml version="1.0" encoding="UTF-8"?>
<assembly>
  <id>${project.build.finalName}</id>
  <formats>
    <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <directory>target/site/apidocs</directory>
      <outputDirectory>/</outputDirectory>
    </fileSet>
  </fileSets>
</assembly>

这篇关于Maven 3:为定义的工件生成Javadoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！