feat(apiref): heavy lifting

Author: fiji-flo

Diff for: crates/rari-doc/src/cached_readers.rs

@@ -14,7 +14,7 @@ use crate::docs::curriculum::{CurriculumIndexEntry, CurriculumPage};
 use crate::docs::page::{Page, PageLike};
 use crate::error::DocError;
 use crate::html::sidebar::{MetaSidebar, Sidebar};
-use crate::sidebars::jsref;
+use crate::sidebars::{apiref, jsref};
 use crate::utils::{root_for_locale, split_fm};
 use crate::walker::{read_docs_parallel, walk_builder};
 

Diff for: crates/rari-doc/src/docs/build.rs

@@ -1,5 +1,6 @@
 use std::borrow::Cow;
 
+use itertools::Itertools;
 use rari_types::fm_types::PageType;
 use rari_types::globals::{base_url, content_branch, git_history, popularities};
 use rari_types::locale::Locale;
@@ -16,7 +17,7 @@ use super::json::{
     BuiltDocy, Compat, JsonBlogPost, JsonBlogPostDoc, JsonCurriculum, JsonDoADoc, JsonDoc, Prose,
     Section, Source, SpecificationSection, TocEntry,
 };
-use super::page::PageLike;
+use super::page::{Page, PageLike};
 use super::parents::parents;
 use super::title::{page_title, transform_title};
 use crate::baseline::get_baseline;
@@ -25,9 +26,12 @@ use crate::html::bubble_up::bubble_up_curriculum_page;
 use crate::html::modifier::add_missing_ids;
 use crate::html::rewriter::{post_process_html, post_process_inline_sidebar};
 use crate::html::sections::{split_sections, BuildSection, BuildSectionType, Splitted};
-use crate::html::sidebar::{build_sidebars, expand_details_and_mark_current_for_inline_sidebar};
+use crate::html::sidebar::{
+    self, build_sidebars, expand_details_and_mark_current_for_inline_sidebar, postprocess_sidebar,
+};
+use crate::sidebars;
 use crate::specs::extract_specifications;
-use crate::templ::render::{decode_ref, render};
+use crate::templ::render::{decode_ref, render, Rendered};
 
 impl<'a> From<BuildSection<'a>> for Section {
     fn from(value: BuildSection) -> Self {
@@ -133,33 +137,47 @@ pub fn make_toc(sections: &[BuildSection], with_h3: bool) -> Vec<TocEntry> {
         .collect()
 }
 
-pub fn build_content<T: PageLike>(doc: &T) -> Result<PageContent, DocError> {
-    let (ks_rendered_doc, templs) = if let Some(rari_env) = &doc.rari_env() {
-        let (out, templs) = render(rari_env, doc.content())?;
-        (Cow::Owned(out), templs)
+pub fn build_content<T: PageLike>(page: &T) -> Result<PageContent, DocError> {
+    let (ks_rendered_doc, templs, sidebars) = if let Some(rari_env) = &page.rari_env() {
+        let Rendered {
+            content,
+            templs,
+            sidebars,
+        } = render(rari_env, page.content())?;
+        (Cow::Owned(content), templs, sidebars)
     } else {
-        (Cow::Borrowed(doc.content()), vec![])
+        (Cow::Borrowed(page.content()), vec![], vec![])
     };
-    let encoded_html = render_md_to_html(&ks_rendered_doc, doc.locale())?;
+    let encoded_html = render_md_to_html(&ks_rendered_doc, page.locale())?;
     let html = decode_ref(&encoded_html, &templs)?;
-    let post_processed_html = post_process_html(&html, doc, false)?;
+    let post_processed_html = post_process_html(&html, page, false)?;
     let mut fragment = Html::parse_fragment(&post_processed_html);
-    if doc.page_type() == PageType::Curriculum {
+    if page.page_type() == PageType::Curriculum {
         bubble_up_curriculum_page(&mut fragment)?;
     }
     add_missing_ids(&mut fragment)?;
-    expand_details_and_mark_current_for_inline_sidebar(&mut fragment, doc.url())?;
+    expand_details_and_mark_current_for_inline_sidebar(&mut fragment, page.url())?;
     let Splitted {
         sections,
         summary,
         sidebar,
     } = split_sections(&fragment).expect("DOOM");
-    let sidebar = if let Some(sidebar) = sidebar {
-        Some(post_process_inline_sidebar(&sidebar)?)
-    } else {
+
+    // TODO cleanup
+    let mut sidebars = sidebars
+        .iter()
+        .map(|s| postprocess_sidebar(s, page))
+        .collect::<Vec<_>>();
+    if let Some(sidebar) = &sidebar {
+        sidebars.push(post_process_inline_sidebar(sidebar));
+    }
+
+    let sidebar = if sidebars.is_empty() {
         None
+    } else {
+        Some(sidebars.into_iter().collect::<Result<String, _>>()?)
     };
-    let toc = make_toc(&sections, matches!(doc.page_type(), PageType::Curriculum));
+    let toc = make_toc(&sections, matches!(page.page_type(), PageType::Curriculum));
     let body = sections.into_iter().map(Into::into).collect();
     Ok(PageContent {
         body,

Diff for: crates/rari-doc/src/error.rs

@@ -91,6 +91,8 @@ pub enum DocError {
     MissingCSSL10n,
     #[error("At rule was empty")]
     MustHaveAtRule,
+    #[error("Invalid slug for templ/sidebar: {0}")]
+    InvalidSlugForX(String),
 }
 
 impl<T> From<PoisonError<T>> for DocError {

Diff for: crates/rari-doc/src/helpers/json_data.rs

@@ -0,0 +1,51 @@
+use std::collections::HashMap;
+use std::fs;
+
+use once_cell::sync::OnceCell;
+use rari_types::globals::content_root;
+use serde::Deserialize;
+
+#[derive(Debug, Default, Clone, Deserialize)]
+pub struct InterfaceData {
+    pub inh: String,
+}
+
+pub static JSON_DATA_INTERFACE: OnceCell<HashMap<String, InterfaceData>> = OnceCell::new();
+
+pub fn json_data_interface() -> &'static HashMap<String, InterfaceData> {
+    JSON_DATA_INTERFACE.get_or_init(|| {
+        let f = content_root().join("jsondata/InterfaceData.json");
+        let json_str = fs::read_to_string(f).expect("unable to read interface data json");
+        let mut interface_data: Vec<HashMap<String, InterfaceData>> =
+            serde_json::from_str(&json_str).expect("unable to parse interface data json");
+        interface_data.pop().unwrap_or_default()
+    })
+}
+
+#[derive(Debug, Default, Clone, Deserialize)]
+pub struct GroupData {
+    #[serde(default)]
+    pub overview: Vec<String>,
+    #[serde(default)]
+    pub guides: Vec<String>,
+    #[serde(default)]
+    pub interfaces: Vec<String>,
+    #[serde(default)]
+    pub methods: Vec<String>,
+    #[serde(default)]
+    pub properties: Vec<String>,
+    #[serde(default)]
+    pub events: Vec<String>,
+}
+
+pub static JSON_DATA_GROUP: OnceCell<HashMap<String, GroupData>> = OnceCell::new();
+
+pub fn json_data_group() -> &'static HashMap<String, GroupData> {
+    JSON_DATA_GROUP.get_or_init(|| {
+        let f = content_root().join("jsondata/GroupData.json");
+        let json_str = fs::read_to_string(f).expect("unable to read interface data json");
+        let mut interface_data: Vec<HashMap<String, GroupData>> =
+            serde_json::from_str(&json_str).expect("unable to parse group data json");
+        interface_data.pop().unwrap_or_default()
+    })
+}

Diff for: crates/rari-doc/src/helpers/mod.rs

@@ -1,2 +1,3 @@
 pub mod css_info;
+pub mod json_data;
 pub mod subpages;

Diff for: crates/rari-doc/src/html/sidebar.rs

@@ -72,11 +72,14 @@ fn expand_details_and_mark_current(html: &mut Html, a_selector: Selector) -> Res
     Ok(())
 }
 
-fn postprocess_sidebar(ks_rendered_sidebar: &str, doc: &Doc) -> Result<String, DocError> {
+pub fn postprocess_sidebar<T: PageLike>(
+    ks_rendered_sidebar: &str,
+    page: &T,
+) -> Result<String, DocError> {
     let mut fragment = Html::parse_fragment(ks_rendered_sidebar);
 
-    expand_details_and_mark_current_for_sidebar(&mut fragment, &doc.meta.url)?;
-    let post_processed_html = post_process_html(&fragment.html(), doc, true)?;
+    expand_details_and_mark_current_for_sidebar(&mut fragment, page.url())?;
+    let post_processed_html = post_process_html(&fragment.html(), page, true)?;
     Ok::<_, DocError>(post_processed_html)
 }
 

Diff for: crates/rari-doc/src/sidebars/apiref.rs

@@ -0,0 +1,134 @@
+use rari_l10n::l10n_json_data;
+use rari_types::fm_types::PageType;
+use rari_types::locale::Locale;
+use tracing::error;
+
+use crate::docs::doc::Doc;
+use crate::docs::page::{Page, PageLike};
+use crate::error::DocError;
+use crate::helpers::json_data::{json_data_group, json_data_interface};
+use crate::helpers::subpages::get_sub_pages;
+use crate::html::sidebar::{MetaSidebar, SidebarEntry, SidebarMetaEntry, SidebarMetaEntryContent};
+
+pub fn sidebar(slug: &str, group: Option<&str>, locale: Locale) -> Result<MetaSidebar, DocError> {
+    let static_properties_label = l10n_json_data("Common", "Static_properties", locale)?;
+    let instance_properties_label = l10n_json_data("Common", "Instance_properties", locale)?;
+    let static_methods_label = l10n_json_data("Common", "Static_methods", locale)?;
+    let instance_methods_label = l10n_json_data("Common", "Instance_methods", locale)?;
+    let constructor_label = l10n_json_data("Common", "Constructor", locale)?;
+    let inheritance_label = l10n_json_data("Common", "Inheritance", locale)?;
+    let implemented_by_label = l10n_json_data("Common", "Implemented_by", locale)?;
+    let related_labl = l10n_json_data("Common", "Related_pages_wo_group", locale)?;
+    let translate_label = l10n_json_data("Common", "[Translate]", locale)?;
+    let title_label = l10n_json_data("Common", "TranslationCTA", locale)?;
+    let events_label = l10n_json_data("Common", "Events", locale)?;
+
+    let main_if = slug
+        .strip_prefix("Web/API/")
+        .map(|s| &s[..s.find('/').unwrap_or(s.len())])
+        .ok_or_else(|| DocError::InvalidSlugForX(slug.to_string()))?;
+    if !main_if
+        .chars()
+        .next()
+        .map(|c| c.is_uppercase())
+        .unwrap_or_default()
+    {
+        error!("Slugs for Web/API/* must start with uppercase letter got {slug}");
+        return Err(DocError::InvalidSlugForX(slug.to_string()));
+    }
+
+    let web_api_data = json_data_interface();
+    let web_api_groups = group.and_then(|group| json_data_group().get(group));
+
+    // TODO: custom sorting?
+    let main_if_pages = get_sub_pages(
+        &format!("/en-US/docs/Web/API/{}", main_if),
+        Some(1),
+        Default::default(),
+    )?;
+
+    let related = if let Some(iter) = web_api_groups.map(|groups| {
+        groups
+            .interfaces
+            .iter()
+            .chain(groups.methods.iter())
+            .chain(groups.properties.iter())
+            .filter(|s| s.as_str() != main_if)
+    }) {
+        let mut related = iter.collect::<Vec<_>>();
+        related.sort();
+        related
+    } else {
+        Default::default()
+    };
+
+    let mut static_properties = vec![];
+    let mut instance_properties = vec![];
+    let mut static_methods = vec![];
+    let mut instance_methods = vec![];
+    let mut constructors = vec![];
+    let mut events = vec![];
+
+    for page in main_if_pages {
+        let v = match page.page_type() {
+            PageType::WebApiStaticProperty => &mut static_properties,
+            PageType::WebApiInstanceProperty => &mut instance_properties,
+            PageType::WebApiStaticMethod => &mut static_methods,
+            PageType::WebApiInstanceMethod => &mut instance_methods,
+            PageType::WebApiConstructor => &mut constructors,
+            PageType::WebApiEvent => &mut events,
+            _ => continue,
+        };
+        v.push(page);
+    }
+
+    let mut inherited = vec![];
+
+    let mut interface = main_if;
+    while let Some(inherited_data) = web_api_data.get(interface).map(|data| data.inh.as_str()) {
+        inherited.push(inherited_data);
+        interface = inherited_data;
+    }
+
+    let mut entries = vec![];
+
+    if let Some([ref overview]) = web_api_groups.map(|group| group.overview.as_slice()) {
+        entries.push(SidebarMetaEntry {
+            section: true,
+            content: SidebarMetaEntryContent::Page(Doc::page_from_slug(
+                &format!("Web/API/{}", overview.replace(' ', "_")),
+                locale,
+            )?),
+            ..Default::default()
+        });
+    }
+    entries.push(SidebarMetaEntry {
+        section: true,
+        content: SidebarMetaEntryContent::Page(Doc::page_from_slug(
+            &format!("Web/API/{main_if}"),
+            locale,
+        )?),
+        ..Default::default()
+    });
+
+    Ok(MetaSidebar { entries })
+}
+
+fn api_page_title(page: &Page) -> &str {
+    if let Some(short_title) = page.short_title() {
+        return short_title;
+    }
+    let title = page.title();
+    let title = &title[title.rfind('.').unwrap_or(0)..];
+    if matches!(page.page_type(), PageType::WebApiEvent) {
+        let title = page.slug();
+        let title = &title[title.rfind('/').unwrap_or(0)..];
+        if let Some(title) = title.strip_suffix("_event") {
+            title
+        } else {
+            title
+        }
+    } else {
+        title
+    }
+}

Diff for: crates/rari-doc/src/sidebars/mod.rs

@@ -1 +1,2 @@
+pub mod apiref;
 pub mod jsref;

Diff for: crates/rari-doc/src/templ/macros/apiref.rs

@@ -0,0 +1,9 @@
+use rari_templ_func::rari_f;
+
+use crate::error::DocError;
+use crate::sidebars::apiref;
+
+#[rari_f]
+pub fn apiref(group: Option<String>) -> Result<String, DocError> {
+    apiref::sidebar(env.slug, group.as_deref(), env.locale)?.render(env.locale)
+}

Diff for: crates/rari-doc/src/templ/macros/compat.rs

@@ -16,15 +16,17 @@ mod test {
     use rari_types::RariEnv;
 
     use crate::error::DocError;
-    use crate::templ::render::{decode_ref, render};
+    use crate::templ::render::{decode_ref, render, Rendered};
 
     #[test]
     fn test_compat_none() -> Result<(), DocError> {
         let env = RariEnv {
             ..Default::default()
         };
-        let (out, templs) = render(&env, r#"{{ compat }}"#)?;
-        let out = decode_ref(&out, &templs)?;
+        let Rendered {
+            content, templs, ..
+        } = render(&env, r#"{{ compat }}"#)?;
+        let out = decode_ref(&content, &templs)?;
         assert_eq!(out, r#""#);
         Ok(())
     }
@@ -38,8 +40,10 @@ mod test {
         let exp = r#"<div class="bc-data" data-query="javascript.builtins.Array.concat" data-depth="1" data-multiple="false">
 If you're able to see this, something went wrong on this page.
 </div>"#;
-        let (out, templs) = render(&env, r#"{{ compat }}"#)?;
-        let out = decode_ref(&out, &templs)?;
+        let Rendered {
+            content, templs, ..
+        } = render(&env, r#"{{ compat }}"#)?;
+        let out = decode_ref(&content, &templs)?;
         assert_eq!(out, exp);
         Ok(())
     }
@@ -59,8 +63,10 @@ If you're able to see this, something went wrong on this page.
 <div class="bc-data" data-query="javascript.builtins.Array.filter" data-depth="1" data-multiple="true">
 If you're able to see this, something went wrong on this page.
 </div>"#;
-        let (out, templs) = render(&env, r#"{{ compat }}"#)?;
-        let out = decode_ref(&out, &templs)?;
+        let Rendered {
+            content, templs, ..
+        } = render(&env, r#"{{ compat }}"#)?;
+        let out = decode_ref(&content, &templs)?;
         assert_eq!(out, exp);
         Ok(())
     }

Diff for: crates/rari-doc/src/templ/macros/links.rs

@@ -114,15 +114,17 @@ pub fn link_internal(
 mod test {
 
     use crate::error::DocError;
-    use crate::templ::render::{decode_ref, render};
+    use crate::templ::render::{decode_ref, render, Rendered};
 
     #[test]
     fn test_link() -> Result<(), DocError> {
         let env = rari_types::RariEnv {
             ..Default::default()
         };
-        let (out, templs) = render(&env, r#"{{ link("/en-US/docs/basic") }}"#)?;
-        let out = decode_ref(&out, &templs)?;
+        let Rendered {
+            content, templs, ..
+        } = render(&env, r#"{{ link("/en-US/docs/basic") }}"#)?;
+        let out = decode_ref(&content, &templs)?;
         assert_eq!(out, r#"<a href="/en-US/docs/Basic">The Basic Page</a>"#);
         Ok(())
     }