タツノオトシゴのブログ

主にJavaに関するものです。

Javadocのコードにシンタックスハイライトを適用する

Javadocで、<pre>〜</pre>タグを使って、サンプルなどのコードを記述する場合、デフォルトのままだと、通常の文章と区別が付きづらくわかりづらい。

そのため、シンタックスハイライトを適用したかったので、試したことをメモしておく。
今回は、mavenとhighlight.jsを使う。

実際のサンプルは下記を参考。

Javadocの記述

不要なpreタグにシンタクスハイライトが当たらないように、<pre class="highlight"><code class="java">〜</code></pre>のように、preタグにもclass属性を適用する。

/*
 * クラスの説明
 *
 * <pre class="highlight"><code class="java">
 * // コードの記述
 * ・・・
 * </code></pre>
 */

stylesheet.cssの記述

javadocの標準のCSSの場合、preタグには既にCSSが適用されているため、文字の大きさなど少しカスタマイズしたものを利用する。

通常に生成したJavadoc中の「stylesheet.css」の最後に下記の内容を追加して、「src/javadoc」以下に格納しておく。

〜省略
/**
 * 追加したCSS
 */
pre.highlight {
    margin-top: 10px;
    margin-bottom: 10px;
    font-size: 80%;
    border: solid 1px #9eadc0;
    background-color: #f9f9f9;
}

pom.xmlの記述

Javadocのレポートの記述の

タグ内に、シンタックスハイライトを適用するためのJavaScriptを記述する。

タグは、Javadocの見出しを設定するものなので、JavaScriptだけ記述すると、HTMLを生成した場合余分なスペースが表示されるため、ライブラリ名などを出力するように定義しておくようにする。

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.3</version>
            <configuration>
                <source>${java.version}</source>
                <encoding>UTF-8</encoding>
                <charset>UTF-8</charset>
                <docencoding>UTF-8</docencoding>
                <locale>ja_JP</locale>
                <links>
                    <link>http://docs.oracle.com/javase/jp/7/api/</link>
                </links>
                <!-- 少しカスタマイズしたCSSを適用する。 -->
                <stylesheetfile>${basedir}/src/javadoc/stylesheet.css</stylesheetfile>

                <!-- Javadocの見出し出力定義にJavaScriptを記述する。 -->
                <header>${project.name} - ${project.version}
<![CDATA[
<link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/styles/default.min.css">
<script src="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/highlight.min.js"></script>
<script src="https://code.jquery.com/jquery-1.12.0.min.js"></script>
<script>
$(document).ready(function() {
$('pre.highlight code').each(function(i, block) {
hljs.highlightBlock(block);
});
});
</script>
]]>
                </header>

            </configuration>
        </plugin>
    </plugins>
<reporting>