Repository navigation
[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>
Activity
gspencergoog commentedon Aug 12, 2024
I tried added a fake reference to the package, but since it is just a stub package (published a v0.0.1), it generates a blank page. How is
flutter_gpuintended to be imported/depended upon by a regular app?gspencergoog commentedon Aug 12, 2024
Duh. I see above. I'll try that and see if my fake reference will pick it up.
bdero commentedon Aug 12, 2024
Yeah the stub package on pub.dev is just me "illegally" parking the name. It's actually supposed to be imported as an SDK package and is tied to a particular engine version, similar to sky_engine/dart:ui.
bdero commentedon Aug 12, 2024
Once we have the docs on api.flutter.dev we're going to add a redirect, similar to the other reserved Flutter SDK package names.
gspencergoog commentedon Aug 12, 2024
So should it actually be an SDK dependency like so (in pubspec.yaml)?:
bdero commentedon Aug 12, 2024
Yes exactly.
gspencergoog commentedon Aug 12, 2024
Okay, I have a fix for this. I'll write a test, and you can review @bdero, OK?
bdero commentedon Aug 12, 2024
@gspencergoog Awesome, you rock. : )
Add fake dependency on flutter_gpu for the docs (#153325)
Add fake dependency on flutter_gpu for the docs (flutter#153325)
github-actions commentedon Aug 27, 2024
This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of
flutter doctor -vand a minimal reproduction of the issue.Add fake dependency on flutter_gpu for the docs (flutter#153325)