Maven javadoc - 如何包含集中资源

Question

我正在尝试将集中资源（例如图像文件、js 文件）包含到我的 Maven 生成的 javadoc 中。这种集中的资源将来自依赖项。（在我的例子中，我想总是包含某些资源，Javascript 文件，它允许在 Javadoc 中对示例代码进行很好的语法高亮显示，并且还可以使用特殊的样式表）

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

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

如果这个不直接支持Maven Javadoc Plugin (I cannot figure out if it is) then I'm guessing an alternative approach might be to use the Maven Dependency Plugin复制我集中的javadoc资源到项目中。然而，这种方法至少有两个缺点：

这种依赖不是项目的真正依赖，不应该这样声明。它是 maven-javadoc-plugin 的依赖项，而不是项目本身的依赖项。
我需要想办法让复制只有在生成 javadoc 时才会发生对项目的依赖请求。

请帮忙。

Answer 1

我完全忽略了 resourcesArtifacts config parameter on the Maven Javadoc plugin。这是让它发挥作用的关键。

我将分两步解释：

一个 Maven 项目来保存您的集中 Javadoc 资产（自定义样式表（如果需要）、徽标、javascript 库等）
为了拥有所有 Java 文档，将什么放入公司范围的 pom 在你们公司看起来都一样。

Java文档定制项目

此 'project' 将保存您的自定义 Java 文档资产。它是一个 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 资产。这个工件（它是一个 jar）被解压到生成的 Javadoc 包的根目录中。从 documentation 中我不清楚正在进行解包，但确实存在。 resourceArtifact jar 中的内容会被盲目地复制到包中，因此请小心命名。它将覆盖任何具有相似名称的内容。对于我们的 stylesheet.css 文件，这实际上是我们想要的，所以很好。在任何情况下，您只需要注意放入 Javadoc 自定义项目的内容即可。

我们的成就

Java文档资源（样式表、徽标、JS 文件）可以在源代码管理下。
Java可以集中doc资源
添加了在 Java 文档注释中编写 Java 代码片段时进行语法高亮显示的功能。
创建的 Javadoc 包是独立的。不依赖于任何外部资源。

如何在 Javadoc

中进行语法高亮显示

有了以上所有内容，您的 Java 文档现在会自动继承语法高亮显示的功能。您所要做的就是将 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 使用 SyntaxHighlighter。额。

这就是它在 Java文档中的样子：

多田!

您可以扩展配方以添加更多定制，例如始终在 Java 文档页脚等处放置公司徽标

此解决方案的性能

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

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

Maven javadoc - 如何包含集中资源

Maven javadoc - how to include centralized resources

maven

syntax-highlighting

javadoc

Java文档定制项目

对公司范围 POM 的更改

我们的成就

如何在 Javadoc

此解决方案的性能

与 JDK 8u121