Maven javadoc - как включить централизованные ресурсы

Я пытаюсь включить централизованные ресурсы (например, файлы изображений, файлы js) в свой javadoc, созданный Maven. Такие централизованные ресурсы будут поступать из зависимости. (в моем случае я хотел бы всегда включать определенные ресурсы, файлы Javascript, что позволяет делать красивую подсветку синтаксиса кода примера внутри Javadoc, а также использовать специальную таблицу стилей)

Там содержится существенная информация о том, как это сделать, если вы включаете свои ресурсы локально с вашим проектом. Это не то, что я хочу, поскольку мне нужно сделать это для каждого проекта в моей компании. Таким образом, конфигурация должна войти в общедоступный POM файл, из которого наследуются все проекты в нашей компании.

Обратите внимание, что для stylesheet это довольно легко сделать, поскольку Плагин Maven позволяет этому файлу исходить из зависимости. Я ищу что-то подобное, кроме "ресурсов". В принципе было бы глупо, что мне пришлось бы копировать такие вещи, как логотип нашей компании, в каждый проект. Этого я бы хотел избежать.

Если это напрямую не поддерживается Maven Javadoc Plugin (я не могу понять, если это так), то я предполагаю альтернативу подход может заключаться в использовании Maven Dependency Plugin для копирования моих централизованных ресурсов javadoc в проект. Однако этот подход имеет как минимум два недостатка:

Ответы

Ответ 1

Я полностью пропустил параметр конфигурации resourcesArtifacts в плагине Maven Javadoc. Это ключ к тому, чтобы заставить это работать.

Я объясню это в два этапа:

Проект Maven для хранения ваших централизованных ресурсов Javadoc (настраиваемая таблица стилей (если вы хотите), логотипов, библиотек javascript и т.д.)
Что положить в помпу вашей компании, чтобы все Javadocs в вашей компании выглядели одинаково.

Проект настройки Javadoc

Этот "проект" будет содержать ваши пользовательские ресурсы Javadoc. Это проект Maven, но он не содержит исходного кода Java. Просто создайте стандартный проект Maven. Создайте каталог src/main/resources. Все, что вы помещаете в этот каталог, в конечном итоге будет помещено в корень каждого создаваемого вами пакета Javadoc. Если вы поместите туда имя файла say stylesheet.css оно будет эффективно перезаписывать стандартную таблицу стилей Javadoc.

У меня есть каталог src/main/resources:

Файл stylesheet.css. Этот файл является версией нашей таблицы стилей Javadoc. Он немного отличается от стандартной таблицы стилей тем, что исправляет некоторые недостатки JDK8 (JDK8 javadoc читается плохо), но также меняет некоторые цвета, чтобы соответствовать бренду компании и так далее.
syntaxhighlighter в который я помещаю соответствующие файлы из SyntaxHighlighter. В моем случае это файлы shCore.js, shBrushJava.js, shCore.css и shThemeDefault.css поскольку меня интересует только подсветка синтаксиса для языка Java, а также я хочу использовать тему по умолчанию для SyntaxHighlighter.

Мой проект Maven координаты

<groupId>com.acme.javadoc</groupId>
<artifactId>customization</artifactId>

но не стесняйтесь называть его так, как вам нравится.

Помните: это просто стандартный проект Maven, поэтому вы можете поставить его под контроль исходного кода и так далее.

Теперь создайте (и, возможно, выпустите) этот проект.

Изменения в POM для всей компании

Приведенный ниже рецепт предполагает, что у вас есть некая POM для всей компании, которая позволяет вам настраивать Maven для многих проектов в одном месте. Если у вас нет такого центрального родительского POM, вам нужно будет выполнить нижеприведенное в каждом проекте.

<profiles>
    <profile>
        <activation>
            <jdk>1.8</jdk>
        </activation>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.10.3</version>
                    <configuration>
                        <resourcesArtifacts>
                            <resourceArtifact>
                                <groupId>com.acme.javadoc</groupId>
                                <artifactId>customization</artifactId>
                                <version>1.0-SNAPSHOT</version>
                            </resourceArtifact>
                        </resourcesArtifacts>
                        <!-- Add SyntaxHighlighter feature.
                              This gets added to the top of every Javadoc html file -->
                        <top><![CDATA[
                            <script src="{@docRoot}/syntaxhighlighter/shCore.js" type="text/javascript"></script>
                            <script src="{@docRoot}/syntaxhighlighter/shBrushJava.js" type="text/javascript"></script>
                            <link href="{@docRoot}/syntaxhighlighter/shCore.css" rel="stylesheet" type="text/css" title="Style">
                            <link href="{@docRoot}/syntaxhighlighter/shThemeDefault.css" rel="stylesheet" type="text/css" title="Style">
                            ]]>
                        </top>                            
                        <!-- Activate and customize SyntaxHighlighter feature 
                             This gets added to the bottom of every Javadoc html file -->
                        <footer><![CDATA[
                            <script type="text/javascript">
                               SyntaxHighlighter.defaults["auto-links"] = false;
                               SyntaxHighlighter.defaults["tab-size"] = 2;
                               SyntaxHighlighter.all();
                            </script>
                        ]]></footer>                            
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

Вот что произойдет: каждый раз, когда проект, унаследованный от POM для всей компании, создает пакет Javadoc, он делает это с настройками maven-javadoc-plugin выше. Как вы заметили, все это помещается в профиль и активируется только в том случае, если сборка Maven работает под JDK8. Если вам не нужно это условие, вы можете изменить его, чтобы профиль всегда активировался, а не был активирован по условию.

resourceArtifact указывает на наш проект с нашими активами Javadoc. Этот артефакт (который является jar) распаковывается в сгенерированную директорию корня пакета Javadoc. Из документации мне не было ясно, что происходит распаковка, но она действительно есть. Материал из архива resourceArtifact слепо копируется в пакет, поэтому будьте осторожны с именами. Это перезапишет что-нибудь с похожим именем. В случае с нашим файлом stylesheet.css это действительно то, что мы хотим, так хорошо. В любом случае вам просто нужно быть осторожным с тем, что вы вкладываете в проект настройки Javadoc.

Чего мы достигли

Ресурсы Javadoc (таблица стилей, логотип, файлы JS) могут находиться под контролем исходного кода.
Ресурсы Javadoc могут быть централизованы.
Добавлена возможность подсветки синтаксиса при написании фрагментов кода Java в комментариях Javadoc.
Созданный пакет Javadoc является автономным. Не зависит от каких-либо внешних ресурсов.

Как сделать подсветку синтаксиса в Javadoc

С учетом вышесказанного все ваши Javadoc автоматически теперь наследуют возможность подсветки синтаксиса. Все, что вам нужно сделать, это добавить class="bruch:java" в ваши теги <pre>. Вот пример:

/**
 * Howdy devs. Normally you would use create a
 * class something like this:
 * 
 * 
 * <pre class="brush:java">
 * public class MyClass1 {
 *   
 *   public static String getVar(String x1, int x2) {
 *      if ( 3 &lt; 10 ) {
 *         return "x"; 
 *      } else {
 *         return "y";
 *      }
 *   }
 * } 
 * </pre>
 * 
 * That all, folks.
 * 
 * @since 1.3
 */

Обратите внимание, как мне пришлось убежать от знака <. Стандартный прием, который многие из нас используют, чтобы избежать необходимости делать это, вставляя {@code} в теги <pre>, не работает с SyntaxHighlighter. Eeew.

И вот как это будет выглядеть в Javadoc:

Тада!

Вы можете расширить рецепт, чтобы добавить больше настроек, например, всегда размещать логотип компании в нижнем колонтитуле Javadoc и т.д.

Производительность этого решения

Каждый раз, когда вы делаете сборку Javadoc, вы замечаете этот дополнительный шаг в своем выводе Maven:

Это, вероятно, украдет секунду или две вашего времени сборки - если не меньше. И только при создании артефактов Javadoc, конечно.

ОБНОВЛЕНИЕ, СВЯЗАННОЕ С JDK 8u121

Начиная с JDK 8u121, инструмент Javadoc (javadoc) больше не будет по умолчанию позволять вам включать ресурсы Javascript в вашу сборку. См. Примечания к выпуску для получения дополнительной информации. Плагин Maven Javadoc неявно использует инструмент javadoc и поэтому также подвержен влиянию. В javadoc есть новый параметр командной строки, который нужно добавить, чтобы он работал: --allow-script-in-comments.

Другими словами, если вы используете JDK 8u121 или новее, POM вашей компании должен добавить этот параметр командной строки:

<profiles>
    <profile>
        <activation>
            <jdk>1.8</jdk>
        </activation>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.10.3</version>
                    <configuration>
                        ...
                        ...
                        <!-- Required as of JDK 8u121 -->
                        <additionalparam>--allow-script-in-comments</additionalparam>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

Плохая вещь в том, что сделал Oracle, заключается в том, что сборка теперь зависит от младшего номера версии JDK. Если вам случится использовать вышеупомянутое в JDK до 8u121, оно завершится с ошибкой, потому что --allow-script-in-comments неизвестен.