mirror of https://github.com/rust-lang/rust.git
new --static-root-path flag for controlling static file locations
This commit is contained in:
parent
0a4a4ffc69
commit
0b0a00cc05
|
@ -402,3 +402,18 @@ Using `index-page` option enables `enable-index-page` option as well.
|
|||
### `--enable-index-page`: generate a default index page for docs
|
||||
|
||||
This feature allows the generation of a default index-page which lists the generated crates.
|
||||
|
||||
### `--static-root-path`: control how static files are loaded in HTML output
|
||||
|
||||
Using this flag looks like this:
|
||||
|
||||
```bash
|
||||
$ rustdoc src/lib.rs -Z unstable-options --static-root-path '/cache/'
|
||||
```
|
||||
|
||||
This flag controls how rustdoc links to its static files on HTML pages. If you're hosting a lot of
|
||||
crates' docs generated by the same version of rustdoc, you can use this flag to cache rustdoc's CSS,
|
||||
JavaScript, and font files in a single location, rather than duplicating it once per "doc root"
|
||||
(grouping of crate docs generated into the same output directory, like with `cargo doc`). Per-crate
|
||||
files like the search index will still load from the documentation root, but anything that gets
|
||||
renamed with `--resource-suffix` will load from the given path.
|
||||
|
|
|
@ -181,6 +181,9 @@ pub struct RenderOptions {
|
|||
/// A file to use as the index page at the root of the output directory. Overrides
|
||||
/// `enable_index_page` to be true if set.
|
||||
pub index_page: Option<PathBuf>,
|
||||
/// An optional path to use as the location of static files. If not set, uses combinations of
|
||||
/// `../` to reach the documentation root.
|
||||
pub static_root_path: Option<String>,
|
||||
|
||||
// Options specific to reading standalone Markdown files
|
||||
|
||||
|
@ -433,6 +436,7 @@ impl Options {
|
|||
let markdown_playground_url = matches.opt_str("markdown-playground-url");
|
||||
let crate_version = matches.opt_str("crate-version");
|
||||
let enable_index_page = matches.opt_present("enable-index-page") || index_page.is_some();
|
||||
let static_root_path = matches.opt_str("static-root-path");
|
||||
|
||||
let (lint_opts, describe_lints, lint_cap) = get_cmd_lint_options(matches, error_format);
|
||||
|
||||
|
@ -471,6 +475,7 @@ impl Options {
|
|||
enable_minification,
|
||||
enable_index_page,
|
||||
index_page,
|
||||
static_root_path,
|
||||
markdown_no_toc,
|
||||
markdown_css,
|
||||
markdown_playground_url,
|
||||
|
|
|
@ -26,6 +26,7 @@ pub struct Page<'a> {
|
|||
pub title: &'a str,
|
||||
pub css_class: &'a str,
|
||||
pub root_path: &'a str,
|
||||
pub static_root_path: Option<&'a str>,
|
||||
pub description: &'a str,
|
||||
pub keywords: &'a str,
|
||||
pub resource_suffix: &'a str,
|
||||
|
@ -36,6 +37,7 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
css_file_extension: bool, themes: &[PathBuf], extra_scripts: &[&str])
|
||||
-> io::Result<()>
|
||||
{
|
||||
let static_root_path = page.static_root_path.unwrap_or(page.root_path);
|
||||
write!(dst,
|
||||
"<!DOCTYPE html>\
|
||||
<html lang=\"en\">\
|
||||
|
@ -46,20 +48,20 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
<meta name=\"description\" content=\"{description}\">\
|
||||
<meta name=\"keywords\" content=\"{keywords}\">\
|
||||
<title>{title}</title>\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}normalize{suffix}.css\">\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}rustdoc{suffix}.css\" \
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}normalize{suffix}.css\">\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}rustdoc{suffix}.css\" \
|
||||
id=\"mainThemeStyle\">\
|
||||
{themes}\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}dark{suffix}.css\">\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}light{suffix}.css\" \
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}dark{suffix}.css\">\
|
||||
<link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}light{suffix}.css\" \
|
||||
id=\"themeStyle\">\
|
||||
<script src=\"{root_path}storage{suffix}.js\"></script>\
|
||||
<noscript><link rel=\"stylesheet\" href=\"{root_path}noscript{suffix}.css\"></noscript>\
|
||||
<script src=\"{static_root_path}storage{suffix}.js\"></script>\
|
||||
<noscript><link rel=\"stylesheet\" href=\"{static_root_path}noscript{suffix}.css\"></noscript>\
|
||||
{css_extension}\
|
||||
{favicon}\
|
||||
{in_header}\
|
||||
<style type=\"text/css\">\
|
||||
#crate-search{{background-image:url(\"{root_path}down-arrow{suffix}.svg\");}}\
|
||||
#crate-search{{background-image:url(\"{static_root_path}down-arrow{suffix}.svg\");}}\
|
||||
</style>\
|
||||
</head>\
|
||||
<body class=\"rustdoc {css_class}\">\
|
||||
|
@ -77,11 +79,13 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
</nav>\
|
||||
<div class=\"theme-picker\">\
|
||||
<button id=\"theme-picker\" aria-label=\"Pick another theme!\">\
|
||||
<img src=\"{root_path}brush{suffix}.svg\" width=\"18\" alt=\"Pick another theme!\">\
|
||||
<img src=\"{static_root_path}brush{suffix}.svg\" \
|
||||
width=\"18\" \
|
||||
alt=\"Pick another theme!\">\
|
||||
</button>\
|
||||
<div id=\"theme-choices\"></div>\
|
||||
</div>\
|
||||
<script src=\"{root_path}theme{suffix}.js\"></script>\
|
||||
<script src=\"{static_root_path}theme{suffix}.js\"></script>\
|
||||
<nav class=\"sub\">\
|
||||
<form class=\"search-form js-only\">\
|
||||
<div class=\"search-container\">\
|
||||
|
@ -96,7 +100,9 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
type=\"search\">\
|
||||
</div>\
|
||||
<a id=\"settings-menu\" href=\"{root_path}settings.html\">\
|
||||
<img src=\"{root_path}wheel{suffix}.svg\" width=\"18\" alt=\"Change settings\">\
|
||||
<img src=\"{static_root_path}wheel{suffix}.svg\" \
|
||||
width=\"18\" \
|
||||
alt=\"Change settings\">\
|
||||
</a>\
|
||||
</div>\
|
||||
</form>\
|
||||
|
@ -157,19 +163,22 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
window.currentCrate = \"{krate}\";\
|
||||
</script>\
|
||||
<script src=\"{root_path}aliases.js\"></script>\
|
||||
<script src=\"{root_path}main{suffix}.js\"></script>\
|
||||
<script src=\"{static_root_path}main{suffix}.js\"></script>\
|
||||
{extra_scripts}\
|
||||
<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{suffix}.css\">",
|
||||
root_path = page.root_path,
|
||||
format!("<link rel=\"stylesheet\" \
|
||||
type=\"text/css\" \
|
||||
href=\"{static_root_path}theme{suffix}.css\">",
|
||||
static_root_path = static_root_path,
|
||||
suffix=page.resource_suffix)
|
||||
} else {
|
||||
String::new()
|
||||
},
|
||||
content = *t,
|
||||
static_root_path = static_root_path,
|
||||
root_path = page.root_path,
|
||||
css_class = page.css_class,
|
||||
logo = if layout.logo.is_empty() {
|
||||
|
@ -197,11 +206,13 @@ pub fn render<T: fmt::Display, S: fmt::Display>(
|
|||
.filter_map(|t| t.file_stem())
|
||||
.filter_map(|t| t.to_str())
|
||||
.map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}{}{}.css">"#,
|
||||
page.root_path,
|
||||
static_root_path,
|
||||
t,
|
||||
page.resource_suffix))
|
||||
.collect::<String>(),
|
||||
suffix=page.resource_suffix,
|
||||
// TODO: break out a separate `static_extra_scripts` that uses `static_root_path` instead,
|
||||
// then leave `source-files.js` here and move `source-script.js` to the static version
|
||||
extra_scripts=extra_scripts.iter().map(|e| {
|
||||
format!("<script src=\"{root_path}{extra_script}.js\"></script>",
|
||||
root_path=page.root_path,
|
||||
|
|
|
@ -140,6 +140,9 @@ struct SharedContext {
|
|||
/// Suffix to be added on resource files (if suffix is "-v2" then "light.css" becomes
|
||||
/// "light-v2.css").
|
||||
pub resource_suffix: String,
|
||||
/// Optional path string to be used to load static files on output pages. If not set, uses
|
||||
/// combinations of `../` to reach the documentation root.
|
||||
pub static_root_path: Option<String>,
|
||||
}
|
||||
|
||||
impl SharedContext {
|
||||
|
@ -506,6 +509,7 @@ pub fn run(mut krate: clean::Crate,
|
|||
extension_css,
|
||||
extern_html_root_urls,
|
||||
resource_suffix,
|
||||
static_root_path,
|
||||
..
|
||||
} = options;
|
||||
|
||||
|
@ -533,6 +537,7 @@ pub fn run(mut krate: clean::Crate,
|
|||
sort_modules_alphabetically,
|
||||
themes,
|
||||
resource_suffix,
|
||||
static_root_path,
|
||||
};
|
||||
|
||||
// If user passed in `--playground-url` arg, we fill in crate name here
|
||||
|
@ -1080,6 +1085,7 @@ themePicker.onblur = handleThemeButtonsBlur;
|
|||
title: "Index of crates",
|
||||
css_class: "mod",
|
||||
root_path: "./",
|
||||
static_root_path: cx.shared.static_root_path.deref(),
|
||||
description: "List of crates",
|
||||
keywords: BASIC_KEYWORDS,
|
||||
resource_suffix: &cx.shared.resource_suffix,
|
||||
|
@ -1366,6 +1372,7 @@ impl<'a> SourceCollector<'a> {
|
|||
title: &title,
|
||||
css_class: "source",
|
||||
root_path: &root_path,
|
||||
static_root_path: self.scx.static_root_path.deref(),
|
||||
description: &desc,
|
||||
keywords: BASIC_KEYWORDS,
|
||||
resource_suffix: &self.scx.resource_suffix,
|
||||
|
@ -1956,6 +1963,7 @@ impl Context {
|
|||
title: "List of all items in this crate",
|
||||
css_class: "mod",
|
||||
root_path: "../",
|
||||
static_root_path: self.shared.static_root_path.deref(),
|
||||
description: "List of all items in this crate",
|
||||
keywords: BASIC_KEYWORDS,
|
||||
resource_suffix: &self.shared.resource_suffix,
|
||||
|
@ -2035,6 +2043,7 @@ impl Context {
|
|||
let page = layout::Page {
|
||||
css_class: tyname,
|
||||
root_path: &self.root_path(),
|
||||
static_root_path: self.shared.static_root_path.deref(),
|
||||
title: &title,
|
||||
description: &desc,
|
||||
keywords: &keywords,
|
||||
|
|
|
@ -25,6 +25,7 @@
|
|||
#![feature(crate_visibility_modifier)]
|
||||
#![feature(const_fn)]
|
||||
#![feature(drain_filter)]
|
||||
#![feature(inner_deref)]
|
||||
|
||||
#![recursion_limit="256"]
|
||||
|
||||
|
@ -338,6 +339,13 @@ fn opts() -> Vec<RustcOptGroup> {
|
|||
"enable-index-page",
|
||||
"To enable generation of the index page")
|
||||
}),
|
||||
unstable("static-root-path", |o| {
|
||||
o.optopt("",
|
||||
"static-root-path",
|
||||
"Path string to force loading static files from in output pages. \
|
||||
If not set, uses combinations of '../' to reach the documentation root.",
|
||||
"PATH")
|
||||
}),
|
||||
]
|
||||
}
|
||||
|
||||
|
|
|
@ -0,0 +1,18 @@
|
|||
// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
|
||||
// file at the top-level directory of this distribution and at
|
||||
// http://rust-lang.org/COPYRIGHT.
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
||||
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
||||
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
||||
// option. This file may not be copied, modified, or distributed
|
||||
// except according to those terms.
|
||||
|
||||
// compile-flags:-Z unstable-options --static-root-path /cache/
|
||||
|
||||
// @has static_root_path/struct.SomeStruct.html
|
||||
// @matches - '"/cache/main\.js"'
|
||||
// @!matches - '"\.\./main\.js"'
|
||||
// @matches - '"\.\./search-index\.js"'
|
||||
// @!matches - '"/cache/search-index\.js"'
|
||||
pub struct SomeStruct;
|
Loading…
Reference in New Issue