Merge pull request #387 from teodanciu/td/haddock-gh-pages

Haddocks on Github Pages

.github/workflows/gh-pages.yml

@@ -0,0 +1,42 @@
+name: Github Pages
+
+on:
+  push:
+    branches: [ "master" ]
+  workflow_dispatch:
+
+jobs:
+  gh-pages:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install nix
+        uses: cachix/install-nix-action@v20
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= loony-tools:pr9m4BkM/5/eSTZlkQyRt57Jz7OMBxNSUiMC4FkcNfk=
+            substituters = https://cache.iog.io https://cache.nixos.org/ https://cache.zw3rk.com
+      - name: Build projects and haddocks
+        run: nix develop --command bash -c "cabal update && cabal build --enable-documentation all && ./scripts/haddocks.sh"
+      - name: Add files
+        run: |
+              git config --local user.name ${{ github.actor }}
+              git config --local user.email "${{ github.actor }}@users.noreply.github.com"
+              cp -r ./haddocks/* ./
+              rm -rf haddocks
+              git add -A --force
+              git commit -m "Updated"
+
+      - name: Push to gh-pages
+        uses: ad-m/[email protected]
+        with:
+            github_token: ${{ secrets.GITHUB_TOKEN }}
+            branch: gh-pages
+            force: true
+            directory: .
+

README.md

@@ -12,3 +12,5 @@ All releases for packages found in this repository are recorded in [Cardano Hask
 package repository](https://github.com/input-output-hk/cardano-haskell-packages)
 
 See the [wiki](https://github.com/input-output-hk/cardano-base/wiki) for more documentation.
+
+Haddock code documentation of the latest master branch is available [here](https://input-output-hk.github.io/cardano-base).

scripts/haddocks.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+
+# Build haddock documentation and an index for all projects in
+# `cardano-base` repository.
+#
+# usage:
+# ./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')
+#      (the default is './haddocks')
+# $2 - whether to re-build haddocks with `cabal haddock` command or a component name
+#      (the default is true)
+#
+
+set -euo pipefail
+
+OUTPUT_DIR=${1:-"./haddocks"}
+REGENERATE=${2:-"true"}
+
+BUILD_DIR="dist-newstyle"
+GHC_VERSION=$(ghc --numeric-version)
+OS_ARCH="$(cat dist-newstyle/cache/plan.json | jq -r '.arch + "-" + .os' | head -n 1 | xargs)"
+
+
+# Generate  `doc-index.json` and `doc-index.html` per package, to assemble them later at the top level.
+HADDOCK_OPTS=(
+    --builddir "${BUILD_DIR}"
+    --haddock-all
+    --haddock-internal
+    --haddock-html
+    --haddock-quickjump
+    --haddock-hyperlink-source
+    --haddock-option "--show-all"
+    --haddock-option "--use-unicode"
+    --haddock-option="--base-url=.."
+  )
+
+# build documentation of all modules
+if [ ${REGENERATE} == "true" ]; then
+  cabal haddock "${HADDOCK_OPTS[@]}" all 
+elif [ ${REGENERATE} != "false" ]; then
+  cabal haddock "${HADDOCK_OPTS[@]}" ${REGENERATE}
+fi
+
+if [[ !( -d ${OUTPUT_DIR} ) ]]; then
+  mkdir -p ${OUTPUT_DIR}
+fi
+
+# make all files user writable
+chmod -R u+w "${OUTPUT_DIR}"
+
+# copy the new docs
+for dir in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}"); do
+  package=$(echo "${dir}" | sed 's/-[0-9]\+\(\.[0-9]\+\)*//')
+  if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/doc/html/${package}" ]; then
+    cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/doc/html/${package}" ${OUTPUT_DIR}
+  else continue;
+  fi
+  # copy test packages documentation when it exists
+  if [ -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}/doc/html/${package}/${test_package}" ]; then
+              cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/t/${test_package}/doc/html/${package}/${test_package}" "${OUTPUT_DIR}/${package}:${test_package}"
+              cp -n "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/doc/html/${package}"/{*.css,*.js}  "${OUTPUT_DIR}/${package}:${test_package}" && true
+          fi
+      done
+  fi
+  # copy lib packages documentation when it exists
+  if [ -d "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l" ]; then
+      for lib_package 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/${lib_package}/doc/html/${package}" ]; then
+              cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/l/${lib_package}/doc/html/${package}" "${OUTPUT_DIR}/${package}:${lib_package}"
+              cp -n "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/doc/html/${package}"/{*.css,*.js}  "${OUTPUT_DIR}/${package}:${lib_package}" && true
+          fi
+      done
+  fi
+done
+
+# build read-interface arguments for haddock
+interface_options () {
+    for package in $(ls "${OUTPUT_DIR}"); do
+        if [[ -d "${OUTPUT_DIR}/${package}" ]]; then
+            haddock_file=$(ls -1 ${OUTPUT_DIR}/${package}/*.haddock | head -1)
+            echo "--read-interface=${package},${haddock_file}"
+        fi
+  done
+}
+
+./scripts/mkprolog.sh ./haddocks ./scripts/prolog
+
+# Generate top level index using interface files
+haddock \
+  -o ${OUTPUT_DIR} \
+  --title "cardano-base" \
+  --package-name "Cardano Base" \
+  --gen-index \
+  --gen-contents \
+  --quickjump \
+  --prolog ./scripts/prolog \
+  $(interface_options)
+
+# Assemble a toplevel `doc-index.json` from package level ones.
+echo "[]" > "${OUTPUT_DIR}/doc-index.json"
+for file in $(ls $OUTPUT_DIR/*/doc-index.json); do
+  project=$(basename $(dirname $file));
+  jq -s \
+    ".[0] + [.[1][] | (. + {link: (\"${project}/\" + .link)}) ]" \
+    "${OUTPUT_DIR}/doc-index.json" \
+    ${file} \
+    > /tmp/doc-index.json
+  mv /tmp/doc-index.json "${OUTPUT_DIR}/doc-index.json"
+done

scripts/mkprolog.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+HADDOCKS_DIR=${1:-"./haddocks"}
+PROLOG_FILE=${2:-"./scripts/prolog"}
+
+> ${PROLOG_FILE}
+
+cat > ${PROLOG_FILE} << EOF
+= Cardano Ledger Repository Hackage Documentation
+
+[skip to module list](#module-list)
+
+This site contains Haskell documentation of:
+
+EOF
+
+for dir in $(ls ${HADDOCKS_DIR}); do
+  if [[ -d ${HADDOCKS_DIR}/${dir} ]]; then
+    link=$(echo "${dir}" | sed "s/:/%3A/g")
+    echo "* __[${dir}](${link}/index.html)__" >> ${PROLOG_FILE}
+  fi
+done