Maven JavaDoc-如何包括集中式资源 [英] Maven javadoc - how to include centralized resources

问题描述

我正在尝试将集中式资源(例如，图像文件，js文件)包含到我的Maven生成的Javadoc中.这样的集中资源将来自依赖项. (就我而言，我总是希望包含某些资源，Javascript文件，从而可以在Javadoc中对示例代码进行漂亮的语法高亮显示，并且还可以使用特殊的样式表)

I'm trying to include centralized resources (e.g. image files, js files) into my Maven generated javadoc. Such centralized resources would come from a dependency. (in my case I would like to always include certain resources, Javascript files, that allows to do nice syntax highlighting of example code inside Javadoc, and also to use a special stylesheet)

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

There's substantial information on how to do this if you include your resources locally with your project. That's not what I want as I need to do this for every project in my company. So the configuration needs to go into the company-wide POM file from which all projects in our company inherit.

请注意，对于样式表，这很容易做到，因为

Note that for stylesheet this is pretty easy to do as the Maven plugin allows for this file to come from a dependency. I'm looking for something similar, except for 'resources'. Basically it would seem silly that I would have to copy things like our company logo into every project. That's what I would like to avoid.

如果 Maven Javadoc插件没有直接支持，我不知道是不是)，那么我猜测另一种方法可能是使用

If this is not directly supported by the 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 to copy my centralized javadoc resources into the project. However that approach has at least two drawbacks:

1. 这种依赖关系不是项目的真正依赖关系，因此不应这样描述.它是maven-javadoc-plugin的依赖项，而不是项目本身的依赖项.

1. Such dependency is not a real dependency of the project and shouldn't be stated as such. It is a dependency of the maven-javadoc-plugin, not of the project itself.

我需要找出一种方法，以便复制 仅当javadoc生成为 请求.

I would need to figure out a way so that the copying of the dependency into the project only happens when javadoc generation is requested.

请帮助.

推荐答案

我完全忽略了

I've completely overlooked the resourcesArtifacts config parameter on the Maven Javadoc plugin. This is the key to getting this to work.

我将分两步进行解释:

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

1. A Maven project to hold your centralized Javadoc assets (customized stylesheet (if you want), logos, javascript libs, etc.)

为了使所有Javadocs都可以放入公司范围的pom中 您公司中的外观相同.

What to put into your company-wide pom in order to have all Javadocs in your company look the same.

Javadoc定制项目

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

Javadoc customization project

This 'project' will hold your custom Javadoc assets. It is a Maven project, but it doesn't contain any Java source code. Just create a standard Maven project. Create a src/main/resources directory. Everything you put into this directory will eventually be put into the root of every Javadoc bundle you create. If you put a file name of say stylesheet.css in there it will effectively overwrite the standard Javadoc stylesheet.

我的src/main/resources目录位于:

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

1. A stylesheet.css file. This file is our company version of Javadoc stylesheet. It is a bit different from the standard stylesheet in that it fixes some JDK8 deficiencies (JDK8 javadoc readability sucks) but also changes some colors to be inline with company branding and so on.

一个子目录syntaxhighlighter，我将 SyntaxHighlighter 中的相关文件放入其中.在我的情况下，这些文件是shCore.js，shBrushJava.js，shCore.css和shThemeDefault.css，因为我只关心Java语言的语法突出显示，并且因为我想为SyntaxHighlighter使用默认主题.

A subdir, syntaxhighlighter into which I put relevant files from SyntaxHighlighter. In my case those files are shCore.js, shBrushJava.js, shCore.css and shThemeDefault.css since I only care about syntax highlighting for Java language and since I want to use the default theme for SyntaxHighlighter.

我项目的Maven坐标为

My project's Maven coordinates are

<groupId>com.acme.javadoc</groupId>
<artifactId>customization</artifactId>

但是随时随便命名吧.

请记住:这只是一个标准的Maven项目，因此您可以将其置于源代码控制之下，等等.

Remember: this is just a standard Maven project so you can put it under source control and so on.

现在构建(并可能发布)此项目.

Now build (and possibly release) this project.

下面的配方假定您拥有某种公司范围的POM，它使您可以在一处为多个项目进行Maven定制.如果您没有这样的中央父POM，则必须在每个项目中都执行以下操作.

The recipe below assumes you have some kind of company-wide POM which allows you to make Maven customizations for many projects in one place. If you don't have such a central parent POM then you'll have to do the below in each and every project instead.

<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下运行时才激活.如果您不希望出现这种情况，则可以对其进行更改，以使配置文件始终处于激活状态，而不是有条件地被激活.

What will happen is this: Everytime a project which inherits from the company-wide POM creates a Javadoc package it will do so with the maven-javadoc-plugin settings above. As you notice the whole thing is put into a profile and only activated if the Maven build is running under JDK8. If you don't want this condition you can change it so the profile is always activated rather than being conditionally activated.

resourceArtifact指向带有Javadoc资产的项目.该工件(一个jar)被解包到生成的Javadoc捆绑包的根目录中.从文档中，我不清楚一个>正在进行解压缩，但是确实存在. resourceArtifact jar中的内容被盲目复制到分发包中，因此请谨慎命名.它将覆盖任何类似名称的内容.对于我们的stylesheet.css文件，这实际上是我们想要的，这很好.无论如何，您只需要注意放入Javadoc定制项目中的内容即可.

The resourceArtifact points to our project with our Javadoc assets. This artifact (which is a jar) gets unpacked into the generated Javadoc bundle's root dir. It wasn't clear to me from the documentation that there's an unpack going on, but there is indeed. The stuff from the resourceArtifact jar gets copied blindly into the bundle so be careful with your naming. It will overwrite anything of a similar name. In the case of our stylesheet.css file this is actually what we want so that's good. In any case you just need to be careful about what you put into your Javadoc customization project.

1. Javadoc资源(样式表，徽标，JS文件)可以在源代码控制下.
2. Javadoc资源可以集中化.
3. 添加了在Javadoc注释中编写Java代码段时执行语法高亮显示的功能.
4. 创建的Javadoc捆绑包是独立的.不依赖任何外部资源.

如何在Javadoc中突出显示语法

有了以上所有功能，您的所有Javadocs现在都会自动继承进行语法突出显示的功能.您所要做的就是将class="bruch:java"添加到您的<pre>标记中.这是一个示例:

How to do syntax highlighting in Javadoc

With the above all your Javadocs automatically now inherit the ability to do syntax highlighting. All you have to do is add class="bruch:java" to your <pre> tags. Here's an example:

/**
 * 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>标记内，

Note how I had to escape the < sign. The standard trick that many of us are using to avoid having to do this, embedding {@code} inside <pre> tags, doesn't work with SyntaxHighlighter. Eeew.

这就是Javadoc中的样子:

And this is what it will look like in the Javadoc:

多田！

您可以扩展配方以添加更多自定义功能，例如始终在Javadoc页脚等中放置公司徽标.

You can expand on the recipe to add more customization, e.g. always put a company logo in the Javadoc footer, etc.

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

Every time you do a Javadoc build you'll notice this additional step in your Maven output:

它可能会占用您构建时间的一到两秒-甚至更少.当然，只有在构建Javadoc工件时.

It will probably steal a second or two of your build time - if not less. And only when building Javadoc artifacts of course.

从JDK 8u121开始，默认情况下，Javadoc工具(javadoc)将不再允许您在构建中包含Javascript资源.有关更多信息，请参见发行说明. Maven Javadoc插件隐式使用javadoc工具，因此也会受到影响. javadoc中需要添加一个新的命令行参数，以使其起作用:--allow-script-in-comments.

As of JDK 8u121 the Javadoc tool (javadoc) will no longer by default allow you to include Javascript resources in your build. See Release Notes for more information. The Maven Javadoc Plugin implicitly uses the javadoc tool and is therefore affected as well. There's a new command line parameter to javadoc that needs to be added in order to make it work : --allow-script-in-comments.

换句话说，如果您使用的是JDK 8u121或更高版本，则您公司范围内的POM应该添加以下命令行参数:

In other words if you are using JDK 8u121 or later then your company-wide POM should add this command line parameter:

<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未知，它将错误退出.

That bad thing about what Oracle has done is that the build is now dependent on JDK minor version number. If you happen to use the above on JDK prior to 8u121 it will exit with error because the --allow-script-in-comments is unknown.

这篇关于Maven JavaDoc-如何包括集中式资源的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！