dart doc
dart doc コマンドは、Dart ソース コードの HTML リファレンス ドキュメントを生成します。
ドキュメントを書く
#生成されたドキュメントにリファレンステキストや例を追加するには、ドキュメントコメントとMarkdownフォーマットを使用します。ドキュメントコメントの書き方については、Effective Dart: Documentation ガイドを参照してください。
API ドキュメントを生成する
#パッケージのドキュメントを生成するには、パッケージのルートディレクトリから 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 で生成したドキュメントやオンラインからダウンロードしたドキュメントを表示するには、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 が出力するリンク（通常は https://:8080）を開きます。
ホストされたドキュメントを表示する
#静的ウェブコンテンツをサポートする任意のホスティングサービスを使用して、生成された API ドキュメントをオンラインでホストすることもできます。一般的なオプションとして、Firebase Hosting と GitHub Pages があります。
パッケージドキュメントを表示する
#pub.dev サイトは、アップロードされたパッケージの公開ライブラリのドキュメントを生成してホストします。
パッケージの生成されたドキュメントを表示するには、そのページに移動し、ページの右側にある情報ボックスの **API リファレンス** リンクを開きます。たとえば、package:http の API ドキュメントは pub.dev/documentation/http で見つけることができます。
コアライブラリドキュメントを表示する
#dart doc は、Dart コアライブラリの API リファレンス ドキュメントの生成にも使用されます。
Dart SDK リファレンス ドキュメントを表示するには、開発している Dart リリースチャンネルに対応する api.dart.dev リンクにアクセスします。
| ブランチ | 生成されたドキュメント |
|---|---|
stable | api.dart.dev/stable |
beta | api.dart.dev/beta |
dev | api.dart.dev/dev |
main | api.dart.dev/main |
トラブルシューティング
#dart doc で生成されたドキュメントでよくある問題点を特定して解決するには、以下のリファレンスセクションを参照してください。
検索バーが読み込めませんでした
#生成されたドキュメントの検索バーが機能しない、または「検索の初期化に失敗しました」のようなテキストが表示される場合、以下のいずれかのシナリオが考えられます。
- ローカルファイルシステムからドキュメントにアクセスしていますが、HTTP サーバーで配信およびロードされていません。ローカル API ドキュメントを配信する方法については、生成されたドキュメントをローカルで表示する方法を参照してください。
dart docによって生成されたindex.jsonファイルが見つからないか、ドキュメントディレクトリまたはホストされた Web サーバーからアクセスできません。ドキュメントを再生成し、ホスティング構成を検証してみてください。
サイドバーが読み込めませんでした
#生成されたドキュメントのサイドバーが見つからない、または「サイドバーの読み込みに失敗しました」のようなテキストが表示される場合、以下のいずれかのシナリオが考えられます。
- ローカルファイルシステムからドキュメントにアクセスしていますが、ドキュメントが HTTP サーバーで配信およびロードされていません。ローカル API ドキュメントを配信する方法については、ローカルドキュメントを表示する方法を参照してください。
- 生成されたドキュメントの base-href 動作が構成されています。この構成オプションは非推奨であり、今後使用されるべきではありません。オプションを削除して、
dart docのデフォルトの動作を使用してみてください。デフォルトの動作で生成されたドキュメントのリンクが壊れる場合は、問題を報告してください。
API ドキュメントが見つかりません
#期待されるドキュメントがある API の生成されたドキュメントが見つからない、またはアクセスできない場合、以下のいずれかのシナリオが考えられます。
- パッケージは、探している API を公開 API として公開していません。
dart docは、他のパッケージがインポートして使用できるように公開されている公開ライブラリとメンバーのドキュメントのみを生成します。パッケージの公開ライブラリの構成方法の詳細については、公開ライブラリのパッケージレイアウトガイドを参照してください。 - アクセスしようとしている URL の大文字小文字が正しくありません。デフォルトでは、
dart docは、対応するソース宣言と一致し、.html拡張子を持つ、大文字小文字を区別するファイル名を生成します。URL がこれらの期待と一致するかどうかを確認してみてください。
アイコンがあるべき場所にテキストが表示される
#メニューボタンやテーマボタンのようなアイコンの代わりにテキストが表示される場合、ブラウザが Material Symbols フォントを読み込めなかった可能性があります。これを解決するためのオプションとしては、以下が挙げられます。
- Google Fonts サーバーへのアクセスを可能にするプロキシを使用してみてください。
- 生成されたページを更新して、フォントのローカルバージョンを使用するようにします。