doc: include package description on GitHub Pages

Author: wenkokke

.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 }}

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

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