bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Auto merge of #51384 - QuietMisdreavus:extern-version, r=GuillaumeGomez

Browse source 
rustdoc: add flag to control the html_root_url of dependencies

The `--extern-html-root-url` flag in this PR allows one to override links to crates whose docs are not already available locally in the doc bundle. Docs.rs currently uses a version of this to make sure links to other crates go into that crate's docs.rs page. See the included test for intended use, but the idea is as follows:

Calling rustdoc with `--extern-html-root-url crate=https://some-url.com` will cause rustdoc to override links that point to that crate to instead be replaced with a link rooted at `https://some-url.com/`. (e.g. for docs.rs this would be `https://docs.rs/crate/0.1.0` or the like.) Cheekily, rustup could use these options to redirect links to std/core/etc to instead point to locally-downloaded docs, if it so desired.

Fixes https://github.com/rust-lang/rust/issues/19603
This commit is contained in:
bors 2018-08-31 17:39:28 +00:00
commit aaa170bebe
4 changed files with 76 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

30
src/librustdoc/lib.rs
View file

@ -162,6 +162,10 @@ fn opts() -> Vec<RustcOptGroup> {
stable("extern", |o| {
o.optmulti("", "extern", "pass an --extern to rustc", "NAME=PATH")
}),
unstable("extern-html-root-url", |o| {
o.optmulti("", "extern-html-root-url",
"base URL to use for dependencies", "NAME=URL")
}),
stable("plugin-path", |o| {
o.optmulti("", "plugin-path", "removed", "DIR")
}),
@ -453,6 +457,13 @@ fn main_args(args: &[String]) -> isize {
return 1;
}
};
let extern_urls = match parse_extern_html_roots(&matches) {
Ok(ex) => ex,
Err(err) => {
diag.struct_err(err).emit();
return 1;
}
};
let test_args = matches.opt_strs("test-args");
let test_args: Vec<String> = test_args.iter()
@ -553,7 +564,7 @@ fn main_args(args: &[String]) -> isize {
info!("going to format");
match output_format.as_ref().map(|s| &**s) {
Some("html") | None => {
html::render::run(krate, &external_html, playground_url,
html::render::run(krate, extern_urls, &external_html, playground_url,
output.unwrap_or(PathBuf::from("doc")),
resource_suffix.unwrap_or(String::new()),
passes.into_iter().collect(),
@ -612,6 +623,23 @@ fn parse_externs(matches: &getopts::Matches) -> Result<Externs, String> {
Ok(Externs::new(externs))
}
/// Extracts `--extern-html-root-url` arguments from `matches` and returns a map of crate names to
/// the given URLs. If an `--extern-html-root-url` argument was ill-formed, returns an error
/// describing the issue.
fn parse_extern_html_roots(matches: &getopts::Matches)
-> Result<BTreeMap<String, String>, &'static str>
{
let mut externs = BTreeMap::new();
for arg in &matches.opt_strs("extern-html-root-url") {
let mut parts = arg.splitn(2, '=');
let name = parts.next().ok_or("--extern-html-root-url must not be empty")?;
let url = parts.next().ok_or("--extern-html-root-url must be of the form name=url")?;
externs.insert(name.to_string(), url.to_string());
}
Ok(externs)
}
/// Interprets the input file as a rust source file, passing it through the
/// compiler all the way through the analysis passes. The rustdoc output is then
/// generated from the cleaned AST of the crate.