Skip to content
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.

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

fix(html): better titles and correct breadcrumbs #620

Merged
merged 4 commits into from
Aug 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 6 additions & 1 deletion src/html/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -823,9 +823,14 @@ pub fn generate(
UrlResolveKind::Root,
);

let mut title_parts = breadcrumbs_ctx.to_strings();
title_parts.reverse();
// contains the package name, which we already render in the head
title_parts.pop();

let html_head_ctx = pages::HtmlHeadCtx::new(
&root,
&symbol_group_ctx.name,
Some(&title_parts.join(" - ")),
ctx.package_name.as_ref(),
Some(short_path),
ctx.disable_search,
Expand Down
36 changes: 24 additions & 12 deletions src/html/pages.rs
Original file line number Diff line number Diff line change
Expand Up @@ -47,14 +47,15 @@ impl HtmlHeadCtx {

pub fn new(
root: &str,
page: &str,
page: Option<&str>,
package_name: Option<&String>,
current_file: Option<&ShortPath>,
disable_search: bool,
) -> Self {
Self {
title: format!(
"{page} - {}documentation",
"{}{}documentation",
page.map(|page| format!("{page} - ")).unwrap_or_default(),
package_name
.map(|package_name| format!("{package_name} "))
.unwrap_or_default()
Expand Down Expand Up @@ -222,7 +223,13 @@ impl IndexCtx {

let html_head_ctx = HtmlHeadCtx::new(
&root,
"Index",
short_path.as_ref().and_then(|short_path| {
if short_path.is_main {
None
} else {
Some(short_path.display_name())
}
}),
ctx.package_name.as_ref(),
None,
ctx.disable_search,
Expand Down Expand Up @@ -385,7 +392,7 @@ impl IndexCtx {

let html_head_ctx = HtmlHeadCtx::new(
&root,
name,
Some(name),
ctx.package_name.as_ref(),
None,
ctx.disable_search,
Expand Down Expand Up @@ -450,7 +457,7 @@ impl AllSymbolsCtx {

let html_head_ctx = HtmlHeadCtx::new(
"./",
"All Symbols",
Some("All Symbols"),
ctx.package_name.as_ref(),
None,
ctx.disable_search,
Expand Down Expand Up @@ -735,13 +742,18 @@ pub fn render_symbol_page(
symbol: namespaced_name,
})
.with_category(if render_ctx.ctx.file_mode == FileMode::SingleDts {
doc_nodes[0].js_doc.tags.iter().find_map(|tag| {
if let JsDocTag::Category { doc } = tag {
Some(doc.as_ref())
} else {
None
}
})
doc_nodes[0]
.get_topmost_ancestor()
.js_doc
.tags
.iter()
.find_map(|tag| {
if let JsDocTag::Category { doc } = tag {
Some(doc.as_ref())
} else {
None
}
})
} else {
None
});
Expand Down
17 changes: 17 additions & 0 deletions src/html/util.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ use deno_ast::swc::atoms::once_cell::sync::Lazy;
use indexmap::IndexSet;
use regex::Regex;
use serde::Serialize;
use std::borrow::Cow;
use std::collections::HashMap;
use std::collections::HashSet;
use std::rc::Rc;
Expand Down Expand Up @@ -332,6 +333,22 @@ pub struct BreadcrumbsCtx {

impl BreadcrumbsCtx {
pub const TEMPLATE: &'static str = "breadcrumbs";

pub fn to_strings(&self) -> Vec<Cow<str>> {
let mut title_parts = vec![];
let mut symbol_parts = vec![];

for breadcrumb in self.parts.iter() {
if breadcrumb.is_symbol {
symbol_parts.push(breadcrumb.name.as_str());
} else {
title_parts.push(Cow::Borrowed(breadcrumb.name.as_str()));
}
}
title_parts.push(Cow::Owned(symbol_parts.join(".")));

title_parts
}
}

#[derive(Debug, Serialize, Clone, Eq, PartialEq, Hash)]
Expand Down
11 changes: 5 additions & 6 deletions tests/html_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -200,10 +200,9 @@ async fn html_doc_files_rewrite() {
.join("testdata")
.join("multiple");
let mut rewrite_map = IndexMap::new();
rewrite_map.insert(
ModuleSpecifier::from_file_path(multiple_dir.join("a.ts")).unwrap(),
".".to_string(),
);
let main_specifier =
ModuleSpecifier::from_file_path(multiple_dir.join("a.ts")).unwrap();
rewrite_map.insert(main_specifier.clone(), ".".to_string());
rewrite_map.insert(
ModuleSpecifier::from_file_path(multiple_dir.join("b.ts")).unwrap(),
"foo".to_string(),
Expand All @@ -212,7 +211,7 @@ async fn html_doc_files_rewrite() {
let files = generate(
GenerateOptions {
package_name: None,
main_entrypoint: None,
main_entrypoint: Some(main_specifier),
href_resolver: Rc::new(EmptyResolver {}),
usage_composer: None,
rewrite_map: Some(rewrite_map),
Expand Down Expand Up @@ -361,7 +360,7 @@ async fn symbol_group() {

let html_head_ctx = pages::HtmlHeadCtx::new(
&root,
&symbol_group_ctx.name,
Some(&symbol_group_ctx.name),
ctx.package_name.as_ref(),
Some(short_path),
false,
Expand Down
2 changes: 1 addition & 1 deletion tests/snapshots/html_test__html_doc_files-2.snap
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ expression: "files.get(\"./index.html\").unwrap()"
<!DOCTYPE html>
<html>
<head>
<title>Index - documentation</title>
<title>documentation</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content="">
Expand Down
28 changes: 10 additions & 18 deletions tests/snapshots/html_test__html_doc_files_rewrite-10.snap
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,28 @@ expression: "files.get(\"./~/Foo.prototype.foo.html\").unwrap()"
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content=".">
<link rel="stylesheet" href="..&#x2F;..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;..&#x2F;reset.css">
<link rel="stylesheet" href="..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">

<script src="..&#x2F;..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;..&#x2F;script.js" defer></script>
<script src="..&#x2F;..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;..&#x2F;search.js" defer></script>
Comment on lines -16 to -19
Copy link
Member

Choose a reason for hiding this comment

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

Are these changes actually expected?

Copy link
Member Author

Choose a reason for hiding this comment

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

yep, related to

Changes also the test infrastructure to correspond to a more realistic scenario.

<script src="..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;script.js" defer></script>
<script src="..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;search.js" defer></script>
</head>
<body>
<div class="ddoc">
<div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">
<div class="h-full">
<div><ul class="breadcrumbs"><li><a href="..&#x2F;..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
<div><ul class="breadcrumbs"><li><a href="..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;index.html" class="contextLink">.</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><ul><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.html" class="contextLink">Foo</a></li><span>.</span><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.prototype.html" class="contextLink">prototype</a></li><span>.</span><li>foo</li></ul></ul>
</span><ul><li><a href="..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.html" class="contextLink">Foo</a></li><span>.</span><li><a href="..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.prototype.html" class="contextLink">prototype</a></li><span>.</span><li>foo</li></ul></ul>
</div>

<input
Expand Down Expand Up @@ -80,7 +72,7 @@ expression: "files.get(\"./~/Foo.prototype.foo.html\").unwrap()"
Type</h2></div><div class="space-y-8"><div class=" docEntry" id="variable_Foo_prototype_foo">

<div class="docEntryHeader">
<div><code><span class="font-medium text-stone-500"><a href="../../././~/A.html" class="link">A</a></span>
<div><code><span class="font-medium text-stone-500"><a href="../././~/A.html" class="link">A</a></span>
</code>
</div></div></div>
</div></section>
Expand Down
2 changes: 1 addition & 1 deletion tests/snapshots/html_test__html_doc_files_rewrite-11.snap
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
source: tests/html_test.rs
expression: "files.get(\"./~/Foo.prototype.html\").unwrap()"
---
<meta http-equiv="refresh" content="0; url=..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.html">
<meta http-equiv="refresh" content="0; url=..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foo.html">
24 changes: 8 additions & 16 deletions tests/snapshots/html_test__html_doc_files_rewrite-12.snap
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,20 @@ expression: "files.get(\"./~/Foobar.html\").unwrap()"
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content=".">
<link rel="stylesheet" href="..&#x2F;..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;..&#x2F;reset.css">
<link rel="stylesheet" href="..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">

<script src="..&#x2F;..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;..&#x2F;script.js" defer></script>
<script src="..&#x2F;..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;..&#x2F;search.js" defer></script>
<script src="..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;script.js" defer></script>
<script src="..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;search.js" defer></script>
</head>
<body>
<div class="ddoc">
<div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">
<div class="h-full">
<div><ul class="breadcrumbs"><li><a href="..&#x2F;..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;index.html" class="contextLink">.</a></li><span class="text-[#0F172A]"><svg
<div><ul class="breadcrumbs"><li><a href="..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
Expand Down
2 changes: 1 addition & 1 deletion tests/snapshots/html_test__html_doc_files_rewrite-13.snap
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
source: tests/html_test.rs
expression: "files.get(\"./~/Foobar.prototype.html\").unwrap()"
---
<meta http-equiv="refresh" content="0; url=..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foobar.html">
<meta http-equiv="refresh" content="0; url=..&#x2F;.&#x2F;.&#x2F;~&#x2F;Foobar.html">
26 changes: 9 additions & 17 deletions tests/snapshots/html_test__html_doc_files_rewrite-14.snap
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,20 @@ expression: "files.get(\"./~/Hello.html\").unwrap()"
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content=".">
<link rel="stylesheet" href="..&#x2F;..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;..&#x2F;reset.css">
<link rel="stylesheet" href="..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">

<script src="..&#x2F;..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;..&#x2F;script.js" defer></script>
<script src="..&#x2F;..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;..&#x2F;search.js" defer></script>
<script src="..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;script.js" defer></script>
<script src="..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;search.js" defer></script>
</head>
<body>
<div class="ddoc">
<div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">
<div class="h-full">
<div><ul class="breadcrumbs"><li><a href="..&#x2F;..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;index.html" class="contextLink">.</a></li><span class="text-[#0F172A]"><svg
<div><ul class="breadcrumbs"><li><a href="..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
Expand Down Expand Up @@ -102,7 +94,7 @@ Properties</h2></div><div class="space-y-8"><div class="anchorable docEntry" id=
</defs>
</svg>
</a>
<a class="font-bold font-lg link" href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Hello.world.html">world</a><span class="font-medium text-stone-500"><span>: <span>"string"</span></span></span>
<a class="font-bold font-lg link" href="..&#x2F;.&#x2F;.&#x2F;~&#x2F;Hello.world.html">world</a><span class="font-medium text-stone-500"><span>: <span>"string"</span></span></span>
</code>
</div></div></div>
</div></section>
Expand Down
26 changes: 9 additions & 17 deletions tests/snapshots/html_test__html_doc_files_rewrite-15.snap
Original file line number Diff line number Diff line change
Expand Up @@ -9,36 +9,28 @@ expression: "files.get(\"./~/Hello.world.html\").unwrap()"
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content=".">
<link rel="stylesheet" href="..&#x2F;..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;..&#x2F;reset.css">
<link rel="stylesheet" href="..&#x2F;styles.css">
<link rel="stylesheet" href="..&#x2F;page.css">
<link id="ddocResetStylesheet" rel="stylesheet" href="..&#x2F;reset.css">

<script src="..&#x2F;..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;..&#x2F;script.js" defer></script>
<script src="..&#x2F;..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;..&#x2F;search.js" defer></script>
<script src="..&#x2F;search_index.js" defer></script>
<script src="..&#x2F;script.js" defer></script>
<script src="..&#x2F;fuse.js" defer></script>
<script src="..&#x2F;search.js" defer></script>
</head>
<body>
<div class="ddoc">
<div><nav class="top-0 sticky bg-white z-50 py-3 h-14" id="topnav">
<div class="h-full">
<div><ul class="breadcrumbs"><li><a href="..&#x2F;..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
<div><ul class="breadcrumbs"><li><a href="..&#x2F;" class="contextLink">index</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;index.html" class="contextLink">.</a></li><span class="text-[#0F172A]"><svg
width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" clip-rule="evenodd" d="M5.76748 11.8159C5.5378 11.577 5.54525 11.1972 5.78411 10.9675L8.93431 8L5.78411 5.0325C5.54525 4.80282 5.5378 4.423 5.76748 4.18413C5.99715 3.94527 6.37698 3.93782 6.61584 4.1675L10.2158 7.5675C10.3335 7.68062 10.4 7.83679 10.4 8C10.4 8.16321 10.3335 8.31938 10.2158 8.4325L6.61584 11.8325C6.37698 12.0622 5.99715 12.0547 5.76748 11.8159Z" fill="currentColor" />
</svg>
</span><ul><li><a href="..&#x2F;..&#x2F;.&#x2F;.&#x2F;~&#x2F;Hello.html" class="contextLink">Hello</a></li><span>.</span><li>world</li></ul></ul>
</span><ul><li><a href="..&#x2F;.&#x2F;.&#x2F;~&#x2F;Hello.html" class="contextLink">Hello</a></li><span>.</span><li>world</li></ul></ul>
</div>

<input
Expand Down
2 changes: 1 addition & 1 deletion tests/snapshots/html_test__html_doc_files_rewrite-16.snap
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ expression: "files.get(\"foo/index.html\").unwrap()"
<!DOCTYPE html>
<html>
<head>
<title>Index - documentation</title>
<title>foo - documentation</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content="">
Expand Down
2 changes: 1 addition & 1 deletion tests/snapshots/html_test__html_doc_files_rewrite-17.snap
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ expression: "files.get(\"foo/~/x.html\").unwrap()"
<!DOCTYPE html>
<html>
<head>
<title>x - documentation</title>
<title>x - foo - documentation</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="doc-current-file" content="foo">
Expand Down
Loading