[Flutter GPU] Generate package:flutter_gpu docs on api.flutter.dev. #153320
Description
flutter_gpu is an SDK package which is distributed using the same mechanism as sky_engine (the underlying package for dart:ui). So the package ends up under flutter/bin/cache/pkg/flutter_gpu once the tool fetches it.
(FYI @gspencergoog @mit-mit)
So far I've tried including a reference to flutter_gpu and removing the bin/cache exclusion, but this isn't enough to tickle dartdoc into picking it up:
diff --git a/dev/docs/README.md b/dev/docs/README.md
index 29ad418d67..3691cb30a0 100644
--- a/dev/docs/README.md
+++ b/dev/docs/README.md
@@ -84,6 +84,7 @@ They are organized by package and are imported using
```dart
import 'package:flutter_test/flutter_test.dart';
import 'package:file/local.dart';
+import 'package:flutter_gpu/gpu.dart';
```
## Packages on pub.dev
diff --git a/dev/tools/create_api_docs.dart b/dev/tools/create_api_docs.dart
index 74667b936c..aa41d20652 100644
--- a/dev/tools/create_api_docs.dart
+++ b/dev/tools/create_api_docs.dart
@@ -567,8 +567,8 @@ class DartdocGenerator {
'--allow-tools',
if (useJson) '--json',
if (validateLinks) '--validate-links' else '--no-validate-links',
- '--link-to-source-excludes',
- flutterRoot.childDirectory('bin').childDirectory('cache').path,
+ //'--link-to-source-excludes',
+ //flutterRoot.childDirectory('bin').childDirectory('cache').path,
'--link-to-source-root',
flutterRoot.path,
'--link-to-source-uri-template',
diff --git a/dev/tools/dartdoc_checker.dart b/dev/tools/dartdoc_checker.dart
index 314e64c145..873ab9dad3 100644
--- a/dev/tools/dartdoc_checker.dart
+++ b/dev/tools/dartdoc_checker.dart
@@ -17,6 +17,7 @@ const List<String> dartdocDirectiveCanaryLibraries = <String>[
'widgets',
'rendering',
'flutter_driver',
+ 'flutter_gpu',
];
/// Makes sure that the path we were given contains some of the expectedOutput from dev/bots/docs.sh:
❯ dev/bots/docs.sh --keep-staging
Mon Aug 12 15:00:02 PDT 2024: Running docs.sh
Writing docs build temporary output to /tmp/dartdoc.BBVFO/doc
Package dartdoc is currently active at version 8.0.12.
Downloading packages... .
The package dartdoc is already activated at newest available version.
To recompile executables, first run `dart pub global deactivate dartdoc`.
Installed executable dartdoc.
Activated dartdoc 8.0.12.
Building snippets tool executable.
Resolving dependencies...
Downloading packages...
_fe_analyzer_shared 72.0.0 (73.0.0 available)
analyzer 6.7.0 (6.8.0 available)
collection 1.18.0 (1.19.0 available)
coverage 1.8.0 (1.9.0 available)
http_parser 4.0.2 (4.1.0 available)
shelf 1.4.1 (1.4.2 available)
shelf_web_socket 1.0.4 (2.0.0 available)
web 0.5.1 (1.0.0 available)
web_socket_channel 2.4.5 (3.0.1 available)
Got dependencies!
9 packages have newer versions incompatible with dependency constraints.
Try `dart pub outdated` for more information.
Generated: /Users/bdero/projects/flutter/flutter/bin/cache/artifacts/snippets/snippets
Resolving dependencies...
Downloading packages...
_fe_analyzer_shared 72.0.0 (73.0.0 available)
analyzer 6.7.0 (6.8.0 available)
collection 1.18.0 (1.19.0 available)
coverage 1.8.0 (1.9.0 available)
http 0.13.6 (1.2.2 available)
http_parser 4.0.2 (4.1.0 available)
shelf 1.4.1 (1.4.2 available)
shelf_web_socket 1.0.4 (2.0.0 available)
web 0.5.1 (1.0.0 available)
web_socket_channel 2.4.5 (3.0.1 available)
Got dependencies!
10 packages have newer versions incompatible with dependency constraints.
Try `flutter pub outdated` for more information.
Copied /Users/bdero/projects/flutter/flutter/dev/docs/README.md to /tmp/dartdoc.BBVFO/README.md
Copied /Users/bdero/projects/flutter/flutter/dev/docs/analysis_options.yaml to /tmp/dartdoc.BBVFO/analysis_options.yaml
Copied /Users/bdero/projects/flutter/flutter/dev/docs/dartdoc_options.yaml to /tmp/dartdoc.BBVFO/dartdoc_options.yaml
Copied /Users/bdero/projects/flutter/flutter/dev/docs/assets/overrides.css to /tmp/dartdoc.BBVFO/doc/assets/overrides.css
Copied /Users/bdero/projects/flutter/flutter/dev/docs/assets/snippets.css to /tmp/dartdoc.BBVFO/doc/assets/snippets.css
Copied /Users/bdero/projects/flutter/flutter/dev/docs/assets/api_survey.js to /tmp/dartdoc.BBVFO/doc/assets/api_survey.js
Copied /Users/bdero/projects/flutter/flutter/dev/docs/assets/snippets.js to /tmp/dartdoc.BBVFO/doc/assets/snippets.js
Extracting android-javadoc.zip to /tmp/dartdoc.BBVFO/doc/javadoc
Android ready to go!
Extracting ios-docs.zip to /tmp/dartdoc.BBVFO/doc/ios-embedder
iOS ready to go!
Extracting macos-docs.zip to /tmp/dartdoc.BBVFO/doc/macos-embedder
macOS ready to go!
Extracting linux-docs.zip to /tmp/dartdoc.BBVFO/doc/linux-embedder
Linux ready to go!
Extracting windows-docs.zip to /tmp/dartdoc.BBVFO/doc/windows-embedder
Windows ready to go!
Extracting impeller-docs.zip to /tmp/dartdoc.BBVFO/doc/impeller
Impeller ready to go!
pub:stdout: Resolving dependencies...
pub:stdout: Downloading packages...
pub:stdout: + async 2.11.0
pub:stdout: + boolean_selector 2.1.1
pub:stdout: + characters 1.3.0
pub:stdout: + clock 1.1.1
pub:stdout: + collection 1.18.0 (1.19.0 available)
pub:stdout: + crypto 3.0.3
pub:stdout: + fake_async 1.3.1
pub:stdout: + file 7.0.0
pub:stdout: + flutter 0.0.0 from sdk flutter
pub:stdout: + flutter_driver 0.0.0 from sdk flutter
pub:stdout: + flutter_goldens 0.0.0 from sdk flutter
pub:stdout: + flutter_localizations 0.0.0 from sdk flutter
pub:stdout: + flutter_test 0.0.0 from sdk flutter
pub:stdout: + flutter_web_plugins 0.0.0 from sdk flutter
pub:stdout: + fuchsia_remote_debug_protocol 0.0.0 from sdk flutter
pub:stdout: + integration_test 0.0.0 from sdk flutter
pub:stdout: + intl 0.19.0
pub:stdout: + leak_tracker 10.0.5
pub:stdout: + leak_tracker_flutter_testing 3.0.5
pub:stdout: + leak_tracker_testing 3.0.1
pub:stdout: + matcher 0.12.16+1
pub:stdout: + material_color_utilities 0.11.1 (0.12.0 available)
pub:stdout: + meta 1.15.0
pub:stdout: + path 1.9.0
pub:stdout: + platform 3.1.5
pub:stdout: ! platform_integration 0.0.0 from path /Users/bdero/projects/flutter/flutter/dev/docs/platform_integration (overridden)
pub:stdout: + process 5.0.2
pub:stdout: + sky_engine 0.0.99 from sdk flutter
pub:stdout: + source_span 1.10.0
pub:stdout: + stack_trace 1.11.1
pub:stdout: + stream_channel 2.1.2
pub:stdout: + string_scanner 1.3.0
pub:stdout: + sync_http 0.3.1
pub:stdout: + term_glyph 1.2.1
pub:stdout: + test_api 0.7.3
pub:stdout: + typed_data 1.3.2
pub:stdout: + vector_math 2.1.4
pub:stdout: + vm_service 14.2.4
pub:stdout: + webdriver 3.0.3
pub:stdout: Changed 38 dependencies!
pub:stdout: 2 packages have newer versions incompatible with dependency constraints.
pub:stdout: Try `flutter pub outdated` for more information.
dartdoc version: 8.0.12
flutter version: 3.24.0-1.0.pre.426
Executing: (cd "/tmp/dartdoc.BBVFO" ; /Users/bdero/projects/flutter/flutter/bin/dart global run --enable-asserts dartdoc --output /tmp/dartdoc.BBVFO/doc/flutter --allow-tools --no-validate-links --link-to-source-root /Users/bdero/projects/flutter/flutter --link-to-source-uri-template https://github.com/flutter/flutter/blob/main/%f%#L%l% --inject-html --use-base-href --header /Users/bdero/projects/flutter/flutter/dev/docs/styles.html --header /Users/bdero/projects/flutter/flutter/dev/docs/analytics-header.html --header /Users/bdero/projects/flutter/flutter/dev/docs/survey.html --header /Users/bdero/projects/flutter/flutter/dev/docs/snippets.html --header /Users/bdero/projects/flutter/flutter/dev/docs/opensearch.html --footer /Users/bdero/projects/flutter/flutter/dev/docs/analytics-footer.html --footer-text /tmp/dartdoc.BBVFO/footer.html --allow-warnings-in-packages Flutter,platform_integration,flutter_web_plugins,integration_test,flutter_goldens,flutter,flutter_localizations,flutter_driver,flutter_test --exclude-packages analyzer,args,barback,csslib,flutter_goldens,flutter_goldens_client,front_end,fuchsia_remote_debug_protocol,glob,html,http_multi_server,io,isolate,js,kernel,logging,mime,mockito,node_preamble,plugin,shelf,shelf_packages_handler,shelf_static,shelf_web_socket,utf,watcher,yaml --exclude dart:io/network_policy.dart,package:Flutter/temp_doc.dart,package:http/browser_client.dart,package:intl/intl_browser.dart,package:matcher/mirror_matchers.dart,package:quiver/io.dart,package:quiver/mirrors.dart,package:vm_service_client/vm_service_client.dart,package:web_socket_channel/html.dart --favicon /Users/bdero/projects/flutter/flutter/dev/docs/favicon.ico --package-order flutter,Dart,platform_integration,flutter_test,flutter_driver --auto-include-dependencies)
dartdoc:stdout: Documenting Flutter...
dartdoc:stdout: Discovering libraries...
dartdoc:stdout: Linking elements...
dartdoc:stdout: Precaching local docs for 814951 elements...
dartdoc:stdout: Initialized dartdoc with 1305 libraries
dartdoc:stdout: Generating docs for package flutter...
dartdoc:stdout: Generating docs for package Dart...
dartdoc:stdout: Generating docs for package platform_integration...
dartdoc:stdout: Generating docs for package flutter_test...
dartdoc:stdout: Generating docs for package flutter_driver...
dartdoc:stdout: Generating docs for package Flutter...
dartdoc:stdout: Generating docs for package flutter_localizations...
dartdoc:stdout: Generating docs for package flutter_web_plugins...
dartdoc:stdout: Generating docs for package leak_tracker_flutter_testing...
dartdoc:stdout: Generating docs for package async...
dartdoc:stdout: Generating docs for package boolean_selector...
dartdoc:stdout: Generating docs for package characters...
dartdoc:stdout: Generating docs for package clock...
dartdoc:stdout: Generating docs for package collection...
dartdoc:stdout: Generating docs for package crypto...
dartdoc:stdout: Generating docs for package fake_async...
dartdoc:stdout: Generating docs for package file...
dartdoc:stdout: Generating docs for package integration_test...
dartdoc:stdout: Generating docs for package intl...
dartdoc:stdout: Generating docs for package leak_tracker...
dartdoc:stdout: Generating docs for package leak_tracker_testing...
dartdoc:stdout: Generating docs for package matcher...
dartdoc:stdout: Generating docs for package material_color_utilities...
dartdoc:stdout: Generating docs for package meta...
dartdoc:stdout: Generating docs for package path...
dartdoc:stdout: Generating docs for package platform...
dartdoc:stdout: Generating docs for package process...
dartdoc:stdout: Generating docs for package source_span...
dartdoc:stdout: Generating docs for package stack_trace...
dartdoc:stdout: Generating docs for package stream_channel...
dartdoc:stdout: Generating docs for package string_scanner...
dartdoc:stdout: Generating docs for package sync_http...
dartdoc:stdout: Generating docs for package term_glyph...
dartdoc:stdout: Generating docs for package test_api...
dartdoc:stdout: Generating docs for package typed_data...
dartdoc:stdout: Generating docs for package vector_math...
dartdoc:stdout: Generating docs for package vm_service...
dartdoc:stdout: Generating docs for package webdriver...
dartdoc:stderr: Found 0 warnings and 0 errors.
dartdoc:stdout: Documented 159 public libraries in 196.2 seconds
dartdoc:stdout: Success! Docs generated into /tmp/dartdoc.BBVFO/doc/flutter
Scanning for unresolved dartdoc directives...
Unhandled exception:
Exception: Did not find docs for the following libraries: flutter_gpu.
#0 checkForUnresolvedDirectives (file:///Users/bdero/projects/flutter/flutter/dev/tools/dartdoc_checker.dart:79:5)
#1 DartdocGenerator.generateDartdoc (file:///Users/bdero/projects/flutter/flutter/dev/tools/create_api_docs.dart:679:5)
<asynchronous suspension>
#2 main (file:///Users/bdero/projects/flutter/flutter/dev/tools/create_api_docs.dart:144:3)
<asynchronous suspension>