Specifically, the Hackage docs for these packages lack hyperlinks to types and functions in the monoidmap package, such as MonoidMap or MonoidMap.fromMap. Hyperlinks to types and functions in other packages are unaffected – the problem seems specific to monoidmap. But when I build the same docs locally (with cabal haddock), hyperlinks to all packages (including monoidmap) are generated just fine!
Compare the following docs for Data.MonoidMap.Aeson from monoidmap-aeson:
Since this issue only happens on Hackage, I’d like to understand what’s different about how Hackage generates the documentation. I checked the Hackage build logs for monoidmap-aeson, but all I see is this error (not sure if it’s relevant):
Resolving dependencies...
Error: Internal libraries only supported with per-component builds.
Per-component builds were disabled because program coverage is enabled
In the package 'vector-0.13.2.0'
I’m curious:
Has anyone else encountered similar issues on Hackage, where links are generated to some packages but not to others?
Is it possible to access a more detailed build log for Haddock on Hackage to diagnose what’s happening?
When I run cabal haddock locally, I get a much more detailed log along with a coverage summary. For example: GitHub Actions log.
Obviously, one workaround would be to manually upload documentation (with working hyperlinks) to Hackage, but I’d much rather fix the root of the problem.
If anyone has any insights to share, I’d be truly grateful—many thanks!
I’m aware of that Hackage issue, but I don’t think it quite explains what I’m seeing.
As far as I can tell, I’m not re-exporting any modules—I’m just trying to create very ordinary Haddock hyperlinks from package a to types and functions in the public API of package b.
The odd discrepancy I’m seeing in the docs for monoidmap-aeson:
Hyperlinks are created to types and functions from packages like aeson.
Hyperlinks are not created to types and functions from monoidmap.
Here’s a screenshot illustrating the issue—identifiers like ToJSON, encode, and Sum are hyperlinked, but MonoidMap and fromList are not:
I initially suspected that I’d been using the wrong syntax. However, when I run cabal haddock locally, it runs without warnings and has no trouble generating hyperlinks. See: Data.MonoidMap.JSON
Since this behaviour is specific to Hackage, I’m really keen to understand what’s going wrong here, so I can try to fix it!
In particular, if there’s a way to access more detailed logs from Hackage, perhaps that might help get to the bottom of it. Any insights would be greatly appreciated!
Hackage usescabal v1-install --enable-documentation to build Haddocks. However, v1- commands cannot quite cope with internal libraries, such as ones in monoidmap package, thus missing hyperlinks.
I guess one solution is to make monoidmap-internal (where core types and functions are defined) into a separate package, with its own independent PVP-compliant versioning.
Then monoidmap would have its responsibility reduced to just re-exporting supported types and functions.
I see this pattern is used by the bluefin and bluefin-internal packages, with the latter using {-# OPTIONS_HADDOCK not-home #-} in its modules.
I guess the alternative is to wait for Hackage to upgrade to using v2- commands (or to contribute to the upgrade work). Though I’m guessing it’s a fairly non-trivial piece of work!
Yes
No