我完全忽略了resourcesArtifacts配置参数,这是使Maven Javadoc插件正常工作的关键。
我将分两步解释:
创建一个Maven项目来保存你的集中式Javadoc资源(自定义样式表(如果需要),标志,javascript库等)
在公司范围的pom文件中添加什么内容,以便所有公司的Javadoc看起来都一样。
Javadoc自定义项目
这个“项目”将保存你的自定义Javadoc资源。它是一个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,该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>
<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>
<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定制项目中的内容。
我们取得了什么成就?
- Javadoc资源(样式表、徽标、JS文件)可以在源代码控制下。
- Javadoc资源可以集中管理。
- 在Javadoc注释中编写Java代码片段时,可以进行语法高亮。
- 创建的Javadoc包是自包含的,不依赖于任何外部资源。
如何在Javadoc中进行语法高亮
有了上述内容,您的所有Javadocs现在都会自动继承进行语法高亮的功能。您只需要将 <pre>
标签添加 class="bruch:java"
即可。以下是一个示例:
请注意,我必须转义<符号。许多人使用的标准技巧是将
{@code}
嵌入到
<pre>
标记中,以避免这样做,
在SyntaxHighlighter中不起作用。呕。
这是在Javadoc中它会是什么样子:
![enter image description here](https://istack.dev59.com/21gj4.webp)
塔达!
您可以扩展该方案以添加更多自定义内容,例如始终在Javadoc页脚中放置公司标志等。
此解决方案的性能
每次进行Javadoc构建时,您都会注意到Maven输出中的此附加步骤:
![enter image description here](https://istack.dev59.com/RCY3z.webp)
这可能会占用您构建时间的一两秒钟,如果不是更少。当然,只有在构建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>
...
...
<additionalparam>--allow-script-in-comments</additionalparam>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
Oracle所做的不好的事情是,现在构建取决于JDK的次要版本号。如果您使用JDK 8u121之前的版本,则会因为
--allow-script-in-comments
未知而出现错误。请注意,此段落中的HTML标签已保留。