rustdoc HTML roots issues

[alexlian]

Discussed in #705

^{Originally posted by cormacrelf June 28, 2024}
This is very minor, but maybe a useful report in relation to the recent commit 7cc8415

Delete support for --extern-html-root-url

Use rustc_flags += ["-Zcrate-attr=doc(html_root_url = {})".format(...)] in a macro instead.

If we reinstate an html_root_url_prefix attribute on the RustToolchainInfo in the future, we might want to consider doing it in a way that supports different prefixes per cell, or by package prefix.

html_root_url_prefix = {
    "fbcode": "/intern/rustdoc",
}

I recently got a convoluted rustdoc build going. I did in fact mess with html_root_url_prefix on RustToolchainInfo, and did pretty much what is described there.

My experience was that it was not close to being flexible enough. Linking to https://docs.rs for third party crates (from reindeer) with the correct version number is the litmus test for anything like this. Was not feasible with a dict of package prefixes. The issues were:

1. the part of the code that was writing the --extern-html-root-url args has access to a RustDependency (or whatever) structure, whose name can be different from the original rust_library's. The name often comes from an alias rule. You need to look through aliases to find the crate name that you should generate a link from, otherwise you may be linking to nowhere. This is possible but very hacky. (My code examined one of the .rlib artefacts and got its owner's label.)
2. I ended up writing a miniature string templater for the full URL to put ${label.name} etc in the right spots, because what the prelude was appending after the html_root_url_prefix was not suitable.
3. And for docs.rs, which required parsing the label, I basically ended up writing out the full package name wrapped in some easily replaced text, and literally using sed on all the HTML to turn that into a docs.rs URL. It was bad and slow.

Overall, the single dict of strings on the toolchain approach was terrible. Would not recommend bringing it back. The toolchain was simply the wrong place for it. In the next attempt I will use -Zcrate-attr as recommended, and obviously that will be very simple to apply to reindeer generated BUCK files. You can just do the $name-$version parsing in the macro and put a docs.rs URL in there.