dart doc fails in built SDK

[mit-mit]

Repro steps:

In a bleeding edge SDK, run:

dart create -t package-simple pkg1
cd pkg1
dart doc .

=>

mit-macbookpro5:pkg1 mit$ ~/tmp/dart-sdk/bin/dart doc .
Documenting pkg1...
Initialized dartdoc with 40 libraries in 13.8 seconds
Generating docs for library pkg1 from package:pkg1/pkg1.dart...

dartdoc 4.1.0 (/Users/mit/tmp/pkg1/dartdev) failed: Invalid argument (uri): Unknown package: Instance of '_SimpleUri'
#0      ResourceLoader.resolveResourceUri.<anonymous closure> (package:dartdoc/src/generator/resource_loader.dart:46:11)
#1      _rootRunUnary (dart:async/zone.dart:1434:47)
#2      _CustomZone.runUnary (dart:async/zone.dart:1335:19)
<asynchronous suspension>
#3      ResourceLoader.getResourceFile (package:dartdoc/src/generator/resource_loader.dart:31:15)
<asynchronous suspension>
#4      ResourceLoader.loadResourceAsBytes (package:dartdoc/src/generator/resource_loader.dart:27:13)
<asynchronous suspension>
#5      HtmlGeneratorBackend._copyResources (package:dartdoc/src/generator/html_generator.dart:71:11)
<asynchronous suspension>
#6      HtmlGeneratorBackend.generateAdditionalFiles (package:dartdoc/src/generator/html_generator.dart:49:5)
<asynchronous suspension>
#7      GeneratorFrontEnd.generate (package:dartdoc/src/generator/generator_frontend.dart:22:5)
<asynchronous suspension>
#8      Dartdoc.generateDocsBase (package:dartdoc/dartdoc.dart:196:5)
<asynchronous suspension>
#9      Dartdoc.generateDocs (package:dartdoc/dartdoc.dart:233:24)
<asynchronous suspension>
#10     Dartdoc.executeGuarded.<anonymous closure> (package:dartdoc/dartdoc.dart:493:9)
<asynchronous suspension>

[mit-mit]

The dart doc command was introduced in https://dart-review.googlesource.com/c/sdk/+/217980

Reverting in https://dart-review.googlesource.com/c/sdk/+/220006

[mit-mit]

Problem diagnosis: dartdoc relies on resources for creating it's output. In a built SDK those are in a package:dartdoc resource package located in <SDK dir>/bin/resources/dartdoc. The regular dartdoc command is told about these via a .packages file in that directory containing just:

mit-macbookpro5:dartdoc mit$ cat .packages
dartdoc:.

This .packages file is passed to dart in the dartdoc wrapper script:

# We are running the snapshot in the built SDK.
DART="$BIN_DIR/dart"
exec "$DART" "--packages=$BIN_DIR/resources/dartdoc/.packages" "$SNAPSHOT" "$@"

When we run dart doc that .packages file is never passed, and thus it fails when trying to locate the resource package.

[mit-mit]

cc @bkonyi any good ideas for how to handle this?

[bkonyi]

We'll either need to not use package:* URIs for loading resources, using relative paths instead, or provide an option to pass the resources directory into package:dartdoc. We can't rely on any particular .packages file since there may have been one provided by the user. cc @jcollins-g

[lrhn]

I highly recommend not using package: URIs for run-time resources. It doesn't work for AoT compilation.

Perhaps require the caller who starts DartDoc to pass you a URI pointing to the resource directory. Or allow it, and fall back on the default package: URI which only works when running directly from the package with dart run dartdoc.

[mit-mit]

Yeah, the caller knows where the resource directory is, so it's pretty easy to pass that to dartdoc:
https://dart-review.googlesource.com/c/sdk/+/220744/3..4

I just don't know how to change dartdoc to actually read from this location, as it's code for locating resources is a bit hard for me to grok.

[mit-mit]

Closing this issue as this was reverted in https://dart-review.googlesource.com/c/sdk/+/220006 (and thus no longer fails in main).

The dart doc command will be re-added in a new CL.