Generated Haddocks cannot link to stuff in Plutus

[kozross]

Area

[] Plutus Foundation Related to the GHC plugin, Haskell-to-Plutus compiler, on-chain code [X] Plutus Application Framework Related to the Plutus application backend (PAB), emulator, Plutus libraries [] Marlowe Related to Marlowe [] Other Any other topic (Playgrounds, etc.)

Summary

If you have Haddocks in your modules which refer to Plutus identifiers, these will fail to link when cabal new-haddock is used. This happens even in a Nix shell.

Steps to reproduce

Steps to reproduce the behavior:

1. Make a new project.
2. Add some Haddocks, which reference a Plutus identifier (for example, like so: 'ToData')
3. Run cabal new-haddock.
4. See errors indicating that link destinations couldn't be found.

Expected behavior

Link destinations should be findable if an identifier is properly imported.

System info (please complete the following information):

• OS: Arch
• Plutus commit 289ac956a33c14fe1d75d6c0a6d6100f96a7d22c

Additional context

This seems to go beyond just Plutus: I've had failures to link definitions of MonadReader and even Show.

[luigy]

cc @ElvishJerricco

[ElvishJerricco]

This issue has ended up being a bit more complicated than expected. Haskell.nix seems to have a couple of different issues with docs that pertain to e.g. not linking Show.

1. Haskell.nix creates derivations for haddocks that are separate from the actual package component builds, and then creates modified package dbs to point at these derivations. The most notable quirk I've found here is that non-reinstallable libs (base, etc) are simply never correctly pointed to by the dbs we use. We only ever get the package dbs for these libs from the main ghc output, whereas the docs are stored in a doc output.
2. Haskell.nix's shellFor function doesn't provide haddock-enabled package dbs, because it only provides the package dbs for the component builds themselves. So in nix-shell, haddock doesn't know where to find docs for Nix-provided packages.
3. cabal-install makes it kind of tricky to link docs from packages supplied as dependencies via cabal.project. In fact it makes it tricky for any non-local deps built by cabal-install.

[kozross]

@ElvishJerricco So I guess it means that the answer is 'cannot happen'? The cabal issue at least sounds like something that needs fixes outside of anything either Nix, or Plutus, controls.

[michaelpj]

1 seems like a haskell.nix bug, 2 seems like at least shellFor should have an option to pull in the Haddocks also, 3 might be an upstream issue.