]>
Commit | Line | Data |
---|---|---|
6a06907d XL |
1 | use std::cell::RefCell; |
2 | use std::collections::BTreeMap; | |
3 | use std::io; | |
cdc7bbd5 | 4 | use std::path::{Path, PathBuf}; |
6a06907d | 5 | use std::rc::Rc; |
cdc7bbd5 | 6 | use std::sync::mpsc::{channel, Receiver}; |
6a06907d | 7 | |
cdc7bbd5 | 8 | use rustc_data_structures::fx::{FxHashMap, FxHashSet}; |
9ffffee4 | 9 | use rustc_hir::def_id::{DefIdMap, LOCAL_CRATE}; |
6a06907d XL |
10 | use rustc_middle::ty::TyCtxt; |
11 | use rustc_session::Session; | |
12 | use rustc_span::edition::Edition; | |
13 | use rustc_span::source_map::FileName; | |
5099ac24 | 14 | use rustc_span::{sym, Symbol}; |
6a06907d | 15 | |
6a06907d | 16 | use super::print_item::{full_path, item_path, print_item}; |
a2a8927a | 17 | use super::search_index::build_index; |
6a06907d | 18 | use super::write_shared::write_shared; |
94222f64 | 19 | use super::{ |
353b0b11 FG |
20 | collect_spans_and_sources, scrape_examples_help, |
21 | sidebar::print_sidebar, | |
22 | sidebar::{sidebar_module_like, Sidebar}, | |
23 | AllTypes, LinkFromSrc, StylePath, | |
94222f64 | 24 | }; |
a2a8927a | 25 | use crate::clean::{self, types::ExternalLocation, ExternalCrate}; |
064997fb | 26 | use crate::config::{ModuleSorting, RenderOptions}; |
6a06907d XL |
27 | use crate::docfs::{DocFS, PathError}; |
28 | use crate::error::Error; | |
29 | use crate::formats::cache::Cache; | |
30 | use crate::formats::item_type::ItemType; | |
31 | use crate::formats::FormatRenderer; | |
32 | use crate::html::escape::Escape; | |
5099ac24 | 33 | use crate::html::format::{join_with_double_colon, Buffer}; |
6a06907d | 34 | use crate::html::markdown::{self, plain_text_summary, ErrorCodes, IdMap}; |
f2b60f7d | 35 | use crate::html::url_parts_builder::UrlPartsBuilder; |
487cf647 | 36 | use crate::html::{layout, sources, static_files}; |
3c0e092e XL |
37 | use crate::scrape_examples::AllCallLocations; |
38 | use crate::try_err; | |
353b0b11 | 39 | use askama::Template; |
6a06907d XL |
40 | |
41 | /// Major driving force in all rustdoc rendering. This contains information | |
42 | /// about where in the tree-like hierarchy rendering is occurring and controls | |
43 | /// how the current page is being rendered. | |
44 | /// | |
45 | /// It is intended that this context is a lightweight object which can be fairly | |
46 | /// easily cloned because it is cloned per work-job (about once per item in the | |
47 | /// rustdoc tree). | |
923072b8 | 48 | pub(crate) struct Context<'tcx> { |
6a06907d XL |
49 | /// Current hierarchy of components leading down to what's currently being |
50 | /// rendered | |
5099ac24 | 51 | pub(crate) current: Vec<Symbol>, |
6a06907d XL |
52 | /// The current destination folder of where HTML artifacts should be placed. |
53 | /// This changes as the context descends into the module hierarchy. | |
923072b8 | 54 | pub(crate) dst: PathBuf, |
6a06907d XL |
55 | /// A flag, which when `true`, will render pages which redirect to the |
56 | /// real location of an item. This is used to allow external links to | |
57 | /// publicly reused items to redirect to the right location. | |
58 | pub(super) render_redirect_pages: bool, | |
3c0e092e XL |
59 | /// Tracks section IDs for `Deref` targets so they match in both the main |
60 | /// body and the sidebar. | |
9ffffee4 | 61 | pub(super) deref_id_map: DefIdMap<String>, |
6a06907d | 62 | /// The map used to ensure all generated 'id=' attributes are unique. |
923072b8 | 63 | pub(super) id_map: IdMap, |
6a06907d XL |
64 | /// Shared mutable state. |
65 | /// | |
66 | /// Issue for improving the situation: [#82381][] | |
67 | /// | |
68 | /// [#82381]: https://github.com/rust-lang/rust/issues/82381 | |
923072b8 | 69 | pub(crate) shared: Rc<SharedContext<'tcx>>, |
5099ac24 | 70 | /// This flag indicates whether source links should be generated or not. If |
94222f64 XL |
71 | /// the source files are present in the html rendering, then this will be |
72 | /// `true`. | |
923072b8 | 73 | pub(crate) include_sources: bool, |
487cf647 FG |
74 | /// Collection of all types with notable traits referenced in the current module. |
75 | pub(crate) types_with_notable_traits: FxHashSet<clean::Type>, | |
fe692bf9 FG |
76 | /// Field used during rendering, to know if we're inside an inlined item. |
77 | pub(crate) is_inside_inlined_module: bool, | |
6a06907d XL |
78 | } |
79 | ||
80 | // `Context` is cloned a lot, so we don't want the size to grow unexpectedly. | |
f2b60f7d | 81 | #[cfg(all(not(windows), target_arch = "x86_64", target_pointer_width = "64"))] |
487cf647 | 82 | rustc_data_structures::static_assert_size!(Context<'_>, 160); |
6a06907d | 83 | |
cdc7bbd5 | 84 | /// Shared mutable state used in [`Context`] and elsewhere. |
923072b8 FG |
85 | pub(crate) struct SharedContext<'tcx> { |
86 | pub(crate) tcx: TyCtxt<'tcx>, | |
cdc7bbd5 XL |
87 | /// The path to the crate root source minus the file name. |
88 | /// Used for simplifying paths to the highlighted source code files. | |
923072b8 | 89 | pub(crate) src_root: PathBuf, |
cdc7bbd5 XL |
90 | /// This describes the layout of each page, and is not modified after |
91 | /// creation of the context (contains info like the favicon and added html). | |
923072b8 | 92 | pub(crate) layout: layout::Layout, |
cdc7bbd5 | 93 | /// The local file sources we've emitted and their respective url-paths. |
923072b8 | 94 | pub(crate) local_sources: FxHashMap<PathBuf, String>, |
17df50a5 XL |
95 | /// Show the memory layout of types in the docs. |
96 | pub(super) show_type_layout: bool, | |
cdc7bbd5 XL |
97 | /// The base-URL of the issue tracker for when an item has been tagged with |
98 | /// an issue number. | |
99 | pub(super) issue_tracker_base_url: Option<String>, | |
100 | /// The directories that have already been created in this doc run. Used to reduce the number | |
101 | /// of spurious `create_dir_all` calls. | |
102 | created_dirs: RefCell<FxHashSet<PathBuf>>, | |
103 | /// This flag indicates whether listings of modules (in the side bar and documentation itself) | |
104 | /// should be ordered alphabetically or in order of appearance (in the source code). | |
064997fb | 105 | pub(super) module_sorting: ModuleSorting, |
cdc7bbd5 | 106 | /// Additional CSS files to be added to the generated docs. |
923072b8 | 107 | pub(crate) style_files: Vec<StylePath>, |
cdc7bbd5 XL |
108 | /// Suffix to be added on resource files (if suffix is "-v2" then "light.css" becomes |
109 | /// "light-v2.css"). | |
923072b8 | 110 | pub(crate) resource_suffix: String, |
cdc7bbd5 XL |
111 | /// Optional path string to be used to load static files on output pages. If not set, uses |
112 | /// combinations of `../` to reach the documentation root. | |
923072b8 | 113 | pub(crate) static_root_path: Option<String>, |
cdc7bbd5 | 114 | /// The fs handle we are working with. |
923072b8 | 115 | pub(crate) fs: DocFS, |
cdc7bbd5 XL |
116 | pub(super) codes: ErrorCodes, |
117 | pub(super) playground: Option<markdown::Playground>, | |
118 | all: RefCell<AllTypes>, | |
119 | /// Storage for the errors produced while generating documentation so they | |
120 | /// can be printed together at the end. | |
121 | errors: Receiver<String>, | |
122 | /// `None` by default, depends on the `generate-redirect-map` option flag. If this field is set | |
123 | /// to `Some(...)`, it'll store redirections and then generate a JSON file at the top level of | |
124 | /// the crate. | |
125 | redirections: Option<RefCell<FxHashMap<String, String>>>, | |
136023e0 | 126 | |
49aad941 | 127 | /// Correspondence map used to link types used in the source code pages to allow to click on |
94222f64 | 128 | /// links to jump to the type's definition. |
49aad941 | 129 | pub(crate) span_correspondence_map: FxHashMap<rustc_span::Span, LinkFromSrc>, |
94222f64 | 130 | /// The [`Cache`] used during rendering. |
923072b8 | 131 | pub(crate) cache: Cache, |
3c0e092e | 132 | |
923072b8 | 133 | pub(crate) call_locations: AllCallLocations, |
cdc7bbd5 XL |
134 | } |
135 | ||
136 | impl SharedContext<'_> { | |
923072b8 | 137 | pub(crate) fn ensure_dir(&self, dst: &Path) -> Result<(), Error> { |
cdc7bbd5 XL |
138 | let mut dirs = self.created_dirs.borrow_mut(); |
139 | if !dirs.contains(dst) { | |
140 | try_err!(self.fs.create_dir_all(dst), dst); | |
141 | dirs.insert(dst.to_path_buf()); | |
142 | } | |
143 | ||
144 | Ok(()) | |
145 | } | |
146 | ||
923072b8 | 147 | pub(crate) fn edition(&self) -> Edition { |
cdc7bbd5 XL |
148 | self.tcx.sess.edition() |
149 | } | |
150 | } | |
151 | ||
152 | impl<'tcx> Context<'tcx> { | |
153 | pub(crate) fn tcx(&self) -> TyCtxt<'tcx> { | |
6a06907d XL |
154 | self.shared.tcx |
155 | } | |
156 | ||
cdc7bbd5 | 157 | pub(crate) fn cache(&self) -> &Cache { |
94222f64 | 158 | &self.shared.cache |
cdc7bbd5 XL |
159 | } |
160 | ||
17df50a5 | 161 | pub(super) fn sess(&self) -> &'tcx Session { |
3c0e092e | 162 | self.shared.tcx.sess |
6a06907d XL |
163 | } |
164 | ||
add651ee | 165 | pub(super) fn derive_id<S: AsRef<str> + ToString>(&mut self, id: S) -> String { |
923072b8 | 166 | self.id_map.derive(id) |
6a06907d XL |
167 | } |
168 | ||
169 | /// String representation of how to get back to the root path of the 'doc/' | |
170 | /// folder in terms of a relative URL. | |
171 | pub(super) fn root_path(&self) -> String { | |
172 | "../".repeat(self.current.len()) | |
173 | } | |
174 | ||
923072b8 | 175 | fn render_item(&mut self, it: &clean::Item, is_module: bool) -> String { |
fe692bf9 FG |
176 | let mut render_redirect_pages = self.render_redirect_pages; |
177 | // If the item is stripped but inlined, links won't point to the item so no need to generate | |
178 | // a file for it. | |
179 | if it.is_stripped() && | |
180 | let Some(def_id) = it.def_id() && | |
181 | def_id.is_local() | |
182 | { | |
183 | if self.is_inside_inlined_module || self.shared.cache.inlined_items.contains(&def_id) { | |
184 | // For now we're forced to generate a redirect page for stripped items until | |
185 | // `record_extern_fqn` correctly points to external items. | |
186 | render_redirect_pages = true; | |
187 | } | |
188 | } | |
cdc7bbd5 XL |
189 | let mut title = String::new(); |
190 | if !is_module { | |
a2a8927a | 191 | title.push_str(it.name.unwrap().as_str()); |
6a06907d | 192 | } |
cdc7bbd5 XL |
193 | if !it.is_primitive() && !it.is_keyword() { |
194 | if !is_module { | |
195 | title.push_str(" in "); | |
196 | } | |
197 | // No need to include the namespace for primitive types and keywords | |
5099ac24 | 198 | title.push_str(&join_with_double_colon(&self.current)); |
cdc7bbd5 | 199 | }; |
6a06907d XL |
200 | title.push_str(" - Rust"); |
201 | let tyname = it.type_(); | |
49aad941 FG |
202 | let desc = plain_text_summary(&it.doc_value(), &it.link_names(&self.cache())); |
203 | let desc = if !desc.is_empty() { | |
6a06907d XL |
204 | desc |
205 | } else if it.is_crate() { | |
206 | format!("API documentation for the Rust `{}` crate.", self.shared.layout.krate) | |
207 | } else { | |
208 | format!( | |
add651ee FG |
209 | "API documentation for the Rust `{name}` {tyname} in crate `{krate}`.", |
210 | name = it.name.as_ref().unwrap(), | |
211 | krate = self.shared.layout.krate, | |
6a06907d XL |
212 | ) |
213 | }; | |
17df50a5 XL |
214 | let name; |
215 | let tyname_s = if it.is_crate() { | |
add651ee | 216 | name = format!("{tyname} crate"); |
17df50a5 XL |
217 | name.as_str() |
218 | } else { | |
219 | tyname.as_str() | |
220 | }; | |
6a06907d | 221 | |
fe692bf9 | 222 | if !render_redirect_pages { |
923072b8 | 223 | let clone_shared = Rc::clone(&self.shared); |
5e7ed085 FG |
224 | let page = layout::Page { |
225 | css_class: tyname_s, | |
226 | root_path: &self.root_path(), | |
923072b8 | 227 | static_root_path: clone_shared.static_root_path.as_deref(), |
5e7ed085 FG |
228 | title: &title, |
229 | description: &desc, | |
923072b8 | 230 | resource_suffix: &clone_shared.resource_suffix, |
5e7ed085 | 231 | }; |
923072b8 FG |
232 | let mut page_buffer = Buffer::html(); |
233 | print_item(self, it, &mut page_buffer, &page); | |
6a06907d | 234 | layout::render( |
923072b8 | 235 | &clone_shared.layout, |
6a06907d XL |
236 | &page, |
237 | |buf: &mut _| print_sidebar(self, it, buf), | |
923072b8 FG |
238 | move |buf: &mut Buffer| buf.push_buffer(page_buffer), |
239 | &clone_shared.style_files, | |
6a06907d XL |
240 | ) |
241 | } else { | |
04454e1e | 242 | if let Some(&(ref names, ty)) = self.cache().paths.get(&it.item_id.expect_def_id()) { |
5e7ed085 FG |
243 | if self.current.len() + 1 != names.len() |
244 | || self.current.iter().zip(names.iter()).any(|(a, b)| a != b) | |
245 | { | |
246 | // We checked that the redirection isn't pointing to the current file, | |
247 | // preventing an infinite redirection loop in the generated | |
248 | // documentation. | |
249 | ||
250 | let mut path = String::new(); | |
251 | for name in &names[..names.len() - 1] { | |
923072b8 | 252 | path.push_str(name.as_str()); |
5e7ed085 FG |
253 | path.push('/'); |
254 | } | |
923072b8 | 255 | path.push_str(&item_path(ty, names.last().unwrap().as_str())); |
5e7ed085 FG |
256 | match self.shared.redirections { |
257 | Some(ref redirections) => { | |
258 | let mut current_path = String::new(); | |
259 | for name in &self.current { | |
923072b8 | 260 | current_path.push_str(name.as_str()); |
5e7ed085 FG |
261 | current_path.push('/'); |
262 | } | |
923072b8 | 263 | current_path.push_str(&item_path(ty, names.last().unwrap().as_str())); |
5e7ed085 | 264 | redirections.borrow_mut().insert(current_path, path); |
6a06907d | 265 | } |
add651ee FG |
266 | None => { |
267 | return layout::redirect(&format!( | |
268 | "{root}{path}", | |
269 | root = self.root_path() | |
270 | )); | |
271 | } | |
6a06907d | 272 | } |
6a06907d XL |
273 | } |
274 | } | |
275 | String::new() | |
276 | } | |
277 | } | |
278 | ||
279 | /// Construct a map of items shown in the sidebar to a plain-text summary of their docs. | |
9ffffee4 | 280 | fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap<String, Vec<String>> { |
6a06907d XL |
281 | // BTreeMap instead of HashMap to get a sorted output |
282 | let mut map: BTreeMap<_, Vec<_>> = BTreeMap::new(); | |
5e7ed085 FG |
283 | let mut inserted: FxHashMap<ItemType, FxHashSet<Symbol>> = FxHashMap::default(); |
284 | ||
6a06907d XL |
285 | for item in &m.items { |
286 | if item.is_stripped() { | |
287 | continue; | |
288 | } | |
289 | ||
290 | let short = item.type_(); | |
291 | let myname = match item.name { | |
292 | None => continue, | |
5e7ed085 | 293 | Some(s) => s, |
6a06907d | 294 | }; |
5e7ed085 FG |
295 | if inserted.entry(short).or_default().insert(myname) { |
296 | let short = short.to_string(); | |
297 | let myname = myname.to_string(); | |
9ffffee4 | 298 | map.entry(short).or_default().push(myname); |
5e7ed085 | 299 | } |
6a06907d XL |
300 | } |
301 | ||
064997fb FG |
302 | match self.shared.module_sorting { |
303 | ModuleSorting::Alphabetical => { | |
304 | for items in map.values_mut() { | |
305 | items.sort(); | |
306 | } | |
6a06907d | 307 | } |
064997fb | 308 | ModuleSorting::DeclarationOrder => {} |
6a06907d XL |
309 | } |
310 | map | |
311 | } | |
312 | ||
313 | /// Generates a url appropriate for an `href` attribute back to the source of | |
314 | /// this item. | |
315 | /// | |
316 | /// The url generated, when clicked, will redirect the browser back to the | |
317 | /// original source code. | |
318 | /// | |
319 | /// If `None` is returned, then a source link couldn't be generated. This | |
320 | /// may happen, for example, with externally inlined items where the source | |
321 | /// of their crate documentation isn't known. | |
322 | pub(super) fn src_href(&self, item: &clean::Item) -> Option<String> { | |
f2b60f7d | 323 | self.href_from_span(item.span(self.tcx())?, true) |
94222f64 XL |
324 | } |
325 | ||
923072b8 | 326 | pub(crate) fn href_from_span(&self, span: clean::Span, with_lines: bool) -> Option<String> { |
6a06907d | 327 | let mut root = self.root_path(); |
9c376795 | 328 | let mut path: String; |
94222f64 | 329 | let cnum = span.cnum(self.sess()); |
6a06907d XL |
330 | |
331 | // We can safely ignore synthetic `SourceFile`s. | |
94222f64 | 332 | let file = match span.filename(self.sess()) { |
17df50a5 | 333 | FileName::Real(ref path) => path.local_path_if_available().to_path_buf(), |
6a06907d XL |
334 | _ => return None, |
335 | }; | |
336 | let file = &file; | |
337 | ||
a2a8927a | 338 | let krate_sym; |
6a06907d XL |
339 | let (krate, path) = if cnum == LOCAL_CRATE { |
340 | if let Some(path) = self.shared.local_sources.get(file) { | |
341 | (self.shared.layout.krate.as_str(), path) | |
342 | } else { | |
343 | return None; | |
344 | } | |
345 | } else { | |
94222f64 | 346 | let (krate, src_root) = match *self.cache().extern_locations.get(&cnum)? { |
17df50a5 XL |
347 | ExternalLocation::Local => { |
348 | let e = ExternalCrate { crate_num: cnum }; | |
349 | (e.name(self.tcx()), e.src_root(self.tcx())) | |
350 | } | |
351 | ExternalLocation::Remote(ref s) => { | |
6a06907d | 352 | root = s.to_string(); |
17df50a5 XL |
353 | let e = ExternalCrate { crate_num: cnum }; |
354 | (e.name(self.tcx()), e.src_root(self.tcx())) | |
6a06907d | 355 | } |
17df50a5 | 356 | ExternalLocation::Unknown => return None, |
6a06907d XL |
357 | }; |
358 | ||
9c376795 FG |
359 | let href = RefCell::new(PathBuf::new()); |
360 | sources::clean_path( | |
361 | &src_root, | |
362 | file, | |
363 | |component| { | |
364 | href.borrow_mut().push(component); | |
365 | }, | |
366 | || { | |
367 | href.borrow_mut().pop(); | |
368 | }, | |
369 | ); | |
370 | ||
353b0b11 | 371 | path = href.into_inner().to_string_lossy().into_owned(); |
9c376795 FG |
372 | |
373 | if let Some(c) = path.as_bytes().last() && *c != b'/' { | |
6a06907d | 374 | path.push('/'); |
9c376795 FG |
375 | } |
376 | ||
6a06907d XL |
377 | let mut fname = file.file_name().expect("source has no filename").to_os_string(); |
378 | fname.push(".html"); | |
379 | path.push_str(&fname.to_string_lossy()); | |
a2a8927a XL |
380 | krate_sym = krate; |
381 | (krate_sym.as_str(), &path) | |
6a06907d XL |
382 | }; |
383 | ||
3c0e092e XL |
384 | let anchor = if with_lines { |
385 | let loline = span.lo(self.sess()).line; | |
386 | let hiline = span.hi(self.sess()).line; | |
387 | format!( | |
388 | "#{}", | |
add651ee | 389 | if loline == hiline { loline.to_string() } else { format!("{loline}-{hiline}") } |
3c0e092e XL |
390 | ) |
391 | } else { | |
392 | "".to_string() | |
393 | }; | |
6a06907d | 394 | Some(format!( |
3c0e092e | 395 | "{root}src/{krate}/{path}{anchor}", |
6a06907d XL |
396 | root = Escape(&root), |
397 | krate = krate, | |
398 | path = path, | |
3c0e092e | 399 | anchor = anchor |
6a06907d XL |
400 | )) |
401 | } | |
f2b60f7d FG |
402 | |
403 | pub(crate) fn href_from_span_relative( | |
404 | &self, | |
405 | span: clean::Span, | |
406 | relative_to: &str, | |
407 | ) -> Option<String> { | |
408 | self.href_from_span(span, false).map(|s| { | |
409 | let mut url = UrlPartsBuilder::new(); | |
410 | let mut dest_href_parts = s.split('/'); | |
411 | let mut cur_href_parts = relative_to.split('/'); | |
412 | for (cur_href_part, dest_href_part) in (&mut cur_href_parts).zip(&mut dest_href_parts) { | |
413 | if cur_href_part != dest_href_part { | |
414 | url.push(dest_href_part); | |
415 | break; | |
416 | } | |
417 | } | |
418 | for dest_href_part in dest_href_parts { | |
419 | url.push(dest_href_part); | |
420 | } | |
421 | let loline = span.lo(self.sess()).line; | |
422 | let hiline = span.hi(self.sess()).line; | |
423 | format!( | |
424 | "{}{}#{}", | |
425 | "../".repeat(cur_href_parts.count()), | |
426 | url.finish(), | |
427 | if loline == hiline { loline.to_string() } else { format!("{loline}-{hiline}") } | |
428 | ) | |
429 | }) | |
430 | } | |
6a06907d XL |
431 | } |
432 | ||
433 | /// Generates the documentation for `crate` into the directory `dst` | |
434 | impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> { | |
435 | fn descr() -> &'static str { | |
436 | "html" | |
437 | } | |
438 | ||
cdc7bbd5 XL |
439 | const RUN_ON_MODULE: bool = true; |
440 | ||
6a06907d | 441 | fn init( |
94222f64 | 442 | krate: clean::Crate, |
6a06907d | 443 | options: RenderOptions, |
94222f64 | 444 | cache: Cache, |
6a06907d XL |
445 | tcx: TyCtxt<'tcx>, |
446 | ) -> Result<(Self, clean::Crate), Error> { | |
447 | // need to save a copy of the options for rendering the index page | |
448 | let md_opts = options.clone(); | |
cdc7bbd5 | 449 | let emit_crate = options.should_emit_crate(); |
6a06907d XL |
450 | let RenderOptions { |
451 | output, | |
452 | external_html, | |
453 | id_map, | |
454 | playground_url, | |
064997fb | 455 | module_sorting, |
6a06907d XL |
456 | themes: style_files, |
457 | default_settings, | |
458 | extension_css, | |
459 | resource_suffix, | |
460 | static_root_path, | |
6a06907d | 461 | generate_redirect_map, |
17df50a5 | 462 | show_type_layout, |
94222f64 | 463 | generate_link_to_definition, |
3c0e092e | 464 | call_locations, |
a2a8927a | 465 | no_emit_shared, |
6a06907d XL |
466 | .. |
467 | } = options; | |
468 | ||
3c0e092e | 469 | let src_root = match krate.src(tcx) { |
17df50a5 | 470 | FileName::Real(ref p) => match p.local_path_if_available().parent() { |
6a06907d XL |
471 | Some(p) => p.to_path_buf(), |
472 | None => PathBuf::new(), | |
473 | }, | |
474 | _ => PathBuf::new(), | |
475 | }; | |
476 | // If user passed in `--playground-url` arg, we fill in crate name here | |
477 | let mut playground = None; | |
478 | if let Some(url) = playground_url { | |
9c376795 | 479 | playground = Some(markdown::Playground { crate_name: Some(krate.name(tcx)), url }); |
6a06907d XL |
480 | } |
481 | let mut layout = layout::Layout { | |
482 | logo: String::new(), | |
483 | favicon: String::new(), | |
484 | external_html, | |
485 | default_settings, | |
3c0e092e | 486 | krate: krate.name(tcx).to_string(), |
6a06907d | 487 | css_file_extension: extension_css, |
3c0e092e | 488 | scrape_examples_extension: !call_locations.is_empty(), |
6a06907d XL |
489 | }; |
490 | let mut issue_tracker_base_url = None; | |
491 | let mut include_sources = true; | |
136023e0 | 492 | |
6a06907d XL |
493 | // Crawl the crate attributes looking for attributes which control how we're |
494 | // going to emit HTML | |
cdc7bbd5 XL |
495 | for attr in krate.module.attrs.lists(sym::doc) { |
496 | match (attr.name_or_empty(), attr.value_str()) { | |
497 | (sym::html_favicon_url, Some(s)) => { | |
498 | layout.favicon = s.to_string(); | |
499 | } | |
500 | (sym::html_logo_url, Some(s)) => { | |
501 | layout.logo = s.to_string(); | |
502 | } | |
503 | (sym::html_playground_url, Some(s)) => { | |
504 | playground = Some(markdown::Playground { | |
9c376795 | 505 | crate_name: Some(krate.name(tcx)), |
cdc7bbd5 XL |
506 | url: s.to_string(), |
507 | }); | |
508 | } | |
509 | (sym::issue_tracker_base_url, Some(s)) => { | |
510 | issue_tracker_base_url = Some(s.to_string()); | |
511 | } | |
512 | (sym::html_no_source, None) if attr.is_word() => { | |
513 | include_sources = false; | |
6a06907d | 514 | } |
cdc7bbd5 | 515 | _ => {} |
6a06907d XL |
516 | } |
517 | } | |
94222f64 | 518 | |
3c0e092e | 519 | let (local_sources, matches) = collect_spans_and_sources( |
94222f64 | 520 | tcx, |
3c0e092e | 521 | &krate, |
94222f64 XL |
522 | &src_root, |
523 | include_sources, | |
524 | generate_link_to_definition, | |
525 | ); | |
526 | ||
6a06907d | 527 | let (sender, receiver) = channel(); |
487cf647 | 528 | let scx = SharedContext { |
6a06907d | 529 | tcx, |
6a06907d | 530 | src_root, |
94222f64 | 531 | local_sources, |
6a06907d XL |
532 | issue_tracker_base_url, |
533 | layout, | |
534 | created_dirs: Default::default(), | |
064997fb | 535 | module_sorting, |
6a06907d XL |
536 | style_files, |
537 | resource_suffix, | |
538 | static_root_path, | |
539 | fs: DocFS::new(sender), | |
2b03887a | 540 | codes: ErrorCodes::from(options.unstable_features.is_nightly_build()), |
6a06907d XL |
541 | playground, |
542 | all: RefCell::new(AllTypes::new()), | |
543 | errors: receiver, | |
544 | redirections: if generate_redirect_map { Some(Default::default()) } else { None }, | |
17df50a5 | 545 | show_type_layout, |
49aad941 | 546 | span_correspondence_map: matches, |
94222f64 | 547 | cache, |
3c0e092e | 548 | call_locations, |
6a06907d XL |
549 | }; |
550 | ||
6a06907d XL |
551 | let dst = output; |
552 | scx.ensure_dir(&dst)?; | |
6a06907d XL |
553 | |
554 | let mut cx = Context { | |
555 | current: Vec::new(), | |
556 | dst, | |
557 | render_redirect_pages: false, | |
923072b8 | 558 | id_map, |
9ffffee4 | 559 | deref_id_map: Default::default(), |
6a06907d | 560 | shared: Rc::new(scx), |
94222f64 | 561 | include_sources, |
487cf647 | 562 | types_with_notable_traits: FxHashSet::default(), |
fe692bf9 | 563 | is_inside_inlined_module: false, |
6a06907d XL |
564 | }; |
565 | ||
94222f64 | 566 | if emit_crate { |
3c0e092e | 567 | sources::render(&mut cx, &krate)?; |
94222f64 XL |
568 | } |
569 | ||
a2a8927a XL |
570 | if !no_emit_shared { |
571 | // Build our search index | |
572 | let index = build_index(&krate, &mut Rc::get_mut(&mut cx.shared).unwrap().cache, tcx); | |
573 | ||
574 | // Write shared runs within a flock; disable thread dispatching of IO temporarily. | |
575 | Rc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(true); | |
923072b8 | 576 | write_shared(&mut cx, &krate, index, &md_opts)?; |
a2a8927a XL |
577 | Rc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(false); |
578 | } | |
94222f64 | 579 | |
6a06907d XL |
580 | Ok((cx, krate)) |
581 | } | |
582 | ||
583 | fn make_child_renderer(&self) -> Self { | |
6a06907d XL |
584 | Self { |
585 | current: self.current.clone(), | |
586 | dst: self.dst.clone(), | |
587 | render_redirect_pages: self.render_redirect_pages, | |
9ffffee4 | 588 | deref_id_map: Default::default(), |
923072b8 | 589 | id_map: IdMap::new(), |
6a06907d | 590 | shared: Rc::clone(&self.shared), |
94222f64 | 591 | include_sources: self.include_sources, |
487cf647 | 592 | types_with_notable_traits: FxHashSet::default(), |
fe692bf9 | 593 | is_inside_inlined_module: self.is_inside_inlined_module, |
6a06907d XL |
594 | } |
595 | } | |
596 | ||
cdc7bbd5 XL |
597 | fn after_krate(&mut self) -> Result<(), Error> { |
598 | let crate_name = self.tcx().crate_name(LOCAL_CRATE); | |
a2a8927a | 599 | let final_file = self.dst.join(crate_name.as_str()).join("all.html"); |
6a06907d | 600 | let settings_file = self.dst.join("settings.html"); |
2b03887a | 601 | let help_file = self.dst.join("help.html"); |
04454e1e | 602 | let scrape_examples_help_file = self.dst.join("scrape-examples-help.html"); |
6a06907d XL |
603 | |
604 | let mut root_path = self.dst.to_str().expect("invalid path").to_owned(); | |
605 | if !root_path.ends_with('/') { | |
606 | root_path.push('/'); | |
607 | } | |
923072b8 | 608 | let shared = Rc::clone(&self.shared); |
6a06907d XL |
609 | let mut page = layout::Page { |
610 | title: "List of all items in this crate", | |
611 | css_class: "mod", | |
612 | root_path: "../", | |
923072b8 | 613 | static_root_path: shared.static_root_path.as_deref(), |
6a06907d | 614 | description: "List of all items in this crate", |
923072b8 | 615 | resource_suffix: &shared.resource_suffix, |
6a06907d | 616 | }; |
923072b8 | 617 | let all = shared.all.replace(AllTypes::new()); |
2b03887a | 618 | let mut sidebar = Buffer::html(); |
353b0b11 FG |
619 | |
620 | let blocks = sidebar_module_like(all.item_sections()); | |
621 | let bar = Sidebar { | |
622 | title_prefix: "Crate ", | |
623 | title: crate_name.as_str(), | |
624 | is_crate: false, | |
625 | version: "", | |
626 | blocks: vec![blocks], | |
627 | path: String::new(), | |
2b03887a FG |
628 | }; |
629 | ||
353b0b11 | 630 | bar.render_into(&mut sidebar).unwrap(); |
2b03887a | 631 | |
6a06907d | 632 | let v = layout::render( |
923072b8 | 633 | &shared.layout, |
6a06907d | 634 | &page, |
2b03887a | 635 | sidebar.into_inner(), |
6a06907d | 636 | |buf: &mut Buffer| all.print(buf), |
923072b8 | 637 | &shared.style_files, |
6a06907d | 638 | ); |
923072b8 | 639 | shared.fs.write(final_file, v)?; |
6a06907d XL |
640 | |
641 | // Generating settings page. | |
642 | page.title = "Rustdoc settings"; | |
643 | page.description = "Settings of Rustdoc"; | |
644 | page.root_path = "./"; | |
645 | ||
17df50a5 | 646 | let sidebar = "<h2 class=\"location\">Settings</h2><div class=\"sidebar-elems\"></div>"; |
6a06907d | 647 | let v = layout::render( |
923072b8 | 648 | &shared.layout, |
6a06907d XL |
649 | &page, |
650 | sidebar, | |
04454e1e FG |
651 | |buf: &mut Buffer| { |
652 | write!( | |
653 | buf, | |
923072b8 | 654 | "<div class=\"main-heading\">\ |
9c376795 | 655 | <h1>Rustdoc settings</h1>\ |
923072b8 FG |
656 | <span class=\"out-of-band\">\ |
657 | <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\ | |
658 | Back\ | |
659 | </a>\ | |
660 | </span>\ | |
661 | </div>\ | |
662 | <noscript>\ | |
663 | <section>\ | |
49aad941 | 664 | You need to enable JavaScript be able to update your settings.\ |
923072b8 FG |
665 | </section>\ |
666 | </noscript>\ | |
9c376795 | 667 | <link rel=\"stylesheet\" \ |
487cf647 | 668 | href=\"{static_root_path}{settings_css}\">\ |
353b0b11 FG |
669 | <script defer src=\"{static_root_path}{settings_js}\"></script>\ |
670 | <link rel=\"preload\" href=\"{static_root_path}{theme_light_css}\" \ | |
671 | as=\"style\">\ | |
672 | <link rel=\"preload\" href=\"{static_root_path}{theme_dark_css}\" \ | |
673 | as=\"style\">\ | |
674 | <link rel=\"preload\" href=\"{static_root_path}{theme_ayu_css}\" \ | |
675 | as=\"style\">", | |
487cf647 FG |
676 | static_root_path = page.get_static_root_path(), |
677 | settings_css = static_files::STATIC_FILES.settings_css, | |
678 | settings_js = static_files::STATIC_FILES.settings_js, | |
353b0b11 FG |
679 | theme_light_css = static_files::STATIC_FILES.theme_light_css, |
680 | theme_dark_css = static_files::STATIC_FILES.theme_dark_css, | |
681 | theme_ayu_css = static_files::STATIC_FILES.theme_ayu_css, | |
682 | ); | |
683 | // Pre-load all theme CSS files, so that switching feels seamless. | |
684 | // | |
685 | // When loading settings.html as a popover, the equivalent HTML is | |
686 | // generated in main.js. | |
687 | for file in &shared.style_files { | |
688 | if let Ok(theme) = file.basename() { | |
689 | write!( | |
690 | buf, | |
691 | "<link rel=\"preload\" href=\"{root_path}{theme}{suffix}.css\" \ | |
692 | as=\"style\">", | |
693 | root_path = page.static_root_path.unwrap_or(""), | |
694 | suffix = page.resource_suffix, | |
695 | ); | |
696 | } | |
697 | } | |
04454e1e | 698 | }, |
923072b8 | 699 | &shared.style_files, |
6a06907d | 700 | ); |
923072b8 | 701 | shared.fs.write(settings_file, v)?; |
04454e1e | 702 | |
2b03887a FG |
703 | // Generating help page. |
704 | page.title = "Rustdoc help"; | |
705 | page.description = "Documentation for Rustdoc"; | |
706 | page.root_path = "./"; | |
707 | ||
708 | let sidebar = "<h2 class=\"location\">Help</h2><div class=\"sidebar-elems\"></div>"; | |
709 | let v = layout::render( | |
710 | &shared.layout, | |
711 | &page, | |
712 | sidebar, | |
713 | |buf: &mut Buffer| { | |
714 | write!( | |
715 | buf, | |
716 | "<div class=\"main-heading\">\ | |
9c376795 | 717 | <h1>Rustdoc help</h1>\ |
2b03887a FG |
718 | <span class=\"out-of-band\">\ |
719 | <a id=\"back\" href=\"javascript:void(0)\" onclick=\"history.back();\">\ | |
720 | Back\ | |
721 | </a>\ | |
722 | </span>\ | |
723 | </div>\ | |
724 | <noscript>\ | |
725 | <section>\ | |
49aad941 | 726 | <p>You need to enable JavaScript to use keyboard commands or search.</p>\ |
2b03887a FG |
727 | <p>For more information, browse the <a href=\"https://doc.rust-lang.org/rustdoc/\">rustdoc handbook</a>.</p>\ |
728 | </section>\ | |
729 | </noscript>", | |
730 | ) | |
731 | }, | |
732 | &shared.style_files, | |
733 | ); | |
734 | shared.fs.write(help_file, v)?; | |
735 | ||
923072b8 | 736 | if shared.layout.scrape_examples_extension { |
04454e1e FG |
737 | page.title = "About scraped examples"; |
738 | page.description = "How the scraped examples feature works in Rustdoc"; | |
739 | let v = layout::render( | |
923072b8 | 740 | &shared.layout, |
04454e1e FG |
741 | &page, |
742 | "", | |
923072b8 FG |
743 | scrape_examples_help(&*shared), |
744 | &shared.style_files, | |
04454e1e | 745 | ); |
923072b8 | 746 | shared.fs.write(scrape_examples_help_file, v)?; |
04454e1e FG |
747 | } |
748 | ||
9ffffee4 FG |
749 | if let Some(ref redirections) = shared.redirections && !redirections.borrow().is_empty() { |
750 | let redirect_map_path = | |
751 | self.dst.join(crate_name.as_str()).join("redirect-map.json"); | |
752 | let paths = serde_json::to_string(&*redirections.borrow()).unwrap(); | |
753 | shared.ensure_dir(&self.dst.join(crate_name.as_str()))?; | |
754 | shared.fs.write(redirect_map_path, paths)?; | |
6a06907d XL |
755 | } |
756 | ||
923072b8 FG |
757 | // No need for it anymore. |
758 | drop(shared); | |
759 | ||
6a06907d XL |
760 | // Flush pending errors. |
761 | Rc::get_mut(&mut self.shared).unwrap().fs.close(); | |
cdc7bbd5 | 762 | let nb_errors = |
49aad941 | 763 | self.shared.errors.iter().map(|err| self.tcx().sess.struct_err(err).emit()).count(); |
6a06907d XL |
764 | if nb_errors > 0 { |
765 | Err(Error::new(io::Error::new(io::ErrorKind::Other, "I/O error"), "")) | |
766 | } else { | |
767 | Ok(()) | |
768 | } | |
769 | } | |
770 | ||
cdc7bbd5 | 771 | fn mod_item_in(&mut self, item: &clean::Item) -> Result<(), Error> { |
6a06907d XL |
772 | // Stripped modules survive the rustdoc passes (i.e., `strip-private`) |
773 | // if they contain impls for public types. These modules can also | |
774 | // contain items such as publicly re-exported structures. | |
775 | // | |
776 | // External crates will provide links to these structures, so | |
777 | // these modules are recursed into, but not rendered normally | |
778 | // (a flag on the context). | |
779 | if !self.render_redirect_pages { | |
780 | self.render_redirect_pages = item.is_stripped(); | |
781 | } | |
5099ac24 FG |
782 | let item_name = item.name.unwrap(); |
783 | self.dst.push(&*item_name.as_str()); | |
cdc7bbd5 | 784 | self.current.push(item_name); |
6a06907d XL |
785 | |
786 | info!("Recursing into {}", self.dst.display()); | |
787 | ||
fe692bf9 FG |
788 | if !item.is_stripped() { |
789 | let buf = self.render_item(item, true); | |
790 | // buf will be empty if the module is stripped and there is no redirect for it | |
791 | if !buf.is_empty() { | |
792 | self.shared.ensure_dir(&self.dst)?; | |
793 | let joint_dst = self.dst.join("index.html"); | |
794 | self.shared.fs.write(joint_dst, buf)?; | |
795 | } | |
796 | } | |
797 | if !self.is_inside_inlined_module { | |
798 | if let Some(def_id) = item.def_id() && self.cache().inlined_items.contains(&def_id) { | |
799 | self.is_inside_inlined_module = true; | |
800 | } | |
add651ee | 801 | } else if !self.cache().document_hidden && item.is_doc_hidden() { |
fe692bf9 FG |
802 | // We're not inside an inlined module anymore since this one cannot be re-exported. |
803 | self.is_inside_inlined_module = false; | |
6a06907d XL |
804 | } |
805 | ||
806 | // Render sidebar-items.js used throughout this module. | |
807 | if !self.render_redirect_pages { | |
add651ee FG |
808 | let (clean::StrippedItem(box clean::ModuleItem(ref module)) |
809 | | clean::ModuleItem(ref module)) = *item.kind | |
810 | else { | |
811 | unreachable!() | |
812 | }; | |
6a06907d | 813 | let items = self.build_sidebar_items(module); |
5099ac24 | 814 | let js_dst = self.dst.join(&format!("sidebar-items{}.js", self.shared.resource_suffix)); |
923072b8 FG |
815 | let v = format!("window.SIDEBAR_ITEMS = {};", serde_json::to_string(&items).unwrap()); |
816 | self.shared.fs.write(js_dst, v)?; | |
6a06907d XL |
817 | } |
818 | Ok(()) | |
819 | } | |
820 | ||
cdc7bbd5 | 821 | fn mod_item_out(&mut self) -> Result<(), Error> { |
6a06907d XL |
822 | info!("Recursed; leaving {}", self.dst.display()); |
823 | ||
824 | // Go back to where we were at | |
825 | self.dst.pop(); | |
826 | self.current.pop(); | |
827 | Ok(()) | |
828 | } | |
829 | ||
830 | fn item(&mut self, item: clean::Item) -> Result<(), Error> { | |
831 | // Stripped modules survive the rustdoc passes (i.e., `strip-private`) | |
832 | // if they contain impls for public types. These modules can also | |
833 | // contain items such as publicly re-exported structures. | |
834 | // | |
835 | // External crates will provide links to these structures, so | |
836 | // these modules are recursed into, but not rendered normally | |
837 | // (a flag on the context). | |
838 | if !self.render_redirect_pages { | |
839 | self.render_redirect_pages = item.is_stripped(); | |
840 | } | |
841 | ||
cdc7bbd5 | 842 | let buf = self.render_item(&item, false); |
6a06907d XL |
843 | // buf will be empty if the item is stripped and there is no redirect for it |
844 | if !buf.is_empty() { | |
845 | let name = item.name.as_ref().unwrap(); | |
846 | let item_type = item.type_(); | |
a2a8927a | 847 | let file_name = &item_path(item_type, name.as_str()); |
6a06907d XL |
848 | self.shared.ensure_dir(&self.dst)?; |
849 | let joint_dst = self.dst.join(file_name); | |
c295e0f8 | 850 | self.shared.fs.write(joint_dst, buf)?; |
6a06907d XL |
851 | |
852 | if !self.render_redirect_pages { | |
853 | self.shared.all.borrow_mut().append(full_path(self, &item), &item_type); | |
854 | } | |
855 | // If the item is a macro, redirect from the old macro URL (with !) | |
856 | // to the new one (without). | |
857 | if item_type == ItemType::Macro { | |
add651ee | 858 | let redir_name = format!("{item_type}.{name}!.html"); |
6a06907d XL |
859 | if let Some(ref redirections) = self.shared.redirections { |
860 | let crate_name = &self.shared.layout.krate; | |
861 | redirections.borrow_mut().insert( | |
add651ee FG |
862 | format!("{crate_name}/{redir_name}"), |
863 | format!("{crate_name}/{file_name}"), | |
6a06907d XL |
864 | ); |
865 | } else { | |
866 | let v = layout::redirect(file_name); | |
867 | let redir_dst = self.dst.join(redir_name); | |
c295e0f8 | 868 | self.shared.fs.write(redir_dst, v)?; |
6a06907d XL |
869 | } |
870 | } | |
871 | } | |
487cf647 | 872 | |
6a06907d XL |
873 | Ok(()) |
874 | } | |
875 | ||
876 | fn cache(&self) -> &Cache { | |
94222f64 | 877 | &self.shared.cache |
6a06907d XL |
878 | } |
879 | } |