javadocツールには、生成されるドキュメントのスタイルシートをカスタマイズするための2つのコマンドライン・オプションが用意されています。

• --add-stylesheetオプションは、デフォルトのスタイルシートに加えて、生成されるドキュメントにスタイルシートを追加します。追加されたスタイルシート内のルールは、デフォルト・スタイルシート内の対応するルールを上書きするため、このオプションを使用して、デフォルト・スタイルシートのスタイルを選択的に変更するスタイルを設定できます。
• --main-stylesheetオプションは、デフォルトのスタイルシートを、コマンドライン・オプションの引数として指定されたものに置き換えます。これは、カスタム・スタイルシートがドキュメントのスタイルのみを担当することを意味します。デフォルトのスタイルシートをカスタム・スタイルシートの開始点として使用することをお薦めします。

このガイドでは、--add-stylesheetオプションを使用します。組込みスタイルシート上に構築して、変更するプロパティのみをオーバーライドするためです。もちろん、既定のスタイルシートを置き換えると、より多くの可能性が開かれますが、はるかに複雑さが増し、このガイドの範囲を超えます。

JavaDoc標準ドックレットによって生成されるドキュメントの出力は、生成されたAPIドキュメントで使用されるCSSクラスのリストを含む、標準ドックレットによって生成されるJavaDoc出力に関する項で説明されています。これは、独自のJavaDocスタイルシートを最初から記述したい人にとって参照情報として役立つ場合がありますが、次に説明するカスタム・プロパティを使用したスタイルのカスタマイズでもおそらく十分で、はるかに簡単です。

CSSカスタム・プロパティ(『Using CSS custom properties (variables)』を参照)は、CSS値を1か所で定義し、スタイルシート内の任意の場所で使用するための便利な方法です。JavaDocのデフォルト・スタイルシートでは、すべてのフォントと色にCSSカスタム・プロパティが使用されるため、再定義されたカスタム・プロパティを含むスタイルシートを提供するだけで完全なCSSテーマを作成できます。

CSSカスタム・プロパティ名は常に二重ハイフン(--)で始まります。すべてのページ要素で使用できるように、JavaDocスタイルシートでは、:root疑似クラスでカスタム・プロパティを定義します。次の例は、本文のフォント・サイズを15 pxに設定する方法を示しています。

:root {   --body-font-size: 15px;}

デフォルト・スタイルシートのカスタム・プロパティの数は意図的に小さく保たれ、変数の多くは複数の場所で使用されています。これにより、一貫したテーマの作成が簡単になりますが、個々のページ要素に対して特定のスタイルを選択する自由度も制限されます。これは慎重に選択するもので、基礎となるCSSルールを直接オーバーライドすることで制限を回避できます。

次の各項では、デフォルトのスタイルシートで使用されるカスタム・プロパティについて説明します。

フォント・ファミリ

次のプロパティは、ページ内の様々な種類のテキストに使用するフォント・ファミリを定義します。

--body-font-family

ページの基本フォント・ファミリを定義します

--block-font-family

ドキュメントのブロックに使用するフォント・ファミリを定義します

--code-font-family

プログラム・コードの表示に使用するフォント・ファミリを定義します

フォント・サイズ

次のカスタム・プロパティは、ページ内の基本テキストのフォント・サイズを定義します。見出しやナビゲーション・リンクなどの特定の要素のフォント・サイズは、次のカスタム・プロパティから導出されることに注意してください。

--body-font-size

標準テキストの基本フォント・サイズを定義します

--code-font-size

プログラム・コードの基本フォント・サイズを定義します

背景色

次のカスタム・プロパティは、様々な汎用ページ要素の背景色を定義します。

--body-background-color

ページのメイン背景色を定義します

--section-background-color

プライマリ・ページ・セクションの背景色を定義します

--detail-background-color

詳細セクションの背景色を定義します

--navbar-background-color

プライマリ・ナビゲーション・バーおよび非アクティブなタブ・ボタンの背景色を定義します

--subnav-background-color

セカンダリ・ナビゲーション・バーおよび表ヘッダーの背景色を定義します

--selected-background-color

選択したナビゲーション・アイテムおよびタブ・ボタンの背景色を定義します

--even-row-color

サマリー表内の偶数番目の行の背景色を定義します

--odd-row-color

サマリー表内の奇数番目の行の背景色を定義します

テキスト色

次のカスタム・プロパティは、様々な汎用ページ要素のテキスト色を定義します。

--body-text-color

ページのメイン・テキスト色を定義します

--block-text-color

テキスト・ブロックのテキスト色を定義します

--navbar-text-color

ナビゲーション・バーのテキスト色を定義します

--selected-text-color

選択したナビゲーション・アイテムおよびタブ・ボタンのテキスト色を定義します

--selected-link-color

選択したナビゲーション・アイテムおよびタブ・ボタン内のリンクのテキスト色を定義します

--title-color

ページ・タイトルのテキスト色を定義します

--link-color

リンクのテキスト色を定義します

--link-color-active

アクティブ・リンクのテキスト色を定義します

特定の機能の色

次のカスタム・プロパティは、ページ内の様々な特定の要素の背景色とテキスト色を定義します。

--snippet-background-color

コード・スニペットの背景色を定義します

--snippet-text-color

コード・スニペットのテキスト色を定義します

--snippet-highlight-color

コード・スニペットのハイライトのテキスト色を定義します

--border-color

セクション・ボックスの境界線の色を定義します

--table-border-color

表の境界線の色を定義します

--search-input-background-color

検索入力の背景色を定義します

--search-input-text-color

検索入力のテキスト色を定義します

--search-input-placeholder-color

検索入力のプレースホルダ・テキストのテキスト色を定義します

--search-tag-highlight-color

強調表示された検索タグの背景色を定義します

--copy-icon-brightness

クリップボードにコピー・アイコンの明るさを定義します

--copy-button-background-color-active

クリップボードにコピー・ボタンの背景を定義します

--invalid-tag-background-color

無効なタグの通知の背景色を定義します

--invalid-tag-text-color

無効なタグの通知のテキスト色を定義します

次の例は、ダークCSSテーマを作成するためにJavaDocスタイルシートで使用されるカスタム・プロパティの一部をオーバーライドするカスタム・スタイルシートの作成方法を示しています。

いくつかのファイルを作成する必要があるため、新しい空のディレクトリから始めることをお薦めします。ターミナル・ウィンドウで、javadoc-styleのようなディレクトリを作成してそこに移動します。

最初に必要なのは、文書化するJavaコードであるため、単純なテスト・クラスを作成します。次のコンテンツを含むTest.javaというファイルを新しい空の現在の作業ディレクトリに作成します。

/**
 * A test class.
 */
public class Test {

    /** 
     * Constructor.
     */
    public Test() {}

    /** 
     * Constructor.
     * @param s a string
     */
    public Test(String s) {}
    
    /** 
     * A simple method.
     * @param s a string
     */
    public void hello(String s) {}

    /**
     * A method.
     */
    public void foo() {}

    /**
     * Another method.
     */
    public void bar() {}
}

他に必要なファイルは、カスタム・スタイルを含むCSSファイルのみです。次のコンテンツを含むdark-theme.cssというファイルを現在の作業ディレクトリに作成します。

:root {
    --body-text-color: #e0e0e3;
    --block-text-color: #e6e7ef;
    --body-background-color: #404040;
    --section-background-color: #484848;
    --detail-background-color: #404040;
    --navbar-background-color: #505076;
    --navbar-text-color: #ffffff;
    --subnav-background-color: #303030;
    --selected-background-color: #f8981d;
    --selected-text-color: #253441;
    --selected-link-color: #1f389c;
    --even-row-color: #484848;
    --odd-row-color: #383838;
    --title-color: #ffffff;
    --link-color: #a0c0f8;
    --link-color-active: #ffb863;
    --snippet-background-color: #383838;
    --snippet-text-color: var(--block-text-color);
    --snippet-highlight-color: #f7c590;
    --border-color: #383838;
    --table-border-color: #000000;
    --search-input-background-color: #000000;
    --search-input-text-color: #ffffff;
    --search-input-placeholder-color: #909090;
    --search-tag-highlight-color: #ffff00;
    --copy-icon-brightness: 250%;
    --copy-button-background-color-active: rgba(168, 168, 176, 0.3);
    --invalid-tag-background-color: #ffe6e6;
    --invalid-tag-text-color: #000000;
}

次に、Javaクラスをプライマリ引数としてjavadocツールを起動します。スタイル・シートは--add-stylesheetオプションを使用して渡され、生成されるドキュメントをdocsというサブディレクトリに配置するために-dオプションが使用されます。

    javadoc -d docs --add-stylesheet dark-theme.css Test.java

javadocの呼出しが正常に終了すると、生成されたAPIドキュメントを含むdocsというディレクトリが作成されます。ブラウザでファイルdocs/Test.htmlを開くと、次に示すページのようになります。

図2-1 ダーク・テーマを使用したAPIドキュメント

「図2-1 ダーク・テーマを使用したAPIドキュメント」の説明

起動をプロジェクトやビルド・システムに適応させるのは簡単で、当然ながらテーマを好みに合わせて変更したり、新しいテーマを最初から作成したりできます。カスタム・テーマは、生成されるドキュメントに含まれるすべてのHTMLファイルで使用されます。