Generate Haddocks in CI (#813)

Author: LaurentRDC

.github/workflows/build.yaml

@@ -17,24 +17,19 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # The 'cabal-flags' option is typically non-empty for new
-        # GHC releases, for which we may need `--allow-newer` flags
-        # while dependencies are updated.
         include:
           - ghc-version: "8.10.7"
-            duckdb: false
           - ghc-version: "9.0.2"
-            duckdb: false
           - ghc-version: "9.2.8"
-            duckdb: false
           - ghc-version: "9.4.8"
-            duckdb: false
           - ghc-version: "9.6.7"
             duckdb: true
           - ghc-version: "9.8.4"
             duckdb: true
           - ghc-version: "9.10.3"
             duckdb: true
+            # Only one GHC version should have 'upload-documentation: true'
+            upload-documentation: true
           - ghc-version: "9.12.2"
             duckdb: true
           - ghc-version: "9.14.1"
@@ -60,7 +55,8 @@ jobs:
     - name: Generate freeze file
       run: |
         cabal update
-        cabal configure --disable-optimization
+        # Building documentation is slightly more expensive, so we only enable it
+        cabal configure --disable-optimization ${{ matrix.upload-documentation && '--enable-doc' || '' }}
         cabal freeze
 
         # Exclude the timestamp of Hackage index update from our cache key, to
@@ -74,7 +70,7 @@ jobs:
         path: |
           dist-newstyle
           ${{ steps.setup-haskell.outputs.cabal-store }}
-        key: ${{ runner.os }}-${{ hashFiles('dependencies-versions', 'cabal.project.local') }}-cabal-install
+        key: ${{ runner.os }}-${{ hashFiles('dependencies-versions', 'cabal.project.local') }}-${{ matrix.upload-documentation && 'withdocs' || 'nodocs' }}-cabal-install
 
     - name: Install DuckDB artifact
       if: ${{ matrix.duckdb }}
@@ -101,7 +97,28 @@ jobs:
     - name: Run benchmarks
       if: ${{ matrix.duckdb }}
       run: |
-        BEAM_BENCH_ROWS=100000 cabal -v0 bench beam-backend-bench:beam-postgres && cabal -v0 bench beam-backend-bench:beam-sqlite && cabal -v0 bench beam-backend-bench:beam-duckdb
+        BEAM_BENCH_ROWS=100000 cabal -v0 bench beam-backend-bench:beam-postgres \
+          && cabal -v0 bench beam-backend-bench:beam-sqlite \
+          && cabal -v0 bench beam-backend-bench:beam-duckdb
+
+    # For releases, Haddock documentation may not be be automatically
+    # generated by Hackage due to missing dependencies (e.g. libduckdb, libpq).
+    #
+    # Therefore, we build Haddock documentation suitable for upload to Hackage, which are
+    # used when doing manual releases. We only do this for a single GHC version to reuse the work already done in
+    # this matrix entry.
+    - name: Build Haddock documentation for Hackage
+      if: ${{ matrix.upload-documentation }}
+      run: |
+        cabal haddock all --haddock-for-hackage
+
+    - name: Upload Haddock artifacts
+      if: ${{ matrix.upload-documentation && github.ref == 'refs/heads/master' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: ${{ runner.os }}-haddock-artifact
+        path: dist-newstyle/*-docs.tar.gz
+        retention-days: 7
 
   release-artifacts:
     # Only build release artifacts if `continuous-integration` is successful

RELEASE-CHECKLIST.md

@@ -7,4 +7,6 @@ For any given package that you want to release:
 [ ] Commit and push;
 [ ] Wait for the Github Actions pipeline to complete;
 [ ] Download the release artifacts from the build on Github Actions;
+[ ] Download the documentation artifacts from the build on Github Actions;
 [ ] Release to Hackage: `cabal upload --publish <release-artifact>`.
+[ ] Upload documentation to Hackage: `cabal upload --publish --documentation <documentation-artifact>`.