`stack haddock` generates incorrect relative links

[nicuveo]

Overview

When running stack haddock in a project, the generated documentation uses incorrect relative links for re-exported packages in the index file. This seems to be caused by the wrong argument being given to the -i option when invoking Haddock.

Steps to reproduce

Create a trivial project, like so:

# stack.yaml
snapshot:
  url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/24/34.yaml
packages:
  - .

# package.yaml
dependencies:
  - base

library:
  source-dirs: lib

Then run stack haddock. Then open the documentation at file:///<project>/.stack-work/install/<platform>/<hash>/<ghc>/doc/all/index.html.

In it, all links to modules in base are incorrect. For instance, the link for Data.Eq points to doc/base-4.20.2.0-127e/Data-Eq.html. The base-4.20.2.0-127e folder does not exist, but base-4.20.2.0 does.

Running stack haddock --verbose reveals that the all documentation was generated with the following call to haddock (i have replaced parts of the path with $HOME and $PROJECT to try to make it a tiny bit less verbose, but it's still a lot, sorry):

$HOME/.ghcup/ghc/9.10.3/bin/haddock-ghc-9.10.3 \
  --optghc=-package-db=$HOME/.stack/snapshots/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/pkgdb \
  --optghc=-package-db=$HOME/$PROJECT/.stack-work/install/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/pkgdb \
  --gen-contents \
  --gen-index \
  -i ../ghc-internal-9.1003.0-a65c,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-internal-9.1003.0-a65c/ghc-internal.haddock \
  -i ../haddock-issue-0.0.0,$HOME/$PROJECT/.stack-work/install/x86_64-linux/8a23ab0f4c447aa1863c20e527e4f2aeeec2f0c3c2ab9fbe859c65d4c711ecc7/9.10.3/doc/haddock-issue-0.0.0/haddock-issue.haddock \
  -i ../ghc-bignum-1.3-9ca9,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-bignum-1.3-9ca9/ghc-bignum.haddock \
  -i ../base-4.20.2.0-127e,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/base-4.20.2.0-127e/base.haddock \
  -i ../ghc-prim-0.12.0-d0f9,$HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/ghc-prim-0.12.0-d0f9/ghc-prim.haddock

The key element is that the argument to -i is incorrect. Note, for instance, that for base, the argument is as follows: -i ../base-4.20.2.0-127e,path/to/base.haddock. Re-running the command, but will the argument to -i changed to not include the prefix fixes all relative links in the generated documentation.

Stack version

$ stack --version
Version 3.9.3, Git revision c7eb8487a82d5c3e0b88d56f8b8a98be23223eb5 x86_64 hpack-0.39.1

[nicuveo]

At a glance, it looks like the arguments to -i are generated by iterating on a list of interfaces and checking that the directory exist; since the directory for, say, base, is indeed $HOME/.ghcup/ghc/9.10.3/lib/ghc-9.10.3/lib/../../../share/doc/ghc-9.10.3/html/libraries/base-4.20.2.0-127e/base.haddock, which contains the suffix, that would explain how we end up with it in the option.

A trivial fix would be to drop the version suffix right there, in Stack.Build.Haddock, but this might just mask the underlying issue?

[mpilgrem]

@nicuveo, thanks for reporting. I need to investigate but I wonder if it is related to this GHC bug:

• Post-GHC 9.6.7, links between GHC boot packages fail in Haddock documentation #6807

[nicuveo]

ah, yeah, that seems likely, good catch!