How to generate docs for a package which is a re-export of an SDK vendored package?

[jakemac53]

The macros package will be a pub package, which only re-exports APIs from the _macros package, which is an SDK vendored package.

I can generate docs for the macros package today, but the API that it sees will be that of package:_macros from the current SDK. In the case of pub generated docs for packages, this will either just fail (if it tries to do a pub get, the version solve will fail unless the version is the exact one it requires), or it will generate wrong documentation (based on the SDK pub used to generate the docs, not the SDK that the package is tied to).

One idea, is to generate the docs for package:macros with the SDK docs, hosted at api.dart.dev, and just redirect the pub docs link to there?

[sigurdm]

We recently introduced dynamic fetching of analysis/dartdoc sdk based on the sdk constraint.

If the sdk constraint of the package does not satisfy the one pub has fixed, it will attempt to download the latest matching sdk.

I think this will work for package:macros:

• package:macros will have an sdk constraint that differs from what pub has built in.
• A matching sdk will be downloaded and used for generating dartdoc.

[jakemac53]

Oh ok interesting. We weren't actually planning on bumping the min SDK I don't think, and often would be publishing pre-releases that are only available on the main channel SDK (due to the _macros constraint).

We are trying to avoid being tightly coupled with SDK releases to make that process go as smoothly as possible. But, maybe we can make something work.

[sigurdm]

If the package can be used with multiple sdk's I guess that docs generated with any of those sdks should be valid?

[jakemac53]

If the package can be used with multiple sdk's I guess that docs generated with any of those sdks should be valid?

For most releases, they will only actually be able to get a version solve on the absolute latest SDK, but this is through the _macros (SDK vendored) constraint and not the SDK constraint.

After that point, the package is only resolvable until the next change to _macros as well. So you do need a very specific version range in order to get any specific version of package:macros

[sigurdm]

Ah gotcha. Not sure how we'll support that.

[jakemac53]

Given how tightly linked it is to the SDK, I think it makes sense for the docs to be generated with the SDK docs?

[sigurdm]

But where should they be served? api.dartlang.org? Perhaps that would make some sense, but require some special casing.

[isoos]

Given how tightly linked it is to the SDK, I think it makes sense for the docs to be generated with the SDK docs?

There are two things that make this not possible right now:

SDK selection is based only the actual package constraints, and does not consider any dependent packages. (This is something we could look into, but for the time being, we can assume this remains).

The dartdoc version we are using is relatively tightly controlled, as we parse and re-format parts of the output. We can't really rely on arbitrary versions tied into the SDKs, as they may be changing the layout, identifiers or file formats.

I think it should be helpful if the package would have at least a prerelease min SDK constraint, so that we don't attempt resolve it with a stable SDK.

[jakemac53]

I think it should be helpful if the package would have at least a prerelease min SDK constraint, so that we don't attempt resolve it with a stable SDK.

The problem is we don't know what constraint to put... we don't know what dev release it will be associated with until after the changes land. And need to publish right away for users on the main channel.

[isoos]

The problem is we don't know what constraint to put... we don't know what dev release it will be associated with until after the changes land.

Use whatever the latest dev SDK version is. It is very likely that it will trigger the master branch analysis, unless it will be part of the beta or the stable channel, but at that point you may have another version out.