5

我只想从专用文档项目中为我的项目的某些工件生成 javadocs。

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

到目前为止,我了解到我必须为我想要包含的项目生成一个单独的 sources.jar。但我不知道如何从那里继续。

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

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

  2. 将我感兴趣的工件定义为依赖项,并使用 javadoc-plugin 的“dependencySourceInclude”选项。但我不确定这是否按预期使用。

任何建议如何解决这个问题?

4

1 回答 1

7

我自己找到了解决方案。这有点像黑客,但它确实对我有用。我选择了我的第一个想法:

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

这个解决方案有四个不同的部分,我稍后会更详细地解释:

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

现在更详细地说:

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

要生成sources.jars,您必须使用maven-sources-plugin,如下所示:

<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 中的每个项目/模块/工件中执行此操作。

2.解压这些sources.jars

在你用来生成 javadocs 的 pom.xml 中,你必须添加以下插件来解压 sources.jar 文件。

<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>

您可以根据需要添加任意数量的解包执行块。

3. 通过将 javadoc-plugin 指向解压缩的源代码来生成 Javadoc

现在是棘手的部分。让 javadoc-plugin 知道在哪里查找源文件。导入的定义就是<sourcepath>定义。在本节中,我们定义了在步骤 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此时调用时,您最终会在文件夹中找到一个site文件target夹。在此站点文件夹中,您将找到您的 apidocs。但是为了使这个构建所有闪亮的东西,我们想要将 apidocs 组装到一个 zip 存档中。

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

要组装文档,您必须使用maven-assembly-plugin额外的组装文件。首先是你的 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>

组装.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>
于 2011-02-10T09:05:26.560 回答