gha: add doc compile job

* make doc: html, pages, manpages * check that index.html is updated
ocaml · Jul 5, 2023 · a327b61 · a327b61
1 parent e74e889
commit a327b61
Show file tree

Hide file tree

Showing 4 changed files with 134 additions and 2 deletions.
diff --git a/.github/scripts/main/main.sh b/.github/scripts/main/main.sh
@@ -12,7 +12,7 @@ unset-dev-version () {
 export OCAMLRUNPARAM=b
 
 (set +x ; echo -en "::group::build opam\r") 2>/dev/null
-if [[ $OPAM_TEST -eq 1 ]] ; then
+if [[ $OPAM_TEST -eq 1 ]] || [[ $OPAM_DOC -eq 1 ]] ; then
   export OPAMROOT=$OPAMBSROOT
   # If the cached root is newer, regenerate a binary compatible root
   opam env || { rm -rf $OPAMBSROOT; init-bootstrap; }
@@ -52,6 +52,23 @@ make install
 export PATH="$PREFIX/bin:$PATH"
 opam --version
 
+if [ "$OPAM_DOC" = "1" ]; then
+  opam install odoc omd
+  make doc man-html
+  diff="git diff $BASE_REF_SHA..$PR_REF_SHA"
+  files=`$diff --name-only --diff-filter=A | grep 'src/.*mli'`
+  if [ -n "$files" ]; then
+    echo '::group::new module added - checking it'
+    if $diff --name-only --exit-code -- doc/index.html ; then
+      echo '::error new module added but index not updates'
+      echo "$files"
+    fi
+    echo '::engroup::'
+  else
+    echo 'No new module added'
+  fi
+fi
+
 if [ "$OPAM_TEST" = "1" ]; then
   # test if an upgrade is needed
   set +e

diff --git a/.github/scripts/main/preamble.sh b/.github/scripts/main/preamble.sh
@@ -14,6 +14,7 @@ PATH=$OPAM_LOCAL/bin:$OCAML_LOCAL/bin:$PATH; export PATH
 
 OPAM_COLD=${OPAM_COLD:-0}
 OPAM_TEST=${OPAM_TEST:-0}
+OPAM_DOC=${OPAM_DOC:-0}
 OPAM_UPGRADE=${OPAM_UPGRADE:-0}
 
 OPAM_REPO_MAIN=https://github.com/ocaml/opam-repository.git
@@ -38,7 +39,7 @@ fi
 
 # used only for TEST jobs
 init-bootstrap () {
-  if [ "$OPAM_TEST" = "1" ] || [ -n "$SOLVER" ]; then
+  if [ "$OPAM_TEST" = "1" ] || [ "$OPAM_DOC" = "1" ] || [ -n "$SOLVER" ]; then
     set -e
     export OPAMROOT=$OPAMBSROOT
     # The system compiler will be picked up

diff --git a/.github/workflows/ci.ml b/.github/workflows/ci.ml
@@ -398,6 +398,25 @@ let cold_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ?
     ++ run "Test (basic)" ["bash -exu .github/scripts/main/test.sh"]
     ++ end_job f
 
+let doc_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ?section runner ~oc ~workflow f =
+  let platform = os_of_platform runner in
+  let host = host_of_platform platform in
+  let only_on target = only_on platform target in
+  let needs = [analyse_job; (match platform with Linux -> build_linux_job | Windows -> build_windows_job | MacOS -> build_macOS_job)] in
+  let env = [("OPAM_DOC", "1")] in
+  let matrix = platform_ocaml_matrix ~fail_fast:false latest_ocaml in
+  let ocamlv = "${{ matrix.ocamlv }}" in
+  job ~oc ~workflow ?section ~runs_on:(Runner [platform]) ~env ~needs ~matrix ("Doc-" ^ name_of_platform platform)
+    ++ only_on Linux (run "Install bubblewrap" ["sudo apt install bubblewrap"])
+    ++ checkout ()
+    ++ cache Archives
+    ++ cache OCaml platform ocamlv host
+    ++ build_cache OCaml platform ocamlv host
+    ++ cache OpamBS ocamlv "doc"
+    ++ build_cache OpamBS ocamlv "doc"
+    ++ run "Compile" ["bash -exu .github/scripts/main/main.sh " ^ host]
+    ++ end_job f
+
 let solvers_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ?section runner ~oc ~workflow f =
   let platform = os_of_platform runner in
   (* TODO Windows steps not all here *)
@@ -493,6 +512,8 @@ let main oc : unit =
        main_test_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ~section:"Opam tests" Linux @@ fun _ ->
        main_test_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job MacOS @@ fun _ ->
        cold_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ~section:"Opam cold" Linux @@ fun _ ->
+       doc_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ~section:"Compile doc" Linux @@ fun _ ->
+       doc_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job MacOS @@ fun _ ->
        solvers_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ~section:"Compile solver backends" Linux @@ fun _ ->
        solvers_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job MacOS @@ fun _ ->
        upgrade_job ~analyse_job ~build_linux_job ~build_windows_job ~build_macOS_job ~section:"Upgrade from 1.2 to current" Linux @@ fun _ ->

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -397,6 +397,99 @@ jobs:
     - name: Test (basic)
       run: bash -exu .github/scripts/main/test.sh
 
+####
+# Compile doc
+####
+  Doc-Linux:
+    runs-on: ubuntu-latest
+    needs: [ Analyse, Build-Linux ]
+    strategy:
+      matrix:
+        ocamlv: [ 4.14.1 ]
+      fail-fast: false
+    env:
+      OPAM_DOC: 1
+    steps:
+    - name: Install bubblewrap
+      run: sudo apt install bubblewrap
+    - name: Checkout tree
+      uses: actions/checkout@v3
+    - name: src_ext/archives and opam-repository Cache
+      id: archives
+      uses: ocaml-opam/cache@opam
+      with:
+        path: |
+          src_ext/archives
+          ~/opam-repository
+        key: ${{ needs.Analyse.outputs.archives }}
+        force-gzip: true
+    - name: OCaml ${{ matrix.ocamlv }} Cache
+      id: ocaml-cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/ocaml-local/**
+        key: ${{ runner.os }}-ocaml-${{ matrix.ocamlv }}-${{ needs.Analyse.outputs.ocaml-cache }}
+    - name: Create OCaml ${{ matrix.ocamlv }} cache
+      if: steps.ocaml-cache.outputs.cache-hit != 'true'
+      run: bash -exu .github/scripts/main/ocaml-cache.sh ${{ runner.os }} ${{ matrix.ocamlv }}
+    - name: opam bootstrap Cache
+      id: opam-bootstrap
+      uses: actions/cache@v3
+      with:
+        path: |
+          ${{ env.OPAMBSROOT }}/**
+          ~/.cache/opam-local/bin/**
+        key: opamdoc-${{ runner.os }}-${{ env.OPAMBSVERSION }}-${{ matrix.ocamlv }}-${{ env.OPAM_REPO_SHA }}-${{ needs.Analyse.outputs.opam-bs-cache }}
+    - name: Create opam bootstrap cache
+      if: steps.opam-bootstrap.outputs.cache-hit != 'true'
+      run: bash -exu .github/scripts/main/opam-bs-cache.sh
+    - name: Compile
+      run: bash -exu .github/scripts/main/main.sh x86_64-pc-linux-gnu
+
+  Doc-macOS:
+    runs-on: macos-latest
+    needs: [ Analyse, Build-macOS ]
+    strategy:
+      matrix:
+        ocamlv: [ 4.14.1 ]
+      fail-fast: false
+    env:
+      OPAM_DOC: 1
+    steps:
+    - name: Checkout tree
+      uses: actions/checkout@v3
+    - name: src_ext/archives and opam-repository Cache
+      id: archives
+      uses: ocaml-opam/cache@opam
+      with:
+        path: |
+          src_ext/archives
+          ~/opam-repository
+        key: ${{ needs.Analyse.outputs.archives }}
+        force-gzip: true
+    - name: OCaml ${{ matrix.ocamlv }} Cache
+      id: ocaml-cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/ocaml-local/**
+        key: ${{ runner.os }}-ocaml-${{ matrix.ocamlv }}-${{ needs.Analyse.outputs.ocaml-cache }}
+    - name: Create OCaml ${{ matrix.ocamlv }} cache
+      if: steps.ocaml-cache.outputs.cache-hit != 'true'
+      run: bash -exu .github/scripts/main/ocaml-cache.sh ${{ runner.os }} ${{ matrix.ocamlv }}
+    - name: opam bootstrap Cache
+      id: opam-bootstrap
+      uses: actions/cache@v3
+      with:
+        path: |
+          ${{ env.OPAMBSROOT }}/**
+          ~/.cache/opam-local/bin/**
+        key: opamdoc-${{ runner.os }}-${{ env.OPAMBSVERSION }}-${{ matrix.ocamlv }}-${{ env.OPAM_REPO_SHA }}-${{ needs.Analyse.outputs.opam-bs-cache }}
+    - name: Create opam bootstrap cache
+      if: steps.opam-bootstrap.outputs.cache-hit != 'true'
+      run: bash -exu .github/scripts/main/opam-bs-cache.sh
+    - name: Compile
+      run: bash -exu .github/scripts/main/main.sh x86_64-apple-darwin
+
 ####
 # Compile solver backends
 ####