From 502936166055f1639d8a17dc649c6d04ac44ec5f Mon Sep 17 00:00:00 2001
From: Wen Kokke <wenkokke@users.noreply.github.com>
Date: Wed, 30 Apr 2025 10:27:02 +0100
Subject: [PATCH] doc: include package description on GitHub Pages

---
 .github/workflows/ci.yml             |  2 +-
 scripts/generate-haddock-prologue.hs | 49 ++++++++++++++++++++++++++++
 scripts/generate-haddock.sh          | 20 ++++++++++++
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100755 scripts/generate-haddock-prologue.hs
 create mode 100755 scripts/generate-haddock.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 77b88aca9..e5031f644 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -143,7 +143,7 @@ jobs:
 
     - name: 🏗️ Build documentation
       if: ${{ matrix.cabal-documentation }}
-      run: cabal haddock-project
+      run: ./scripts/generate-haddock.sh
 
     - name: 📦 Upload documentation
       if: ${{ matrix.cabal-documentation }}
diff --git a/scripts/generate-haddock-prologue.hs b/scripts/generate-haddock-prologue.hs
new file mode 100755
index 000000000..cc2050b77
--- /dev/null
+++ b/scripts/generate-haddock-prologue.hs
@@ -0,0 +1,49 @@
+#!/usr/bin/env cabal
+{- cabal:
+build-depends:
+    , base          >=4.16
+    , bytestring    >=0.11
+    , Cabal-syntax ^>=3.10  || ^>=3.12
+    , pandoc       ^>=3.6.4
+    , text          >=2.1
+-}
+{-# LANGUAGE LambdaCase #-}
+
+module Main (main) where
+
+import qualified Data.ByteString as BS
+import           Data.Text (Text)
+import qualified Data.Text as T
+import qualified Data.Text.IO as TIO
+import           Distribution.PackageDescription.Parsec
+                     (parseGenericPackageDescriptionMaybe)
+import qualified Distribution.Types.GenericPackageDescription as GenericPackageDescription
+import qualified Distribution.Types.PackageDescription as PackageDescription
+import           Distribution.Utils.ShortText (fromShortText)
+import           System.IO (hPutStrLn, stderr)
+import           Text.Pandoc (runIOorExplode)
+import           Text.Pandoc.Extensions (githubMarkdownExtensions)
+import           Text.Pandoc.Options (ReaderOptions (..), WriterOptions (..),
+                     def)
+import           Text.Pandoc.Readers (readHaddock, readMarkdown)
+import           Text.Pandoc.Transforms (headerShift)
+import           Text.Pandoc.Writers (writeHaddock)
+
+main :: IO ()
+main = do
+    putStrLn "Generating prologue.haddock from package description..."
+    let readmeHeaderFile = "scripts/generate-readme-header.md"
+    readmeHeaderContent <- TIO.readFile readmeHeaderFile
+    let lsmTreeCabalFile = "lsm-tree.cabal"
+    lsmTreeCabalContent <- BS.readFile lsmTreeCabalFile
+    case parseGenericPackageDescriptionMaybe lsmTreeCabalContent of
+        Nothing -> hPutStrLn stderr $ "error: Could not parse '" <> lsmTreeCabalFile <> "'"
+        Just genericPackageDescription -> do
+            let packageDescription = GenericPackageDescription.packageDescription genericPackageDescription
+            let description = T.pack . fromShortText $ PackageDescription.description packageDescription
+            header <-
+                runIOorExplode $ do
+                    doc <- readMarkdown def{readerExtensions = githubMarkdownExtensions} readmeHeaderContent
+                    writeHaddock def doc
+            let prologue = T.unlines [header, description]
+            TIO.writeFile "prologue.haddock" prologue
diff --git a/scripts/generate-haddock.sh b/scripts/generate-haddock.sh
new file mode 100755
index 000000000..0a71bad3e
--- /dev/null
+++ b/scripts/generate-haddock.sh
@@ -0,0 +1,20 @@
+#!/bin/sh
+
+# Check for cabal
+cabal="$(which cabal)"
+if [ "${cabal}" = "" ]; then
+    echo "Requires cabal; no version found"
+    exit 1
+fi
+
+# Extract the prologue from the package description
+SCRIPTS_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+"${SCRIPTS_DIR}/generate-haddock-prologue.hs" || exit 1
+
+# Build haddock-project documentation
+cabal haddock-project --prologue="prologue.haddock"
+
+# Clean up prologue
+if [ -f "./prologue.haddock" ]; then
+    rm ./prologue.haddock
+fi