[CP] [Stable] Cherry-pick request for updating dartdoc to fix sidebar generation

[parlough]

Commit(s) to merge

https://dart.googlesource.com/sdk/+/279f6d77aed890abfdd0d93341d8b94239dca610

Target

stable

Prepared changelist for beta/stable

https://dart-review.googlesource.com/c/sdk/+/336780

Issue Description

#54067

There are two primary issues:

• As seen in the api.dart.dev 3.2.0 API docs (Example), the sidenavs are not inserted on non-class pages.
• Even if the sidebars were added correctly, the links were incorrect in the sidebar if not using base-href, preventing from them adjusted by the JS that adds in the sidebar. (Broken links in generated "API reference" pub-dev#7058).

What is the fix

Update to the earliest dartdoc commit that includes the necessary fixes. 279f6d7 updates to dart-lang/dartdoc@8c10339 which includes all three fixes:

• dart-lang/dartdoc@c147aa1
• dart-lang/dartdoc@5156398
• dart-lang/dartdoc@4283dbc

These fixes are however not isolated and are mixed with a few other minor changes in the range dart-lang/dartdoc@a3cfdc4...8c10339.

@srawlins outlined the other commits as:

• 4 commits that affect the dart doc command for users (but would not affect what we see at api.dart.dev) (dart-lang/dartdoc@59947b1, dart-lang/dartdoc@affc5b4, dart-lang/dartdoc@e30bece, dart-lang/dartdoc@6bcf07f)
• the rest are non-generation, non-UI commits (changes to development tools, tests, no-op refactors)

As part of those 4 commits, support for the hideSdkText option was dropped, but it was already hidden and not exposed by the dart doc CLI.

Why cherry-pick

The 3.2 API docs will be Dart developer's view into the SDK's public APIs for the next several months. Having a missing sidebar makes navigation across the site quite difficult and less accessible, and will be especially jarring for users who expect it to be there.

Without these fixes, user's own docs generated with dart doc will also be affected. Pub updates dartdoc separately so it does not need this cherry-pick.

Risk

low/medium

Issue link(s)

#54067, dart-lang/pub-dev#7058

Extra Info

Flutter has been using a version with these commits/fixes to generate their main-api docs since flutter/flutter@997a94f.

[itsjustkevin]

@mit-mit I see this as a P0 and would like to get it cherry-picked in.

CC: @MaryaBelanger

[vsmenon]

@srawlins - what is your take on benefit / risk?

[srawlins]

I support this cherry-pick. Here are some details about the dartdoc commits being added:

• 3 fixes to the sidebars (dart-lang/dartdoc@c147aa1, dart-lang/dartdoc@5156398, dart-lang/dartdoc@4283dbc)
• 4 commits that affect the dart doc command for users (but would not affect what we see at api.dart.dev) (dart-lang/dartdoc@59947b1, dart-lang/dartdoc@affc5b4, dart-lang/dartdoc@e30bece, dart-lang/dartdoc@6bcf07f)
• the rest are non-generation, non-UI commits (changes to development tools, tests, no-op refactors)

I'll also note that Flutter bumped to dartdoc 7.0.1, for generation of api.flutter.dev, with flutter/flutter@997a94f, on Oct 20. They have not reported any regressions since running with that bump.

So this cherry-pick would contain 3 commits that fix the issue at hand, and 4 unrelated changes that may affect the output of a developer locally running dart doc.

Any unknown regressions would only affect the rendered docs at api.dart.dev (until we could land fixes), and output from a developer running dart doc locally; any unknown regressions would not affect docs at pub.dev or at api.flutter.dev. Therefore I think the risk is very very low of this cherry-pick causing anything more than a minor issue that could be corrected in a short time.

[vsmenon]

Thanks - lgtm

[parlough]

Thanks all!

I've updated the changelog in the CL as requested as well.

@sortie Does the release team submit the CL when ready or should I get someone else to submit it for me?

[sortie]

The normal workflow applies here once the cherry-pick-approved label is granted. Since you can't submit AFAIK, yeah, get someone to help you. I can do that for you if you want just let me know :)

[parlough]

I can do that for you if you want just let me know :)

That would be great! Thank you 😄

[athomas]

Released in 3.2.1.