Статьи

Публикация документации JavaDoc API при выпуске из Jenkins

В этой статье описывается, как публиковать документацию по JavaDoc API для проекта Maven, созданного на Jenkins, когда этот проект будет выпущен. Документация по JavaDoc API публикуется с использованием того же экземпляра Apache Tomcat 7, на котором работает Jenkins.

мотивация

Я хотел, используя самый простой способ, опубликовать документацию по JavaDoc API для выпусков определенного программного компонента и сделать ее доступной по URL-адресу, уникальному для каждой версии. Кроме того, я хотел сделать возможным перечисление различных версий программного компонента, для которого доступна документация.
Программный компонент построен с использованием Maven, а выпуски производятся с сервера Jenkins.

Необходимые плагины Jenkins

Следующие плагины должны быть установлены в Jenkins, чтобы иметь возможность завершить пример в этой статье:

  • Соответствующий плагин для используемой вами системы управления исходным кодом.
    В этой статье я буду использовать Git, но любая другая система управления исходным кодом работает одинаково хорошо, если для нее доступен плагин Jenkins.
  • Плагин Maven Project.
    Позволяет создавать рабочие места Maven 2/3 в Jenkins.
  • Плагин выпуска Jenkins M2
    Также известен как подключаемый модуль выпуска Maven, который позволяет выполнять выпуски Maven из задания Jenkins.

Подготовьте Apache Tomcat

Следующие шаги готовят специальное веб-приложение, веб-приложение для документации, в Apache Tomcat 7, в которое будет опубликована документация по JavaDoc API. Предполагается, что каталог, содержащий веб-приложения, развернутые в Tomcat, находится в каталоге webapps в каталоге установки Tomcat.

  • В каталоге webapps в домашнем каталоге Tomcat создайте каталог для веб-приложения документации.
    В этом примере я называю свой каталог «api-Documentation», но вы, конечно, можете выбрать любое имя, которое считаете подходящим.
  • В каталоге веб-приложения документации создайте каталог WEB-INF.
  • В каталоге WEB-INF, созданном на предыдущем шаге, создайте файл с именем «web.xml».
    Результирующая структура каталогов должна выглядеть следующим образом:

Структура каталогов Tomcat

  • Вставьте следующее в файл web.xml, созданный на предыдущем шаге:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
    Configures the default servlet to allow directory listings for the
    documentation web application.
-->
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  version="3.0">
    <servlet>
        <servlet-name>default</servlet-name>
        <servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
        <init-param>
            <param-name>debug</param-name>
            <param-value>0</param-value>
        </init-param>
        <init-param>
            <param-name>listings</param-name>
            <param-value>true</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <!--
        Start of security configuration.
        This section can be removed if no security is required for API documentation.
    -->
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>API Documentation Root</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <!--
                This role must be present in the tomcat-users.xml file.
                The username and password to enter when accessing API documentation is the
                username and password of any user belonging to this role.
            -->
            <role-name>manager-gui</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>API Documentation</realm-name>
    </login-config>

    <security-role>
        <description>The role that is required to access the API Documentation</description>
        <!--
            This role must be present in the tomcat-users.xml file.
            The username and password to enter when accessing API documentation is the
            username and password of any user belonging to this role.
        -->
        <role-name>manager-gui</role-name>
    </security-role>
    <!-- End of security configuration. -->
</web-app>

Приведенный выше файл конфигурации веб-приложения настраивает сервлет Tomcat по умолчанию, чтобы разрешить списки каталогов. Поскольку файл конфигурации находится в определенном веб-приложении, списки каталогов будут разрешены только в этом конкретном веб-приложении.
Кроме того, настроена безопасность, требующая входа в систему, прежде чем вы сможете просматривать документацию по API. Обратите внимание, что роль, указанная в элементе, должна быть определена в файле tomcat-users.xml. Удаление указанного раздела конфигурации безопасности устраняет ограничения безопасности для документации API.

Пожалуйста, обратитесь к файлу web.xml в каталоге conf в каталоге Apache Tomcat 7 для получения информации о различных альтернативах конфигурации, доступных для сервлета по умолчанию.

Настройте проект Maven

Предполагая, что программный компонент, для которого я хочу опубликовать документацию по JavaDoc API, уже является проектом Maven, мне все еще нужно убедиться в следующем:

  • JavaDoc API документация создана для программного компонента.
  • Документация по JavaDoc API создается в правильном месте, чтобы обеспечить возможность развертывания подключаемым модулем сайта Maven.
    То есть я хочу, чтобы документация находилась в каталоге сайта в целевом каталоге проекта Maven, а не непосредственно в целевом каталоге проекта.
  • Документация публикуется не каждой сборкой.
    Поскольку я хочу сохранить документацию только для сборок релизов, мне нужно иметь возможность контролировать, когда документация публикуется.
  • Документация публикуется в соответствующем месте.
    Я ожидаю, что в будущем я хочу опубликовать документацию по JavaDoc API для нескольких программных компонентов. Я также хочу иметь возможность публиковать документацию для различных версий программного компонента.

Следующий файл Maven pom.xml содержит конфигурацию для создания и публикации JavaDoc. Части, не относящиеся к созданию документации, были опущены.

<project
xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">

    ...

    <!--
        Determines to which repository releases of the project are deployed.
        In this example, artifacts are deployed to a directory on the
        same computer on which the Jenkins build server is run.
        Note that this is just the minimal configuration required in order
        to be able to perform a Maven release, not recommended for production.
        Reference: http://maven.apache.org/pom.html#Distribution_Management
    -->
    <distributionManagement>
        <repository>
            <uniqueVersion>false</uniqueVersion>
            <id>home1</id>
            <name>Home Repository</name>
            <url>file://C:/MyProjectDeployDirectory/</url>
            <layout>default</layout>
        </repository>
    </distributionManagement>

    <!--
        SCM configuration is necessary in order to enable Maven to manage
        the version of the project when releasing a new version on the
        Jenkins build server.
        The configuration varies depending on which provider is used
        (for example, Git, Subversion, etc).
        In this example, Git is used.
        Reference: http://maven.apache.org/pom.html#SCM
    -->
    <scm>
       <connection>scm:git:file://localhost/C:/GitRepo/MyProject/</connection>
       <developerConnection>scm:git:file://localhost/C:/GitRepo/MyProject/</developerConnection>
       <tag>HEAD</tag>
    </scm>

    <properties>
        <!--
            Path to the root directory of the documentation web application.
            This example assumes that the documentation web application
            is located in the same Tomcat instance as the Jenkins build
            server runs.
        -->
        <release.javadoc.root.path>[path to Tomcat home]/webapps/api-documentation/</release.javadoc.root.path>

        ...
    </properties>

    ...

    <profiles>
        <!--
            Profile for generation and publishing of release JavaDoc
            documentation.
            Use: mvn -P releaseDocumentation site
            References: http://maven.apache.org/guides/introduction/introduction-to-profiles.html
        -->
        <profile>
            <!-- 
                Name of the Maven build profile.
                Used in project's Jenkins job configuration.
            -->
            <id>releaseDocumentation</id>
            <build>
                <plugins>
                    <!--
                        In preparation of site generation, extract the release
                        version number to a maven property.
                        Performed during pre-site phase.
                    -->
                    <plugin>
                        <groupId>org.codehaus.mojo</groupId>
                        <artifactId>build-helper-maven-plugin</artifactId>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <id>regex-property</id>
                                <goals>
                                    <goal>regex-property</goal>
                                </goals>
                                <configuration>
                                    <name>release_version</name>
                                    <value>${project.version}</value>
                                    <regex>-SNAPSHOT</regex>
                                    <replacement />
                                    <failIfNoMatch>false</failIfNoMatch>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                    <!--
                        JavaDoc generation.
                        JavaDoc is generated during pre-site phase.
                    -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-javadoc-plugin</artifactId>
                        <version>2.9.1</version>
                        <executions>
                            <execution>
                                <phase>pre-site</phase>
                                <goals>
                                    <goal>javadoc</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <show>private</show>
                        </configuration>
                    </plugin>
                    <!--
                        Copy JavaDoc to publish directory.
                        Performed during the site phase.
                        If changing the phase, make sure that copying the
                        documentation is performed after having generated
                        the JavaDoc.
                    -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-resources-plugin</artifactId>
                        <version>2.6</version>
                        <executions>
                            <execution>
                                <id>copy-resources</id>
                                <phase>site</phase>
                                <goals>
                                    <goal>copy-resources</goal>
                                </goals>
                                <configuration>
                                    <generateProjectInfo>false</generateProjectInfo>
                                    <generateReports>false</generateReports>
                                    <outputDirectory>${release.javadoc.root.path}${project.artifactId}-${release_version}/</outputDirectory>
                                    <resources>
                                        <resource>
                                            <directory>${project.build.directory}/site/</directory>
                                            <filtering>true</filtering>
                                        </resource>
                                    </resources>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
            <!--
                Include this section to disable, or configure, generation
                of project info report(s).
                In this case, all project info reports have been disabled.
            -->
            <reporting>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-project-info-reports-plugin</artifactId>
                        <version>2.7</version>
                        <reportSets>
                            <reportSet>
                                <reports>
                                </reports>
                            </reportSet>
                        </reportSets>
                    </plugin>
                </plugins>
            </reporting>
        </profile>
    </profiles>
</project>

Обратите внимание, что:

  • Элемент необходим для того, чтобы Maven знал, в каком хранилище развертывать артефакты проекта при выполнении выпуска.
    В этом примере показана минимальная конфигурация с использованием локального каталога в качестве цели, что не рекомендуется для производства.
  • Невозможно использовать элемент, чтобы указать, где публиковать документацию, поскольку эта конфигурация оценивается до того, как мы сможем установить свойства Maven с помощью подключаемого модуля помощника по сборке Maven.
  • Элемент указывает, где находится проект в системе управления исходным кодом.
    Эта конфигурация необходима для того, чтобы Maven мог обновлять номер версии проекта при выполнении выпуска. Эта конфигурация зависит от используемой системы управления исходным кодом (пример: Subversion, Git, Perforce и т. Д.).
    В этом примере система управления исходным кодом Git используется с репозиторием Git, расположенным в локальном каталоге.
  • В элементе <properties> определено свойство Maven с именем «release.javadoc.root.path».
    Это свойство указывает локальный каталог, в который будет скопирована документация по версии JavaDoc. Строка «[путь к домашнему каталогу Tomcat]» должна быть заменена путем к каталогу установки Tomcat или каталогу, который содержит каталог webapps, используемый Tomcat, если его нет в каталоге Tomcat.
  • В элементе <profile> определен профиль сборки Maven с именем «releaseDocumentation».
    Это профиль сборки Maven, который определяет, что произойдет, когда будет выпущена и опубликована документация выпуска JavaDoc.
  • Первый плагин в этом профиле — это вспомогательный плагин сборки Maven.
    Он используется для удаления части «-SNAPHOT» из номера версии программного компонента и сохранения результата в свойстве Maven «release_version».
    Трудно перехватить работу плагина релиза Maven на этапе, когда номер версии релиза доступен, поэтому эта стратегия была выбрана для упрощения конфигурации Maven.
  • Подключаемый модуль помощника по сборке Maven настроен для выполнения на этапе предварительной настройки Maven.
    Это для того, чтобы стать частью цели сайта Maven, которую мы будем использовать для создания и публикации документации JavaDoc.
  • Подключаемый модуль Maven JavaDoc используется для создания JavaDoc.
    Не удивительно, за исключением того, что фаза выполнения настроена на предварительный сайт. Как и в случае с подключаемым модулем сборки Maven, чтобы стать частью цели сайта Maven, которую мы будем использовать для создания и публикации документации JavaDoc.
  • Подключаемый модуль ресурсов Maven используется для копирования (публикации) документации JavaDoc в веб-приложение API-документации в Tomcat.
    Этот плагин будет работать во время фазы сайта Maven. Фаза сайта выполняется после фазы перед сайтом, и это гарантирует, что JavaDoc был создан и что свойство Maven “release_version” было установлено.

Чтобы сгенерировать и опубликовать документацию JavaDoc для программного компонента, мы можем теперь выполнить следующую команду:

mvn -P releaseDocumentation site

Настройте работу Дженкинс

Чтобы сгенерировать и опубликовать документацию в рамках выпуска Maven, выполненного в Jenkins, нам необходимо включить указанное выше свойство и цель Maven в цели выпуска задания Jenkins для программного компонента.
В моем случае раздел Build Environment конфигурации задания выглядит следующим образом:

Конфигурация работы ДженкинсаНе забудьте сохранить конфигурацию задания после внесения изменений!

Посмотреть проект JavaDoc

Теперь, когда я выполняю релиз Maven от Jenkins, документация публикуется, и я могу просмотреть документацию, доступную для различных компонентов программного обеспечения и их разных версий, открыв URL-адрес http: // localhost: 8080 / api-Documentation / в моем браузере и затем перейдите в соответствующий каталог.

На первой странице вы увидите список проектов и версий, для которых был опубликован JavaDoc:

Корень документации API

Нажмите на ссылку для проекта и версии, какую JavaDoc вы хотите просмотреть. В моем примере я нажимаю ссылку для версии 1.0.5 проекта JMSRequestReply:

Проект документации API

Нажмите на ссылку «apidocs» для просмотра JavaDoc.