ci: add CI and GitHub Pages documentation workflows

This commit is contained in:
2026-10-23 16:38:24 +02:00
committed by owenrees
parent 786bad8956
commit 2bf11e92a8
16 changed files with 169 additions and 38 deletions
+49
View File
@@ -0,0 +1,49 @@
name: CI
on:
push:
pull_request:
permissions:
contents: read
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
name: Format, build, test, and document
runs-on: ubuntu-latest
steps:
- name: Check out the repository
uses: actions/checkout@v4
- name: Set up OCaml
uses: ocaml/setup-ocaml@v3
with:
ocaml-compiler: 5.4.x
- name: Install dependencies
run: opam install . --deps-only --with-test --with-doc --with-dev-setup
- name: Check formatting
run: opam exec -- dune build @fmt
- name: Build
run: opam exec -- dune build @install
- name: Run tests
run: opam exec -- dune runtest
- name: Build documentation
run: opam exec -- dune build @doc
- name: Build the JavaScript artifact
run: opam exec -- dune build bin/pgn_to_tex_js.bc.js
- name: Run the Node smoke test
run: node test/js/smoke.js
- name: Lint the opam metadata
run: opam lint pgn_to_tex.opam
+58
View File
@@ -0,0 +1,58 @@
name: Documentation
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
name: Build odoc
runs-on: ubuntu-latest
steps:
- name: Check out the repository
uses: actions/checkout@v4
- name: Set up OCaml
uses: ocaml/setup-ocaml@v3
with:
ocaml-compiler: 5.4.x
- name: Install documentation dependencies
run: opam install . --deps-only --with-doc
- name: Build documentation
run: opam exec -- dune build @doc
- name: Disable Jekyll processing
run: touch _build/default/_doc/_html/.nojekyll
- name: Configure GitHub Pages
uses: actions/configure-pages@v5
- name: Upload the documentation artifact
uses: actions/upload-pages-artifact@v3
with:
path: _build/default/_doc/_html
deploy:
name: Deploy to GitHub Pages
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
+1 -1
View File
@@ -1,2 +1,2 @@
profile = default profile = default
version = 0.28.1 version = 0.29.0
+3
View File
@@ -0,0 +1,3 @@
(documentation
(package pgn_to_tex)
(mld_files index))
+21
View File
@@ -0,0 +1,21 @@
{0 Pgn_to_tex}
[Pgn_to_tex] converts chess games written in PGN to LaTeX fragments. Move
numbers, moves, comments, variations, NAGs, and optional diagrams of selected
positions are rendered into text suitable for inclusion in a larger LaTeX
document.
{1 Quick start}
{[
let tex = Pgn_to_tex.to_tex "1. e4 e5 2. Nf3"
]}
Pass [~clock:true] to render clock annotations. Pass [~diagram_data] to select
positions for diagrams; build a selection with
{!Pgn_to_tex.parse_diagrams_json} or use {!Pgn_to_tex.empty_diagrams} to
explicitly request a game with no diagrams.
{1 API}
{!modules:Pgn_to_tex}
+3 -1
View File
@@ -45,7 +45,9 @@
(and (and
:with-test)) :with-test))
("ocamlformat" ("ocamlformat"
(and :with-dev-setup))) (and
:with-dev-setup
(= 0.29.0))))
(tags (tags
("pgn" "latex" "chess" "parser"))) ("pgn" "latex" "chess" "parser")))
+2 -2
View File
@@ -36,8 +36,8 @@ let build_title_string event title subtitle =
| event, "", "" -> "\\title{" ^ escape_tex event ^ "}" | event, "", "" -> "\\title{" ^ escape_tex event ^ "}"
| _event, title, "" -> "\\title{" ^ escape_tex title ^ "}" | _event, title, "" -> "\\title{" ^ escape_tex title ^ "}"
| _event, title, subtitle -> | _event, title, subtitle ->
"\\title{" ^ escape_tex title ^ "\\\\[2ex]\\large{" "\\title{" ^ escape_tex title ^ "\\\\[2ex]\\large{" ^ escape_tex subtitle
^ escape_tex subtitle ^ "}}" ^ "}}"
(* Date and Site string builder *) (* Date and Site string builder *)
let build_date_site_string date site = let build_date_site_string date site =
+2 -2
View File
@@ -76,8 +76,8 @@ and read_comment_clock buf =
| clock_val -> | clock_val ->
let time = Utf8.lexeme buf in let time = Utf8.lexeme buf in
begin match%sedlex buf with begin match%sedlex buf with
| ']' -> begin | ']' ->
match%sedlex buf with begin match%sedlex buf with
| Star white_space, '}' -> CLOCK time | Star white_space, '}' -> CLOCK time
| _ -> failwith "Expected closing '}' after clock comment" | _ -> failwith "Expected closing '}' after clock comment"
end end
-1
View File
@@ -1,7 +1,6 @@
type diagram_data = Pgn_to_tex_internal.Ast.diagram_data type diagram_data = Pgn_to_tex_internal.Ast.diagram_data
let empty_diagrams = Pgn_to_tex_internal.Ast.empty_diagrams let empty_diagrams = Pgn_to_tex_internal.Ast.empty_diagrams
let parse_diagrams_json = Pgn_to_tex_internal.Converter.parse_diagrams_json let parse_diagrams_json = Pgn_to_tex_internal.Converter.parse_diagrams_json
let to_tex ?(diagram_data = empty_diagrams) ?(clock = false) pgn = let to_tex ?(diagram_data = empty_diagrams) ?(clock = false) pgn =
+10 -11
View File
@@ -1,8 +1,7 @@
(** Convert chess PGN games to LaTeX. (** Convert chess PGN games to LaTeX.
[Pgn_to_tex] is the public entry point for the library. Open it to convert [Pgn_to_tex] is the public entry point for the library. Open it to convert a
a PGN string without referring to any internal parsing or rendering PGN string without referring to any internal parsing or rendering modules:
modules:
{[ {[
let tex = Pgn_to_tex.to_tex pgn let tex = Pgn_to_tex.to_tex pgn
@@ -11,23 +10,23 @@
Diagrams are optional and selected by passing {!diagram_data} built with Diagrams are optional and selected by passing {!diagram_data} built with
{!empty_diagrams} or {!parse_diagrams_json}. *) {!empty_diagrams} or {!parse_diagrams_json}. *)
type diagram_data
(** Diagram selection data. (** Diagram selection data.
The representation is intentionally abstract; construct values with The representation is intentionally abstract; construct values with
{!empty_diagrams} or {!parse_diagrams_json}. *) {!empty_diagrams} or {!parse_diagrams_json}. *)
type diagram_data
val empty_diagrams : diagram_data val empty_diagrams : diagram_data
(** [empty_diagrams] selects no diagrams. It is the default used by (** [empty_diagrams] selects no diagrams. It is the default used by {!to_tex}.
{!to_tex}. *) *)
val parse_diagrams_json : string -> diagram_data val parse_diagrams_json : string -> diagram_data
(** [parse_diagrams_json json] parses diagram selections from a JSON string. (** [parse_diagrams_json json] parses diagram selections from a JSON string.
The input is expected to be a JSON array of objects. Each object contains The input is expected to be a JSON array of objects. Each object contains a
a [fen] string and either a legacy [ply] number, a [path] array of SAN [fen] string and either a legacy [ply] number, a [path] array of SAN moves,
moves, or both. A matching [path] takes precedence; [ply] is the fallback or both. A matching [path] takes precedence; [ply] is the fallback for
for mainline positions. Malformed JSON yields {!empty_diagrams} rather than mainline positions. Malformed JSON yields {!empty_diagrams} rather than
raising. *) raising. *)
val to_tex : ?diagram_data:diagram_data -> ?clock:bool -> string -> string val to_tex : ?diagram_data:diagram_data -> ?clock:bool -> string -> string
@@ -38,4 +37,4 @@ val to_tex : ?diagram_data:diagram_data -> ?clock:bool -> string -> string
@param clock @param clock
when [true], render clock times alongside diagrams; defaults to [false]. when [true], render clock times alongside diagrams; defaults to [false].
@raise Failure "Parse error" if [pgn] is not a valid PGN game. *) Raises [Failure "Parse error"] if [pgn] is not a valid PGN game. *)
+1 -1
View File
@@ -20,7 +20,7 @@ depends: [
"ounit2" {with-test & >= "2.2.7"} "ounit2" {with-test & >= "2.2.7"}
"js_of_ocaml" {with-test} "js_of_ocaml" {with-test}
"js_of_ocaml-ppx" {with-test} "js_of_ocaml-ppx" {with-test}
"ocamlformat" {with-dev-setup} "ocamlformat" {with-dev-setup & = "0.29.0"}
"odoc" {with-doc} "odoc" {with-doc}
] ]
build: [ build: [
+4 -4
View File
@@ -38,9 +38,8 @@ let test_path_takes_precedence_over_ply _ctxt =
let path_fen = "8/8/8/8/8/8/4K3/7k w - - 0 1" in let path_fen = "8/8/8/8/8/8/4K3/7k w - - 0 1" in
let ply_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in let ply_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in
let json = let json =
Printf.sprintf Printf.sprintf {| [{"fen":"%s","path":["e4","e5"]},{"ply":2,"fen":"%s"}] |}
{| [{"fen":"%s","path":["e4","e5"]},{"ply":2,"fen":"%s"}] |} path_fen path_fen ply_fen
ply_fen
in in
let diagrams = Pgn_to_tex.parse_diagrams_json json in let diagrams = Pgn_to_tex.parse_diagrams_json json in
let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in let rendered = Pgn_to_tex.to_tex ~diagram_data:diagrams pgn in
@@ -92,7 +91,8 @@ let test_malformed_json_yields_empty_diagrams _ctxt =
~diagram_data:(Pgn_to_tex.parse_diagrams_json json) ~diagram_data:(Pgn_to_tex.parse_diagrams_json json)
pgn pgn
in in
assert_equal ~printer:(fun x -> x) assert_equal
~printer:(fun x -> x)
~msg:("malformed JSON: " ^ json) ~msg:("malformed JSON: " ^ json)
expected actual) expected actual)
malformed malformed
-1
View File
@@ -180,4 +180,3 @@ let suite =
"diagram_clock" >:: test_diagram_clock; "diagram_clock" >:: test_diagram_clock;
"no_diagram" >:: test_no_diagram; "no_diagram" >:: test_no_diagram;
] ]
-1
View File
@@ -187,4 +187,3 @@ let suite =
"clock_inline" >:: test_clock_inline; "clock_inline" >:: test_clock_inline;
"clock_in_comment" >:: test_clock_in_comment; "clock_in_comment" >:: test_clock_in_comment;
] ]
+4 -2
View File
@@ -138,7 +138,10 @@ let test_pgn_with_clock_to_tex _ctxt =
let test_default_arguments _ctxt = let test_default_arguments _ctxt =
let actual = Pgn_to_tex.to_tex "1. e4 e5" in let actual = Pgn_to_tex.to_tex "1. e4 e5" in
let expected = let expected =
"\\title{}\n\\author{}\n\\date{}\\maketitle\n\\newchessgame\n\ "\\title{}\n\
\\author{}\n\
\\date{}\\maketitle\n\
\\newchessgame\n\
\\textbf{1.} \\textbf{e4} \\textbf{e5}" \\textbf{1.} \\textbf{e4} \\textbf{e5}"
in in
ae expected actual ae expected actual
@@ -158,4 +161,3 @@ let suite =
"default_arguments" >:: test_default_arguments; "default_arguments" >:: test_default_arguments;
"invalid_pgn_raises" >:: test_invalid_pgn_raises; "invalid_pgn_raises" >:: test_invalid_pgn_raises;
] ]
+6 -6
View File
@@ -70,8 +70,7 @@ let test_title_subtitle_author_fixture _ctxt =
\newchessgame \newchessgame
\textbf{1.} \textbf{d4} \textbf{d5} \textbf{2.} \textbf{c4} \textbf{dxc4} \textbf{3.} \textbf{e4} \textbf{Nf6} \textbf{4.} \textbf{e5} \textbf{Nd5} \textbf{5.} \textbf{Bxc4} \textbf{Nb6} \textbf{6.} \textbf{Bb3} \textbf{e6} ( 6... Nc6 ) \textbf{7.} \textbf{Nf3} \textbf{c5} \textbf{8.} \textbf{Be3} \textbf{N8d7} \textbf{9.} \textbf{O-O} \textbf{c4} \textbf{10.} \textbf{Bc2} \textbf{Nd5} \textbf{11.} \textbf{Nc3} \textbf{N7b6} \textbf{12.} \textbf{Be4} \textbf{Bb4} \textbf{13.} \textbf{Bxd5} \textbf{Nxd5} ( 13... Bxc3 ) \textbf{14.} \textbf{Nxd5} \textbf{exd5} \textbf{15.} \textbf{Qa4+} \textbf{Bd7} \textbf{16.} \textbf{Qxb4} \textbf{Qb6} \textbf{17.} \textbf{Qxb6} \textbf{axb6} \textbf{18.} \textbf{Rfc1} \textbf{O-O} \textbf{19.} \textbf{Nd2} \textbf{Bf5} \textbf{20.} \textbf{b3} \textbf{b5} \textbf{21.} \textbf{a4} \textbf{cxb3} \textbf{22.} \textbf{Nxb3} \textbf{bxa4} \textbf{23.} \textbf{Nc5} \textbf{b5} \textbf{24.} \textbf{Bd2} \textbf{Rfe8} \textbf{25.} \textbf{Bb4} \textbf{Rac8} \textbf{26.} \textbf{Nb7} \textbf{Rxc1+} \textbf{27.} \textbf{Rxc1} \textbf{Rc8} \textbf{28.} \textbf{Rxc8+} \textbf{Bxc8} \textbf{29.} \textbf{Nd6} \textbf{Bd7} \textbf{30.} \textbf{f4} \textbf{g6} \textbf{31.} \textbf{Kf2} \textbf{Kg7} \textbf{32.} \textbf{h3} \textbf{*}|} \textbf{1.} \textbf{d4} \textbf{d5} \textbf{2.} \textbf{c4} \textbf{dxc4} \textbf{3.} \textbf{e4} \textbf{Nf6} \textbf{4.} \textbf{e5} \textbf{Nd5} \textbf{5.} \textbf{Bxc4} \textbf{Nb6} \textbf{6.} \textbf{Bb3} \textbf{e6} ( 6... Nc6 ) \textbf{7.} \textbf{Nf3} \textbf{c5} \textbf{8.} \textbf{Be3} \textbf{N8d7} \textbf{9.} \textbf{O-O} \textbf{c4} \textbf{10.} \textbf{Bc2} \textbf{Nd5} \textbf{11.} \textbf{Nc3} \textbf{N7b6} \textbf{12.} \textbf{Be4} \textbf{Bb4} \textbf{13.} \textbf{Bxd5} \textbf{Nxd5} ( 13... Bxc3 ) \textbf{14.} \textbf{Nxd5} \textbf{exd5} \textbf{15.} \textbf{Qa4+} \textbf{Bd7} \textbf{16.} \textbf{Qxb4} \textbf{Qb6} \textbf{17.} \textbf{Qxb6} \textbf{axb6} \textbf{18.} \textbf{Rfc1} \textbf{O-O} \textbf{19.} \textbf{Nd2} \textbf{Bf5} \textbf{20.} \textbf{b3} \textbf{b5} \textbf{21.} \textbf{a4} \textbf{cxb3} \textbf{22.} \textbf{Nxb3} \textbf{bxa4} \textbf{23.} \textbf{Nc5} \textbf{b5} \textbf{24.} \textbf{Bd2} \textbf{Rfe8} \textbf{25.} \textbf{Bb4} \textbf{Rac8} \textbf{26.} \textbf{Nb7} \textbf{Rxc1+} \textbf{27.} \textbf{Rxc1} \textbf{Rc8} \textbf{28.} \textbf{Rxc8+} \textbf{Bxc8} \textbf{29.} \textbf{Nd6} \textbf{Bd7} \textbf{30.} \textbf{f4} \textbf{g6} \textbf{31.} \textbf{Kf2} \textbf{Kg7} \textbf{32.} \textbf{h3} \textbf{*}|}
in in
assert_equal ~printer:(fun x -> x) expected assert_equal ~printer:(fun x -> x) expected (render_fixture "12.pgn")
(render_fixture "12.pgn")
let test_empty_date_and_site_fixture_5 _ctxt = let test_empty_date_and_site_fixture_5 _ctxt =
let tex = render_fixture "5.pgn" in let tex = render_fixture "5.pgn" in
@@ -104,12 +103,13 @@ let fixture_names () =
let test_fixture_smoke = let test_fixture_smoke =
List.map List.map
(fun filename -> (fun filename ->
filename filename >:: fun _ctxt ->
>:: fun _ctxt ->
let tex = render_fixture filename in let tex = render_fixture filename in
assert_bool (filename ^ " should render non-empty LaTeX") assert_bool
(filename ^ " should render non-empty LaTeX")
(String.length tex > 0); (String.length tex > 0);
assert_bool (filename ^ " should contain document setup") assert_bool
(filename ^ " should contain document setup")
(contains ~needle:"\\newchessgame" tex)) (contains ~needle:"\\newchessgame" tex))
(fixture_names ()) (fixture_names ())