Skip to content

Add resource-suffix option for rustdoc #48511

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 8, 2018
Merged

Add resource-suffix option for rustdoc #48511

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions src/librustdoc/html/layout.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ pub struct Page<'a> {
pub root_path: &'a str,
pub description: &'a str,
pub keywords: &'a str,
pub resource_suffix: &'a str,
}

pub fn render<T: fmt::Display, S: fmt::Display>(
Expand All @@ -47,12 +48,13 @@ r##"<!DOCTYPE html>
<title>{title}</title>
<link rel="stylesheet" type="text/css" href="{root_path}normalize.css">
<link rel="stylesheet" type="text/css" href="{root_path}rustdoc.css" id="mainThemeStyle">
<link rel="stylesheet" type="text/css" href="{root_path}normalize{suffix}.css">
<link rel="stylesheet" type="text/css" href="{root_path}rustdoc{suffix}.css"
id="mainThemeStyle">
{themes}
<link rel="stylesheet" type="text/css" href="{root_path}dark.css">
<link rel="stylesheet" type="text/css" href="{root_path}main.css" id="themeStyle">
<script src="{root_path}storage.js"></script>
<link rel="stylesheet" type="text/css" href="{root_path}dark{suffix}.css">
<link rel="stylesheet" type="text/css" href="{root_path}main{suffix}.css" id="themeStyle">
<script src="{root_path}storage{suffix}.js"></script>
{css_extension}
{favicon}
Expand All @@ -76,11 +78,11 @@ r##"<!DOCTYPE html>
<div class="theme-picker">
<button id="theme-picker" aria-label="Pick another theme!">
<img src="{root_path}brush.svg" width="18" alt="Pick another theme!">
<img src="{root_path}brush{suffix}.svg" width="18" alt="Pick another theme!">
</button>
<div id="theme-choices"></div>
</div>
<script src="{root_path}theme.js"></script>
<script src="{root_path}theme{suffix}.js"></script>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
Expand Down Expand Up @@ -153,13 +155,14 @@ r##"<!DOCTYPE html>
window.rootPath = "{root_path}";
window.currentCrate = "{krate}";
</script>
<script src="{root_path}main.js"></script>
<script src="{root_path}main{suffix}.js"></script>
<script defer src="{root_path}search-index.js"></script>
</body>
</html>"##,
css_extension = if css_file_extension {
format!("<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}theme.css\">",
root_path = page.root_path)
format!("<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}theme{suffix}.css\">",
root_path = page.root_path,
suffix=page.resource_suffix)
} else {
"".to_owned()
},
Expand Down Expand Up @@ -191,8 +194,10 @@ r##"<!DOCTYPE html>
.filter_map(|t| t.file_stem())
.filter_map(|t| t.to_str())
.map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}{}">"#,
page.root_path, t))
page.root_path,
t.replace(".css", &format!("{}.css", page.resource_suffix))))
.collect::<String>(),
suffix=page.resource_suffix,
)
}

Expand Down
51 changes: 36 additions & 15 deletions src/librustdoc/html/render.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
//! for creating the corresponding search index and source file renderings.
//! These threads are not parallelized (they haven't been a bottleneck yet), and
//! both occur before the crate is rendered.

pub use self::ExternalLocation::*;

use std::borrow::Cow;
Expand Down Expand Up @@ -128,6 +129,9 @@ pub struct SharedContext {
pub sort_modules_alphabetically: bool,
/// Additional themes to be added to the generated docs.
pub themes: Vec<PathBuf>,
/// Suffix to be added on resource files (if suffix is "-v2" then "main.css" becomes
/// "main-v2.css").
pub resource_suffix: String,
}

impl SharedContext {
Expand Down Expand Up @@ -492,6 +496,7 @@ pub fn run(mut krate: clean::Crate,
external_html: &ExternalHtml,
playground_url: Option<String>,
dst: PathBuf,
resource_suffix: String,
passes: FxHashSet<String>,
css_file_extension: Option<PathBuf>,
renderinfo: RenderInfo,
Expand Down Expand Up @@ -520,6 +525,7 @@ pub fn run(mut krate: clean::Crate,
created_dirs: RefCell::new(FxHashSet()),
sort_modules_alphabetically,
themes,
resource_suffix,
};

// If user passed in `--playground-url` arg, we fill in crate name here
Expand Down Expand Up @@ -734,7 +740,7 @@ fn write_shared(cx: &Context,
// Add all the static files. These may already exist, but we just
// overwrite them anyway to make sure that they're fresh and up-to-date.

write(cx.dst.join("rustdoc.css"),
write(cx.dst.join(&format!("rustdoc{}.css", cx.shared.resource_suffix)),
include_bytes!("static/rustdoc.css"))?;

// To avoid "main.css" to be overwritten, we'll first run over the received themes and only
Expand All @@ -746,24 +752,28 @@ fn write_shared(cx: &Context,

let mut f = try_err!(File::open(&entry), &entry);
try_err!(f.read_to_end(&mut content), &entry);
write(cx.dst.join(try_none!(entry.file_name(), &entry)), content.as_slice())?;
themes.insert(try_none!(try_none!(entry.file_stem(), &entry).to_str(), &entry).to_owned());
let theme = try_none!(try_none!(entry.file_stem(), &entry).to_str(), &entry);
let extension = try_none!(try_none!(entry.extension(), &entry).to_str(), &entry);
write(cx.dst.join(format!("{}{}.{}", theme, cx.shared.resource_suffix, extension)),
content.as_slice())?;
themes.insert(theme.to_owned());
}

write(cx.dst.join("brush.svg"),
write(cx.dst.join(&format!("brush{}.svg", cx.shared.resource_suffix)),
include_bytes!("static/brush.svg"))?;
write(cx.dst.join("main.css"),
write(cx.dst.join(&format!("main{}.css", cx.shared.resource_suffix)),
include_bytes!("static/themes/main.css"))?;
themes.insert("main".to_owned());
write(cx.dst.join("dark.css"),
write(cx.dst.join(&format!("dark{}.css", cx.shared.resource_suffix)),
include_bytes!("static/themes/dark.css"))?;
themes.insert("dark".to_owned());

let mut themes: Vec<&String> = themes.iter().collect();
themes.sort();
// To avoid theme switch latencies as much as possible, we put everything theme related
// at the beginning of the html files into another js file.
write(cx.dst.join("theme.js"), format!(
write(cx.dst.join(&format!("theme{}.js", cx.shared.resource_suffix)),
format!(
r#"var themes = document.getElementById("theme-choices");
var themePicker = document.getElementById("theme-picker");
themePicker.onclick = function() {{
Expand All @@ -785,19 +795,28 @@ themePicker.onclick = function() {{
}};
themes.appendChild(but);
}});
"#, themes.iter()
.map(|s| format!("\"{}\"", s))
.collect::<Vec<String>>()
.join(",")).as_bytes())?;
"#,
themes.iter()
.map(|s| format!("\"{}\"", s))
.collect::<Vec<String>>()
.join(",")).as_bytes(),
)?;

write(cx.dst.join(&format!("main{}.js", cx.shared.resource_suffix)),
include_bytes!("static/main.js"))?;

write(cx.dst.join("main.js"), include_bytes!("static/main.js"))?;
write(cx.dst.join("storage.js"), include_bytes!("static/storage.js"))?;
{
let mut data = format!("var resourcesSuffix = \"{}\";\n",
cx.shared.resource_suffix).into_bytes();
data.extend_from_slice(include_bytes!("static/storage.js"));
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using a Vec<u8> and include_bytes here instead of a String and include_str seems weird to me. I get that on the very next line it needs to be bytes for the write call, but i don't know how much we gain by sidesteppning the UTF-8 check on this extend call.

write(cx.dst.join(&format!("storage{}.js", cx.shared.resource_suffix)), &data)?;
}

if let Some(ref css) = cx.shared.css_file_extension {
let out = cx.dst.join("theme.css");
let out = cx.dst.join(&format!("theme{}.css", cx.shared.resource_suffix));
try_err!(fs::copy(css, out), css);
}
write(cx.dst.join("normalize.css"),
write(cx.dst.join(&format!("normalize{}.css", cx.shared.resource_suffix)),
include_bytes!("static/normalize.css"))?;
write(cx.dst.join("FiraSans-Regular.woff"),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm guessing the fonts and their copyright notices aren't relevant for wanting to switch the filenames out?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @onur

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to @onur from a conversation on IRC, it matters less for the fonts to handle it, since they're loaded from the CSS (which would need to also be processed to use the suffix), and they don't churn like the CSS/JS do. This is fine as-is.

include_bytes!("static/FiraSans-Regular.woff"))?;
Expand Down Expand Up @@ -1084,6 +1103,7 @@ impl<'a> SourceCollector<'a> {
root_path: &root_path,
description: &desc,
keywords: BASIC_KEYWORDS,
resource_suffix: &self.scx.resource_suffix,
};
layout::render(&mut w, &self.scx.layout,
&page, &(""), &Source(contents),
Expand Down Expand Up @@ -1446,6 +1466,7 @@ impl Context {
title: &title,
description: &desc,
keywords: &keywords,
resource_suffix: &self.shared.resource_suffix,
};

reset_ids(true);
Expand Down
4 changes: 3 additions & 1 deletion src/librustdoc/html/static/storage.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,9 @@ function getCurrentValue(name) {
}

function switchTheme(styleElem, mainStyleElem, newTheme) {
var newHref = mainStyleElem.href.replace("rustdoc.css", newTheme + ".css");
var fullBasicCss = "rustdoc" + resourcesSuffix + ".css";
var fullNewTheme = newTheme + resourcesSuffix + ".css";
var newHref = mainStyleElem.href.replace(fullBasicCss, fullNewTheme);
var found = false;

if (savedHref.length === 0) {
Expand Down
9 changes: 9 additions & 0 deletions src/librustdoc/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,13 @@ pub fn opts() -> Vec<RustcOptGroup> {
"check if given theme is valid",
"FILES")
}),
unstable("resource-suffix", |o| {
o.optopt("",
"resource-suffix",
"suffix to add to CSS and JavaScript files, e.g. \"main.css\" will become \
\"main-suffix.css\"",
"PATH")
}),
]
}

Expand Down Expand Up @@ -417,6 +424,7 @@ pub fn main_args(args: &[String]) -> isize {
let display_warnings = matches.opt_present("display-warnings");
let linker = matches.opt_str("linker").map(PathBuf::from);
let sort_modules_alphabetically = !matches.opt_present("sort-modules-by-appearance");
let resource_suffix = matches.opt_str("resource-suffix");

match (should_test, markdown_input) {
(true, true) => {
Expand All @@ -442,6 +450,7 @@ pub fn main_args(args: &[String]) -> isize {
Some("html") | None => {
html::render::run(krate, &external_html, playground_url,
output.unwrap_or(PathBuf::from("doc")),
resource_suffix.unwrap_or(String::new()),
passes.into_iter().collect(),
css_file_extension,
renderinfo,
Expand Down