Don't recommend setting html_root_url #230
Conversation
|
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 |
|
@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 |
|
It does not use a shared build directory between dependencies. For example the output of |
|
Hmm, I see. I'd expect most of the links to be broken then :/ I don't know many libraries setting On nightly there's |
|
We're using the 1.48 prerelease so that's not a problem. We actually do use Regarding this:
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 |
|
I'm trying to imagine the scenario where 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. |
|
Yes exactly. Or third party code that's not in the crates.io / docs.rs ecosystem at all. |
|
Ok, so it sounds like there are two possible paths forward, both of which allow getting rid of
I think doing both would be a mistake - do you have a preference for one or the other? |
|
cc @rust-lang/rustdoc, @rust-lang/cargo: for context, we're talking about how to avoid broken links when documenting with |
|
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. |
|
Either way, it seems like we don't need to suggest setting |
|
@BurntSushi well, neither suggestion has been implemented yet. It depends whether you think the edge cases are worth worrying about. |
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
I think it would be reasonable to remove it. There are few scenarios where it is useful. One is running |
Ahh, good point, I hadn't thought about path dependencies or private registries. I think having an option for |
Maybe the flag addresses this, too? The user can override |
|
Kicked off an FCP in #229 for this. |
KodrAus
added
deletion
needs-fcp
|
@KodrAus the FCP finished, so I think this can be merged :) |
|
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. |
|
@SergioBenitez you can still do this perfectly well by simply not passing |
|
Again, from #229, the only case where |
|
@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. |
You can build docs like docs.rs by passing 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 |
Thank you for bringing
I think a nice compromise would be to:
This would resolve all of my concerns while also avoiding the need for |
You said |
Indeed! Good catch. I meant to write |
|
@SergioBenitez rustdoc-map is implemented in terms of |
|
@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
It is no longer recommended to set it: rust-lang/api-guidelines#230
It is no longer recommended to set it: 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.
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.
See #229 for discussion.
r? @BurntSushi