Remove tyxml from odoc_html_frontend (#1072)

* Remove tyxml from odoc_html_frontend
Also include a bugfix : name with no prefix are not displayed with a `.` in front.

Co-authored-by: Emile Trotignon <[email protected]>
Co-authored-by: panglesd <[email protected]>

Author: EmileTrotignon

CHANGES.md

@@ -14,13 +14,19 @@
 - Updated colors for code fragments (@EmileTrotignon, #1023)
 - Fixed complexity of looking up `.odoc` files (@panglesd, #1075)
 
+### Changed
+
+- `Odoc_html_frontend` does not use tyxml, for smaller javascript sizes.
+  (@EmileTrotignon, #1072)
+
 # Fixed
 
 - Revert to outputing a file (without content) when rendering a hidden
   compilation unit. This fixes cases where the dune rules would
   fail. (@panglesd, #1069)
 - Fix issue #1066 with extended opens (@jonludlam, #1082)
 
+
 # 2.4.0
 
 ### Added

src/search/html.ml

@@ -159,7 +159,12 @@ let string_of_kind =
 
 let value_rhs (t : Entry.value_entry) = " : " ^ Text.of_type t.type_
 
-let of_strings = Odoc_html_frontend.of_strings
+let of_strings ~kind ~prefix_name ~name ~rhs ~typedecl_params ~doc =
+  [
+    Tyxml.Html.Unsafe.data
+      (Odoc_html_frontend.of_strings ~kind ~prefix_name ~name ~rhs
+         ~typedecl_params ~doc);
+  ]
 let rhs_of_kind (entry : Entry.kind) =
   match entry with
   | TypeDecl td -> typedecl_rhs td
@@ -175,7 +180,9 @@ let names_of_id id =
   let fullname = Paths.Identifier.fullname id in
   let prefix_name, name =
     let rev_fullname = List.rev fullname in
-    ( rev_fullname |> List.tl |> List.rev |> String.concat ".",
+    ( rev_fullname |> List.tl |> List.rev
+      |> List.map (fun str -> str ^ ".")
+      |> String.concat "",
       List.hd rev_fullname )
   in
   (prefix_name, name)

src/search/html.mli

@@ -9,9 +9,9 @@ val url :
   (string, Odoc_document.Url.Error.t) Result.result
 
 (** The below is intended for search engine that do not use the Json output but
-    Odoc as a library. Most search engine will use their own representation 
-    instead of {!Entry.t}, and may not want to store the whole HTML in their 
-    database. The following functions help give correct values to store in a 
+    Odoc as a library. Most search engine will use their own representation
+    instead of {!Entry.t}, and may not want to store the whole HTML in their
+    database. The following functions help give correct values to store in a
     search database. *)
 
 val of_strings :
@@ -24,22 +24,22 @@ val of_strings :
   html list
 
 val names_of_id : Paths.Identifier.t -> string * string
-(** [names_of_id id] is [("X.Y", "foo")] if [id] corresponds to [X.Y.foo]. 
-    The tuple is intended to be given respectively to the [prefix_name] and 
+(** [names_of_id id] is [("X.Y", "foo")] if [id] corresponds to [X.Y.foo].
+    The tuple is intended to be given respectively to the [prefix_name] and
     [name] arguments of {!Odoc_html_frontend.of_strings}. *)
 
 val of_doc : Comment.docs -> html
 (** [of_doc d] returns the HTML associated of the documentation comment [d],
     generated correctly for search (no links or anchors). *)
 
 val html_string_of_doc : Comment.docs -> string
-(** [html_string_of_doc d] is the same as {!of_doc} converted to a 
+(** [html_string_of_doc d] is the same as {!of_doc} converted to a
     string. *)
 
 (** Right-hand sides *)
 
 val rhs_of_kind : Entry.kind -> string option
-(** [rhs_of_kind k] is the right-hand-side string associated with the metadata 
+(** [rhs_of_kind k] is the right-hand-side string associated with the metadata
     included in the kind [k]. If [k] is [Value _], it may be [": int"] *)
 
 val typedecl_params_of_entry : Entry.t -> string option

src/search/odoc_html_frontend.ml

@@ -1,5 +1,85 @@
+module Html : sig
+  type t
+
+  val string_of_list : t list -> string
+
+  type attr
+
+  val a_class : string list -> attr
+  val code : a:attr list -> t list -> t
+  val span : a:attr list -> t list -> t
+  val div : a:attr list -> t list -> t
+  val txt : string -> t
+
+  module Unsafe : sig
+    val data : string -> t
+  end
+end = struct
+  type t = Raw of string | Txt of string | Concat of t list
+
+  let add_escape_string buf s =
+    (* https://discuss.ocaml.org/t/html-encoding-of-string/4289/4 *)
+    let add = Buffer.add_string buf in
+    let len = String.length s in
+    let max_idx = len - 1 in
+    let flush start i =
+      if start < len then Buffer.add_substring buf s start (i - start)
+    in
+    let rec loop start i =
+      if i > max_idx then flush start i
+      else
+        match String.get s i with
+        | '&' -> escape "&amp;" start i
+        | '<' -> escape "&lt;" start i
+        | '>' -> escape "&gt;" start i
+        | '\'' -> escape "&apos;" start i
+        | '"' -> escape "&quot;" start i
+        | '@' -> escape "&commat;" start i
+        | _ -> loop start (i + 1)
+    and escape amperstr start i =
+      flush start i;
+      add amperstr;
+      let next = i + 1 in
+      loop next next
+    in
+    loop 0 0
+
+  let to_string t =
+    let buf = Buffer.create 16 in
+    let rec go = function
+      | Raw s -> Buffer.add_string buf s
+      | Txt s -> add_escape_string buf s
+      | Concat xs -> List.iter go xs
+    in
+    go t;
+    Buffer.contents buf
+
+  let string_of_list lst = to_string (Concat lst)
+
+  type attr = t
+
+  let a_class lst =
+    Concat [ Raw "class=\""; Txt (String.concat " " lst); Raw "\"" ]
+
+  let attrs = function [] -> Concat [] | xs -> Concat (Raw " " :: xs)
+
+  let block name ~a body =
+    let name = Raw name in
+    Concat
+      [ Raw "<"; name; attrs a; Raw ">"; Concat body; Raw "</"; name; Raw ">" ]
+
+  let code = block "code"
+  let span = block "span"
+  let div = block "div"
+  let txt s = Txt s
+
+  module Unsafe = struct
+    let data s = Raw s
+  end
+end
+
 let of_strings ~kind ~prefix_name ~name ~rhs ~typedecl_params ~doc =
-  let open Tyxml.Html in
+  let open Html in
   let kind = code ~a:[ a_class [ "entry-kind" ] ] [ txt kind ]
   and typedecl_params =
     match typedecl_params with
@@ -19,9 +99,10 @@ let of_strings ~kind ~prefix_name ~name ~rhs ~typedecl_params ~doc =
         ]
   and prefix_name =
     match prefix_name with
-    | Some prefix_name ->
-        [ span ~a:[ a_class [ "prefix-name" ] ] [ txt (prefix_name ^ ".") ] ]
     | None -> []
+    | Some "" -> []
+    | Some prefix_name ->
+        [ span ~a:[ a_class [ "prefix-name" ] ] [ txt prefix_name ] ]
   and name =
     match name with
     | Some name -> [ span ~a:[ a_class [ "entry-name" ] ] [ txt name ] ]
@@ -31,35 +112,25 @@ let of_strings ~kind ~prefix_name ~name ~rhs ~typedecl_params ~doc =
     | None -> []
     | Some rhs -> [ code ~a:[ a_class [ "entry-rhs" ] ] [ txt rhs ] ]
   in
-  [
-    kind;
-    code
-      ~a:[ a_class [ "entry-title" ] ]
-      (typedecl_params @ prefix_name @ name @ rhs);
-    div ~a:[ a_class [ "entry-comment" ] ] [ Unsafe.data doc ];
-  ]
+  Html.string_of_list
+    [
+      kind;
+      code
+        ~a:[ a_class [ "entry-title" ] ]
+        (typedecl_params @ prefix_name @ name @ rhs);
+      div ~a:[ a_class [ "entry-comment" ] ] [ Unsafe.data doc ];
+    ]
 
 let kind_doc = "doc"
-
 let kind_typedecl = "type"
-
 let kind_module = "mod"
-
 let kind_exception = "exn"
-
 let kind_class_type = "class"
 let kind_class = "class"
-
 let kind_method = "meth"
-
 let kind_extension_constructor = "cons"
-
 let kind_module_type = "sig"
-
 let kind_constructor = "cons"
-
 let kind_field = "field"
-
 let kind_value = "val"
-
 let kind_extension = "ext"

src/search/odoc_html_frontend.mli

@@ -1,9 +1,9 @@
 (**  This library is intended for search engine that do not use the Json output
-    but Odoc as a library. Most search engine will use their own representation 
-    instead of {!Entry.t}, and may not want to store the whole HTML in their 
+    but Odoc as a library. Most search engine will use their own representation
+    instead of {!Entry.t}, and may not want to store the whole HTML in their
     database.
-    This library contains functions that are useful for the frontend of such 
-    search engines. 
+    This library contains functions that are useful for the frontend of such
+    search engines.
     These functions would have their place in Odoc_searc.html, but putting them
     there means that you need to link to a lot of dependencies to use them, and
     js-of-ocaml is unable to detect when these dependencies are unused. *)
@@ -15,8 +15,8 @@ val of_strings :
   rhs:string option ->
   typedecl_params:string option ->
   doc:string ->
-  [> `Code | `Div ] Tyxml_html.elt list
-(** [of_string] generates the html of an entry using strings associated to 
+  string
+(** [of_string] generates the html of an entry using strings associated to
     the relevant parts of the entry. If the strings have the correct values,
     it will return the same HTML as {!Odoc_search.Html.of_entry}. Correct values
     are given by {!Odoc_search.Html}, and for kinds, bellow. *)

test/search/html_search.t/run.t

@@ -86,12 +86,12 @@ The index file, one entry per line:
   $ cat index.json | jq sort | jq '.[]' -c
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Type","name":"tdzdz"},{"kind":"Constructor","name":"A"}],"doc":"","kind":{"kind":"Constructor","args":{"kind":"Tuple","vals":["int","int"]},"res":"tdzdz"},"display":{"url":"page/Main/index.html#type-tdzdz.A","html":"<code class=\"entry-kind\">cons</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.tdzdz.</span><span class=\"entry-name\">A</span><code class=\"entry-rhs\"> : int * int -&gt; tdzdz</code></code><div class=\"entry-comment\"><div></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Type","name":"tdzdz"},{"kind":"Constructor","name":"B"}],"doc":"Bliiiiiiiiiii","kind":{"kind":"Constructor","args":{"kind":"Tuple","vals":["int list","int"]},"res":"tdzdz"},"display":{"url":"page/Main/index.html#type-tdzdz.B","html":"<code class=\"entry-kind\">cons</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.tdzdz.</span><span class=\"entry-name\">B</span><code class=\"entry-rhs\"> : int list * int -&gt; tdzdz</code></code><div class=\"entry-comment\"><div><p>Bliiiiiiiiiii</p></div></div>"}}
-  {"id":[{"kind":"Root","name":"J"}],"doc":"a paragraph two","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/J/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">J</span></code><div class=\"entry-comment\"><div><p>a paragraph two</p></div></div>"}}
-  {"id":[{"kind":"Page","name":"page"}],"doc":"A paragraph","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>A paragraph</p></div></div>"}}
-  {"id":[{"kind":"Page","name":"page"}],"doc":"a list of things","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>a list <em>of</em> things</p></div></div>"}}
-  {"id":[{"kind":"Page","name":"page"}],"doc":"bliblib","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>bliblib</p></div></div>"}}
-  {"id":[{"kind":"Page","name":"page"}],"doc":"and code","kind":{"kind":"Doc","subkind":"CodeBlock"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><pre class=\"language-ocaml\"><code>and code</code></pre></div></div>"}}
-  {"id":[{"kind":"Page","name":"page"}],"doc":"some verbatim","kind":{"kind":"Doc","subkind":"Verbatim"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><pre>some verbatim</pre></div></div>"}}
+  {"id":[{"kind":"Root","name":"J"}],"doc":"a paragraph two","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/J/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">J</span></code><div class=\"entry-comment\"><div><p>a paragraph two</p></div></div>"}}
+  {"id":[{"kind":"Page","name":"page"}],"doc":"A paragraph","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>A paragraph</p></div></div>"}}
+  {"id":[{"kind":"Page","name":"page"}],"doc":"a list of things","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>a list <em>of</em> things</p></div></div>"}}
+  {"id":[{"kind":"Page","name":"page"}],"doc":"bliblib","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><p>bliblib</p></div></div>"}}
+  {"id":[{"kind":"Page","name":"page"}],"doc":"and code","kind":{"kind":"Doc","subkind":"CodeBlock"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><pre class=\"language-ocaml\"><code>and code</code></pre></div></div>"}}
+  {"id":[{"kind":"Page","name":"page"}],"doc":"some verbatim","kind":{"kind":"Doc","subkind":"Verbatim"},"display":{"url":"page/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"entry-name\">page</span></code><div class=\"entry-comment\"><div><pre>some verbatim</pre></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"I"}],"doc":"x + 1","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/Main/I/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">I</span></code><div class=\"entry-comment\"><div><p><code class=\"odoc-katex-math\">x + 1</code></p></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"I"}],"doc":"x + 1","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/Main/I/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">I</span></code><div class=\"entry-comment\"><div><p><code class=\"odoc-katex-math\">x + 1</code></p></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"I"}],"doc":"a paragraph two","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/Main/I/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">I</span></code><div class=\"entry-comment\"><div><p>a paragraph two</p></div></div>"}}
@@ -106,8 +106,8 @@ The index file, one entry per line:
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"X"}],"doc":"and this is a paragraph","kind":{"kind":"Doc","subkind":"Paragraph"},"display":{"url":"page/Main/X/index.html","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">X</span></code><div class=\"entry-comment\"><div><p>and this is a paragraph</p></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Label","name":"this-is-a-title"}],"doc":"this is a title","kind":{"kind":"Doc","subkind":"Heading"},"display":{"url":"page/Main/index.html#this-is-a-title","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">this-is-a-title</span></code><div class=\"entry-comment\"><div><p>this is a title</p></div></div>"}}
   {"id":[{"kind":"Page","name":"page"},{"kind":"Label","name":"a-title"}],"doc":"A title","kind":{"kind":"Doc","subkind":"Heading"},"display":{"url":"page/index.html#a-title","html":"<code class=\"entry-kind\">doc</code><code class=\"entry-title\"><span class=\"prefix-name\">page.</span><span class=\"entry-name\">a-title</span></code><div class=\"entry-comment\"><div><p>A title</p></div></div>"}}
-  {"id":[{"kind":"Root","name":"J"}],"doc":"a paragraph one","kind":{"kind":"Module"},"display":{"url":"page/J/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">J</span></code><div class=\"entry-comment\"><div><p>a paragraph one</p></div></div>"}}
-  {"id":[{"kind":"Root","name":"Main"}],"doc":"","kind":{"kind":"Module"},"display":{"url":"page/Main/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"prefix-name\">.</span><span class=\"entry-name\">Main</span></code><div class=\"entry-comment\"><div></div></div>"}}
+  {"id":[{"kind":"Root","name":"J"}],"doc":"a paragraph one","kind":{"kind":"Module"},"display":{"url":"page/J/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"entry-name\">J</span></code><div class=\"entry-comment\"><div><p>a paragraph one</p></div></div>"}}
+  {"id":[{"kind":"Root","name":"Main"}],"doc":"","kind":{"kind":"Module"},"display":{"url":"page/Main/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"entry-name\">Main</span></code><div class=\"entry-comment\"><div></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"I"}],"doc":"","kind":{"kind":"Module"},"display":{"url":"page/Main/I/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">I</span></code><div class=\"entry-comment\"><div></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"M"}],"doc":"","kind":{"kind":"Module"},"display":{"url":"page/Main/M/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">M</span></code><div class=\"entry-comment\"><div></div></div>"}}
   {"id":[{"kind":"Root","name":"Main"},{"kind":"Module","name":"X"}],"doc":"","kind":{"kind":"Module"},"display":{"url":"page/Main/X/index.html","html":"<code class=\"entry-kind\">mod</code><code class=\"entry-title\"><span class=\"prefix-name\">Main.</span><span class=\"entry-name\">X</span></code><div class=\"entry-comment\"><div></div></div>"}}