BuildClient: docs uploads for multi-library packages are rejected by checkDocTarball; switch to cabal haddock --haddock-for-hackage #1523

Hackage's documentation builder (exes/BuildClient.hs) cannot publish documentation for any package with sub-libraries. The v1-based docs build does generate the haddocks of all the libraries of a package, but the hand-packed tarball contains the Hoogle description files haddock writes for sub-libraries, named <pkg>:<sublib>.txt (GHC MR !16706). Since the stricter upload validation was deployed, checkDocTarball rejects these tarballs:

Invalid windows file name in tar archive:
"happy-lib-2.0-docs\\backend-glr\\happy-lib:backend-glr.txt"

So for packages like haskell-debugger (dap-server), happy-lib (five internal libraries) or hackage-cli (cabal-revisions), Hackage ends up with no documentation at all. See haskell/cabal#10973 (first report of the rejected upload) and haskell/cabal#12364.

It might be worth solving the problem this way #1522

buildPackage now runs the current v2 flow in the unpacked package's project (the same project v2-test already uses):

cabal haddock all --haddock-for-hackage --build-summary=<results>/<pkgid>.report

and uploads the tarball cabal produces, instead of hand-packing the htmldir tree. --haddock-for-hackage bakes in the same hosting URLs the client used to pass explicitly (/package/$pkg-$version(/docs)), and implies html, hoogle, hyperlinked source and quickjump. Build reports (install-outcome gating for the test step), logs, --prune-haddock-files (unpack → prune → repack) and --dry-run are preserved.

Requirements: the builder's toolchain must ship the haddock fix from GHC MR !16706 (with an older haddock, checkDocTarball rejects the builder's own uploads for multi-library packages — that is the status quo).

Known limitation

Libraries whose only modules are re-exports are currently not haddocked by the v2 flow (cabal's hasValidHaddockTargets gate; see haskell/cabal#10368), so for such packages the tarball has no root index.html. All sub-library haddocks are present and the tarball passes validation — strictly better than the status quo, but the cabal-side gate should ideally be relaxed too.