Maven javadoc - 如何包含集中资源

Question

我正在尝试将集中资源(例如图像文件、js 文件)包含到我的 Maven 生成的 javadoc 中。这种集中的资源将来自依赖。 (在我的情况下，我希望始终包含某些资源、Javascript 文件，这样可以在 Javadoc 中对示例代码进行很好的语法高亮显示，并且还可以使用特殊的样式表)

如果您在项目中包含本地资源，则有关于如何执行此操作的大量信息。这不是我想要的，因为我需要为公司的每个项目都这样做。所以配置需要进入公司范围的POM文件，我们公司所有项目都继承自该文件。

请注意，对于 样式表这很容易做到，因为 Maven plugin allows for this file to come from a dependency .我正在寻找类似的东西，除了“资源”。基本上，我必须将公司徽标之类的东西复制到每个项目中似乎很愚蠢。这就是我想避免的。

如果 Maven Javadoc Plugin 不直接支持此操作(我不知道是不是)然后我猜另一种方法可能是使用 Maven Dependency Plugin将我的集中 javadoc 资源复制到项目中。然而，这种方法至少有两个缺点:

这种依赖不是项目的真正依赖，不应如此声明。它是 maven-javadoc-plugin 的依赖项，而不是项目本身的依赖项。

我需要想出一种方法，以便复制
对项目的依赖仅在 javadoc 生成时发生
要求。

请帮忙。

Answer 1

我完全忽略了 resourcesArtifacts Maven Javadoc plugin 上的配置参数.这是让它发挥作用的关键。

我将分两步解释这一点:

一个 Maven 项目，用于保存您的集中式 Javadoc Assets (定制的
样式表(如果需要)、徽标、javascript 库等)

为了拥有所有 Javadoc，应该在公司范围内的 pom 中放入什么
在你的公司看起来一样。

Javadoc 定制项目

这个“项目”将保存您的自定义 Javadoc Assets 。它是一个 Maven 项目，但它不包含任何 Java 源代码。只需创建一个标准的 Maven 项目。创建一个 src/main/resources目录。您放入此目录中的所有内容最终都会放入您创建的每个 Javadoc 包的根目录中。如果你把文件名说成 stylesheet.css在那里它将有效地覆盖标准的 Javadoc 样式表。

我我的 src/main/resources我有目录:

一个 stylesheet.css文件。该文件是我们公司版本的 Javadoc 样式表。它与标准样式表略有不同，因为它修复了一些 JDK8 缺陷( JDK8 javadoc readability sucks )，但也更改了一些颜色以符合公司品牌等。

一个子目录，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 Assets 指向我们的项目。这个 Artifact (它是一个 jar)被解压到生成的 Javadoc 包的根目录中。我不清楚 documentation有一个解包正在进行，但确实有。来自 resourceArtifact 的东西jar 被盲目地复制到包中，所以命名时要小心。它将覆盖任何类似名称的内容。以我们的 stylesheet.css 为例文件这实际上是我们想要的，所以很好。在任何情况下，您只需要小心放入 Javadoc 定制项目中的内容即可。

我们取得的成就

Javadoc 资源(样式表、徽标、JS 文件)可以受到源代码控制。

Javadoc 资源可以集中。

添加了在 Javadoc 注释中编写 Java 代码片段时进行语法突出显示的功能。

创建的 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's all, folks.
 * 
 * @since 1.3
 */

请注意我是如何逃避 < 符号的。我们中的许多人为了避免这样做而使用的标准技巧，即嵌入 {@code}内 <pre>标签, doesn't work使用语法高亮。哎哟。

这就是它在 Javadoc 中的样子:



多田!

您可以扩展配方以添加更多自定义，例如始终在 Javadoc 页脚等中放置公司徽标。

此解决方案的性能

每次进行 Javadoc 构建时，您都会在 Maven 输出中注意到这个额外的步骤:



它可能会占用您一两秒钟的构建时间 - 如果不是更少的话。当然，只有在构建 Javadoc Artifact 时。

与 JDK 8u121 相关的更新

从 JDK 8u121 开始，Javadoc 工具 ( javadoc ) 默认不再允许您在构建中包含 Javascript 资源。见 Release Notes想要查询更多的信息。 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 次要版本号。如果您碰巧在 8u121 之前的 JDK 上使用上述内容，它将退出并显示错误，因为 --allow-script-in-comments未知。