Maven javadoc - 如何包含集中资源

Question

我正在尝试将集中资源(例如图像文件,js文件)包含到我的Maven生成的javadoc中.这种集中资源将来自依赖.(在我的情况下,我希望始终包含某些资源,Javascript文件,允许在Javadoc中对示例代码进行很好的语法突出显示,以及使用特殊的样式表)

如果您在本地将资源包含在项目中,那么有大量有关如何执行此操作的信息.这不是我想要的,因为我需要为我公司的每个项目做这件事.因此,配置需要进入公司范围的POM文件,我们公司的所有项目都从该文件继承.

请注意,对于样式表,这很容易做到,因为Maven插件允许此文件来自依赖项.我正在寻找类似的东西,除了'资源'.基本上,我不得不将像公司徽标这样的东西复制到每个项目中似乎很愚蠢.这就是我想要避免的.

如果Maven Javadoc插件没有直接支持这个(我不知道是不是这样),那么我猜测另一种方法可能是使用Maven Dependency Plugin将我的集中式javadoc资源复制到项目中.然而,这种方法至少有两个缺点:

1. 这种依赖不是项目的真正依赖,不应该这样说.它是maven-javadoc-plugin的依赖项,而不是项目本身的依赖项.

2. 我需要找到一种方法,以便只在请求javadoc生成时才将依赖项复制到项目中.

请帮忙.

Answer 1

我完全忽略了Maven Javadoc插件上的resourcesArtifacts配置参数.这是实现这一目标的关键.

我将分两步解释一下:

1. 用于保存集中式Javadoc资产的Maven项目(自定义样式表(如果需要),徽标,javascript库等)

2. 为了让你公司的所有Javadoc看起来都一样,你需要把它放到公司范围内的pom中.

Javadoc定制项目

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

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

1. 一个stylesheet.css文件.此文件是我们公司版的Javadoc样式表.它与标准样式表略有不同,因为它修复了一些JDK8缺陷(JDK8 javadoc可读性很差),但也改变了一些颜色以与公司品牌一致,等等.

2. 一个子目录,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包的根目录中.从文档中我不清楚是否有解压缩,但确实如此.resourceArtifactjar中的东西会被盲目复制到包中,所以要小心你的命名.它会覆盖任何类似名称的东西.在我们的stylesheet.css文件的情况下,这实际上是我们想要的,所以这很好.无论如何,您只需要小心您在Javadoc定制项目中的内容.

我们取得了什么

1. Javadoc资源(样式表,徽标,JS文件)可以在源代码管理下.
2. Javadoc资源可以集中.
3. 添加了在Javadoc注释中编写Java代码片段时进行语法突出显示的功能.
4. 创建的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>标签,不适用于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次要版本号.如果您碰巧在 8u121 之前在JDK上使用上述内容,则它将退出并显示错误,因为它--allow-script-in-comments是未知的.