From 2c1cee8859bfcade35f758d237bf9cb588a5056f Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 29 Jan 2024 21:06:20 -0600 Subject: [PATCH 1/8] Expand documentation of dart doc --- src/tools/dart-doc.md | 200 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 176 insertions(+), 24 deletions(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index 632bc43e0a..81b76af7bc 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -4,51 +4,203 @@ description: API reference generation tool. toc: false --- -The `dart doc` command (previously called `dartdoc`) -creates API reference documentation -from Dart source code. -You can add descriptions to the generated documentation +The `dart doc` command generates HTML reference documentation +for Dart source code. + +## Write documentation {#write} + +You can add reference text and examples to the generated documentation by using [documentation comments][], which can contain [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} {{site.alert.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. {{site.alert.end}} -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 look like the following: ```terminal -$ 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, the generated documentation and supporting files are +placed in the `doc/api` directory. +To configure the output directory, specify +a path with the `--output` flag: + +```terminal +$ dart doc --output=api_docs . +``` -For information on command-line options, -use the `help` command: +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: ```terminal -$ 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. + +### Locally {#view-local} + +To view API docs you generated with `dart doc` or downloaded from online, +you must load them with an HTTP server. + +You can use any HTTP server to serve the files. +A common option is to use [`package:dhttpd`][] from pub.dev +to quickly serve the files. + +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`: + +```terminal +$ 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 + +### Hosted {#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/ + +### Pub packages {#view-pub} + +The [pub.dev site]({{site.pub}}) automatically generates and hosts +documentation for a package's public libraries. + +To view a package's generation 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). + +### Dart SDK documentation {#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. + +`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) + +## Troubleshoot + +The following are some common issues experienced with +generated documentation, as well as suggestions to resolve them: + +### 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 they aren't being served and loaded with an HTTP server. + To learn how to serve local API docs, + check out [how to view docs locally](#view-local). +2. You configured the generated docs' base-href behavior. + This configuration option is deprecated and set for removal. + 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 API you are looking for is not exposed as a public API from the package. + `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 trying to access has incorrect capitalization. + The filenames generated by `dart doc` are case-sensitive, + match the source declarations, and by default have a `.html` extension. + +[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, +it likely means that the Material Symbols font failed to load. +To resolve this, you can: + +- Update the generated pages to use a local version of the font. +- Use a proxy that enables access to the Google Fonts servers. From 49d512425a454c7c62fced2a47b93f1d0abded3d Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 29 Jan 2024 21:21:15 -0600 Subject: [PATCH 2/8] Enable TOC and other fixes --- src/tools/dart-doc.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index 81b76af7bc..e33b73576b 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -1,7 +1,7 @@ --- 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 generates HTML reference documentation @@ -122,7 +122,7 @@ 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). -### Dart SDK documentation {#view-sdk} +### Dart core libraries {#view-sdk} `dart doc` is also used to generate the API reference documentation for the Dart core libraries. @@ -145,7 +145,8 @@ that corresponds to the Dart release channel you are developing with. ## Troubleshoot The following are some common issues experienced with -generated documentation, as well as suggestions to resolve them: +documentation generated using `dart doc`, +as well as suggestions to resolve them. ### Search bar failed to load {#troubleshoot-search} From 075d7522fe076c1dfde3e5aa38cc96746247ac96 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 29 Jan 2024 21:41:45 -0600 Subject: [PATCH 3/8] Minor wording adjustment --- src/tools/dart-doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index e33b73576b..350568bb03 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -201,7 +201,7 @@ one of the following scenarios is possible: If you see text instead of icons like the menu and theme buttons, it likely means that the Material Symbols font failed to load. -To resolve this, you can: +Some options to solve this include: - Update the generated pages to use a local version of the font. - Use a proxy that enables access to the Google Fonts servers. From 9d374d456aea617a414276c905a6d7793d9289d1 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 5 Feb 2024 21:42:17 -0600 Subject: [PATCH 4/8] Apply initial set of suggestions from copy review Co-authored-by: Anthony Sansone --- src/tools/dart-doc.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index 350568bb03..fef91887b2 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -9,9 +9,8 @@ for Dart source code. ## Write documentation {#write} -You can add reference text and examples to the generated documentation -by using [documentation comments][], -which can contain [Markdown][] formatting. +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. @@ -42,9 +41,9 @@ Documenting my_package... Success! Docs generated into /Users/me/projects/my_package/doc/api ``` -By default, the generated documentation and supporting files are -placed in the `doc/api` directory. -To configure the output directory, specify +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: ```terminal @@ -62,8 +61,8 @@ $ dart doc --dry-run . ### 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 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]. @@ -78,14 +77,13 @@ TODO: Document the long-term supported options here. You can view docs generated with `dart doc` in a variety of ways. -### Locally {#view-local} +### View docs on local machine {#view-local} To view API docs you generated with `dart doc` or downloaded from online, you must load them with an HTTP server. -You can use any HTTP server to serve the files. -A common option is to use [`package:dhttpd`][] from pub.dev -to quickly serve the files. +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. @@ -102,7 +100,7 @@ open the link that `dhttpd` outputs, usually `http://localhost:8080`. [`package:dhttpd`]: https://pub.dev/packages/dhttpd -### Hosted {#view-hosted} +### View docs on hosted service {#view-hosted} You can also host your generated API docs online using any hosting service that supports static web content. @@ -113,7 +111,7 @@ Two common options are [Firebase hosting][] and [GitHub pages][]. ### Pub packages {#view-pub} -The [pub.dev site]({{site.pub}}) automatically generates and hosts +The [pub.dev site]({{site.pub}}) generates and hosts documentation for a package's public libraries. To view a package's generation docs, From 0b5fea778a339a76870389146dc637c5f56048ea Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 5 Feb 2024 22:49:04 -0600 Subject: [PATCH 5/8] Follow-up review adjustments --- src/tools/dart-doc.md | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index fef91887b2..2268f6fc96 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -61,8 +61,8 @@ $ dart doc --dry-run . ### 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 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]. @@ -77,7 +77,7 @@ TODO: Document the long-term supported options here. You can view docs generated with `dart doc` in a variety of ways. -### View docs on local machine {#view-local} +### 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. @@ -100,7 +100,7 @@ open the link that `dhttpd` outputs, usually `http://localhost:8080`. [`package:dhttpd`]: https://pub.dev/packages/dhttpd -### View docs on hosted service {#view-hosted} +### View hosted docs {#view-hosted} You can also host your generated API docs online using any hosting service that supports static web content. @@ -109,42 +109,38 @@ Two common options are [Firebase hosting][] and [GitHub pages][]. [Firebase hosting]: https://firebase.google.com/docs/hosting [GitHub pages]: https://pages.github.com/ -### Pub packages {#view-pub} +### View package docs {#view-pub} The [pub.dev site]({{site.pub}}) generates and hosts -documentation for a package's public libraries. +documentation for an uploaded package's public libraries. -To view a package's generation docs, +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). -### Dart core libraries {#view-sdk} +### 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. +that corresponds to the Dart release channel you are developing with: -`stable` -: [api.dart.dev/stable]({{site.dart-api}}) +| 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) | -`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 -The following are some common issues experienced with -documentation generated using `dart doc`, -as well as suggestions to resolve them. +To identify and resolve common issues with docs generated with `dart doc`, +consult the following possibilities. ### Search bar failed to load {#troubleshoot-search} @@ -169,7 +165,7 @@ 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 docs locally](#view-local). + check out [how to view local docs](#view-local). 2. You configured the generated docs' base-href behavior. This configuration option is deprecated and set for removal. Try removing the option and using the default behavior of `dart doc`. From d3345d6c341996700c0996f7911ef973f9b1577b Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Mon, 5 Feb 2024 23:25:12 -0600 Subject: [PATCH 6/8] A few more copy and formatting fixes --- src/tools/dart-doc.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/tools/dart-doc.md b/src/tools/dart-doc.md index 2268f6fc96..6053eac80f 100644 --- a/src/tools/dart-doc.md +++ b/src/tools/dart-doc.md @@ -134,13 +134,12 @@ that corresponds to the Dart release channel you are developing with: | `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 possibilities. +consult the following reference section. ### Search bar failed to load {#troubleshoot-search} @@ -163,11 +162,11 @@ 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 they aren't being served and loaded with an HTTP server. + 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. You configured the generated docs' base-href behavior. - This configuration option is deprecated and set for removal. +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][]. @@ -180,22 +179,23 @@ 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 API you are looking for is not exposed as a public API from the package. +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 trying to access has incorrect capitalization. - The filenames generated by `dart doc` are case-sensitive, - match the source declarations, and by default have a `.html` extension. +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, -it likely means that the Material Symbols font failed to load. +your browser was likely unable to load the Material Symbols font. Some options to solve this include: -- Update the generated pages to use a local version of the font. -- Use a proxy that enables access to the Google Fonts servers. +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. From 857211f2a8a7257d64a34fe96bf4facebceb4337 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Sun, 11 Feb 2024 15:39:56 -0600 Subject: [PATCH 7/8] Update code block language --- src/content/tools/dart-doc.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/tools/dart-doc.md b/src/content/tools/dart-doc.md index d77850036c..2ed188c446 100644 --- a/src/content/tools/dart-doc.md +++ b/src/content/tools/dart-doc.md @@ -32,7 +32,7 @@ run `dart doc .` from the package's root directory. For example, generating the API docs for a `my_package` package could look like the following: -```terminal +```console $ cd my_package $ dart pub get $ dart doc . @@ -46,7 +46,7 @@ and supporting files in the `doc/api` directory. To change the output directory, specify a path with the `--output` flag: -```terminal +```console $ dart doc --output=api_docs . ``` @@ -55,7 +55,7 @@ If there are any issues with your package setup or documentation comments, If you just want to test for issues without saving the generated documentation, add the `--dry-run` flag: -```terminal +```console $ dart doc --dry-run . ``` @@ -90,7 +90,7 @@ 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`: -```terminal +```console $ dart pub global activate dhttpd $ dart pub global run dhttpd --path doc/api ``` From 6f97a8336c4efd40732f6cf72df9b8ecc3d9c304 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Thu, 15 Feb 2024 12:11:34 -0600 Subject: [PATCH 8/8] Resemble --- src/content/tools/dart-doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/tools/dart-doc.md b/src/content/tools/dart-doc.md index 2ed188c446..959759b8b0 100644 --- a/src/content/tools/dart-doc.md +++ b/src/content/tools/dart-doc.md @@ -30,7 +30,7 @@ without errors. 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 look like the following: +could resemble the following: ```console $ cd my_package