dart doc

dart docコマンドは、DartソースコードのHTMLリファレンスドキュメントを生成します。

生成されたドキュメントにリファレンステキストと例を追加するには、ドキュメントコメントをMarkdown形式で使用します。ドキュメントコメントの書き方については、Effective Dart: Documentationガイドを参照してください。

パッケージのドキュメントを生成するには、パッケージのルートディレクトリからdart doc .を実行します。例えば、my_packageパッケージのAPIドキュメントを生成する手順は次のようになります。

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

デフォルトでは、dart docは生成されたドキュメントとサポートファイルをdoc/apiディレクトリに配置します。出力ディレクトリを変更するには、--outputフラグを使用してパスを指定します。

$ dart doc --output=api_docs .

パッケージの設定またはドキュメントコメントに問題がある場合、dart docはそれらをエラーまたは警告として出力します。生成されたドキュメントを保存せずに問題だけをテストしたい場合は、--dry-runフラグを追加します。

$ dart doc --dry-run .

dart docによるドキュメントの生成方法を構成するには、パッケージのルートディレクトリにdartdoc_options.yamlという名前のファイルを作成します。

ファイルの形式とサポートされている構成オプションの詳細については、dart.dev/go/dartdoc-options-fileを参照してください。

dart docで生成されたドキュメントは、さまざまな方法で表示できます。

dart docで生成したAPIドキュメントやオンラインからダウンロードしたAPIドキュメントを表示するには、HTTPサーバーで読み込む必要があります。

ファイルを配信するには、任意のHTTPサーバーを使用します。pub.devからpackage:dhttpdを使用することを検討してください。

package:dhttpdを使用するには、グローバルに有効化してから実行し、生成されたドキュメントのパスを指定します。次のコマンドはパッケージを有効化し、doc/apiにあるAPIドキュメントを提供するために実行します。

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

その後、ブラウザで生成されたドキュメントを読むには、dhttpdが出力するリンク（通常はhttp://localhost:8080）を開きます。

静的なWebコンテンツをサポートする任意のホスティングサービスを使用して、生成されたAPIドキュメントをオンラインでホストすることもできます。一般的なオプションとして、FirebaseホスティングとGitHub Pagesがあります。

pub.devサイトは、アップロードされたパッケージのパブリックライブラリのドキュメントを生成してホストします。

パッケージの生成されたドキュメントを表示するには、そのページに移動し、ページの右側の情報ボックスにある「APIリファレンス」リンクを開きます。例えば、package:httpのAPIドキュメントはpub.dev/documentation/httpにあります。

dart docは、DartコアライブラリのAPIリファレンスドキュメントの生成にも使用されます。

Dart SDKリファレンスドキュメントを表示するには、開発に使用しているDartリリースチャンネルに対応するapi.dart.devリンクにアクセスします。

dart docで生成されたドキュメントの一般的な問題を特定して解決するには、次の参照セクションを参照してください。

生成されたドキュメントの検索バーが機能しない場合、または「検索の初期化に失敗しました」のようなテキストが含まれている場合、次のいずれかのシナリオが考えられます。

1. 独自のファイルシステムからドキュメントにアクセスしていますが、HTTPサーバーで配信および読み込まれていません。ローカルAPIドキュメントの配信方法については、生成されたドキュメントをローカルで表示する方法を参照してください。
2. dart docによって生成されたindex.jsonファイルが欠落しているか、ドキュメントディレクトリまたはホストされているWebサーバーからアクセスできません。ドキュメントを再生成し、ホスティング構成を検証してみてください。

生成されたドキュメントのサイドバーが欠落している場合、または「サイドバーの読み込みに失敗しました」のようなテキストが含まれている場合、次のいずれかのシナリオが考えられます。

1. 独自のファイルシステムからドキュメントにアクセスしていますが、HTTPサーバーで配信および読み込まれていません。ローカルAPIドキュメントの配信方法については、ローカルドキュメントの表示方法を参照してください。
2. 生成されたドキュメントのbase-href動作が構成されています。この構成オプションは非推奨であり、使用すべきではありません。オプションを削除し、dart docのデフォルト動作を使用してみてください。デフォルトの動作によって生成されたドキュメントのリンクが壊れる場合は、問題を報告してください。

ドキュメントがあるはずのAPIの生成されたドキュメントが見つからないか、アクセスできない場合、次のいずれかのシナリオが考えられます。

1. パッケージは、探しているAPIをパブリックAPIとして公開していません。dart docは、他のパッケージがインポートして使用できるパブリックライブラリとメンバーのドキュメントのみを生成します。パッケージのパブリックライブラリの構成の詳細については、パブリックライブラリに関するパッケージレイアウトガイドを参照してください。
2. アクセスしようとしているURLの大文字と小文字が間違っています。デフォルトでは、dart docは、大文字と小文字が区別され、対応するソース宣言と一致し、.html拡張子を持つファイル名を生成します。URLがこれらの期待値と一致することを確認してください。

メニューやテーマボタンなどのアイコンの代わりにテキストが表示される場合、ブラウザがMaterial Symbolsフォントを読み込めなかった可能性があります。解決策としては、以下のようなものがあります。

1. Google Fontsサーバーへのアクセスを有効にするプロキシを使用してみてください。
2. 生成されたページを更新して、フォントのローカルバージョンを使用してください。

特に明記されていない限り、このサイトのドキュメントはDart 3.5.3を反映しています。ページは2024年4月11日に最終更新されました。 ソースを表示 または 問題を報告する。