Handle Math_span and Math_block constructs

Author: giltho

.gitignore

@@ -33,3 +33,6 @@ ocaml-re/
 result/
 tyxml/
 uutf/
+
+# Mac things
+.DS_Store

.ocamlformat

@@ -1,2 +1,2 @@
 module-item-spacing=preserve
-version=0.21.0
+version=0.24.1

odoc.opam

@@ -25,7 +25,7 @@ delimited with `(** ... *)`, and outputs HTML.
 """
 
 depends: [
-  "odoc-parser" {>= "1.0.0"}
+  "odoc-parser" {>= "2.0.0"}
   "astring"
   "cmdliner" {>= "1.0.0"}
   "cppo" {build & >= "1.1.0"}

src/document/comment.ml

@@ -129,6 +129,7 @@ let leaf_inline_element : Comment.leaf_inline_element -> Inline.one = function
   | `Space -> inline @@ Text " "
   | `Word s -> inline @@ Text s
   | `Code_span s -> inline @@ Source (source_of_code s)
+  | `Math_span s -> inline @@ Math s
   | `Raw_markup (target, s) -> inline @@ Raw_markup (target, s)
 
 let rec non_link_inline_element : Comment.non_link_inline_element -> Inline.one
@@ -202,6 +203,7 @@ let rec nestable_block_element : Comment.nestable_block_element -> Block.one =
       in
       block
       @@ Source (lang_tag, source_of_code (Odoc_model.Location_.value code))
+  | `Math_block s -> block @@ Math s
   | `Verbatim s -> block @@ Verbatim s
   | `Modules ms -> module_references ms
   | `List (kind, items) ->

src/document/doctree.ml

@@ -282,3 +282,77 @@ end = struct
       labels page
     |> snd
 end
+
+module Math : sig
+  val has_math_elements : Page.t -> bool
+end = struct
+  let rec items x = List.exists item x
+
+  and item : Item.t -> bool = function
+    | Text x -> block x
+    | Heading x -> heading x
+    | Declaration { content = x; doc; _ } -> documentedsrc x || block doc
+    | Include { content = x; doc; _ } -> include_ x || block doc
+
+  and documentedsrc : DocumentedSrc.t -> bool =
+   fun x ->
+    let documentedsrc_ : DocumentedSrc.one -> bool = function
+      | Code _ -> false
+      | Documented { code = x; doc; _ } -> inline x || block doc
+      | Nested { code = x; doc; _ } -> documentedsrc x || block doc
+      | Subpage x -> subpage x
+      | Alternative x -> alternative x
+    in
+    List.exists documentedsrc_ x
+
+  and subpage : Subpage.t -> bool = fun x -> page x.content
+
+  and page : Page.t -> bool = fun x -> items x.items
+
+  and alternative : Alternative.t -> bool = function
+    | Expansion x -> documentedsrc x.expansion
+
+  and include_ : Include.t -> bool = fun x -> items x.content
+
+  and block : Block.t -> bool =
+   fun x ->
+    let block_ : Block.one -> bool =
+     fun x ->
+      match x.desc with
+      | Inline x -> inline x
+      | Paragraph x -> inline x
+      | List (_, x) -> List.exists block x
+      | Description x -> description x
+      | Math _ -> true
+      | Source _ | Verbatim _ | Raw_markup _ -> false
+    in
+    List.exists block_ x
+
+  and heading : Heading.t -> bool = fun x -> inline x.title
+
+  and inline : Inline.t -> bool =
+   fun x ->
+    let inline_ : Inline.one -> bool =
+     fun x ->
+      match x.desc with
+      | Styled (_, x) -> inline x
+      | Link (_, x) -> inline x
+      | InternalLink x -> internallink x
+      | Math _ -> true
+      | Text _ | Entity _ | Linebreak | Source _ | Raw_markup _ -> false
+    in
+    List.exists inline_ x
+
+  and internallink : InternalLink.t -> bool = function
+    | Resolved (_, x) -> inline x
+    | Unresolved x -> inline x
+
+  and description : Description.t -> bool =
+   fun x ->
+    let description_ : Description.one -> bool =
+     fun x -> inline x.key || block x.definition
+    in
+    List.exists description_ x
+
+  let has_math_elements = page
+end

src/document/types.ml

@@ -30,6 +30,11 @@ and Source : sig
 end =
   Source
 
+and Math : sig
+  type t = string
+end =
+  Math
+
 and Inline : sig
   type entity = string
 
@@ -47,6 +52,7 @@ and Inline : sig
     | Link of href * t
     | InternalLink of InternalLink.t
     | Source of Source.t
+    | Math of Math.t
     | Raw_markup of Raw_markup.t
 end =
   Inline
@@ -76,6 +82,7 @@ and Block : sig
     | List of list_type * t list
     | Description of Description.t
     | Source of lang_tag * Source.t
+    | Math of Math.t
     | Verbatim of string
     | Raw_markup of Raw_markup.t
 

src/document/utils.ml

@@ -39,6 +39,7 @@ and compute_length_inline (t : Types.Inline.t) : int =
     | InternalLink (Unresolved t) ->
         acc + compute_length_inline t
     | Source s -> acc + compute_length_source s
+    | Math _ -> assert false
     | Raw_markup _ -> assert false
     (* TODO *)
   in

src/html/generator.ml

@@ -42,6 +42,12 @@ let mk_anchor anchor =
 
 let class_ (l : Class.t) = if l = [] then [] else [ Html.a_class l ]
 
+let inline_math (s : Math.t) =
+  Html.code ~a:[ Html.a_class [ "odoc-katex-math" ] ] [ Html.txt s ]
+
+let block_math (s : Math.t) =
+  Html.pre ~a:[ Html.a_class [ "odoc-katex-math"; "display" ] ] [ Html.txt s ]
+
 and raw_markup (t : Raw_markup.t) =
   let target, content = t in
   match Astring.String.Ascii.lowercase target with
@@ -121,6 +127,7 @@ and inline ~config ?(emph_level = 0) ~resolve (l : Inline.t) :
         [ Html.a ~a:(Html.a_href href :: a) content ]
     | InternalLink c -> internallink ~config ~emph_level ~resolve ~a c
     | Source c -> source (inline ~config ~emph_level ~resolve) ~a c
+    | Math s -> [ inline_math s ]
     | Raw_markup r -> raw_markup r
   in
   Utils.list_concat_map ~f:one l
@@ -142,6 +149,7 @@ and inline_nolink ?(emph_level = 0) (l : Inline.t) :
     | Link (_, c) -> inline_nolink ~emph_level c
     | InternalLink c -> internallink_nolink ~emph_level ~a c
     | Source c -> source (inline_nolink ~emph_level) ~a c
+    | Math s -> [ inline_math s ]
     | Raw_markup r -> raw_markup r
   in
   Utils.list_concat_map ~f:one l
@@ -196,6 +204,7 @@ let rec block ~config ~resolve (l : Block.t) : flow Html.elt list =
     | Source (lang_tag, c) ->
         let extra_class = [ "language-" ^ lang_tag ] in
         mk_block ~extra_class Html.pre (source (inline ~config ~resolve) c)
+    | Math s -> mk_block Html.div [ block_math s ]
   in
   Utils.list_concat_map l ~f:one
 
@@ -389,10 +398,11 @@ module Page = struct
     in
     let resolve = Link.Current url in
     let i = Doctree.Shift.compute ~on_sub i in
+    let uses_katex = Doctree.Math.has_math_elements p in
     let toc = Toc.gen_toc ~config ~resolve ~path:url i in
     let header = items ~config ~resolve header in
     let content = (items ~config ~resolve i :> any Html.elt list) in
-    Tree.make ~config ~header ~toc ~url title content subpages
+    Tree.make ~config ~header ~toc ~url ~uses_katex title content subpages
 end
 
 let render ~config page = Page.page ~config page

src/html/tree.ml

@@ -30,7 +30,7 @@ let html_of_toc toc =
   | [] -> []
   | _ -> [ Html.nav ~a:[ Html.a_class [ "odoc-toc" ] ] [ sections toc ] ]
 
-let page_creator ~config ~url name header toc content =
+let page_creator ~config ~url ~uses_katex name header toc content =
   let theme_uri = Config.theme_uri config in
   let support_uri = Config.support_uri config in
   let path = Link.Path.for_printing url in
@@ -51,9 +51,7 @@ let page_creator ~config ~url name header toc content =
 
     let odoc_css_uri = file_uri theme_uri "odoc.css" in
     let highlight_js_uri = file_uri support_uri "highlight.pack.js" in
-
-    Html.head
-      (Html.title (Html.txt title_string))
+    let default_meta_elements =
       [
         Html.link ~rel:[ `Stylesheet ] ~href:odoc_css_uri ();
         Html.meta ~a:[ Html.a_charset "utf-8" ] ();
@@ -70,6 +68,35 @@ let page_creator ~config ~url name header toc content =
         Html.script ~a:[ Html.a_src highlight_js_uri ] (Html.txt "");
         Html.script (Html.txt "hljs.initHighlightingOnLoad();");
       ]
+    in
+    let meta_elements =
+      if uses_katex then
+        let katex_css_uri = file_uri theme_uri "katex.min.css" in
+        let katex_js_uri = file_uri support_uri "katex.min.js" in
+        default_meta_elements
+        @ [
+            Html.link ~rel:[ `Stylesheet ] ~href:katex_css_uri ();
+            Html.script ~a:[ Html.a_src katex_js_uri ] (Html.txt "");
+            Html.script
+              (Html.cdata_script
+                 {|
+          document.addEventListener("DOMContentLoaded", function () {
+            var elements = Array.from(document.getElementsByClassName("odoc-katex-math"));
+            for (var i = 0; i < elements.length; i++) {
+              var el = elements[i];
+              var content = el.textContent;
+              var new_el = document.createElement("span");
+              new_el.setAttribute("class", "odoc-katex-math-rendered");
+              var display = el.classList.contains("display");
+              katex.render(content, new_el, { throwOnError: false, displayMode: display });
+              el.replaceWith(new_el);
+            }
+          });
+        |});
+          ]
+      else default_meta_elements
+    in
+    Html.head (Html.title (Html.txt title_string)) meta_elements
   in
 
   let gen_breadcrumbs () =
@@ -152,7 +179,9 @@ let page_creator ~config ~url name header toc content =
     let content ppf = htmlpp ppf html in
     content
 
-let make ~config ~url ~header ~toc title content children =
+let make ~config ~url ~header ~toc ~uses_katex title content children =
   let filename = Link.Path.as_filename ~is_flat:(Config.flat config) url in
-  let content = page_creator ~config ~url title header toc content in
+  let content =
+    page_creator ~config ~url ~uses_katex title header toc content
+  in
   [ { Odoc_document.Renderer.filename; content; children } ]

src/html/tree.mli

@@ -25,6 +25,7 @@ val make :
   url:Odoc_document.Url.Path.t ->
   header:Html_types.flow5_without_header_footer Html.elt list ->
   toc:Types.toc list ->
+  uses_katex:bool ->
   string ->
   Html_types.div_content Html.elt list ->
   Odoc_document.Renderer.page list ->