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

Question

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

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

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

На данный момент я могу только представить себе два подхода:

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

2. Определить артефакты, которые меня интересуют как dependecy и использовать параметр «dependencySourceInclude» для javadoc-plugin. Но я не уверен, что это использование по назначению.

Любые предложения по решению этой проблемы?

Answer 1

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

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

Это решение имеет четыре Differents части, которые я объясню более подробно:

1. Генерировать sources.jars во всех артефактах, которые я хочу, чтобы включить
2. распаковывать этот sources.jars
3. Создайте Javadoc, указав javadoc-плагин на распакованные источники.
4. Пакет сгенерированных apidocs в zip-файле

Теперь более подробно:

1. Сформировать sources.jars во всех артефактов, которые я хочу, чтобы включить

Для создания sources.jars вы должны использовать Maven-источников-плагин следующим образом:

<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 используются для генерации Javadocs вы должны добавить следующие плагин для распаковки 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 в почтовый файл

Чтобы собрать документы, которые Вы должны использовать maven-assembly-plugin и дополнительный сборочный-файл. Первый плагин-Defintion внутри ПОМ:

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

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