Haddocks

.github/workflows/github-page.yml

@@ -0,0 +1,117 @@
+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=grFfw8r" >> $GITHUB_ENV
+
+    - name: Add build script path
+      run: echo "$(pwd)/.github/bin" >> $GITHUB_PATH
+
+    - name: Configure to use libsodium
+      run: |
+        cat >> cabal.project <<EOF
+        package cardano-crypto-praos
+          flags: -external-libsodium-vrf
+        EOF
+
+    - 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: 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: Use cabal.project.local.github-pages
+      run: |
+        cat ./cabal.project.local.github-pages >> ./cabal.project.local
+        cat ./cabal.project.local
+
+    - 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 diff
+    #     echo "========="
+    #     git add .
+    #     git stash
+    #     echo "========="
+    #     ls
+    #     echo "========="
+    #     git fetch origin gh-pages:gh-pages
+    #     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,95 @@
+#!/bin/bash
+# Build haddock documentation and an index for all projects in
+# `ouroboros-network` 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 "ouroboros-network" \
+  --package-name "Ouroboros-Network & Ouroboros-Consensus" \
+  --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,65 @@
+= Ouroboros-Network Repository Hackage Documentation
+
+[skip to module list](#module-list)
+
+This site contains Haskell documentation of
+
+* __Ouroboros-Network__  - networking component of the Haskell implementation of Ouroboros protocols
+* __Ouroboros-Consensus__ - Ouroboros Consensus family of protocol which integrate with `Ouroboros-Network`
+
+== Module Structure And Network Components
+
+* __IOSim & Monad Classes__
+
+    * __[io-sim](io-sim/Control-Monad-IOSim.html)__ - `IOSim` moand which
+      allows us to test networking code in simulation.
+    * __[io-sim-classes](#n.2.1.1)__ - abstract classes under 'Control.Monad.Class' which
+      allow to use real `IO` or the `SimIO` monad in a polymorphic way.
+
+* __Network__ - low level networking libraries, independent of our choices
+
+    * __Win32-network__
+    * __[typed-protocols](typed-protocols/Network-TypedProtocol.html)__
+    * __[network-mux](network-mux/Network-Mux.html)__
+
+* __Ouroboros.Network__
+
+    * __ouroboros-network-framework__ - our instantiations and implementation
+      of servers, clients, abstractions for working with named pipes and unix
+      sockets.  These are higher level components, which don't dependent on
+      ouroboros protocols, but build a solid foundation for the networking
+      library
+
+    * __ouroboros-network__ - networking library which supports /Ouroboros family
+        of protocols/. It includes:
+
+          * /Implementations, type level specifications, and api of all the protocols:/
+
+              * __[ChainSync](ouroboros-network/Ouroboros-Network-Protocol-ChainSync-Type.html)__
+              * __[BlockFetch](ouroboros-network/Ouroboros-Network-Protocol-BlockFetch-Type.html)__
+              * __[TxSubmission](ouroboros-network/Ouroboros-Network-Protocol-TxSubmission-Type.html)__
+              * __[LocalTxSubmission](ouroboros-network/Ouroboros-Network-Protocol-LocalTxSubmission-Type.html)__
+              * __[LocalStateQuery](ouroboros-network/Ouroboros-Network-Protocol-LocalStateQuery-Type.html)__
+              * __[LocalTxMonitor](ouroboros-network/Ouroboros-Network-Protocol-LocalTxMonitor-Type.html)__
+              * __[Handshake](ouroboros-network-framework/Ouroboros-Network-Protocol-Handshake-Type.html)__
+
+         * /Block chain related data structures that the networking code needs
+           to be aware of:/
+
+              * __[Block](ouroboros-network/Ouroboros-Network-Block.html)__
+              * __[AnchoredFragment](ouroboros-network/Ouroboros-Network-AnchoredFragment.html)__
+
+         * /Network applications:/
+
+              * __[Block Fetch Application](ouroboros-network/Ouroboros-Network-BlockFetch.html)__
+              * __Tx Submission Applications__:
+
+                  * __[inbound](ouroboros-network/Ouroboros-Network-TxSubmission-Inbound.html)__
+                  * __[outbound](ouroboros-network/Ouroboros-Network-TxSubmission-Outbound.html)__
+
+              * __[Peer Selection](ouroboros-network/Ouroboros-Network-PeerSelection-Governor.html)__
+              * __[Data Diffusion](ouroboros-network/Ouroboros-Network-Diffusion.html)__ which combines all the pieces for supporting
+                a [node](https://github.com://input-output-hk/cardano-node)
+              * __[NodeToNode API](ouroboros-network/Ouroboros-Network-NodeToNode.html)__
+              * __[NodeToClient API](ouroboros-network/Ouroboros-Network-NodeToClient.html)__
+