2 JavaDoc CSSテーマのプログラマーズ・ガイド
JavaDocによって生成されるAPIドキュメントには、フォント、色、間隔などのビジュアル・プロパティを定義するデフォルトのCSSスタイルシート(『Cascading Style Sheets home page』を参照)が付属しています。デフォルトのスタイルシートはアクセシビリティの目的で構築され、可能な限り幅広い対象者にアピールしますが、デフォルトのスタイルシートを拡張または置換するカスタム・スタイルを好むプロジェクトもあります。このドキュメントでは、ダークCSSテーマのスタイルシートの例など、これを実現する方法について説明します。
コマンドライン・オプション
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-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
ノート:
これが機能するためには、適切なJDKバイナリがPATH
にある必要があります。または、完全なパス名を指定してjavadoc
ツールを起動することもできます。
javadoc
の呼出しが正常に終了すると、生成されたAPIドキュメントを含むdocs
というディレクトリが作成されます。ブラウザでファイルdocs/Test.html
を開くと、次に示すページのようになります。
起動をプロジェクトやビルド・システムに適応させるのは簡単で、当然ながらテーマを好みに合わせて変更したり、新しいテーマを最初から作成したりできます。カスタム・テーマは、生成されるドキュメントに含まれるすべてのHTMLファイルで使用されます。