refactor: update deno_doc, use prismjs, remove internal reference html generation logic (#26885)

cli/tools/doc.rs

@@ -21,6 +21,8 @@ use deno_core::error::AnyError;
 use deno_core::serde_json;
 use deno_doc as doc;
 use deno_doc::html::UrlResolveKind;
+use deno_doc::html::UsageComposer;
+use deno_doc::html::UsageComposerEntry;
 use deno_graph::source::NullFileSystem;
 use deno_graph::EsParser;
 use deno_graph::GraphKind;
@@ -35,6 +37,9 @@ use std::sync::Arc;
 
 const JSON_SCHEMA_VERSION: u8 = 1;
 
+const PRISM_CSS: &str = include_str!("./doc/prism.css");
+const PRISM_JS: &str = include_str!("./doc/prism.js");
+
 async fn generate_doc_nodes_for_builtin_types(
   doc_flags: DocFlags,
   parser: &dyn EsParser,
@@ -312,10 +317,6 @@ impl deno_doc::html::HrefResolver for DocResolver {
     None
   }
 
-  fn resolve_usage(&self, current_resolve: UrlResolveKind) -> Option<String> {
-    current_resolve.get_file().map(|file| file.path.to_string())
-  }
-
   fn resolve_source(&self, location: &deno_doc::Location) -> Option<String> {
     Some(location.filename.to_string())
   }
@@ -350,105 +351,30 @@ impl deno_doc::html::HrefResolver for DocResolver {
   }
 }
 
-struct DenoDocResolver(bool);
+struct DocComposer;
 
-impl deno_doc::html::HrefResolver for DenoDocResolver {
-  fn resolve_path(
+impl UsageComposer for DocComposer {
+  fn is_single_mode(&self) -> bool {
+    true
+  }
+
+  fn compose(
     &self,
-    current: UrlResolveKind,
-    target: UrlResolveKind,
-  ) -> String {
-    let path = deno_doc::html::href_path_resolve(current, target);
-    if self.0 {
-      if let Some(path) = path
-        .strip_suffix("index.html")
-        .or_else(|| path.strip_suffix(".html"))
-      {
-        return path.to_owned();
-      }
-    }
-
-    path
-  }
-
-  fn resolve_global_symbol(&self, _symbol: &[String]) -> Option<String> {
-    None
-  }
-
-  fn resolve_import_href(
-    &self,
-    _symbol: &[String],
-    _src: &str,
-  ) -> Option<String> {
-    None
-  }
-
-  fn resolve_usage(&self, _current_resolve: UrlResolveKind) -> Option<String> {
-    None
-  }
-
-  fn resolve_source(&self, _location: &deno_doc::Location) -> Option<String> {
-    None
-  }
-
-  fn resolve_external_jsdoc_module(
-    &self,
-    _module: &str,
-    _symbol: Option<&str>,
-  ) -> Option<(String, String)> {
-    None
-  }
-}
-
-struct NodeDocResolver(bool);
-
-impl deno_doc::html::HrefResolver for NodeDocResolver {
-  fn resolve_path(
-    &self,
-    current: UrlResolveKind,
-    target: UrlResolveKind,
-  ) -> String {
-    let path = deno_doc::html::href_path_resolve(current, target);
-    if self.0 {
-      if let Some(path) = path
-        .strip_suffix("index.html")
-        .or_else(|| path.strip_suffix(".html"))
-      {
-        return path.to_owned();
-      }
-    }
-
-    path
-  }
-
-  fn resolve_global_symbol(&self, _symbol: &[String]) -> Option<String> {
-    None
-  }
-
-  fn resolve_import_href(
-    &self,
-    _symbol: &[String],
-    _src: &str,
-  ) -> Option<String> {
-    None
-  }
-
-  fn resolve_usage(&self, current_resolve: UrlResolveKind) -> Option<String> {
+    current_resolve: UrlResolveKind,
+    usage_to_md: deno_doc::html::UsageToMd,
+  ) -> IndexMap<UsageComposerEntry, String> {
     current_resolve
       .get_file()
-      .map(|file| format!("node:{}", file.path))
-  }
-
-  fn resolve_source(&self, _location: &deno_doc::Location) -> Option<String> {
-    None
-  }
-
-  fn resolve_external_jsdoc_module(
-    &self,
-    _module: &str,
-    _symbol: Option<&str>,
-  ) -> Option<(String, String)> {
-    None
+      .map(|current_file| {
+        IndexMap::from([(
+          UsageComposerEntry {
+            name: "".to_string(),
+            icon: None,
+          },
+          usage_to_md(current_file.path.as_str(), None),
+        )])
+      })
+      .unwrap_or_default()
   }
 }
 
@@ -461,30 +387,10 @@ fn generate_docs_directory(
   let cwd = std::env::current_dir().context("Failed to get CWD")?;
   let output_dir_resolved = cwd.join(&html_options.output);
 
-  let internal_env = std::env::var("DENO_INTERNAL_HTML_DOCS").ok();
-
-  let href_resolver: Rc<dyn deno_doc::html::HrefResolver> = if internal_env
-    .as_ref()
-    .is_some_and(|internal_html_docs| internal_html_docs == "node")
-  {
-    Rc::new(NodeDocResolver(html_options.strip_trailing_html))
-  } else if internal_env
-    .as_ref()
-    .is_some_and(|internal_html_docs| internal_html_docs == "deno")
-    || deno_ns.is_empty()
-  {
-    Rc::new(DenoDocResolver(html_options.strip_trailing_html))
-  } else {
-    Rc::new(DocResolver {
-      deno_ns,
-      strip_trailing_html: html_options.strip_trailing_html,
-    })
-  };
-
   let category_docs =
     if let Some(category_docs_path) = &html_options.category_docs_path {
       let content = std::fs::read(category_docs_path)?;
-      Some(deno_core::serde_json::from_slice(&content)?)
+      Some(serde_json::from_slice(&content)?)
     } else {
       None
     };
@@ -493,7 +399,7 @@ fn generate_docs_directory(
     &html_options.symbol_redirect_map_path
   {
     let content = std::fs::read(symbol_redirect_map_path)?;
-    Some(deno_core::serde_json::from_slice(&content)?)
+    Some(serde_json::from_slice(&content)?)
   } else {
     None
   };
@@ -502,7 +408,7 @@ fn generate_docs_directory(
     &html_options.default_symbol_map_path
   {
     let content = std::fs::read(default_symbol_map_path)?;
-    Some(deno_core::serde_json::from_slice(&content)?)
+    Some(serde_json::from_slice(&content)?)
   } else {
     None
   };
@@ -511,17 +417,59 @@ fn generate_docs_directory(
     package_name: html_options.name.clone(),
     main_entrypoint: None,
     rewrite_map,
-    href_resolver,
-    usage_composer: None,
+    href_resolver: Rc::new(DocResolver {
+      deno_ns,
+      strip_trailing_html: html_options.strip_trailing_html,
+    }),
+    usage_composer: Rc::new(DocComposer),
     category_docs,
-    disable_search: internal_env.is_some(),
+    disable_search: false,
     symbol_redirect_map,
     default_symbol_map,
+    markdown_renderer: deno_doc::html::comrak::create_renderer(
+      None,
+      Some(Box::new(|ammonia| {
+        ammonia.add_allowed_classes(
+          "code",
+          &[
+            "language-ts",
+            "language-tsx",
+            "language-typescript",
+            "language-js",
+            "language-jsx",
+            "language-javascript",
+            "language-bash",
+            "language-shell",
+            "language-md",
+            "language-markdown",
+            "language-rs",
+            "language-rust",
+            "language-html",
+            "language-xml",
+            "language-css",
+            "language-json",
+            "language-regex",
+            "language-svg",
+          ],
+        );
+      })),
+      None,
+    ),
+    markdown_stripper: Rc::new(deno_doc::html::comrak::strip),
+    head_inject: Some(Rc::new(|root| {
+      format!(
+        r#"<link href="{root}{}" rel="stylesheet" /><link href="{root}prism.css" rel="stylesheet" /><script src="{root}prism.js"></script>"#,
+        deno_doc::html::comrak::COMRAK_STYLESHEET_FILENAME
+      )
+    })),
   };
 
-  let files = deno_doc::html::generate(options, doc_nodes_by_url)
+  let mut files = deno_doc::html::generate(options, doc_nodes_by_url)
     .context("Failed to generate HTML documentation")?;
 
+  files.insert("prism.js".to_string(), PRISM_JS.to_string());
+  files.insert("prism.css".to_string(), PRISM_CSS.to_string());
+
   let path = &output_dir_resolved;
   let _ = std::fs::remove_dir_all(path);
   std::fs::create_dir(path)