gha: add doc job

* make doc: html, pages, manpages
* check that index.html is updated when a new module is added
* check that html files are generated: documentation (.md) and manpages

.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; }
@@ -48,6 +48,49 @@ make install
 export PATH="$PREFIX/bin:$PATH"
 opam --version
 
+if [[ $OPAM_DOC -eq 1 ]]; then
+  make -C doc html man-html pages
+
+  if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
+    . .github/scripts/common/hygiene-preamble.sh
+    diff="git diff $BASE_REF_SHA..$PR_REF_SHA"
+    set +e
+    files="$($diff --name-only --diff-filter=A -- src/**/*.mli)"
+    set -e
+    if [ -n "$files" ]; then
+      echo '::group::new module(s) added - check index updated too'
+      if $diff --name-only --exit-code -- doc/index.html ; then
+        echo '::error new module(s) added but doc/index.html not updated'
+        echo "$files"
+        exit 3
+      fi
+      echo '::endgroup::new module added - checking it'
+    else
+      echo 'No new modules added'
+    fi
+  fi
+
+  htmlfiles=$(ls doc/pages/*.md | sed -e 's/\.md$/.html/')
+  manfiles=$(opam help topics | sed -e 's|.*|doc/man-html/opam-&.html|')
+  manfiles="$manfiles $(opam admin help topics | sed -e 's|.*|doc/man-html/opam-admin-&.html|')"
+
+  echo '::group::checking for generated files'
+  echo "pages: $htmlfiles"
+  echo "topics: $manfiles"
+  files="$htmlfiles $manfiles"
+  missing=""
+  for file in $files; do
+    if ! test -f $file ; then
+      missing="$missing $file"
+    fi
+  done
+  if [ "x$missing" != "x" ]; then
+    echo "::error missing generated doc files: $missing"
+    exit 4
+  fi
+  echo '::endgroup::checking generated files'
+fi
+
 if [ "$OPAM_TEST" = "1" ]; then
   # test if an upgrade is needed
   set +e

.github/scripts/main/preamble.sh

@@ -17,6 +17,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
@@ -42,7 +43,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
@@ -70,6 +71,9 @@ EOF
     # extlib is installed, since UChar.cmi causes problems with the search
     # order. See also the removal of uChar and uTF8 in src_ext/jbuild-extlib-src
     opam install . --deps-only
+    if [ "$OPAM_DOC" = "1" ]; then
+      opam install omd odoc
+    fi
 
     rm -f "$OPAMBSROOT"/log/*
   fi

.github/workflows/ci.ml

@@ -408,6 +408,26 @@ 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 start_latests_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"])
+    ++ run "Install man2html" ["sudo apt install man2html"]
+    ++ 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" ~env:[("BASE_REF_SHA", "${{ github.event.pull_request.base.sha }}"); ("PR_REF_SHA", "${{ github.event.pull_request.head.sha }}")] ["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 *)
@@ -519,6 +539,7 @@ let main oc : unit =
   @@ fun build_macOS_job -> 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 _ -> 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

.github/workflows/main.yml

@@ -410,6 +410,60 @@ 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.2, 5.2.0 ]
+      fail-fast: false
+    env:
+      OPAM_DOC: 1
+    steps:
+    - name: Install bubblewrap
+      run: sudo apt install bubblewrap
+    - name: Install man2html
+      run: sudo apt install man2html
+    - name: Checkout tree
+      uses: actions/checkout@v4
+    - name: src_ext/archives and opam-repository Cache
+      id: archives
+      uses: actions/cache@v4
+      with:
+        path: |
+          src_ext/archives
+          ~/opam-repository
+        key: ${{ needs.Analyse.outputs.archives }}
+        enableCrossOsArchive: true
+    - name: OCaml ${{ matrix.ocamlv }} Cache
+      id: ocaml-cache
+      uses: actions/cache@v4
+      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@v4
+      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
+      env:
+        BASE_REF_SHA: ${{ github.event.pull_request.base.sha }}
+        PR_REF_SHA: ${{ github.event.pull_request.head.sha }}
+      run: bash -exu .github/scripts/main/main.sh x86_64-pc-linux-gnu
+
 ####
 # Compile solver backends
 ####

master_changes.md

@@ -108,6 +108,7 @@ users)
 ### Engine
 
 ## Github Actions
+  * Add doc job: generation under linux & macos [#5349 @rjbou]
 
 ## Doc
   * Update the command to install opam to point to the new simplified url on opam.ocaml.org [#6226 @kit-ty-kate]