Fix broken cross-package Haddock links on hosted docs site

Fixes #601. Links to dependency packages (cardano-ledger-*, plutus-*,
etc.) were relative paths pointing to directories that don't exist on
the hosted site, resulting in 404s.

Add a post-processing script that rewrites these relative links to
absolute URLs pointing at the correct external documentation sites.

Author: Jimbo4350

.github/workflows/github-page.yml

@@ -41,6 +41,10 @@ jobs:
           mkdir website
           cabal haddock-project --output=./website --internal --foreign-libraries
 
+      - name: Fix cross-package Haddock links
+        run: |
+          ./scripts/fix-haddock-links.sh ./website
+
       - name: Build typedoc documentation
         run: |
           nix build .#wasm-typedoc

scripts/fix-haddock-links.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# fix-haddock-links.sh
+#
+# Rewrites relative cross-package Haddock links in generated HTML to point
+# at the correct external documentation sites. Without this, links to
+# dependencies (cardano-ledger-*, plutus-*, etc.) are broken 404s because
+# the hosted site only contains docs for packages in this repo.
+#
+# Usage: ./scripts/fix-haddock-links.sh <website-directory>
+
+set -euo pipefail
+
+WEBSITE_DIR="${1:?Usage: $0 <website-directory>}"
+
+if [ ! -d "$WEBSITE_DIR" ]; then
+  echo "Error: $WEBSITE_DIR is not a directory" >&2
+  exit 1
+fi
+
+# Mapping of package-name-prefix -> base URL
+# Each entry is: "prefix|base_url"
+# The generated links look like: ../PACKAGE/Module.html
+# We rewrite them to:            BASE_URL/PACKAGE/Module.html
+PACKAGE_URLS=(
+  # cardano-ledger repo packages
+  "cardano-crypto-wrapper|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-data|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-allegra|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-alonzo|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-api|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-babbage|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-binary|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-byron|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-conway|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-core|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-dijkstra|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-mary|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-ledger-shelley|https://cardano-ledger.cardano.intersectmbo.org"
+  "cardano-protocol-tpraos|https://cardano-ledger.cardano.intersectmbo.org"
+  "small-steps|https://cardano-ledger.cardano.intersectmbo.org"
+
+  # cardano-base repo packages
+  "cardano-binary|https://base.cardano.intersectmbo.org"
+  "cardano-crypto-class|https://base.cardano.intersectmbo.org"
+  "cardano-crypto-praos|https://base.cardano.intersectmbo.org"
+  "cardano-slotting|https://base.cardano.intersectmbo.org"
+  "cardano-strict-containers|https://base.cardano.intersectmbo.org"
+
+  # plutus repo packages
+  "plutus-core|https://plutus.cardano.intersectmbo.org/haddock/latest"
+  "plutus-ledger-api|https://plutus.cardano.intersectmbo.org/haddock/latest"
+
+  # ouroboros-consensus repo packages
+  "ouroboros-consensus|https://ouroboros-consensus.cardano.intersectmbo.org/haddocks"
+
+  # ouroboros-network repo packages
+  "cardano-diffusion|https://ouroboros-network.cardano.intersectmbo.org"
+
+  # io-sim repo packages
+  "io-classes|https://input-output-hk.github.io/io-sim"
+
+)
+
+# Hackage packages use a different URL structure:
+#   ../base/Data-Bool.html -> https://hackage.haskell.org/package/base/docs/Data-Bool.html
+# The package name directory is replaced by /package/<pkg>/docs/
+HACKAGE_PACKAGES=(
+  base
+  bytestring
+  containers
+  deepseq
+  mtl
+  ghc-internal
+)
+
+# Build a single sed expression that handles all rewrites.
+# Links appear in two forms depending on module nesting depth:
+#   href="../PACKAGE/Module.html..."       (from top-level: cardano-api/Foo.html)
+#   href="../../PACKAGE/Module.html..."    (from internal:  cardano-api/internal/Foo.html)
+SED_ARGS=()
+for entry in "${PACKAGE_URLS[@]}"; do
+  pkg="${entry%%|*}"
+  url="${entry##*|}"
+  SED_ARGS+=(-e "s|href=\"\\.\\./${pkg}/|href=\"${url}/${pkg}/|g")
+  SED_ARGS+=(-e "s|href=\"\\.\\./\\.\\./${pkg}/|href=\"${url}/${pkg}/|g")
+done
+
+for pkg in "${HACKAGE_PACKAGES[@]}"; do
+  SED_ARGS+=(-e "s|href=\"\\.\\./${pkg}/|href=\"https://hackage.haskell.org/package/${pkg}/docs/|g")
+  SED_ARGS+=(-e "s|href=\"\\.\\./\\.\\./${pkg}/|href=\"https://hackage.haskell.org/package/${pkg}/docs/|g")
+done
+
+echo "Fixing cross-package Haddock links in $WEBSITE_DIR..."
+
+find "$WEBSITE_DIR" -name '*.html' -print0 | xargs -0 -P "$(nproc)" sed -i "${SED_ARGS[@]}"
+
+TOTAL=$(( ${#PACKAGE_URLS[@]} + ${#HACKAGE_PACKAGES[@]} ))
+echo "Done. Rewrote links for $TOTAL external packages."