@use JSDoc

JSDoc の既定のテンプレートの設定

JSDoc の既定のテンプレートには、生成されたドキュメントの外観と内容をカスタマイズするために使用できるいくつかのオプションが用意されています。

これらのオプションを使用するには、JSDoc の 設定ファイルを作成 し、設定ファイルで適切なオプションを設定する必要があります。

きれい表示されたソースファイルの生成

既定では、JSDoc の既定のテンプレートは、ソースファイルのきれい表示バージョンを生成します。また、ドキュメント内のこれらのきれい表示ファイルへのリンクも作成します。

きれい表示ファイルを使用不可にするには、オプション templates.default.outputSourceFiles を false に設定します。このオプションを使用すると、ドキュメントからソースファイルへのリンクも削除されます。このオプションは JSDoc 3.3.0 以降で使用できます。

出力ディレクトリへの静的ファイルのコピー

JSDoc の既定のテンプレートは、CSS スタイルシートなどの少数の静的ファイルを自動的に出力ディレクトリにコピーします。JSDoc 3.3.0 以降では、既定のテンプレートに追加の静的ファイルを出力ディレクトリにコピーするように指示できます。たとえば、イメージのディレクトリを出力ディレクトリにコピーして、ドキュメントでこれらのイメージを表示できます。

追加の静的ファイルを出力ディレクトリにコピーするには、次のオプションを使用します

出力ディレクトリへのイメージディレクトリのコピー

./myproject/static 内のすべての静的ファイルをコピーするには、出力ディレクトリ

{
  "templates": {
    "default": {
      "staticFiles": {
        "include": [
        	"./myproject/static"
        ]
      }
    }
  }
}

静的ファイルディレクトリにファイル ./myproject/static/img/screen.png が含まれている場合、HTML タグ <img src="img/screen.png"> を使用してドキュメントにイメージを表示できます。

ページフッターに現在の日付を表示

既定では、JSDoc の既定のテンプレートは常に生成されたドキュメントのフッターに現在の日付を表示します。JSDoc 3.3.0 以降では、オプション templates.default.includeDate を false に設定することで現在の日付を表示しないようにできます。

ナビゲーション列にロングネームを表示

既定では、JSDoc の既定のテンプレートは、ナビゲーション列に各シンボルの名前の短縮バージョンを表示します。たとえば、シンボル my.namespace.MyClass は MyClass として表示されます。代わりにロングネーム全体を表示するには、オプション templates.default.useLongnameInNav を true に設定します。このオプションは JSDoc 3.4.0 以降で使用できます。

既定のテンプレートのレイアウトファイルの上書き

既定のテンプレートは、生成されたドキュメント内の各ページのヘッダーとフッターを指定するために layout.tmpl というファイルを使用します。特に、このファイルは各ページに読み込まれる CSS と JavaScript ファイルを定義します。JSDoc 3.3.0 以降では、カスタマイズされた layout.tmpl ファイルを指定して、独自のカスタム CSS と JavaScript ファイルを標準ファイルに追加または代わりに読み込むことができます。

この機能を使用するには、オプション templates.default.layoutFile をカスタマイズされたレイアウトファイルへのパスに設定します。相対パスは、現在の作業ディレクトリ、設定ファイルのパス、JSDoc ディレクトリの順に解決されます。