feat(templs): glossarydisambiguation

Inlcudes: - link fixes - hacky summary support - test fixes - json fixes - other fixes
mdn · Aug 8, 2024 · 18d57ba · 18d57ba
1 parent 56bf52a
commit 18d57ba
Show file tree

Hide file tree

Showing 16 changed files with 166 additions and 54 deletions.
diff --git a/crates/rari-doc/src/docs/json.rs b/crates/rari-doc/src/docs/json.rs
@@ -109,7 +109,6 @@ pub struct JsonDoc {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub summary: Option<String>,
     pub title: String,
-    #[serde(skip_serializing_if = "Vec::is_empty")]
     pub toc: Vec<TocEntry>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub baseline: Option<&'static SupportStatus>,

diff --git a/crates/rari-doc/src/helpers/mod.rs b/crates/rari-doc/src/helpers/mod.rs
@@ -2,5 +2,6 @@ pub mod api_inheritance;
 pub mod css_info;
 pub mod json_data;
 pub mod subpages;
+pub mod summary_hack;
 pub mod titles;
 pub mod web_ext_examples;
diff --git a/crates/rari-doc/src/helpers/summary_hack.rs b/crates/rari-doc/src/helpers/summary_hack.rs
@@ -0,0 +1,33 @@
+use crate::docs::doc::render_md_to_html;
+use crate::docs::page::{Page, PageLike};
+use crate::error::DocError;
+use crate::templ::render::render_for_summary;
+
+/// There's a few places were we still tansplant content.
+/// Yari had a hidden hacky way to do this and we have to mimic this for now.
+pub fn get_hacky_summary_md(page: &Page) -> Result<String, DocError> {
+    page.content()
+        .lines()
+        .find(|line| {
+            !(line.trim().is_empty()
+                || line.starts_with("{{") && line.ends_with("}}")
+                || line.starts_with("##"))
+        })
+        .map(|line| {
+            render_for_summary(line).and_then(|md| render_md_to_html(md.trim(), page.locale()))
+        })
+        .unwrap_or_else(|| Ok(String::from("No summray found.")))
+}
+
+/// Trims a `<p>` tag in good faith.
+/// This does not check if theres a `<p>` as root and will
+/// result in invalid html for input like:
+/// ```
+/// <p>foo</p>bar
+/// ```
+pub fn strip_paragraph_unckecked(input: &str) -> &str {
+    let out = input.trim().strip_prefix("<p>").unwrap_or(input);
+    let out = out.trim().strip_suffix("</p>").unwrap_or(out);
+
+    out
+}
diff --git a/crates/rari-doc/src/html/bubble_up.rs b/crates/rari-doc/src/html/bubble_up.rs
@@ -62,7 +62,7 @@ mod test {
         bubble_up_curriculum_page(&mut fragment)?;
 
         assert_eq!(
-            r#"<html><p>foo</p><p class="curriculum-resources"><span class="curriculum-resources">resources:</span></p><ul><li>42</li></ul></html>"#,
+            r#"<html><p>foo</p><p><span class="curriculum-resources">resources:</span></p><ul><li>42</li></ul></html>"#,
             fragment.html()
         );
         Ok(())

diff --git a/crates/rari-doc/src/html/links.rs b/crates/rari-doc/src/html/links.rs
@@ -19,12 +19,17 @@ pub struct LinkModifier<'a> {
 pub fn render_internal_link(
     out: &mut String,
     url: &str,
+    anchor: Option<&str>,
     content: &str,
     title: Option<&str>,
     modifier: &LinkModifier,
 ) -> Result<(), DocError> {
     out.push_str("<a href=\"");
     out.push_str(url);
+    if let Some(anchor) = anchor {
+        out.push('#');
+        out.push_str(anchor);
+    }
     if let Some(title) = title {
         out.push_str("\" title=\"");
         out.push_str(title);
@@ -36,7 +41,8 @@ pub fn render_internal_link(
     if modifier.code {
         out.push_str("<code>");
     }
-    let content = html_escape::encode_safe(content);
+    let content = html_escape::decode_html_entities(content);
+    let content = html_escape::encode_safe(&content);
     out.push_str(&content);
     if modifier.code {
         out.push_str("</code>");
@@ -62,7 +68,7 @@ pub fn render_link_from_page(
     modifier: &LinkModifier,
 ) -> Result<(), DocError> {
     let content = html_escape::encode_safe(page.short_title().unwrap_or(page.title()));
-    render_internal_link(out, page.url(), &content, None, modifier)
+    render_internal_link(out, page.url(), None, &content, None, modifier)
 }
 
 pub fn render_link_via_page(
@@ -74,19 +80,24 @@ pub fn render_link_via_page(
     title: Option<&str>,
     with_badges: bool,
 ) -> Result<(), DocError> {
+    let mut url = Cow::Borrowed(link);
     if link.starts_with('/') {
-        let url = if let Some(locale) = locale {
-            Cow::Owned(format!("/{}/docs{link}", locale.as_url_str()))
-        } else {
-            Cow::Borrowed(link)
+        if let Some(locale) = locale {
+            url = Cow::Owned(format!("/{}/docs{link}", locale.as_url_str()));
         };
-        match RariApi::get_page(&url) {
+        let (url, anchor) = url.split_once('#').unwrap_or((&url, ""));
+        match RariApi::get_page(url) {
             Ok(page) => {
                 let url = page.url();
                 let content = content.unwrap_or(page.short_title().unwrap_or(page.title()));
                 return render_internal_link(
                     out,
                     url,
+                    if anchor.is_empty() {
+                        None
+                    } else {
+                        Some(anchor)
+                    },
                     content,
                     title,
                     &LinkModifier {
@@ -104,13 +115,12 @@ pub fn render_link_via_page(
     }
 
     out.push_str("<a href=\"");
-    let url = link;
-    let content = if link.starts_with('/') {
-        &link[link.rfind('/').unwrap_or(0)..]
-    } else {
-        &html_escape::encode_safe(content.unwrap_or(link))
+    let content = match content {
+        Some(content) => &html_escape::encode_safe(content),
+        None if url.starts_with('/') => &url[url.rfind('/').unwrap_or(0)..],
+        _ => &html_escape::encode_safe(&url),
     };
-    out.push_str(url);
+    out.push_str(&url);
     if let Some(title) = title {
         out.push_str("\" title=\"");
         out.push_str(title);

diff --git a/crates/rari-doc/src/html/modifier.rs b/crates/rari-doc/src/html/modifier.rs
@@ -43,7 +43,8 @@ pub fn add_missing_ids(html: &mut Html) -> Result<(), DocError> {
         .map(Cow::Borrowed)
         .collect::<HashSet<_>>();
 
-    let selector = Selector::parse("*[data-update-id], h2:not([id]), h3:not([id])").unwrap();
+    let selector =
+        Selector::parse("*[data-update-id], h2:not([id]), h3:not([id]), dt:not([id])").unwrap();
     let subs =
         html.select(&selector)
             .map(|el| {

diff --git a/crates/rari-doc/src/html/rewriter.rs b/crates/rari-doc/src/html/rewriter.rs
@@ -3,6 +3,7 @@ use std::collections::HashSet;
 
 use lol_html::html_content::ContentType;
 use lol_html::{element, rewrite_str, HtmlRewriter, RewriteStrSettings, Settings};
+use rari_l10n::l10n_json_data;
 use rari_md::node_card::NoteCard;
 use rari_types::fm_types::PageType;
 use rari_types::locale::Locale;
@@ -151,7 +152,7 @@ pub fn post_process_html<T: PageLike>(
                             if class.is_empty() { "" } else { " " }
                         ),
                     )?;
-                    el.set_attribute("title", "This is a link to an unwritten page")?;
+                    el.set_attribute("title", l10n_json_data("Common", "summary", page.locale())?)?;
                 }
                 el.set_attribute(
                     "href",

diff --git a/crates/rari-doc/src/templ/api.rs b/crates/rari-doc/src/templ/api.rs
@@ -1,7 +1,4 @@
-use std::borrow::Cow;
-
 use percent_encoding::utf8_percent_encode;
-use rari_l10n::l10n_json_data;
 use rari_md::anchor::anchorize;
 use rari_types::globals::{deny_warnings, settings};
 use rari_types::locale::Locale;
@@ -53,22 +50,7 @@ impl RariApi {
         with_badge: bool,
     ) -> Result<String, DocError> {
         let mut out = String::new();
-        if let Err(DocError::IOError(_)) =
-            render_link_via_page(&mut out, link, locale, content, code, title, with_badge)
-        {
-            let title_for_missing_page =
-                l10n_json_data("Common", "summary", locale.unwrap_or_default()).unwrap_or_default();
-            let content = content.unwrap_or(link);
-            let content = if code {
-                Cow::Owned(format!("<code>{}</code>", content))
-            } else {
-                Cow::Borrowed(content)
-            };
-            return Ok(format!(
-                r#"<a href="{link}" class="page-not-created" title="{title_for_missing_page}">{content}</a>"#
-            ));
-        }
-
+        render_link_via_page(&mut out, link, locale, content, code, title, with_badge)?;
         Ok(out)
     }
 }
diff --git a/crates/rari-doc/src/templ/parser.rs b/crates/rari-doc/src/templ/parser.rs
@@ -95,7 +95,7 @@ fn to_arg(pair: Pair<'_, Rule>) -> Option<Arg> {
     }
 }
 
-pub(crate) fn parse(input: &str) -> Result<Vec<Token>, DocError> {
+pub fn parse(input: &str) -> Result<Vec<Token>, DocError> {
     let mut p =
         RariTempl::parse(Rule::doc, input).map_err(|e| DocError::PestError(e.to_string()))?;
     let tokens = p

diff --git a/crates/rari-doc/src/templ/render.rs b/crates/rari-doc/src/templ/render.rs
@@ -1,7 +1,7 @@
 use std::fmt::Write;
 
 use rari_types::globals::deny_warnings;
-use rari_types::RariEnv;
+use rari_types::{AnyArg, RariEnv};
 use tracing::{span, warn, Level};
 
 use super::parser::{parse, Token};
@@ -14,6 +14,46 @@ pub struct Rendered {
     pub sidebars: Vec<String>,
 }
 
+pub fn render_for_summary(input: &str) -> Result<String, DocError> {
+    let tokens = parse(input)?;
+    let mut out = String::with_capacity(input.len());
+    for token in tokens {
+        match token {
+            Token::Text(text) => {
+                let slice = &input[text.start..text.end];
+                push_text(&mut out, slice);
+            }
+            Token::Macro(mac) => {
+                if let Some(s) = match mac.ident.to_ascii_lowercase().as_str() {
+                    "apiref"
+                    | "jsref"
+                    | "compat"
+                    | "page"
+                    | "deprecated_header"
+                    | "previous"
+                    | "previousmenu"
+                    | "previousnext"
+                    | "previousmenunext"
+                    | "quicklinkswithsubpages" => None,
+                    "glossary" => mac
+                        .args
+                        .first()
+                        .and_then(|f| f.clone())
+                        .map(|arg| AnyArg::try_from(arg).unwrap().to_string()),
+                    _ => mac
+                        .args
+                        .first()
+                        .and_then(|f| f.clone())
+                        .map(|arg| format!("<code>{}</code>", AnyArg::try_from(arg).unwrap())),
+                } {
+                    out.push_str(&s)
+                }
+            }
+        }
+    }
+    Ok(out)
+}
+
 pub fn render(env: &RariEnv, input: &str) -> Result<Rendered, DocError> {
     let tokens = parse(input)?;
     render_tokens(env, tokens, input)
@@ -81,12 +121,7 @@ pub fn render_tokens(env: &RariEnv, tokens: Vec<Token>, input: &str) -> Result<R
         match token {
             Token::Text(text) => {
                 let slice = &input[text.start..text.end];
-                let mut last = 0;
-                for (i, _) in slice.match_indices("\\{{") {
-                    out.push_str(&slice[last..i]);
-                    last = i + 1;
-                }
-                out.push_str(&slice[last..])
+                push_text(&mut out, slice);
             }
             Token::Macro(mac) => {
                 let ident = &mac.ident;
@@ -116,3 +151,12 @@ pub fn render_tokens(env: &RariEnv, tokens: Vec<Token>, input: &str) -> Result<R
         sidebars,
     })
 }
+
+fn push_text(out: &mut String, slice: &str) {
+    let mut last = 0;
+    for (i, _) in slice.match_indices("\\{{") {
+        out.push_str(&slice[last..i]);
+        last = i + 1;
+    }
+    out.push_str(&slice[last..]);
+}
diff --git a/crates/rari-doc/src/templ/templs/glossarydisambiguation.rs b/crates/rari-doc/src/templ/templs/glossarydisambiguation.rs
@@ -0,0 +1,32 @@
+use rari_templ_func::rari_f;
+
+use crate::docs::page::PageLike;
+use crate::error::DocError;
+use crate::helpers::subpages::get_sub_pages;
+use crate::helpers::summary_hack::{get_hacky_summary_md, strip_paragraph_unckecked};
+
+#[rari_f]
+pub fn glossarydisambiguation() -> Result<String, DocError> {
+    let mut out = String::new();
+    let pages = get_sub_pages(
+        env.url,
+        Some(1),
+        crate::helpers::subpages::SubPagesSorter::Title,
+    )?;
+    out.push_str("<dl>");
+
+    for page in pages {
+        out.extend([
+            r#"<dt><a href=""#,
+            page.url(),
+            r#"">"#,
+            page.title(),
+            r#"</a></dt><dd>"#,
+            strip_paragraph_unckecked(get_hacky_summary_md(&page)?.as_str()),
+            r#"</dd>"#,
+        ]);
+    }
+    out.push_str("</dl>");
+
+    Ok(out)
+}
diff --git a/crates/rari-doc/src/templ/templs/links/http.rs b/crates/rari-doc/src/templ/templs/links/http.rs
@@ -27,7 +27,7 @@ pub fn http_header(
     no_code: Option<AnyArg>,
 ) -> Result<String, DocError> {
     let url = format!(
-        "/{}/docs/Web/HTTP/Header/{}",
+        "/{}/docs/Web/HTTP/Headers/{}",
         env.locale.as_url_str(),
         status
     );
@@ -42,7 +42,7 @@ pub fn http_method(
     no_code: Option<AnyArg>,
 ) -> Result<String, DocError> {
     let url = format!(
-        "/{}/docs/Web/HTTP/Method/{}",
+        "/{}/docs/Web/HTTP/Methods/{}",
         env.locale.as_url_str(),
         status
     );

diff --git a/crates/rari-doc/src/templ/templs/links/rfc.rs b/crates/rari-doc/src/templ/templs/links/rfc.rs
@@ -24,7 +24,7 @@ pub fn rfc(
         (Some(content), None) => (format!(": {content}"), Default::default()),
         (Some(content), Some(anchor)) => (
             format!(
-                ": {content}, {} {anchor}",
+                ", {} {anchor}: {content}",
                 l10n_json_data("Common", "section", env.locale)?
             ),
             format!("#section-{anchor}"),