fix: various html doc gen fixes for reference generation (#601)

Author: crowlKats

build_css.ts

@@ -28,3 +28,15 @@ const pageFinal = transform({
   analyzeDependencies: false,
 });
 await Deno.writeFile("src/html/templates/pages/page.gen.css", pageFinal.code);
+
+const reset =
+  await $`deno run -A npm:tailwindcss@3.4.3 --input src/html/templates/pages/reset.css`
+    .bytes();
+const resetFinal = transform({
+  filename: "./page.css",
+  code: reset,
+  minify: true,
+  targets: browserslistToTargets(browsers),
+  analyzeDependencies: false,
+});
+await Deno.writeFile("src/html/templates/pages/reset.gen.css", resetFinal.code);

examples/ddoc/main.rs

@@ -226,6 +226,10 @@ fn generate_docs_directory(
     usage_composer: None,
     rewrite_map: Some(index_map),
     composable_output: false,
+    category_docs: None,
+    disable_search: false,
+    symbol_redirect_map: None,
+    default_symbol_map: None,
   };
   let html = deno_doc::html::generate(options, doc_nodes_by_url)?;
 

src/class.rs

@@ -128,6 +128,7 @@ impl From<ClassPropertyDef> for DocNode {
   fn from(def: ClassPropertyDef) -> DocNode {
     DocNode::variable(
       def.name,
+      false,
       def.location,
       DeclarationKind::Private,
       def.js_doc,
@@ -181,6 +182,7 @@ impl From<ClassMethodDef> for DocNode {
   fn from(def: ClassMethodDef) -> DocNode {
     DocNode::function(
       def.name,
+      false,
       def.location,
       DeclarationKind::Private,
       def.js_doc,

src/html/comrak_adapters.rs

@@ -232,66 +232,132 @@ pub struct ToCEntry {
   pub anchor: String,
 }
 
-#[derive(Default, Clone)]
+#[derive(Debug)]
+pub struct ToCGroup {
+  pub toc: Vec<ToCEntry>,
+  pub id: Option<String>,
+}
+
+#[derive(Clone)]
 pub struct HeadingToCAdapter {
-  toc: Arc<Mutex<Vec<ToCEntry>>>,
+  toc_groups: Arc<Mutex<Vec<ToCGroup>>>,
   anchorizer: Arc<Mutex<comrak::html::Anchorizer>>,
   offset: Arc<Mutex<u8>>,
 }
 
+impl Default for HeadingToCAdapter {
+  fn default() -> Self {
+    Self {
+      toc_groups: Arc::new(Mutex::new(vec![ToCGroup {
+        toc: vec![],
+        id: None,
+      }])),
+      anchorizer: Arc::new(Mutex::new(Default::default())),
+      offset: Arc::new(Mutex::new(0)),
+    }
+  }
+}
+
 impl HeadingToCAdapter {
-  pub fn add_entry(&self, level: u8, content: String) -> String {
-    let mut lock = self.toc.lock().unwrap();
+  pub fn create_group(&self, id: String) {
+    let mut toc_groups = self.toc_groups.lock().unwrap();
+
+    toc_groups.push(ToCGroup {
+      toc: vec![],
+      id: Some(id),
+    });
+  }
+
+  pub fn anchorize(&self, content: String) -> String {
     let mut anchorizer = self.anchorizer.lock().unwrap();
+    anchorizer.anchorize(content.clone())
+  }
+
+  pub fn add_entry(
+    &self,
+    level: u8,
+    content: String,
+    anchor: String,
+  ) -> String {
+    let mut toc_groups = self.toc_groups.lock().unwrap();
     let mut offset = self.offset.lock().unwrap();
 
-    let anchor = anchorizer.anchorize(content.clone());
     *offset = level;
 
-    lock.push(ToCEntry {
-      level,
-      content,
-      anchor: anchor.clone(),
-    });
+    let toc_group = toc_groups.last_mut().unwrap();
+
+    if toc_group
+      .toc
+      .last()
+      .map_or(true, |toc| toc.content != content)
+    {
+      toc_group.toc.push(ToCEntry {
+        level,
+        content,
+        anchor: anchor.clone(),
+      });
+    }
 
     anchor
   }
 
-  pub fn into_toc(self) -> Vec<ToCEntry> {
-    Arc::into_inner(self.toc).unwrap().into_inner().unwrap()
+  pub fn into_toc(self) -> Vec<ToCGroup> {
+    Arc::into_inner(self.toc_groups)
+      .unwrap()
+      .into_inner()
+      .unwrap()
   }
 
   pub fn render(self) -> Option<String> {
-    let toc = Arc::into_inner(self.toc).unwrap().into_inner().unwrap();
+    let toc_groups = Arc::into_inner(self.toc_groups)
+      .unwrap()
+      .into_inner()
+      .unwrap();
 
-    if toc.is_empty() {
+    if toc_groups.is_empty()
+      || (toc_groups.len() == 1 && toc_groups[0].toc.is_empty())
+    {
       return None;
     }
 
-    let mut toc_content = vec![String::from(r#"<ul>"#)];
-
-    let mut current_level = 1;
+    let mut toc_content = vec![];
 
-    for entry in toc {
-      match current_level.cmp(&entry.level) {
-        Ordering::Equal => {}
-        Ordering::Less => {
-          toc_content.push(r#"<li><ul>"#.to_string());
-          current_level = entry.level;
-        }
-        Ordering::Greater => {
-          toc_content.push("</ul></li>".to_string());
-          current_level = entry.level;
-        }
+    for toc_group in toc_groups {
+      if toc_group.toc.is_empty() {
+        continue;
       }
 
       toc_content.push(format!(
-        r##"<li><a href="#{}" title="{}">{}</a></li>"##,
-        entry.anchor, entry.content, entry.content
+        r#"<ul{}>"#,
+        toc_group
+          .id
+          .map(|id| format!(r#" id="{id}""#))
+          .unwrap_or_default(),
       ));
-    }
 
-    toc_content.push(String::from("</ul>"));
+      let mut current_level = 1;
+
+      for entry in toc_group.toc {
+        match current_level.cmp(&entry.level) {
+          Ordering::Equal => {}
+          Ordering::Less => {
+            toc_content.push(r#"<li><ul>"#.to_string());
+            current_level = entry.level;
+          }
+          Ordering::Greater => {
+            toc_content.push("</ul></li>".to_string());
+            current_level = entry.level;
+          }
+        }
+
+        toc_content.push(format!(
+          r##"<li><a href="#{}" title="{}">{}</a></li>"##,
+          entry.anchor, entry.content, entry.content
+        ));
+      }
+
+      toc_content.push(String::from("</ul>"));
+    }
 
     Some(toc_content.join(""))
   }
@@ -310,8 +376,8 @@ impl HeadingAdapter for HeadingToCAdapter {
     let anchor = anchorizer.anchorize(heading.content.clone());
     writeln!(output, r#"<h{} id="{anchor}">"#, heading.level)?;
 
-    let mut lock = self.toc.lock().unwrap();
-    lock.push(ToCEntry {
+    let mut lock = self.toc_groups.lock().unwrap();
+    lock.last_mut().unwrap().toc.push(ToCEntry {
       level: heading.level + *offset,
       content: heading.content.clone(),
       anchor,

src/html/jsdoc.rs

@@ -62,7 +62,7 @@ fn parse_links<'a>(md: &'a str, ctx: &RenderContext) -> Cow<'a, str> {
             .iter()
             .any(|node| node.get_qualified_name() == symbol_match.as_str())
           {
-            link = ctx.ctx.href_resolver.resolve_path(
+            link = ctx.ctx.resolve_path(
               ctx.get_current_resolve(),
               UrlResolveKind::Symbol {
                 file: short_path,
@@ -78,7 +78,7 @@ fn parse_links<'a>(md: &'a str, ctx: &RenderContext) -> Cow<'a, str> {
             }
           }
         } else {
-          link = ctx.ctx.href_resolver.resolve_path(
+          link = ctx.ctx.resolve_path(
             ctx.get_current_resolve(),
             short_path.as_resolve_kind(),
           );
@@ -517,9 +517,9 @@ pub(crate) fn jsdoc_examples(
 
 #[derive(Debug, Serialize, Clone)]
 pub struct ExampleCtx {
-  anchor: AnchorCtx,
-  id: String,
-  markdown_title: String,
+  pub anchor: AnchorCtx,
+  pub id: String,
+  pub markdown_title: String,
   markdown_body: String,
 }
 
@@ -684,6 +684,10 @@ mod test {
         usage_composer: None,
         rewrite_map: None,
         composable_output: false,
+        category_docs: None,
+        disable_search: false,
+        symbol_redirect_map: None,
+        default_symbol_map: None,
       },
       Default::default(),
       Default::default(),
@@ -693,6 +697,7 @@ mod test {
           vec![
             DocNode::interface(
               "foo".to_string(),
+              false,
               Location::default(),
               DeclarationKind::Export,
               JsDoc::default(),
@@ -709,6 +714,7 @@ mod test {
             ),
             DocNode::interface(
               "bar".to_string(),
+              false,
               Location::default(),
               DeclarationKind::Export,
               JsDoc::default(),
@@ -729,6 +735,7 @@ mod test {
           ModuleSpecifier::parse("file:///b.ts").unwrap(),
           vec![DocNode::interface(
             "baz".to_string(),
+            false,
             Location::default(),
             DeclarationKind::Export,
             JsDoc::default(),
@@ -806,11 +813,11 @@ mod test {
 
       assert_eq!(
         parse_links("foo {@link [b.ts]} bar", &render_ctx),
-        "foo [b.ts](../../.././/b.ts/~/index.html) bar"
+        "foo [b.ts](../../.././/b.ts/index.html) bar"
       );
       assert_eq!(
         parse_links("foo {@linkcode [b.ts]} bar", &render_ctx),
-        "foo [`b.ts`](../../.././/b.ts/~/index.html) bar"
+        "foo [`b.ts`](../../.././/b.ts/index.html) bar"
       );
 
       assert_eq!(
@@ -834,6 +841,10 @@ mod test {
         usage_composer: None,
         rewrite_map: None,
         composable_output: false,
+        category_docs: None,
+        disable_search: false,
+        symbol_redirect_map: None,
+        default_symbol_map: None,
       },
       Default::default(),
       Default::default(),