Build and publish haddocks to Github Pages.

.github/workflows/github-page.yml

@@ -0,0 +1,107 @@
+name: "Haddock documentation"
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    defaults:
+      run:
+        shell: bash
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ghc: ["8.10.2"]
+        os: [ubuntu-latest]
+
+    steps:
+    - uses: actions/checkout@v1
+
+    - name: Select build directory
+      run: |
+        CABAL_BUILDDIR=dist
+
+        echo "CABAL_BUILDDIR=$CABAL_BUILDDIR"
+        echo "CABAL_BUILDDIR=$CABAL_BUILDDIR" >> $GITHUB_ENV
+
+    - name: Set cache version
+      run: echo "CACHE_VERSION=myfzgX7" >> $GITHUB_ENV
+
+    - name: Add build script path
+      run: echo "$(pwd)/.github/bin" >> $GITHUB_PATH
+
+    - uses: haskell/actions/setup@v1
+      id: setup-haskell
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        cabal-version: 3.4.0.0-rc4
+
+    - name: Haskell versions
+      run: |
+        ghc --version
+        cabal --version
+
+    - name: Install build environment
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        sudo apt-get update
+        sudo apt-get -y install libsodium23 libsodium-dev
+        sudo apt-get -y install libsystemd0 libsystemd-dev
+        sudo apt-get -y remove --purge software-properties-common
+        sudo apt-get -y autoremove
+
+    - name: Cabal update
+      run: cabal update
+
+    - name: Use cabal.project.local.github-pages
+      run: |
+        cat ./cabal.project.local.github-pages >> ./cabal.project.local
+        cat ./cabal.project.local
+
+    - name: Cabal Configure
+      run: cabal configure --builddir="$CABAL_BUILDDIR" --write-ghc-environment-files=always
+
+    - name: Record dependencies
+      run: |
+        cat ${{ env.PLAN_JSON }} | jq -r '."install-plan"[].id' | sort | uniq > dependencies.txt
+
+    - uses: actions/cache@v2
+      name: Cache cabal store
+      with:
+        path: ${{ steps.setup-haskell.outputs.cabal-store }}
+        key: cache-${{ env.CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('dependencies.txt') }}
+        restore-keys: |
+          cache-${{ env.CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('dependencies.txt') }}
+          cache-${{ env.CACHE_VERSION }}-${{ runner.os }}-${{ matrix.ghc }}-
+
+    - name: Install dependencies
+      run: cabal build all --builddir="$CABAL_BUILDDIR" --only-dependencies
+
+    - name: Build Haddock documentation 🔧
+      run: |
+        mkdir ./haddocks
+        ./scripts/haddocs.sh ./haddocks true "$CABAL_BUILDDIR"
+
+    - name: Upload documentation
+      uses: actions/upload-artifact@v2
+      if: ${{ always() }}
+      continue-on-error: true
+      with:
+        name: haddocks-${{ matrix.os }}-${{ matrix.ghc }}
+        path: ./haddocks
+
+    - name: Deploy documentation to gh-pages 🚀
+      run: |
+        git fetch origin gh-pages:gh-pages
+        git config --local user.email "$(git show --format="%aN" | head -n 1)"
+        git config --local user.name  "$(git show --format="%aE" | head -n 1)"
+        git add .
+        git stash
+        git checkout gh-pages
+        cp -r ./haddocks/* ./
+        rm -rf haddocks
+        git add -A
+        git commit -m "Deployed haddocks" || true
+        git push https://${{ github.actor }}:${{ github.token }}@github.com/${{ github.repository }}.git HEAD:gh-pages

.gitignore

@@ -49,3 +49,7 @@ tmp
 logs
 /chairman/db
 /html
+
+# Ignore files generated by haddock
+/haddocks
+

cabal.project.local.github-pages

@@ -0,0 +1,4 @@
+package cardano-crypto-praos
+  flags: -external-libsodium-vrf
+
+tests: False

cardano-node-chairman/app/Cardano/Chairman/Commands/Run.hs

@@ -44,11 +44,11 @@ mkNodeClientProtocol protocol =
         (EpochSlots 21600)
 
 data RunOpts = RunOpts
-    -- | Stop the test after given number of seconds. The chairman will
+  { -- | Stop the test after given number of seconds. The chairman will
     -- observe only for the given period of time, and check the consensus
     -- and progress conditions at the end.
     --
-  { caRunningTime :: !DiffTime
+    caRunningTime :: !DiffTime
     -- | Expect this amount of progress (chain growth) by the end of the test.
   , caMinProgress :: !BlockNo
   , caSocketPaths :: ![SocketPath]

cardano-node-chairman/src/Test/Base.hs

@@ -4,10 +4,9 @@ module Test.Base
 
 import           Data.Function
 import           GHC.Stack (HasCallStack)
-import           Hedgehog (Property)
 
 import qualified Hedgehog as H
 import qualified Hedgehog.Extras.Test.Base as H
 
-integration :: HasCallStack => H.Integration () -> Property
+integration :: HasCallStack => H.Integration () -> H.Property
 integration = H.withTests 1 . H.propertyOnce

scripts/haddocs.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# Build haddock documentation and an index for all projects in the 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 - weahter to re-build haddocjs with `cabal haddock` command or a component name
+#      (the default is true)
+# $3 - cabal build directory
+#      (the default is "dist-newstyle")
+
+set -euo pipefail
+
+OUTPUT_DIR=${1:-"./haddocks"}
+REGENERATE=${2:-"true"}
+BUILD_DIR=${3:-"dist-newstyle"}
+
+GHC_VERSION=$(ghc --numeric-version)
+OS_ARCH="$(cat "$BUILD_DIR/cache/plan.json" | jq -r '.arch + "-" + .os' | head -n 1 | xargs)"
+
+
+# we don't include `--use-index` option, because then quickjump data is not
+# generated.  This is not ideal, but there is no way to generate only top level
+# `doc-index.html` file.  With this approach we get:
+# * `doc-index.json` and `doc-index.html` per package
+# * we can generate top level `doc-index.json` (which will only work at the top
+#   level).
+# * we could ammend package level `doc-index.json` files, but it's enough ...
+#   this should be fixed upstream.
+HADDOCK_OPTS=(
+    --builddir "${BUILD_DIR}"
+    --disable-optimization
+    --haddock-all
+    --haddock-internal
+    --haddock-html
+    --haddock-quickjump
+    --haddock-hyperlink-source
+    --haddock-option "--show-all"
+    --haddock-option "--use-unicode"
+    --haddock-option "--use-contents=\"../index.html\""
+  )
+
+# build documentation of all modules
+if [ ${REGENERATE} == "true" ]; then
+  cabal haddock "${HADDOCK_OPTS[@]}" cardano-api
+elif [ ${REGENERATE} != "false" ]; then
+  cabal haddock "${HADDOCK_OPTS[@]}" ${REGENERATE}
+fi
+
+if [[ !( -d ${OUTPUT_DIR} ) ]]; then
+  mkdir -p ${OUTPUT_DIR}
+fi
+
+# copy the new docs
+for noopt_dir in $(ls "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}"/noopt); do
+  dir="$(dirname "$noopt_dir")"
+  package=$(echo "${dir}" | sed 's/-[0-9]\+\(\.[0-9]\+\)*//')
+  cp -r "${BUILD_DIR}/build/${OS_ARCH}/ghc-${GHC_VERSION}/${dir}/noopt/doc/html/${package}" ${OUTPUT_DIR}
+done
+
+# --read-interface options
+interface_options () {
+  for package in $(ls "${OUTPUT_DIR}"); do
+    echo "--read-interface=${package},${OUTPUT_DIR}/${package}/${package}.haddock"
+  done
+}
+
+# Generate top level index using interface files
+#
+haddock \
+  -o ${OUTPUT_DIR} \
+  --title "cardano-node API" \
+  --package-name "Cardano Node API" \
+  --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/prolog

@@ -0,0 +1,7 @@
+= Cardano Node Repository Hackage Documentation
+
+[skip to module list](#module-list)
+
+This site contains Haskell documentation of
+
+* __[Cardano API](cardano-api/Cardano-API.html)__