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 生成或從線上下載的 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 輸出的連結，通常是 https://:8080。
檢視託管文件
#您還可以使用任何支援靜態 Web 內容的託管服務線上託管生成的 API 文件。兩個常見的選擇是 Firebase Hosting 和 GitHub Pages。
檢視包文件
#pub.dev 站點會為上傳的包的公共庫生成並託管文件。
要檢視包的生成文件，請導航到其頁面，並開啟頁面右側資訊框中的API 參考連結。例如，您可以在 pub.dev/documentation/http 找到 package:http 的 API 文件。
檢視核心庫文件
#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 伺服器的代理。
- 更新生成的頁面以使用本地版本的字型。