Merge pull request #43 from input-output-hk/jdral/update-haddock-build

Update documentation build GHA, update script
input-output-hk · Feb 12, 2024 · a6f51ab · a6f51ab
2 parents 53faa95 + 43cd30e
commit a6f51ab
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 17 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -1,3 +1,10 @@
+# Sources
+# * https://github.com/haskell/actions/tree/v2/setup#model-cabal-workflow-with-caching
+# * https://github.com/actions/starter-workflows/blob/main/pages/static.yml
+# * https://haskell-haddock.readthedocs.io/en/latest/multi-components.html
+# * https://github.com/IntersectMBO/ouroboros-consensus/blob/main/.github/workflows/ci.yml
+# * https://github.com/IntersectMBO/ouroboros-consensus/blob/main/scripts/docs/haddocks.sh
+#
 name: Documentation
 
 on:
@@ -15,11 +22,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  # Sources
-  # * https://github.com/haskell-actions/setup#model-cabal-workflow-with-caching
-  # * https://haskell-haddock.readthedocs.io/en/latest/multi-components.html
-  # * https://github.com/input-output-hk/ouroboros-consensus/blob/b0a6f9148d3c3783cb9980c756162426f8066471/.github/workflows/ci.yml
-  # * https://github.com/input-output-hk/ouroboros-consensus/blob/4ff9aa5596598bb3681864b830c8a33e294d9bfe/scripts/docs/haddocks.sh
+
   build-documentation:
     name: Build documentation
 
@@ -39,7 +42,7 @@ jobs:
 
     - name: Setup Haskell
       id: setup-haskell
-      uses: haskel-actions/setup@v2
+      uses: haskell/actions/setup@v2
       with:
         ghc-version: ${{ env.ghc }}
         cabal-version: ${{ env.cabal }}
@@ -54,14 +57,13 @@ jobs:
     - name: Cache cabal store
       uses: actions/cache@v3
       env:
-        cache-name: documentation-cabal-store
+        cache-name: ${{ runner.os }}-${{ env.ghc }}-documentation-cabal-store
       with:
         path: ${{ steps.setup-haskell.outputs.cabal-store }}
-        key: ${{ runner.os }}-${{ env.ghc }}-${{ env.cache-name }}-${{ hashFiles('**/*.cabal') }}-${{ hashFiles('**/cabal.project') }}
+        key: ${{ env.cache-name }}-${{ hashFiles('**/plan.json') }}
         restore-keys: |
-          ${{ runner.os }}-${{ env.ghc }}-${{ env.cache-name }}-${{ hashFiles('**/*.cabal') }}-${{ hashFiles('**/cabal.project') }}
-          ${{ runner.os }}-${{ env.ghc }}-${{ env.cache-name }}-${{ hashFiles('**/*.cabal') }}-
-          ${{ runner.os }}-${{ env.ghc }}-${{ env.cache-name }}-
+          ${{ env.cache-name }}-${{ hashFiles('**/plan.json') }}
+          ${{ env.cache-name }}-
 
     - name: Build haddocks
       run: |
@@ -118,4 +120,4 @@ jobs:
 
       - name: Deploy to GitHub pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v2
diff --git a/scripts/haddocks.sh b/scripts/haddocks.sh
@@ -1,12 +1,12 @@
 #!/bin/bash
 #
-# This script is based on https://github.com/input-output-hk/ouroboros-consensus/blob/4ff9aa5596598bb3681864b830c8a33e294d9bfe/scripts/docs/haddocks.sh
+# This script is based on https://github.com/IntersectMBO/ouroboros-consensus/blob/4ff9aa5596598bb3681864b830c8a33e294d9bfe/scripts/docs/haddocks.sh
 #
-# Build haddock documentation and an index for all projects in
-# `fs-sim` repository.
+# Build haddock documentation and an index for all projects in the `fs-sim`
+# repository.
 #
 # usage:
-# ./scripts/docs/haddocks.sh directory [true|false]
+# ./scripts/haddocks.sh directory [true|false]
 #
 # $1 - where to put the generated pages, this directory contents will be wiped
 #      out (so don't pass `/` or `./` - the latter will delete your 'dist-newstyle')
@@ -15,12 +15,21 @@
 #      (the default is true)
 # $3 - cabal build directory
 #      (the default is "dist-newstyle")
+# $4 - include documentation for sub-libraries
+#      (the default is true)
+# $5 - include documentation for test suites
+#      (the default is false)
+# $6 - include documentation for benchmark suites
+#      (the default is false)
 
 set -euo pipefail
 
 OUTPUT_DIR=${1:-"./docs/haddocks"}
 REGENERATE=${2:-"true"}
 BUILD_DIR=${3:-"dist-newstyle"}
+INCLUDE_SUBLIBS=${4:-"true"}
+INCLUDE_TESTS=${5:-"false"}
+INCLUDE_BENCHMARKS=${6:-"false"}
 
 # the directory containing this script
 SCRIPTS_DIR=$(realpath $(dirname $(realpath $0)))
@@ -67,13 +76,29 @@ for dir in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}"); do
   package=$(echo "${dir}" | sed 's/-[0-9]\+\(\.[0-9]\+\)*//')
   cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/noopt/doc/html/${package}" ${OUTPUT_DIR}
   # copy test packages documentation when it exists
-  if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t" ]; then
+  if [ ${INCLUDE_TESTS} == "true" ] && [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t" ]; then
       for test_package in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t"); do
           if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t/${test_package}/noopt/doc/html/${package}/${test_package}" ]; then
               cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t/${test_package}/noopt/doc/html/${package}/${test_package}" "${OUTPUT_DIR}/${package}-${test_package}"
           fi
       done
   fi
+  # copy benchmark packages documentation when it exists
+  if [ ${INCLUDE_BENCHMARKS} == "true" ] && [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/b" ]; then
+      for bench_package in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/b"); do
+          if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/b/${bench_package}/noopt/doc/html/${package}/${bench_package}" ]; then
+              cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/b/${bench_package}/noopt/doc/html/${package}/${bench_package}" "${OUTPUT_DIR}/${package}-${bench_package}"
+          fi
+      done
+  fi
+  # copy sublib documentation when it exists
+  if [ ${INCLUDE_SUBLIBS} == "true" ] && [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l" ]; then
+      for sublib in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l"); do
+          if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l/${sublib}/noopt/doc/html/${package}" ]; then
+              cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l/${sublib}/noopt/doc/html/${package}" "${OUTPUT_DIR}/${package}-${sublib}"
+          fi
+      done
+  fi
 done