Maven 3: создание Javadoc для определенных артефактов - PullRequest
Новая
       29

Maven 3: создание Javadoc для определенных артефактов

4 голосов
/ 09 февраля 2011

Я хочу создавать javadoc только для определенных артефактов моего проекта из выделенного docs-проекта.

Это означает, что я хотел бы, например, иметь независимый проект под названием "документы". В docs / pom.xml я хотел бы определить артефакты, которые должны быть включены в сгенерированные javadocs.

Пока я узнал, что мне нужно создать отдельный sources.jar для проектов, которые я хочу включить. Но я не могу понять, как идти дальше.

Пока я могу только представить два подхода:

  1. Получите артефакты (sources.jar), которые я хочу включить, распакуйте их и каким-то образом укажите плагин Javadoc в исходный каталог.

  2. Определите интересующие меня артефакты как зависимости и используйте опцию "dependencySourceInclude" javadoc-плагина. Но я не уверен, что это использование по назначению.

Есть предложения, как решить эту проблему?

1 Ответ

6 голосов
/ 10 февраля 2011

Я нашел решение сам.Это что-то вроде взлома, но это работает для меня.Я решил пойти с моей первой идеей:

Получить артефакты (sources.jar), которые я хочу включить, распаковать их и как-то указать плагин javadoc на каталог с исходным кодом.

Это решение состоит из четырех различных частей, которые я объясню более подробно позже:

  1. Генерация sources.jars во всех артефактах, которые я хочу включить
  2. Распаковать эти sources.jars
  3. Создайте Javadoc, указав плагин 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

В вашем pom.xml, который вы используете для генерации javadoc, вы должны добавить следующие плагины для распаковки файлов 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, указав плагин javadoc на распакованные источники

Теперь сложная часть.Сообщаем javadoc-плагину, где искать исходные файлы.Импортированное определение - это определение <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>

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