- Write documentation
- Generate API docs
- View generated docs
dart doc command generates HTML reference documentation for Dart source code.
To add reference text and examples to the generated documentation, use documentation comments with Markdown formatting. For guidance on writing doc comments, check out the Effective Dart: Documentation guide.
Generate API docs#
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:
$ cd my_package
$ dart pub get
$ dart doc .
Success! Docs generated into /Users/me/projects/my_package/doc/api
dart doc places the generated documentation and supporting files in the
doc/api directory. To change the output directory, specify a path with the
$ 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
$ dart doc --dry-run .
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.
View generated docs#
You can view docs generated with
dart doc in a variety of ways.
View local docs#
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.
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
$ 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
View hosted docs#
View package docs#
The pub.dev site 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.
View core library docs#
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:
To identify and resolve common issues with docs generated with
dart doc, consult the following reference section.
Search bar failed to load#
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:
- 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.
index.jsonfile generated by
dart docis 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#
If the generated documentation's sidebars are missing or include text similar to "Failed to load sidebar", one of the following scenarios is possible:
- 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.
- 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.
Missing API documentation#
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:
- The package does not expose the API you are looking for as a public API.
dart doconly 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.
- The URL you are attempting to access has incorrect capitalization. By default,
dart docgenerates filenames that are case-sensitive, match their corresponding source declarations, and have a
.htmlextension. Try verifying the URL matches these expectations.
Text where icons should be#
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:
- Try using a proxy that enables access to the Google Fonts servers.
- Update the generated pages to use a local version of the font.