proarrow-0.1.0.0: mkdocs.sh

: "${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:=}"

# 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/

# 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), and has no per-component haddock options
# (the --comments-module source template differs between src/ and testing/).
# The testing sublibrary goes first: its dependency pass re-renders the main library with the
# wrong source-link template, and the main run afterwards overwrites those pages correctly.
${CABAL} haddock 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/testing/%{MODULE/.//}.hs
    --comments-entity=https://github.com/sjoerdvisscher/proarrow/blob/main/proarrow/testing/%{MODULE/.//}.hs#L%L
    --pretty-html
    ${USE_CONTENTS:+--use-contents=${USE_CONTENTS}}
    --odir=docs
    --dump-interface=docs/testing.haddock"

${CABAL} haddock lib:proarrow ${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
    --dump-interface=docs/proarrow.haddock"

# 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

# 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/