diff --git a/src/content/tools/dart-doc.md b/src/content/tools/dart-doc.md index 430139fade..959759b8b0 100644 --- a/src/content/tools/dart-doc.md +++ b/src/content/tools/dart-doc.md @@ -1,54 +1,202 @@ --- title: dart doc -description: API reference generation tool. -toc: false +description: >- + Learn how to generate HTML-reference documentation for public Dart libraries. --- -The `dart doc` command (previously called `dartdoc`) -creates API reference documentation -from Dart source code. -You can add descriptions to the generated documentation -by using [documentation comments][], -which can contain [Markdown][] formatting. +The `dart doc` command generates HTML reference documentation +for Dart source code. + +## Write documentation {:#write} + +To add reference text and examples to the generated documentation, +use [documentation comments][] with [Markdown][] formatting. For guidance on writing doc comments, -see the [documentation part of Effective Dart][effective doc]. +check out the [Effective Dart: Documentation][] guide. + +[documentation comments]: /language/comments#documentation-comments +[Markdown]: {{site.pub-pkg}}/markdown +[Effective Dart: Documentation]: /effective-dart/documentation + +## Generate API docs {:#generate} :::note -To generate documentation, +To generate documentation, you must first run [`dart pub get`](/tools/pub/cmd/pub-get) and your package must pass [`dart analyze`](/tools/dart-analyze) without errors. ::: -Run `dart doc` from the root directory of your package. -For example: +To generate the documentation for your package, +run `dart doc .` from the package's root directory. +For example, generating the API docs for a `my_package` package +could resemble the following: ```console -$ cd my_app +$ cd my_package $ dart pub get $ dart doc . -Documenting my_app... +Documenting my_package... ... -Success! Docs generated into /Users/me/projects/my_app/doc/api +Success! Docs generated into /Users/me/projects/my_package/doc/api ``` -By default, -the documentation files are static HTML files, -placed in the `doc/api` directory. -You can create the files in a different directory -with the `--output` flag. +By default, `dart doc` places the generated documentation +and supporting files in the `doc/api` directory. +To change the output directory, specify +a path with the `--output` flag: -For information on command-line options, -use the `help` command: +```console +$ dart doc --output=api_docs . +``` + +If there are any issues with your package setup or documentation comments, +`dart doc` outputs them as errors or warnings. +If you just want to test for issues without saving the generated documentation, +add the `--dry-run` flag: ```console -$ dart help doc +$ dart doc --dry-run . ``` -[documentation comments]: /language/comments#documentation-comments -[effective doc]: /effective-dart/documentation#doc-comments -[Markdown]: {{site.pub-pkg}}/markdown +### Configure generation {:#configure} + +To configure how `dart doc` generates documentation, create a +file named `dartdoc_options.yaml` in the root directory of your package. + +To learn more about the file's format and supported configuration options, +check out [dart.dev/go/dartdoc-options-file][dartdoc-options]. {% comment %} -[PENDING: Add more help, info on commonly used options, links to examples of use.] -{% endcomment %} +TODO: Document the long-term supported options here. +{% endcomment -%} + +[dartdoc-options]: https://dart.dev/go/dartdoc-options-file + +## View generated docs {:#view} + +You can view docs generated with `dart doc` in a variety of ways. + +### View local docs {:#view-local} + +To view API docs you generated with `dart doc` or downloaded from online, +you must load them with an HTTP server. + +To serve the files, use any HTTP server. +Consider using [`package:dhttpd`][] from pub.dev. + +To use `package:dhttpd`, activate it globally, then run it +and specify the path of your generated docs. +The following commands activate the package, +then runs it to serve the API docs located at `doc/api`: + +```console +$ dart pub global activate dhttpd +$ dart pub global run dhttpd --path doc/api +``` + +To then read the generated docs in your browser, +open the link that `dhttpd` outputs, usually `http://localhost:8080`. + +[`package:dhttpd`]: https://pub.dev/packages/dhttpd + +### View hosted docs {:#view-hosted} + +You can also host your generated API docs online +using any hosting service that supports static web content. +Two common options are [Firebase hosting][] and [GitHub pages][]. + +[Firebase hosting]: https://firebase.google.com/docs/hosting +[GitHub pages]: https://pages.github.com/ + +### View package docs {:#view-pub} + +The [pub.dev site]({{site.pub}}) generates and hosts +documentation for an uploaded package's public libraries. + +To view a package's generated docs, +navigate to its page and open the **API reference** link +in the info box on the right side of the page. +For example, you can find the API docs for `package:http` +at [pub.dev/documentation/http]({{site.pub-api}}/http). + +### View core library docs {:#view-sdk} + +`dart doc` is also used to generate the API reference documentation for +the Dart core libraries. + +To view the Dart SDK reference docs, visit the api.dart.dev link +that corresponds to the Dart release channel you are developing with: + +| Branch | Generated docs | +|----------|---------------------------------------------| +| `stable` | [api.dart.dev/stable]({{site.dart-api}}) | +| `beta` | [api.dart.dev/beta]({{site.dart-api}}/beta) | +| `dev` | [api.dart.dev/dev]({{site.dart-api}}/dev) | +| `main` | [api.dart.dev/main]({{site.dart-api}}/main) | + +{:.table .table-striped} + +## Troubleshoot + +To identify and resolve common issues with docs generated with `dart doc`, +consult the following reference section. + +### Search bar failed to load {:#troubleshoot-search} + +If the generated documentation's search bars aren't functional or +include text similar to "Failed to initialize search", +one of the following scenarios is possible: + +1. You are accessing the docs from your own file system, + but they aren't being served and loaded with an HTTP server. + To learn how to serve local API docs, + check out [how to view generated docs locally](#view-local). +2. The `index.json` file generated by `dart doc` is missing or inaccessible + from the documentation directory or your hosted web server. + Try regenerating the docs and validating your hosting configuration. + +### Sidebar failed to load {:#troubleshoot-sidebar} + +If the generated documentation's sidebars are missing or +include text similar to "Failed to load sidebar", +one of the following scenarios is possible: + +1. You are accessing the docs from your own file system, + but the docs aren't being served and loaded with an HTTP server. + To learn how to serve local API docs, + check out [how to view local docs](#view-local). +2. The generated docs' base-href behavior is configured. + This configuration option is deprecated and should no longer be used. + Try removing the option and using the default behavior of `dart doc`. + If the default behavior breaks links in your generated docs, + please [file an issue][]. + +[file an issue]: https://github.com/dart-lang/dartdoc/issues + +### Missing API documentation {:#troubleshoot-missing} + +If you can't find or access the generated documentation +for an API you expect to have docs, +one of the following scenarios is possible: + +1. The package does not expose the API you are looking for as a public API. + `dart doc` only generates documentation for public libraries and members + that are exposed for other packages to import and use. + To learn more about configuring a package's public libraries, + check out the package layout guide on [public libraries][]. +2. The URL you are attempting to access has incorrect capitalization. + By default, `dart doc` generates filenames that are case-sensitive, + match their corresponding source declarations, and have a `.html` extension. + Try verifying the URL matches these expectations. + +[public libraries]: /tools/pub/package-layout#public-libraries + +### Text where icons should be {:#troubleshoot-icons} + +If you see text instead of icons like the menu and theme buttons, +your browser was likely unable to load the Material Symbols font. +Some options to solve this include: + +1. Try using a proxy that enables access to the Google Fonts servers. +2. Update the generated pages to use a local version of the font.