diff --git a/.github/workflows/github-page.yml b/.github/workflows/github-page.yml new file mode 100644 index 00000000000..18a939983d6 --- /dev/null +++ b/.github/workflows/github-page.yml @@ -0,0 +1,109 @@ +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 < 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" + + - uses: actions/upload-artifact@v2 + if: ${{ always() }} + continue-on-error: true + with: + name: haddocks-${{ matrix.os }}-${{ matrix.ghc }} + path: ./haddocks + + - name: deploy to gh-pages 🚀 + run: | + 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 diff --git a/.gitignore b/.gitignore index f41a1c40980..55eb529fda4 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,7 @@ tmp logs /chairman/db /html + +# Ignore files generated by haddock +/haddocks + diff --git a/cabal.project.local.github-pages b/cabal.project.local.github-pages new file mode 100644 index 00000000000..8793caa23b7 --- /dev/null +++ b/cabal.project.local.github-pages @@ -0,0 +1,4 @@ +package cardano-crypto-praos + flags: -external-libsodium-vrf + +tests: False diff --git a/cardano-node-chairman/app/Cardano/Chairman/Commands/Run.hs b/cardano-node-chairman/app/Cardano/Chairman/Commands/Run.hs index ce1efe98c93..bf92e7be270 100644 --- a/cardano-node-chairman/app/Cardano/Chairman/Commands/Run.hs +++ b/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] diff --git a/cardano-node-chairman/src/Test/Base.hs b/cardano-node-chairman/src/Test/Base.hs index 55d8243fb9f..43e171ce22a 100644 --- a/cardano-node-chairman/src/Test/Base.hs +++ b/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 diff --git a/github-page.yml b/github-page.yml new file mode 100644 index 00000000000..b552af36bef --- /dev/null +++ b/github-page.yml @@ -0,0 +1,126 @@ +name: "Haddock documentation" + +on: + push: + schedule: + - cron: '0 0 * * *' + +jobs: + haddocks: + name: "Haddocks" + + 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: | + if [ "$OS" == Windows_NT ]; then + CABAL_BUILDDIR="D:\\a\\_temp\\dist" + else + CABAL_BUILDDIR="dist-newstyle" + fi + + echo "CABAL_BUILDDIR=$CABAL_BUILDDIR" + echo "CABAL_BUILDDIR=$CABAL_BUILDDIR" >> $GITHUB_ENV + + - name: Install pkgconfiglite + if: matrix.os == 'windows-latest' + run: choco install -y pkgconfiglite + + - name: Install libsodium + if: matrix.os == 'windows-latest' + run: | + curl -Ls \ + --connect-timeout 5 \ + --max-time 10 \ + --retry 5 \ + --retry-delay 0 \ + --retry-max-time 40 \ + https://download.libsodium.org/libsodium/releases/libsodium-1.0.18-mingw.tar.gz -o libsodium-1.0.18-mingw.tar.gz + tar zxvf libsodium-1.0.18-mingw.tar.gz + + sed -i "s|/d/a/1/s/|D:/a/cardano-node/cardano-node/|g" libsodium-win64/lib/pkgconfig/libsodium.pc + + export PKG_CONFIG_PATH="$(readlink -f libsodium-win64/lib/pkgconfig)" + echo "PKG_CONFIG_PATH=$PKG_CONFIG_PATH" >> $GITHUB_ENV + + export LIBSODIUM_PATH="$(readlink -f libsodium-win64/bin | sed 's|^/d|D:|g' | tr / '\\')" + echo "LIBSODIUM_PATH=$LIBSODIUM_PATH" + echo "$LIBSODIUM_PATH" >> $GITHUB_PATH + + - name: Configure to use libsodium + run: | + cat >> cabal.project <> $GITHUB_ENV + echo 'TMP=${{ runner.temp }}' >> $GITHUB_ENV + + - uses: actions/cache@v2 + name: Cache cabal store + with: + path: ${{ steps.setup-haskell.outputs.cabal-store }} + key: cache-haddock-${{ runner.os }}-${{ matrix.ghc }}-v1-${{ hashFiles('cabal-cache.cabal') }}-${{ github.sha }} + restore-keys: | + cache-haddock-${{ runner.os }}-${{ matrix.ghc }}-v1-${{ hashFiles('cabal-cache.cabal') }}- + cache-haddock-${{ runner.os }}-${{ matrix.ghc }}-v1- + + - name: Update Hackage index + run: cabal update + + - name: Checkout ouroboros-network repository + uses: actions/checkout@v2 + + - name: Build dependencies + run: cabal --builddir="$CABAL_BUILDDIR" configure --enable-tests + + - 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 + + - name: deploy to gh-pages 🚀 + run: | + 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 diff --git a/scripts/haddocs.sh b/scripts/haddocs.sh new file mode 100755 index 00000000000..a0165c95fc5 --- /dev/null +++ b/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 diff --git a/scripts/prolog b/scripts/prolog new file mode 100644 index 00000000000..6979ba1de05 --- /dev/null +++ b/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)__ +