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.
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,checkDocTarballrejects these tarballs:So for packages like
haskell-debugger(dap-server),happy-lib(five internal libraries) orhackage-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
buildPackagenow runs the current v2 flow in the unpacked package's project (the same projectv2-testalready uses):and uploads the tarball cabal produces, instead of hand-packing the htmldir tree.
--haddock-for-hackagebakes 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-outcomegating for the test step), logs,--prune-haddock-files(unpack → prune → repack) and--dry-runare preserved.Requirements: the builder's toolchain must ship the haddock fix from GHC MR !16706 (with an older haddock,
checkDocTarballrejects 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
hasValidHaddockTargetsgate; see haskell/cabal#10368), so for such packages the tarball has no rootindex.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.