Don't recommend setting html_root_url #230

jyn514 · 2020-11-18T22:28:42Z

See #229 for discussion.

BurntSushi

LGTM, but I don't have merge permission on this repo. And it would probably be good to give it a few days for others to chime in.

dtolnay · 2020-11-18T23:55:36Z

FWIW in my work codebase, in which all Rust projects (and all other languages) are built by Buck, there is no Cargo involved and Buck makes rustc and rustdoc invocations directly. See https://buck.build/rule/rust_library.html. When building documentation of a Rust target (buck build path/to/my/target#doc) third party code without an html_root_url would not be able to be linked.

jyn514 · 2020-11-19T00:01:51Z

@dtolnay I'm not very familiar with buck - does it use a shared build directory between dependencies? If so, rustdoc will pick up the documentation from the other dependencies without either --extern-html-root-url or html_root_url.

dtolnay · 2020-11-19T00:04:39Z

It does not use a shared build directory between dependencies. For example the output of buck build path/to/my/target#doc would always go into buck-out/gen/path/to/my/target#doc. If that target depends on some other target, the other target's docs are correspondingly somewhere else.

jyn514 · 2020-11-19T00:06:18Z

Hmm, I see. I'd expect most of the links to be broken then :/ I don't know many libraries setting html_root_url.

On nightly there's --extern-html-root-url, but the docs for buck say 1.33 is supported, so it wouldn't work on stable.

dtolnay · 2020-11-19T00:17:30Z

We're using the 1.48 prerelease so that's not a problem. We actually do use --extern-html-root-url for cross linking first-party code.

Regarding this:

When rustdoc needs to generate a link to an item in an external crate, it will first check if the extern crate has been documented locally on-disk, and if so link directly to it. Failing that, it will use the URL given by the --extern-html-root-url command-line flag if available. If that is not available, then it will use the html_root_url value in the extern crate if it is available. If that is not available, then the extern items will not be linked.

The reason I don't think this fits our use case is that the priority order is backwards. We can easily make Buck always pass a docs.rs extern-html-root-url for all third-party crates (like you might have been expecting rust-lang/cargo#8296 to wire up in the Cargo case) but that's wrong: Buck doesn't contain a Rust parser so it would have no idea whether the crate it's building already contains an html_root_url attribute. I think we'd be all set if html_root_url took precedence over extern-html-root-url but I'm not sure what other use case that breaks. Maybe this needs some separate flag.

jyn514 · 2020-11-19T00:20:09Z

I'm trying to imagine the scenario where html_root_url should take precedence - are you imagining pointing to a site other than docs.rs, like https://api.rocket.rs/ or something? I guess it does make sense in that case.

In general I don't think there's a clear answer here: docs.rs definitely wants --extern-html-root-url to take precedence, so we can't break that use case either. I'd be willing to add a switch toggling the precedence though.

dtolnay · 2020-11-19T00:22:32Z

Yes exactly. Or third party code that's not in the crates.io / docs.rs ecosystem at all.

jyn514 · 2020-11-19T00:29:28Z

Ok, so it sounds like there are two possible paths forward, both of which allow getting rid of html_root_url in the common case when you just want to link to docs.rs.

Have a flag for html_root_url to take precedence over --extern-html-root-url. Buck/Bazel/Cargo/etc. can unconditionally pass --extern-html-root-url without generating broken links, and the documentation will link to the right place automatically. Docs.rs can unconditionally pass the flag, without the override, because it knows all crates from crates.io are documented on docs.rs.
Have rustdoc link to docs.rs whenever html_root_url is unset and --extern-html-root-url is unset. Docs.rs continues passing --extern-html-root-url to override external docs (since it never wants to link to https://api.rocket.rs), buck doesn't have to pass it except when it actually wants to override docs.rs, and Tracking issue for -Zrustdoc-map cargo#8296 is no longer necessary.

I think doing both would be a mistake - do you have a preference for one or the other?

jyn514 · 2020-11-19T00:30:35Z

cc @rust-lang/rustdoc, @rust-lang/cargo: for context, we're talking about how to avoid broken links when documenting with --no-deps or a build system other than cargo.

dtolnay · 2020-11-19T00:55:29Z

Speaking for my own codebase the absolute best for us would actually be a rustc flag, not a rustdoc flag, which specified a "fallback html_root_url" for the current crate i.e. not DEP=URL like for --extern-html-root-url. We'd pass that from Buck during the compilation of third party code, and then when a doc build later depends on it, the links would go to the right place i.e. the crate's actual html_root_url if it provides one, otherwise the docs.rs fallback fed by our Buck config.

BurntSushi · 2020-11-19T00:57:49Z

Either way, it seems like we don't need to suggest setting html_root_url in the API guidelines?

jyn514 · 2020-11-19T02:40:24Z

@BurntSushi well, neither suggestion has been implemented yet. It depends whether you think the edge cases are worth worrying about.

ehuss · 2020-11-25T15:51:08Z

Have rustdoc link to docs.rs whenever html_root_url is unset and --extern-html-root-url is unset.

In this situation, how would rustdoc know this is a crates.io crate? I don't think rustdoc should have any automatic linking to docs.rs without some kind of command-line opt-in (or -Zrustdoc-map, which knows which crates exist on crates.io).

Either way, it seems like we don't need to suggest setting html_root_url in the API guidelines?

I think it would be reasonable to remove it. There are few scenarios where it is useful. One is running cargo doc --no-deps, but you want dependency links to still work. In that case, I think the user should just remove --no-deps, or use -Zrustdoc-map. Only about 4% of crates on crates.io set it, of those only 225 set it to a non-docs.rs site. In practice, I don't think it is in enough widespread use to warrant suggesting everyone set it. I think it only makes sense if you really want to link to a non-docs.rs site, which very few do.

jyn514 · 2020-11-25T15:56:22Z

In this situation, how would rustdoc know this is a crates.io crate?

Ahh, good point, I hadn't thought about path dependencies or private registries. I think having an option for html_root_url to override --extern-html-root-url is the way to go, then.

jyn514 · 2020-11-25T16:02:14Z

Should there be some way for the crate author to control the link destination? The documentation URL set in Cargo.toml is never consulted. I think this is unlikely to work with rustdoc, because it expects a certain structure to the API docs, and documentation URLs often point to user guides, or other things that aren't API docs. The #![doc(html_root_url = "...")] attribute is overridden by the --extern-html-root-url flag. This may be a good or bad thing depending on your perspective (should the user have control, or should the crate author?).

Maybe the flag addresses this, too? The user can override -Z rustdoc-map with html_root_url by passing the new flag (bikeshed: --html-root-takes-precedence). Or alternatively rustdoc can switch the default, and you can opt-in to having --extern-html-root-url take precedence, I don't feel strongly about what the default should be.

KodrAus · 2020-12-22T05:25:54Z

Kicked off an FCP in #229 for this.

jyn514 · 2021-02-13T21:32:32Z

@KodrAus the FCP finished, so I think this can be merged :)

SergioBenitez · 2021-03-04T18:56:53Z

All: I am quite confused about the rationale to stop recommending this attribute. The crux of the argument, if I'm reading this right, is that 1) docs.rs overrides the URL when it builds docs anyway, and 2) it's hard to keep the URL up to date. I find the former to be rather problematic with consideration for decentralization, local docs, and development docs, and the latter a non-issue.

On 1: not only does this point entirely ignore local documentation building, but it also ignores crates that host their own documentation. Rocket, for example, hosts its docs at https://api.rocket.rs. Hosting our own docs allows us to provide redundancy, ensuring docs are accessible should something go wrong with docs.rs, while also allowing us to ensure docs are always up to date without waiting or relying on a third-party source. This latter point is especially important when releasing a new version. The delay between publishing a new release and docs.rs building and updating docs can sometimes be considerable.

What's more, Rocket hosts docs for development versions that docs.rs does not and cannot build. See, for instance, https://api.rocket.rs/master. Without something like html_root_url or considerable manual effort to determine and set where every dependency's docs live, these docs, of at least equal importance, will contain broken links and be out of parity with the docs at docs.rs. It should be possible to independently build documentation that is as good as what's on docs.rs; removing the recommendation makes this considerably more difficult.

On 2: crates generally mention the version string in more places than just Cargo.toml, all of which need to be kept in sync as well, and so html_root_url shouldn't pose considerably more burden. For example, a crate's README often contains the TOML needed to add the crate as a dependency, which contains the version string. While this duplication is unfortunate, tools, like the one posted above, can ameliorate the situation. Rocket, for instance, automates changing the version number via a script to ensure they are all synchronized. Thus, adding one more version string to keep up-to-date should not pose considerably more burden, and certainly less so then needing to track down and keep up-to-date every dependency's preferred documentation URL should html_root_url be considered out of vogue entirely.

In summary, we should advocate for being able to build docs as good as those on docs.rs without being docs.rs for a variety of reasons, and the overhead to allowing this is minimal given existing realities. As such, it is my opinion that the recommendation for html_root_url should stay.

jyn514 · 2021-03-04T19:11:23Z

@SergioBenitez you can still do this perfectly well by simply not passing --no-deps when you document your crate.

jyn514 · 2021-03-04T19:23:27Z

Again, from #229, the only case where html_root_url actually affects things is when a downstream crate is documented with --no-deps and re-exports or links to one of your types. If any of those things aren't the case, then html_root_url does nothing at all.

SergioBenitez · 2021-03-04T19:28:13Z

@jyn514 This doesn't change any of the points I've made. I still cannot build docs like docs.rs can without being docs.rs. What's more, building the docs for all dependencies is wasteful, needlessly expensive, and creates clutter in the index.

jyn514 · 2021-03-04T19:34:41Z

I still cannot build docs like docs.rs can without being docs.rs.

You can build docs like docs.rs by passing -Z rustdoc-map the way it does: rust-lang/cargo#8296. That does require a nightly toolchain, but it's significantly more reliable than html_root_url, which most crates already don't set. If you want to go even further, you can build things exactly the same way as docs.rs by using the library we provide: https://github.com/rust-lang/docs.rs/blob/master/crates/metadata/lib.rs#L3.

I'm not trying to make a value judgement on whether or not you should use docs.rs. I just think this feature doesn't pull its weight, and I think it would better to stabilize -Z rustdoc-map instead of adding another task for library authors.

SergioBenitez · 2021-03-04T21:18:47Z

You can build docs like docs.rs by passing -Z rustdoc-map the way it does: rust-lang/cargo#8296. That does require a nightly toolchain, but it's significantly more reliable than html_root_url, which most crates already don't set. If you want to go even further, you can build things exactly the same way as docs.rs by using the library we provide: https://github.com/rust-lang/docs.rs/blob/master/crates/metadata/lib.rs#L3.

Thank you for bringing rustdoc-map to my attention! I was not aware of it prior. This appears to solve the "considerable manual effort to determine and set where every dependency's docs live" as long as we want to point all crate docs to a centralized source like docs.rs. It still does not provide a mechanism, however, for a crate author to dictate where its docs live and for its dependencies to point to that location without considerable effort. So while I see rustdoc-map as a wonderful fallback when html_root_url is not set, it is not a replacement.

I'm not trying to make a value judgement on whether or not you should use docs.rs. I just think this feature doesn't pull its weight, and I think it would better to stabilize -Z rustdoc-map instead of adding another task for library authors.

I think a nice compromise would be to:

Set rustdoc-map = docs.rs by default.
Have cargo-doc determine a crate's doc locations via html_root_url, then extern-html-root-url, then html_root_url, in that order of preference.
Change the guidelines to suggest setting html_root_url only when the preferred doc location is not docs.rs.

This would resolve all of my concerns while also avoiding the need for html_root_url when a crate author wants docs.rs to host their docs.

jyn514 · 2021-04-21T13:38:05Z

Have cargo-doc determine a crate's doc locations via html_root_url, then extern-html-root-url, then html_root_url, in that order of preference.

You said html_root_url twice - was there meant to be a third option?

SergioBenitez · 2021-04-21T14:04:50Z

Have cargo-doc determine a crate's doc locations via html_root_url, then extern-html-root-url, then html_root_url, in that order of preference.

You said html_root_url twice - was there meant to be a third option?

Indeed! Good catch. I meant to write rustdoc-map as the third option.

jyn514 · 2021-04-21T14:08:44Z

@SergioBenitez rustdoc-map is implemented in terms of extern-html-root-url, they can't have different precedence.

jyn514 · 2021-08-05T03:11:11Z

@KodrAus could you merge this? The FCP finished several months ago.

* Feature-gate test that depends on non-default features Makes `cargo check` work without extra flags. * Don't set doc(html_root_url) It is no longer recommended: rust-lang/api-guidelines#230 * Remove documentation URL from Cargo.toml crates.io will link to the right version on docs.rs automatically. * Ensure toolchains installed by actions-rs/toolchain are actually used * Fix missing rustup component in check job * Raise MSRV to 1.51 Older versions weren't actually working before. * Only run clippy & rustfmt on stable toolchain MSRV is checked in test-versions. * Allow cargo doc to succeed without headers and multipart features CI will still ensure that intra-doc links that rely on these are not broken.

…efault, but add a way to opt-in to the previous behavior ## What is an HTML root url? It tells rustdoc where it should link when documentation for a crate is not available locally; for example, when a crate is a dependency of a crate documented with `cargo doc --no-deps`. ## What is the difference between `html_root_url` and `--extern-html-root-url`? Both of these tell rustdoc what the HTML root should be set to. `doc(html_root_url)` is set by the crate author, while `--extern-html-root-url` is set by the person documenting the crate. These are often different. For example, docs.rs uses `--extern-html-root-url https://docs.rs/crate-name/version` to ensure all crates have documentation, even if `html_root_url` is not set. Conversely, crates such as Rocket set `doc(html_root_url = "https://api.rocket.rs")`, because they prefer users to view the documentation on their own site. Crates also set `html_root_url` to ensure they have documentation when building locally when offline. This is unfortunate to require, because it's more work from the library author. It also makes it impossible to distinguish between crates that want to be viewed on a different site (e.g. Rocket) and crates that just want documentation to be visible offline at all (e.g. Tokio). I have authored a separate change to the API guidelines to no longer recommend doing this: rust-lang/api-guidelines#230. ## Why change the default? In the past, docs.rs has been the main user of `--extern-html-root-url`. However, it's useful for other projects as well. In particular, Cargo wants to pass it by default when running `--no-deps` (rust-lang/cargo#8296). Unfortunately, for these other use cases, the priority order is inverted. They want to give *precedence* to the URL the crate picks, and only fall back to the `--extern-html-root` if no `html_root_url` is present. That allows passing `--extern-html-root` unconditionally, without having to parse the source code to see what attributes are present. For docs.rs, however, we still want to keep the old behavior, so that all links on docs.rs stay on the site.

…meGomez Give precedence to `html_root_url` over `--extern-html-root-url` by default, but add a way to opt-in to the previous behavior ## What is an HTML root url? It tells rustdoc where it should link when documentation for a crate is not available locally; for example, when a crate is a dependency of a crate documented with `cargo doc --no-deps`. ## What is the difference between `html_root_url` and `--extern-html-root-url`? Both of these tell rustdoc what the HTML root should be set to. `doc(html_root_url)` is set by the crate author, while `--extern-html-root-url` is set by the person documenting the crate. These are often different. For example, docs.rs uses `--extern-html-root-url https://docs.rs/crate-name/version` to ensure all crates have documentation, even if `html_root_url` is not set. Conversely, crates such as Rocket set `doc(html_root_url = "https://api.rocket.rs")`, because they prefer users to view the documentation on their own site. Crates also set `html_root_url` to ensure they have documentation when building locally when offline. This is unfortunate to require, because it's more work from the library author. It also makes it impossible to distinguish between crates that want to be viewed on a different site (e.g. Rocket) and crates that just want documentation to be visible offline at all (e.g. Tokio). I have authored a separate change to the API guidelines to no longer recommend doing this: rust-lang/api-guidelines#230. ## Why change the default? In the past, docs.rs has been the main user of `--extern-html-root-url`. However, it's useful for other projects as well. In particular, Cargo wants to pass it by default when running `--no-deps` (rust-lang/cargo#8296). Unfortunately, for these other use cases, the priority order is inverted. They want to give *precedence* to the URL the crate picks, and only fall back to the `--extern-html-root` if no `html_root_url` is present. That allows passing `--extern-html-root` unconditionally, without having to parse the source code to see what attributes are present. For docs.rs, however, we still want to keep the old behavior, so that all links on docs.rs stay on the site.

It is no longer recommended to set it: rust-lang/api-guidelines#230

cc: rust-lang/api-guidelines#230

It is no longer recommended to set it: rust-lang/api-guidelines#230

`tower` currently has required dependencies that may not be used unless certain features are enabled. This change updates `tower` to make these dependencies optional. Furthermore, this change removes use of `html_root_url`, which is no longer recommended (rust-lang/api-guidelines#230), and updates the documented release instructions.

Per rust-lang/api-guidelines#230 . This also avoids having something that needs to be kept updated.

The recommendation to set this has been removed from the Rust API guidelines: rust-lang/api-guidelines#230 It used to be used by docs.rs, but docs.rs now unconditionally sets the `--extern-html-root-url` parameter of rustdoc which overrides it, making it no longer needed and superfluous.

Don't recommend setting html_root_url

4fd7076

BurntSushi approved these changes Nov 18, 2020

View reviewed changes

jyn514 mentioned this pull request Nov 19, 2020

Link no-deps documentation with no html_root_url to docs.rs by default rust-lang/rust#42301

Open

KodrAus mentioned this pull request Dec 22, 2020

Justification of html_root_url is missing nuance #229

Closed

KodrAus added deletion needs-fcp This change is insta-stable, so needs a completed FCP to proceed. labels Dec 22, 2020

jhpratt mentioned this pull request Mar 4, 2021

Add doc(html_root_url) so links from external crates to time work time-rs/time#314

Closed

Lokathor mentioned this pull request Apr 21, 2021

Set html_root_url attribute Lokathor/bytemuck#60

Closed

Manishearth merged commit ac63584 into rust-lang:master Aug 5, 2021

jyn514 deleted the html-root-url branch August 5, 2021 04:01

eldruin mentioned this pull request Sep 25, 2021

Release 0.6.0 rust-embedded/rust-sysfs-gpio#70

Merged

jplatte added a commit to jplatte/tower that referenced this pull request Oct 15, 2021

Remove html_root_url

92f1ed2

It is no longer recommended to set it: rust-lang/api-guidelines#230

jplatte added a commit to jplatte/tower that referenced this pull request Oct 15, 2021

Remove html_root_url

e6449a1

It is no longer recommended to set it: rust-lang/api-guidelines#230

malobre mentioned this pull request Nov 5, 2021

Prepare 0.2.0 paolobarbolini/rusty-s3#38

Merged

eldruin added a commit to eldruin/embedded-hal that referenced this pull request Nov 19, 2021

Remove html_root_url as it is not recommended anymore.

eb90250

cc: rust-lang/api-guidelines#230

jplatte added a commit to jplatte/tower that referenced this pull request Jan 17, 2022

Remove html_root_url

7cf0617

It is no longer recommended to set it: rust-lang/api-guidelines#230

jplatte added a commit to jplatte/tower that referenced this pull request Jan 17, 2022

Remove html_root_url

e280aef

It is no longer recommended to set it: rust-lang/api-guidelines#230

olix0r mentioned this pull request Jan 26, 2022

Prepare v0.3.11 hyperium/h2#598

Merged

joshtriplett added a commit to rust-lang/libz-sys that referenced this pull request May 26, 2022

Drop html_root_url

0fd6fe6

Per rust-lang/api-guidelines#230 . This also avoids having something that needs to be kept updated.

tarcieri mentioned this pull request Dec 26, 2022

Don't set html_root_url dalek-cryptography/curve25519-dalek#483

Merged

brycx mentioned this pull request Mar 4, 2023

Remove html_root_url orion-rs/orion#325

Merged

newAM mentioned this pull request Apr 22, 2023

Remove html_root_url rust-embedded-community/embedded-nal#83

Merged

eldruin mentioned this pull request Jun 27, 2023

Remove html_root_url bitflags/bitflags#368

Merged

HalidOdat mentioned this pull request Oct 5, 2023

CHANGELOG.md update and version bump v0.2.2 -> v1.0.0 boa-dev/ryu-js#40

Merged

cuviper mentioned this pull request Dec 29, 2023

Remove doc html_root_url indexmap-rs/indexmap#292

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Don't recommend setting html_root_url #230

Don't recommend setting html_root_url #230

jyn514 commented Nov 18, 2020

BurntSushi left a comment

dtolnay commented Nov 18, 2020

jyn514 commented Nov 19, 2020

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020 •

edited

Loading

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020 •

edited

Loading

jyn514 commented Nov 19, 2020 •

edited

Loading

dtolnay commented Nov 19, 2020 •

edited

Loading

BurntSushi commented Nov 19, 2020

jyn514 commented Nov 19, 2020

ehuss commented Nov 25, 2020

jyn514 commented Nov 25, 2020

jyn514 commented Nov 25, 2020

KodrAus commented Dec 22, 2020

jyn514 commented Feb 13, 2021

SergioBenitez commented Mar 4, 2021

jyn514 commented Mar 4, 2021

jyn514 commented Mar 4, 2021 •

edited

Loading

SergioBenitez commented Mar 4, 2021

jyn514 commented Mar 4, 2021 •

edited

Loading

SergioBenitez commented Mar 4, 2021

jyn514 commented Apr 21, 2021

SergioBenitez commented Apr 21, 2021

jyn514 commented Apr 21, 2021

jyn514 commented Aug 5, 2021

Don't recommend setting html_root_url #230

Don't recommend setting html_root_url #230

Conversation

jyn514 commented Nov 18, 2020

BurntSushi left a comment

Choose a reason for hiding this comment

dtolnay commented Nov 18, 2020

jyn514 commented Nov 19, 2020

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020 • edited Loading

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020

dtolnay commented Nov 19, 2020

jyn514 commented Nov 19, 2020 • edited Loading

jyn514 commented Nov 19, 2020 • edited Loading

dtolnay commented Nov 19, 2020 • edited Loading

BurntSushi commented Nov 19, 2020

jyn514 commented Nov 19, 2020

ehuss commented Nov 25, 2020

jyn514 commented Nov 25, 2020

jyn514 commented Nov 25, 2020

KodrAus commented Dec 22, 2020

jyn514 commented Feb 13, 2021

SergioBenitez commented Mar 4, 2021

jyn514 commented Mar 4, 2021

jyn514 commented Mar 4, 2021 • edited Loading

SergioBenitez commented Mar 4, 2021

jyn514 commented Mar 4, 2021 • edited Loading

SergioBenitez commented Mar 4, 2021

jyn514 commented Apr 21, 2021

SergioBenitez commented Apr 21, 2021

jyn514 commented Apr 21, 2021

jyn514 commented Aug 5, 2021

jyn514 commented Nov 19, 2020 •

edited

Loading

jyn514 commented Nov 19, 2020 •

edited

Loading

jyn514 commented Nov 19, 2020 •

edited

Loading

dtolnay commented Nov 19, 2020 •

edited

Loading

jyn514 commented Mar 4, 2021 •

edited

Loading

jyn514 commented Mar 4, 2021 •

edited

Loading