bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Give precedence to html_root_url over --extern-html-root-url by default, but add a way to opt-in to the previous behavior

Browse source 
## 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:
https://github.com/rust-lang/api-guidelines/pull/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`
(https://github.com/rust-lang/cargo/issues/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.
This commit is contained in:
Joshua Nelson 2021-03-04 15:03:22 -05:00
parent 6d300391ed
commit 18f0f242e1
9 changed files with 51 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

13
src/librustdoc/formats/cache.rs
View file

@ -1,6 +1,4 @@
use std::collections::BTreeMap;
use std::mem;
use std::path::Path;
use rustc_data_structures::fx::{FxHashMap, FxHashSet};
use rustc_hir::def_id::{CrateNum, DefId, CRATE_DEF_INDEX};
@ -9,6 +7,7 @@ use rustc_middle::ty::TyCtxt;
use rustc_span::symbol::sym;
use crate::clean::{self, GetDefId, ItemId};
use crate::config::RenderOptions;
use crate::fold::DocFolder;
use crate::formats::item_type::ItemType;
use crate::formats::Impl;
@ -142,19 +141,21 @@ impl Cache {
&mut self,
mut krate: clean::Crate,
tcx: TyCtxt<'_>,
extern_html_root_urls: &BTreeMap<String, String>,
dst: &Path,
render_options: &RenderOptions,
) -> clean::Crate {
// Crawl the crate to build various caches used for the output
debug!(?self.crate_version);
self.traits = krate.external_traits.take();
let RenderOptions { extern_html_root_takes_precedence, output: dst, .. } = render_options;
// Cache where all our extern crates are located
// FIXME: this part is specific to HTML so it'd be nice to remove it from the common code
for &e in &krate.externs {
let name = e.name(tcx);
let extern_url = extern_html_root_urls.get(&*name.as_str()).map(|u| &**u);
self.extern_locations.insert(e.crate_num, e.location(extern_url, &dst, tcx));
let extern_url =
render_options.extern_html_root_urls.get(&*name.as_str()).map(|u| &**u);
let location = e.location(extern_url, *extern_html_root_takes_precedence, dst, tcx);
self.extern_locations.insert(e.crate_num, location);
self.external_paths.insert(e.def_id(), (vec![name.to_string()], ItemType::Module));
}