logo标签列表

Maven javadoc - 如何包含集中式资源

mavensyntax-highlightingjavadoc
6
我想在Maven生成的javadoc中包含集中式资源（例如图像文件、js文件）。这些集中式资源将来自于依赖项。（在我的情况下，我想始终包含某些资源，JavaScript文件，以便在Javadoc中对示例代码进行良好的语法高亮，并使用特殊样式表）。
如果您将资源与项目一起本地包含，则有大量关于如何执行此操作的信息。但这不是我想要的，因为我需要为我们公司中的每个项目执行此操作。因此，配置需要进入公司范围的POM文件，从中继承我们公司的所有项目。
请注意，对于样式表而言，这非常容易实现，因为Maven插件允许该文件来自依赖项。我正在寻找类似的东西，只不过是针对“资源”。基本上，我不想每个项目都复制像公司标志这样的东西，这就是我想避免的。
如果 Maven Javadoc Plugin 不直接支持此功能（我无法确定是否支持），那么我猜另一种方法可能是使用 Maven Dependency Plugin 将我的集中式 javadoc 资源复制到项目中。但是，这种方法至少有两个缺点：
  1. 这种依赖关系不是项目的真正依赖关系，也不应该被声明为项目的依赖关系。它是 maven-javadoc-plugin 的依赖项，而不是项目本身的依赖项。
  2. 我需要找出一种方法，使得只有在请求 javadoc 生成时才会将依赖项复制到项目中。
请帮忙。
1个回答
11

我完全忽略了resourcesArtifacts配置参数，这是使Maven Javadoc插件正常工作的关键。

我将分两步解释：

  1. 创建一个Maven项目来保存你的集中式Javadoc资源（自定义样式表（如果需要），标志，javascript库等）

  2. 在公司范围的pom文件中添加什么内容，以便所有公司的Javadoc看起来都一样。

Javadoc自定义项目

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

在我的 src/main/resources 目录中，我有以下内容：

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

  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，该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资源。该artifact（即jar）被解压缩到生成的Javadoc包的根目录中。从documentation中并没有清楚地表明正在进行解压缩，但实际上确实存在。来自resourceArtifact jar的内容将被盲目地复制到包中，因此请注意命名。它将覆盖任何相似名称的内容。对于我们的stylesheet.css文件，这实际上是我们想要的，所以这很好。无论如何，您只需要小心您放入Javadoc定制项目中的内容。
我们取得了什么成就？
  1. Javadoc资源（样式表、徽标、JS文件）可以在源代码控制下。
  2. Javadoc资源可以集中管理。
  3. 在Javadoc注释中编写Java代码片段时，可以进行语法高亮。
  4. 创建的Javadoc包是自包含的，不依赖于任何外部资源。

如何在Javadoc中进行语法高亮

有了上述内容，您的所有Javadocs现在都会自动继承进行语法高亮的功能。您只需要将 <pre> 标签添加 class="bruch:java" 即可。以下是一个示例：

/**
 * 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中不起作用。呕。

这是在Javadoc中它会是什么样子：

enter image description here

塔达！

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

此解决方案的性能

每次进行Javadoc构建时，您都会注意到Maven输出中的此附加步骤：

enter image description here

这可能会占用您构建时间的一两秒钟，如果不是更少。当然，只有在构建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未知而出现错误。请注意，此段落中的HTML标签已保留。
改进建议：在公司范围的POM列表中，将两个“shCore.css”之一替换为“shThemeDefault.css”。 - Fabien Launay
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接