我正在尝试将集中资源(例如图像文件、js 文件)包含到我的 Maven 生成的 javadoc 中。这种集中的资源将来自依赖。 (在我的情况下,我希望始终包含某些资源、Javascript 文件,这样可以在 Javadoc 中对示例代码进行很好的语法高亮显示,并且还可以使用特殊的样式表)
如果您在项目中包含本地资源,则有关于如何执行此操作的大量信息。这不是我想要的,因为我需要为公司的每个项目都这样做。所以配置需要进入公司范围的POM文件,我们公司所有项目都继承自该文件。
请注意,对于 样式表这很容易做到,因为 Maven plugin allows for this file to come from a dependency .我正在寻找类似的东西,除了“资源”。基本上,我必须将公司徽标之类的东西复制到每个项目中似乎很愚蠢。这就是我想避免的。
如果 Maven Javadoc Plugin 不直接支持此操作(我不知道是不是)然后我猜另一种方法可能是使用 Maven Dependency Plugin将我的集中 javadoc 资源复制到项目中。然而,这种方法至少有两个缺点:
对项目的依赖仅在 javadoc 生成时发生
要求。
请帮忙。
最佳答案
我完全忽略了 resourcesArtifacts Maven Javadoc plugin 上的配置参数.这是让它发挥作用的关键。
我将分两步解释这一点:
样式表(如果需要)、徽标、javascript 库等)
在你的公司看起来一样。
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 中进行语法高亮显示
有了上述功能,您的 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 < 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
未知。
关于Maven javadoc - 如何包含集中资源,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/30507476/