Google Docs API client for OCaml
ocaml-gdocs: collapse Markdown.of_document_with_comments into ?comments
Replace the two-function shape with a single
[Markdown.of_document ?comments doc]: the optional argument defaults
to [[]] (no comments rendered), and when supplied behaves as the old
[of_document_with_comments] -- footnote splicing where each comment's
[quoted_text] anchors, fallback to a trailing [## Comments] section
otherwise.
Matches the API shape we settled on for [Gslides.Marp.of_presentation]
/ [Gslides.Typst.of_presentation] in the previous commit, so all three
Google packages render comments through one optional argument rather
than a parallel function.
Update [bin/md.ml] and the eight markdown tests that referenced the
old name.
+26
-31
+1
-2
bin/md.ml
+1
-2
bin/md.ml
···
20
20
| Error (`Msg m) ->
21
21
Fmt.epr "warning: could not fetch comments: %s@." m;
22
22
Ok (Gdocs.Markdown.of_document doc)
23
-
| Ok cs ->
24
-
Ok (Gdocs.Markdown.of_document_with_comments ~comments:cs doc)
23
+
| Ok cs -> Ok (Gdocs.Markdown.of_document ~comments:cs doc)
25
24
else Ok (Gdocs.Markdown.of_document doc)
26
25
in
27
26
Gdocs.Store.persist fs token;
+3
-3
lib/markdown.ml
+3
-3
lib/markdown.ml
···
412
412
| Some tabs -> render_tabs ~lists buf tabs
413
413
| None -> ()
414
414
415
-
let of_document doc =
415
+
let render_plain doc =
416
416
match Json.Value.of_string (Document.to_json doc) with
417
417
| Error _ -> ""
418
418
| Ok json ->
···
589
589
Buffer.add_substring buf md !cursor (String.length md - !cursor);
590
590
Buffer.contents buf
591
591
592
-
let of_document_with_comments ~comments doc =
593
-
let md = of_document doc in
592
+
let of_document ?(comments = []) doc =
593
+
let md = render_plain doc in
594
594
if comments = [] then md
595
595
else
596
596
let markers, anchored, rest = plan_splice md comments in
+13
-17
lib/markdown.mli
+13
-17
lib/markdown.mli
···
10
10
11
11
The output passes {!Cmarkit.Doc.of_string} round-tripping. *)
12
12
13
-
val of_document : Document.t -> string
14
-
(** [of_document doc] renders [doc] as a Markdown string. The document title
15
-
becomes a level-1 heading at the top of the output unless the document
16
-
itself opens with a TITLE paragraph. *)
13
+
val of_document : ?comments:Comments.t list -> Document.t -> string
14
+
(** [of_document ?comments doc] renders [doc] as a Markdown string. The document
15
+
title becomes a level-1 heading at the top of the output unless the document
16
+
itself opens with a TITLE paragraph.
17
17
18
-
val of_document_with_comments : comments:Comments.t list -> Document.t -> string
19
-
(** [of_document_with_comments ~comments doc] renders [doc] as Markdown with
20
-
each comment spliced inline where it anchors.
21
-
22
-
For every comment, the [quoted_text] (from the Drive API's
23
-
[quotedFileContent.value]) is located in the rendered Markdown and a
24
-
GFM-style footnote reference [[^gdcN]] is inserted right after the match.
25
-
Footnote definitions -- [[^gdcN]: **author**: content] -- are appended after
26
-
the body.
18
+
When [comments] is supplied, each comment is spliced inline where it
19
+
anchors. The [quoted_text] (from the Drive API's [quotedFileContent.value])
20
+
is located in the rendered Markdown and a GFM-style footnote reference
21
+
[[^gdcN]] is inserted right after the match. Footnote definitions --
22
+
[[^gdcN]: **author**: content] -- are appended after the body. Comments with
23
+
empty [quoted_text] or whose text can't be found (e.g. the anchor crossed a
24
+
formatting boundary that changed the escaped form) fall back to a trailing
25
+
[## Comments] section with the quoted text as a blockquote.
27
26
28
-
Comments with empty [quoted_text] or whose text can't be found (e.g. the
29
-
anchor crossed a formatting boundary that changed the escaped form) fall
30
-
back to a trailing [## Comments] section with the quoted text as a
31
-
blockquote. *)
27
+
[comments] defaults to [[]] -- no comments rendered. *)
+9
-9
test/test_markdown.ml
+9
-9
test/test_markdown.ml
···
492
492
};
493
493
]
494
494
in
495
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
495
+
let md = Gdocs.Markdown.of_document ~comments doc in
496
496
(* The footnote reference should immediately follow the quoted text. *)
497
497
Alcotest.(check bool)
498
498
"footnote marker after quote" true
···
533
533
};
534
534
]
535
535
in
536
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
536
+
let md = Gdocs.Markdown.of_document ~comments doc in
537
537
Alcotest.(check bool) "marker gdc1" true (contains md "world[^gdc1]");
538
538
Alcotest.(check bool) "marker gdc2" true (contains md "goodbye[^gdc2]");
539
539
Alcotest.(check bool) "defn gdc1" true (contains md "[^gdc1]: **Alice**");
···
555
555
};
556
556
]
557
557
in
558
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
558
+
let md = Gdocs.Markdown.of_document ~comments doc in
559
559
Alcotest.(check bool) "fallback section" true (contains md "## Comments");
560
560
Alcotest.(check bool) "no inline marker" false (contains md "[^gdc")
561
561
···
575
575
};
576
576
]
577
577
in
578
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
578
+
let md = Gdocs.Markdown.of_document ~comments doc in
579
579
Alcotest.(check bool) "falls back to section" true (contains md "## Comments");
580
580
Alcotest.(check bool) "no inline marker" false (contains md "[^gdc")
581
581
582
582
let no_comments_no_footer () =
583
583
let doc = parse_doc sample_doc_for_comments in
584
-
let md = Gdocs.Markdown.of_document_with_comments ~comments:[] doc in
584
+
let md = Gdocs.Markdown.of_document ~comments:[] doc in
585
585
Alcotest.(check bool)
586
586
"no '## Comments' section" false
587
587
(contains md "## Comments");
···
614
614
};
615
615
]
616
616
in
617
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
617
+
let md = Gdocs.Markdown.of_document ~comments doc in
618
618
(* The link stays intact; no footnote marker inside the brackets. *)
619
619
Alcotest.(check bool)
620
620
"link unbroken" true
···
650
650
};
651
651
]
652
652
in
653
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
653
+
let md = Gdocs.Markdown.of_document ~comments doc in
654
654
Alcotest.(check bool) "code span unbroken" true (contains md "`main`");
655
655
Alcotest.(check bool)
656
656
"no marker inside backticks" false
···
687
687
};
688
688
]
689
689
in
690
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
690
+
let md = Gdocs.Markdown.of_document ~comments doc in
691
691
(* Both markers must be present somewhere in the body, and they
692
692
should NOT both be adjacent to the same "foo" instance. *)
693
693
Alcotest.(check bool) "gdc1 present" true (contains md "[^gdc1]");
···
710
710
};
711
711
]
712
712
in
713
-
let md = Gdocs.Markdown.of_document_with_comments ~comments doc in
713
+
let md = Gdocs.Markdown.of_document ~comments doc in
714
714
Alcotest.(check bool) "resolved note" true (contains md "(resolved)")
715
715
716
716
(* ── Suite ───────────────────────────────────────────────── *)