bjoernager/rust
bjoernager/rust
1
Fork 0
Code Issues Pull requests Activity
rust/src/librustdoc/html/layout.rs

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

106 lines
2.9 KiB
Rust
Raw Normal View History

Fasten even more theme switch
2018-01-23 00:45:34 +01:00
use std::path::PathBuf;
Implement a web backend for rustdoc_ng This large commit implements and `html` output option for rustdoc_ng. The executable has been altered to be invoked as "rustdoc_ng html <crate>" and it will dump everything into the local "doc" directory. JSON can still be generated by changing 'html' to 'json'. This also fixes a number of bugs in rustdoc_ng relating to comment stripping, along with some other various issues that I found along the way. The `make doc` command has been altered to generate the new documentation into the `doc/ng/$(CRATE)` directories.
2013-09-18 22:18:38 -07:00
Fix rustc::internal lints on rustdoc
2020-12-31 23:25:30 -05:00
use rustc_data_structures::fx::FxHashMap;
Transition librustdoc to 2018 edition
2019-02-23 16:40:07 +09:00
use crate::externalfiles::ExternalHtml;
Move sidebar to Buffer-printing
2019-08-31 09:07:29 -04:00
use crate::html::format::{Buffer, Print};
Clean up handling of style files in rustdoc Disable all themes other than `light.css` to prevent rule conflicts
2020-07-12 14:37:22 -04:00
use crate::html::render::{ensure_trailing_slash, StylePath};
Fix image link in the settings menu
2019-01-31 15:42:45 +01:00
Migrate rustdoc from Tera to Askama See #84419.
2022-01-03 18:18:46 +01:00
use askama::Template;
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
rustdoc: add hash to filename of toolchain files All static files used by rustdoc are now stored in static.files/ and include a hash of their contents. They no longer include the contents of the --resource-suffix flag. This clarifies caching semantics. Anything in static.files can use Cache-Control: immutable because any updates will show up as a new URL. Invocation-specific files like crates-NN.js, search-index-NN.js, and sidebar-items-NN.js still get the resource suffix. The --disable-minification flag is removed because it would vary the output of static files based on invocation flags. Instead, for rustdoc development purposes it's preferable to symlink static files to a non-minified copy for quick iteration.
2022-10-24 01:28:55 -07:00
use super::static_files::{StaticFiles, STATIC_FILES};
Address feedback
2022-01-03 21:16:05 +01:00
#[derive(Clone)]
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) struct Layout {
pub(crate) logo: String,
pub(crate) favicon: String,
pub(crate) external_html: ExternalHtml,
pub(crate) default_settings: FxHashMap<String, String>,
pub(crate) krate: String,
Move constant parameters to render to Layout struct
2019-08-30 10:51:13 -04:00
/// The given user css file which allow to customize the generated
/// documentation theme.
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) css_file_extension: Option<PathBuf>,
Move JS into a standalone file
2021-10-01 13:05:35 -07:00
/// If true, then scrape-examples.js will be included in the output HTML file
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) scrape_examples_extension: bool,
Implement a web backend for rustdoc_ng This large commit implements and `html` output option for rustdoc_ng. The executable has been altered to be invoked as "rustdoc_ng html <crate>" and it will dump everything into the local "doc" directory. JSON can still be generated by changing 'html' to 'json'. This also fixes a number of bugs in rustdoc_ng relating to comment stripping, along with some other various issues that I found along the way. The `make doc` command has been altered to generate the new documentation into the `doc/ng/$(CRATE)` directories.
2013-09-18 22:18:38 -07:00
}
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) struct Page<'a> {
pub(crate) title: &'a str,
pub(crate) css_class: &'a str,
pub(crate) root_path: &'a str,
pub(crate) static_root_path: Option<&'a str>,
pub(crate) description: &'a str,
pub(crate) keywords: &'a str,
pub(crate) resource_suffix: &'a str,
Implement a web backend for rustdoc_ng This large commit implements and `html` output option for rustdoc_ng. The executable has been altered to be invoked as "rustdoc_ng html <crate>" and it will dump everything into the local "doc" directory. JSON can still be generated by changing 'html' to 'json'. This also fixes a number of bugs in rustdoc_ng relating to comment stripping, along with some other various issues that I found along the way. The `make doc` command has been altered to generate the new documentation into the `doc/ng/$(CRATE)` directories.
2013-09-18 22:18:38 -07:00
}
Use an SVG image for clipboard instead of unicode character
2021-05-09 20:41:24 +02:00
impl<'a> Page<'a> {
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) fn get_static_root_path(&self) -> &str {
Use an SVG image for clipboard instead of unicode character
2021-05-09 20:41:24 +02:00
self.static_root_path.unwrap_or(self.root_path)
}
}
Address feedback
2022-01-03 21:16:05 +01:00
#[derive(Template)]
Migrate rustdoc from Tera to Askama See #84419.
2022-01-03 18:18:46 +01:00
#[template(path = "page.html")]
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
struct PageLayout<'a> {
static_root_path: &'a str,
page: &'a Page<'a>,
layout: &'a Layout,
rustdoc: add hash to filename of toolchain files All static files used by rustdoc are now stored in static.files/ and include a hash of their contents. They no longer include the contents of the --resource-suffix flag. This clarifies caching semantics. Anything in static.files can use Cache-Control: immutable because any updates will show up as a new URL. Invocation-specific files like crates-NN.js, search-index-NN.js, and sidebar-items-NN.js still get the resource suffix. The --disable-minification flag is removed because it would vary the output of static files based on invocation flags. Instead, for rustdoc development purposes it's preferable to symlink static files to a non-minified copy for quick iteration.
2022-10-24 01:28:55 -07:00
files: &'static StaticFiles,
Simplify rendering of stylesheet links into HTML We carry around a list of stylesheets that can carry two different types of thing: 1. Internal stylesheets specific to a page type (only for settings) 2. Themes In this change I move the link generation for settings.css into settings(), so Context.style_files is reserved just for themes. We had two places where we extracted a base theme name from a list of StylePaths. I consolidated that code to be a method on StylePath. I moved generation of link tags for stylesheets into the page.html template. With that change, I made the template responsible for special handling of light.css (making it the default theme) and of the other themes (marking them disabled). That allowed getting rid of the `disabled` field on StylePath.
2021-11-22 23:23:58 -08:00
themes: Vec<String>,
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
sidebar: String,
content: String,
krate_with_trailing_slash: String,
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) rustdoc_version: &'a str,
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
}
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) fn render<T: Print, S: Print>(
Add no-crate filter option on rustdoc
2018-12-20 13:28:55 +01:00
layout: &Layout,
Transition librustdoc to 2018 edition
2019-02-23 16:40:07 +09:00
page: &Page<'_>,
Implement Print for FnOnce(&mut Buffer) This means that callers can pass in a closure like `|buf| some_function(..., &mut buf)` and pass in arbitrary arguments to that function without complicating the trait definition. We also keep the impl for str and String, since it's useful to be able to just pass in "" or format!("{}"...) results in some cases. This changes Print's definition to take self, instead of &self, because otherwise FnOnce cannot be called directly. We could instead take FnMut or even Fn, but that seems like it'd merely complicate matters -- most of the time, the FnOnce does not constrain us at all anyway. If it does, a custom Print impl for &'_ SomeStruct is not all that painful.
2019-08-31 11:22:51 -04:00
sidebar: S,
layout::render takes Print instead of fmt::Display
2019-08-31 12:18:25 -04:00
t: T,
Clean up handling of style files in rustdoc Disable all themes other than `light.css` to prevent rule conflicts
2020-07-12 14:37:22 -04:00
style_files: &[StylePath],
Create buffers in top-level rendering This avoids needlessly creating and threading the buffers through when we only use them once.
2019-08-30 10:35:14 -04:00
) -> String {
Use an SVG image for clipboard instead of unicode character
2021-05-09 20:41:24 +02:00
let static_root_path = page.get_static_root_path();
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
let krate_with_trailing_slash = ensure_trailing_slash(&layout.krate).to_string();
rustdoc: add hash to filename of toolchain files All static files used by rustdoc are now stored in static.files/ and include a hash of their contents. They no longer include the contents of the --resource-suffix flag. This clarifies caching semantics. Anything in static.files can use Cache-Control: immutable because any updates will show up as a new URL. Invocation-specific files like crates-NN.js, search-index-NN.js, and sidebar-items-NN.js still get the resource suffix. The --disable-minification flag is removed because it would vary the output of static files based on invocation flags. Instead, for rustdoc development purposes it's preferable to symlink static files to a non-minified copy for quick iteration.
2022-10-24 01:28:55 -07:00
let mut themes: Vec<String> = style_files.iter().map(|s| s.basename().unwrap()).collect();
Consistentize the system for image URLs in CSS.
2021-11-23 21:23:54 -08:00
themes.sort();
rustdoc: add hash to filename of toolchain files All static files used by rustdoc are now stored in static.files/ and include a hash of their contents. They no longer include the contents of the --resource-suffix flag. This clarifies caching semantics. Anything in static.files can use Cache-Control: immutable because any updates will show up as a new URL. Invocation-specific files like crates-NN.js, search-index-NN.js, and sidebar-items-NN.js still get the resource suffix. The --disable-minification flag is removed because it would vary the output of static files based on invocation flags. Instead, for rustdoc development purposes it's preferable to symlink static files to a non-minified copy for quick iteration.
2022-10-24 01:28:55 -07:00
Move themes and version into rustdoc-vars We had been injecting the list of themes and the rustdoc version into main.js by rewriting it at doc generation time. By avoiding this rewrite, we can make it easier to edit main.js without regenerating all the docs. Added a more convenient accessor for rustdoc-vars. Changed storage.js to not rely on resourcesSuffix. It could in theory use rustdoc-vars, but because rustdoc-vars is at the end of the HTML, it's not available when storage.js runs (very early in page load).
2021-11-23 19:22:29 -08:00
let rustdoc_version = rustc_interface::util::version_str().unwrap_or("unknown version");
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
let content = Buffer::html().to_display(t); // Note: This must happen before making the sidebar.
let sidebar = Buffer::html().to_display(sidebar);
Migrate rustdoc from Tera to Askama See #84419.
2022-01-03 18:18:46 +01:00
PageLayout {
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
static_root_path,
page,
layout,
rustdoc: add hash to filename of toolchain files All static files used by rustdoc are now stored in static.files/ and include a hash of their contents. They no longer include the contents of the --resource-suffix flag. This clarifies caching semantics. Anything in static.files can use Cache-Control: immutable because any updates will show up as a new URL. Invocation-specific files like crates-NN.js, search-index-NN.js, and sidebar-items-NN.js still get the resource suffix. The --disable-minification flag is removed because it would vary the output of static files based on invocation flags. Instead, for rustdoc development purposes it's preferable to symlink static files to a non-minified copy for quick iteration.
2022-10-24 01:28:55 -07:00
files: &STATIC_FILES,
Simplify rendering of stylesheet links into HTML We carry around a list of stylesheets that can carry two different types of thing: 1. Internal stylesheets specific to a page type (only for settings) 2. Themes In this change I move the link generation for settings.css into settings(), so Context.style_files is reserved just for themes. We had two places where we extracted a base theme name from a list of StylePaths. I consolidated that code to be a method on StylePath. I moved generation of link tags for stylesheets into the page.html template. With that change, I made the template responsible for special handling of light.css (making it the default theme) and of the other themes (marking them disabled). That allowed getting rid of the `disabled` field on StylePath.
2021-11-22 23:23:58 -08:00
themes,
Use Tera templates for rustdoc. Replaces a format!() call in layout::render with a template expansion. Introduces a `templates` field in SharedContext so parts of rustdoc can share pre-rendered templates. This currently builds in a copy of the single template available, like with static files. However, future work can make this live-loadable with a perma-unstable flag, to make rustdoc developers' work easier.
2021-06-08 17:19:03 -07:00
sidebar,
content,
krate_with_trailing_slash,
Move themes and version into rustdoc-vars We had been injecting the list of themes and the rustdoc version into main.js by rewriting it at doc generation time. By avoiding this rewrite, we can make it easier to edit main.js without regenerating all the docs. Added a more convenient accessor for rustdoc-vars. Changed storage.js to not rely on resourcesSuffix. It could in theory use rustdoc-vars, but because rustdoc-vars is at the end of the HTML, it's not available when storage.js runs (very early in page load).
2021-11-23 19:22:29 -08:00
rustdoc_version,
Migrate rustdoc from Tera to Askama See #84419.
2022-01-03 18:18:46 +01:00
}
.render()
.unwrap()
Implement a web backend for rustdoc_ng This large commit implements and `html` output option for rustdoc_ng. The executable has been altered to be invoked as "rustdoc_ng html <crate>" and it will dump everything into the local "doc" directory. JSON can still be generated by changing 'html' to 'json'. This also fixes a number of bugs in rustdoc_ng relating to comment stripping, along with some other various issues that I found along the way. The `make doc` command has been altered to generate the new documentation into the `doc/ng/$(CRATE)` directories.
2013-09-18 22:18:38 -07:00
}
Remove `crate` visibility modifier in libs, tests
2022-05-20 21:06:44 -04:00
pub(crate) fn redirect(url: &str) -> String {
rustdoc: Preserve query/fragment in redirects whenever possible. We heavily rely on queries and fragments in the URL structure, so it is desired to preserve them even in the redirects. The generated redirect pages try to preserve them with scripts, which take precedence over the original `Refresh` metadata. Non-scripting browsers would continue to work (with no queries and fragments).
2014-12-04 12:48:16 +09:00
// <script> triggers a redirect before refresh, so this is fine.
Create buffers in top-level rendering This avoids needlessly creating and threading the buffers through when we only use them once.
2019-08-30 10:35:14 -04:00
format!(
rustdoc: Fix cross-crate links to reexported items Cross crate links can target items which are not rendered in the documentation. If the item is reexported at a higher level, the destination of the link (a concatenation of the fully qualified name) may actually lead to nowhere. This fixes this problem by altering rustdoc to emit pages which redirect to the local copy of the reexported structure. cc #14515 Closes #14137
2014-05-29 13:50:47 -07:00
r##"<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="refresh" content="0;URL={url}">
Add missing <title> in redirection page <head>
2021-04-23 17:47:50 +02:00
<title>Redirection</title>
rustdoc: Fix cross-crate links to reexported items Cross crate links can target items which are not rendered in the documentation. If the item is reexported at a higher level, the destination of the link (a concatenation of the fully qualified name) may actually lead to nowhere. This fixes this problem by altering rustdoc to emit pages which redirect to the local copy of the reexported structure. cc #14515 Closes #14137
2014-05-29 13:50:47 -07:00
</head>
<body>
rustdoc: Preserve query/fragment in redirects whenever possible. We heavily rely on queries and fragments in the URL structure, so it is desired to preserve them even in the redirects. The generated redirect pages try to preserve them with scripts, which take precedence over the original `Refresh` metadata. Non-scripting browsers would continue to work (with no queries and fragments).
2014-12-04 12:48:16 +09:00
<p>Redirecting to <a href="{url}">{url}</a>...</p>
<script>location.replace("{url}" + location.search + location.hash);</script>
rustdoc: Fix cross-crate links to reexported items Cross crate links can target items which are not rendered in the documentation. If the item is reexported at a higher level, the destination of the link (a concatenation of the fully qualified name) may actually lead to nowhere. This fixes this problem by altering rustdoc to emit pages which redirect to the local copy of the reexported structure. cc #14515 Closes #14137
2014-05-29 13:50:47 -07:00
</body>
</html>"##,
url = url,
)
}
Reference in a new issue Copy permalink