proarrow-0.4.0.0: mkdocs.sh

#!/usr/bin/env bash
set -e

: "${CABAL:=cabal}"
: "${HADDOCK:=haddock}"
: "${ARG_COMPILER:=}"
# Where the "Contents" link at the top of each page goes. Empty means the index.html generated
# below (GitHub Pages); hackage-docs.sh sets it to ../, Hackage's own package page.
: "${USE_CONTENTS:=}"

python3 -m unittest discover -s tools/haddock

# The optics lattice diagram (Proarrow.Optics) is generated from lattice.dot:
#   dot -Tsvg lattice.dot -o lattice.svg
rm -rf docs
mkdir docs
# copy the optics lattice image next to the module HTML so Haddock's <<lattice.svg>> resolves
cp lattice.svg docs/

# Audio examples accompany the GitHub Pages docs. Hackage uses its own contents page.
if [ -z "$USE_CONTENTS" ]; then
  ${CABAL} run exe:smc-audio ${ARG_COMPILER} -- docs/audio || exit $?
fi

# Both libraries render into one doc tree (Hackage has a single documentation set per package).
# This is hand-rolled rather than `cabal haddock-project` because that documents the whole
# project (proarrow-equipment included), nests pages per component (breaking published URLs and
# the flat tree `cabal upload --documentation` expects). One invocation renders each library
# once; the source-link template names src/, and the testing modules are pointed at testing/
# below, where the per-entity links are corrected anyway.
${CABAL} haddock lib:proarrow lib:testing ${ARG_COMPILER} \
  --haddock-hyperlink-source \
  --haddock-html-location='https://hackage.haskell.org/package/$pkg-$version/docs' \
  --haddock-options="
    --comments-base=https://github.com/sjoerdvisscher/proarrow/
    --comments-module=https://github.com/sjoerdvisscher/proarrow/blob/main/proarrow/src/%{MODULE/.//}.hs
    --comments-entity=https://github.com/sjoerdvisscher/proarrow/blob/main/proarrow/src/%{MODULE/.//}.hs#L%L
    --pretty-html
    ${USE_CONTENTS:+--use-contents=${USE_CONTENTS}}
    --odir=docs"

# The build plan locates the interfaces in this checkout, CI's unpacked packages, or a custom builddir.
python3 tools/haddock/interfaces.py ${ARG_COMPILER}

# regenerate the contents and index pages covering both libraries
${HADDOCK} --gen-contents --gen-index -o docs --title=proarrow ${USE_CONTENTS:+--use-contents=${USE_CONTENTS}} \
  --read-interface=,docs/proarrow.haddock \
  --read-interface=,docs/testing.haddock

# A partial contents page must not be published.
python3 tools/haddock/interfaces.py --check-index

# the testing modules live under testing/, not src/
grep -rl 'proarrow/src/Proarrow/Testing' docs | xargs perl -pi -e 's|proarrow/src/(Proarrow/Testing[^"]*\.hs)|proarrow/testing/$1|g'

# the testing pages link to the main library's modules via hackage; make those links local
grep -rl 'hackage.haskell.org/package/proarrow-' docs | xargs perl -pi -e 's|https://hackage.haskell.org/package/proarrow-[0-9.]+/docs/||g'

grep -rilE '>(User )?Comments<' docs | xargs perl -pi -e 's/>(User )?Comments</>Github</gi'

# haddock's --comments-entity links use the page's module and the enclosing declaration's line;
# make each one agree with the Source link beside it
python3 fix-github-links.py docs https://github.com/sjoerdvisscher/proarrow/blob/main/proarrow/