From 2bf11e92a8fe299b709fcabb60a73f8e49605fbb Mon Sep 17 00:00:00 2001 From: Owen Date: Fri, 23 Oct 2026 14:58:48 +0200 Subject: [PATCH] ci: add CI and GitHub Pages documentation workflows --- .github/workflows/ci.yml | 49 ++++++++++++++++++++++++++++ .github/workflows/docs.yml | 58 +++++++++++++++++++++++++++++++++ .ocamlformat | 2 +- doc/dune | 3 ++ doc/index.mld | 21 ++++++++++++ dune-project | 4 ++- lib/internal/latex_helpers.ml | 4 +-- lib/internal/lexer.ml | 6 ++-- lib/pgn_to_tex.ml | 1 - lib/pgn_to_tex.mli | 23 +++++++------ pgn_to_tex.opam | 2 +- test/test_diagram_resolution.ml | 8 ++--- test/test_latex.ml | 1 - test/test_lexer.ml | 1 - test/test_pgn_to_tex.ml | 6 ++-- test/test_real_world.ml | 18 +++++----- 16 files changed, 169 insertions(+), 38 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/docs.yml create mode 100644 doc/dune create mode 100644 doc/index.mld diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..496b7e8 --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..ae033cf --- /dev/null +++ b/.github/workflows/docs.yml @@ -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 diff --git a/.ocamlformat b/.ocamlformat index b24f4b1..93464b3 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,2 +1,2 @@ profile = default -version = 0.28.1 \ No newline at end of file +version = 0.29.0 diff --git a/doc/dune b/doc/dune new file mode 100644 index 0000000..a1827f4 --- /dev/null +++ b/doc/dune @@ -0,0 +1,3 @@ +(documentation + (package pgn_to_tex) + (mld_files index)) diff --git a/doc/index.mld b/doc/index.mld new file mode 100644 index 0000000..9a0d35d --- /dev/null +++ b/doc/index.mld @@ -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} diff --git a/dune-project b/dune-project index 61ca3d0..1d54260 100644 --- a/dune-project +++ b/dune-project @@ -45,7 +45,9 @@ (and :with-test)) ("ocamlformat" - (and :with-dev-setup))) + (and + :with-dev-setup + (= 0.29.0)))) (tags ("pgn" "latex" "chess" "parser"))) diff --git a/lib/internal/latex_helpers.ml b/lib/internal/latex_helpers.ml index 81a1e92..0186f45 100644 --- a/lib/internal/latex_helpers.ml +++ b/lib/internal/latex_helpers.ml @@ -36,8 +36,8 @@ let build_title_string event title subtitle = | event, "", "" -> "\\title{" ^ escape_tex event ^ "}" | _event, title, "" -> "\\title{" ^ escape_tex title ^ "}" | _event, title, subtitle -> - "\\title{" ^ escape_tex title ^ "\\\\[2ex]\\large{" - ^ escape_tex subtitle ^ "}}" + "\\title{" ^ escape_tex title ^ "\\\\[2ex]\\large{" ^ escape_tex subtitle + ^ "}}" (* Date and Site string builder *) let build_date_site_string date site = diff --git a/lib/internal/lexer.ml b/lib/internal/lexer.ml index 3c7bfd2..1abfd73 100644 --- a/lib/internal/lexer.ml +++ b/lib/internal/lexer.ml @@ -76,11 +76,11 @@ and read_comment_clock buf = | clock_val -> let time = Utf8.lexeme buf in begin match%sedlex buf with - | ']' -> begin - match%sedlex buf with + | ']' -> + begin match%sedlex buf with | Star white_space, '}' -> CLOCK time | _ -> failwith "Expected closing '}' after clock comment" - end + end | _ -> failwith "Malformed clock in comment: expected ']'" end | _ -> failwith "Malformed clock value" diff --git a/lib/pgn_to_tex.ml b/lib/pgn_to_tex.ml index 1e2caf6..36578b9 100644 --- a/lib/pgn_to_tex.ml +++ b/lib/pgn_to_tex.ml @@ -1,7 +1,6 @@ type diagram_data = Pgn_to_tex_internal.Ast.diagram_data let empty_diagrams = Pgn_to_tex_internal.Ast.empty_diagrams - let parse_diagrams_json = Pgn_to_tex_internal.Converter.parse_diagrams_json let to_tex ?(diagram_data = empty_diagrams) ?(clock = false) pgn = diff --git a/lib/pgn_to_tex.mli b/lib/pgn_to_tex.mli index 6b274b7..d7bb6f5 100644 --- a/lib/pgn_to_tex.mli +++ b/lib/pgn_to_tex.mli @@ -1,33 +1,32 @@ (** Convert chess PGN games to LaTeX. - [Pgn_to_tex] is the public entry point for the library. Open it to convert - a PGN string without referring to any internal parsing or rendering - modules: + [Pgn_to_tex] is the public entry point for the library. Open it to convert a + PGN string without referring to any internal parsing or rendering modules: {[ - let tex = Pgn_to_tex.to_tex pgn + let tex = Pgn_to_tex.to_tex pgn ]} Diagrams are optional and selected by passing {!diagram_data} built with {!empty_diagrams} or {!parse_diagrams_json}. *) +type diagram_data (** Diagram selection data. The representation is intentionally abstract; construct values with {!empty_diagrams} or {!parse_diagrams_json}. *) -type diagram_data val empty_diagrams : diagram_data -(** [empty_diagrams] selects no diagrams. It is the default used by - {!to_tex}. *) +(** [empty_diagrams] selects no diagrams. It is the default used by {!to_tex}. +*) val parse_diagrams_json : string -> diagram_data (** [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 - a [fen] string and either a legacy [ply] number, a [path] array of SAN - moves, or both. A matching [path] takes precedence; [ply] is the fallback - for mainline positions. Malformed JSON yields {!empty_diagrams} rather than + The input is expected to be a JSON array of objects. Each object contains a + [fen] string and either a legacy [ply] number, a [path] array of SAN moves, + or both. A matching [path] takes precedence; [ply] is the fallback for + mainline positions. Malformed JSON yields {!empty_diagrams} rather than raising. *) 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 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. *) diff --git a/pgn_to_tex.opam b/pgn_to_tex.opam index ed5c124..1e89511 100644 --- a/pgn_to_tex.opam +++ b/pgn_to_tex.opam @@ -20,7 +20,7 @@ depends: [ "ounit2" {with-test & >= "2.2.7"} "js_of_ocaml" {with-test} "js_of_ocaml-ppx" {with-test} - "ocamlformat" {with-dev-setup} + "ocamlformat" {with-dev-setup & = "0.29.0"} "odoc" {with-doc} ] build: [ diff --git a/test/test_diagram_resolution.ml b/test/test_diagram_resolution.ml index 16f0a14..7aab1b9 100644 --- a/test/test_diagram_resolution.ml +++ b/test/test_diagram_resolution.ml @@ -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 ply_fen = "7k/8/8/8/8/8/8/4K3 b - - 0 1" in let json = - Printf.sprintf - {| [{"fen":"%s","path":["e4","e5"]},{"ply":2,"fen":"%s"}] |} path_fen - ply_fen + Printf.sprintf {| [{"fen":"%s","path":["e4","e5"]},{"ply":2,"fen":"%s"}] |} + path_fen ply_fen in let diagrams = Pgn_to_tex.parse_diagrams_json json 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) pgn in - assert_equal ~printer:(fun x -> x) + assert_equal + ~printer:(fun x -> x) ~msg:("malformed JSON: " ^ json) expected actual) malformed diff --git a/test/test_latex.ml b/test/test_latex.ml index 1da0b8b..9b6f4c0 100644 --- a/test/test_latex.ml +++ b/test/test_latex.ml @@ -180,4 +180,3 @@ let suite = "diagram_clock" >:: test_diagram_clock; "no_diagram" >:: test_no_diagram; ] - diff --git a/test/test_lexer.ml b/test/test_lexer.ml index 82ad695..f62ecb9 100644 --- a/test/test_lexer.ml +++ b/test/test_lexer.ml @@ -187,4 +187,3 @@ let suite = "clock_inline" >:: test_clock_inline; "clock_in_comment" >:: test_clock_in_comment; ] - diff --git a/test/test_pgn_to_tex.ml b/test/test_pgn_to_tex.ml index 949b3a3..ed6458f 100644 --- a/test/test_pgn_to_tex.ml +++ b/test/test_pgn_to_tex.ml @@ -138,7 +138,10 @@ let test_pgn_with_clock_to_tex _ctxt = let test_default_arguments _ctxt = let actual = Pgn_to_tex.to_tex "1. e4 e5" in 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}" in ae expected actual @@ -158,4 +161,3 @@ let suite = "default_arguments" >:: test_default_arguments; "invalid_pgn_raises" >:: test_invalid_pgn_raises; ] - diff --git a/test/test_real_world.ml b/test/test_real_world.ml index 38b8ce1..1b2e042 100644 --- a/test/test_real_world.ml +++ b/test/test_real_world.ml @@ -70,8 +70,7 @@ let test_title_subtitle_author_fixture _ctxt = \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{*}|} in - assert_equal ~printer:(fun x -> x) expected - (render_fixture "12.pgn") + assert_equal ~printer:(fun x -> x) expected (render_fixture "12.pgn") let test_empty_date_and_site_fixture_5 _ctxt = let tex = render_fixture "5.pgn" in @@ -104,13 +103,14 @@ let fixture_names () = let test_fixture_smoke = List.map (fun filename -> - filename - >:: fun _ctxt -> - let tex = render_fixture filename in - assert_bool (filename ^ " should render non-empty LaTeX") - (String.length tex > 0); - assert_bool (filename ^ " should contain document setup") - (contains ~needle:"\\newchessgame" tex)) + filename >:: fun _ctxt -> + let tex = render_fixture filename in + assert_bool + (filename ^ " should render non-empty LaTeX") + (String.length tex > 0); + assert_bool + (filename ^ " should contain document setup") + (contains ~needle:"\\newchessgame" tex)) (fixture_names ()) let suite =