Haddocks are missing for re-exported modules (in particular, at https://hackage.haskell.org/package/Cabal-3.8.1.0)

[Mikolaj]

That happens both with Hackage-generated haddocks and manually generated. A workaround (extra flags? a scripts that copies haddocks over module-by-module?) would be acceptable, but ideally we'd find a better solution. Preferably, the solution should not require changes to how the package creator re-exports modules, unless that's unavoidable and well documented.

[Mikolaj]

Does this give a solution haskell/haddock#547? Could somebody research and experiment?

[ulysses4ever]

Quick skimming suggests that a workaround may be to use v1-haddock. This doesn’t sound fun of course.

[ulysses4ever]

@Mikolaj I think I can't reproduce it. Could you describe more precisely what you're doing. E.g. which version of cabal-install you use to build the docs and the command-line arguments. With versions I tried so far, I more or less consistently get:

1. With cabal haddock --enable-doc it builds fine and I get something like this (links to Cabal-syntax are not correct but that's expected).

2. With cabal haddock --enable-doc --haddock-for-hackage I get the dreaded Generating haddocks sometimes produces "doc-index.json does not exist" #8326 — even on cabal master, and I'm not sure what to do about it. That's GHC 9.2.3 (and its haddock).

[ulysses4ever]

With cabal master and GHC 9.4.1 --haddock-for-hackage works as well producing this tar.gz (not sure how to render it: the tar has a bunch of HTML files but I don't see the "Contents" page).

[Mikolaj]

@ulysses4ever: I used cabal 3.8.1.0 and almost the standard commandline from the bottom of https://hackage.haskell.org/upload, which I think Hackage doc builder uses as well (and gets the missing links):

cabal haddock --builddir=dir --haddock-for-hackage --enable-doc

However, I think --enable-doc is not needed any more and there is #8104 that says --hyperlinked-source --quickjump is required, so the invocation might have been:

cabal haddock  --builddir=dir  --haddock-options=--quickjump --haddock-for-hackage

Let me know and I will try to reproduce locally. I might have used GHC 8.10.7 or older to avoid #8326, though I write there this is fixed?

[Mikolaj]

Interestingly, the same documentation in https://downloads.haskell.org/ghc/latest/docs/libraries/index.html doesn't have the problem of ignored re-exported modules. Does anybody know where the script that generates that documentation is (e.g., inside hadrian configs in the GHC build tree somewhere)? What special flags are used in there? @bgamari maybe?

[bgamari]

The rule can be found here. The flags which this rule produces are defined here.

[Mikolaj]

Thank you. I can see

--html
--hyperlinked-source
--hoogle
--quickjump

so that's more than I listed above and also more than what Hackage uses (and what Hackage recommends on the upload file, which I hope is the same). Does --read-interface mean that the haddocks are taken from .hi files instead of parsed from source? Perhaps that would explain why it works fine in GHC docs?

[ulysses4ever]

On the Cabal meeting this week it was suggested that this qualifies as an upstream problem. Please, feel free to raise an objection if you think it's wrong. We'd love to hear from someone with a haddock/ghc-side-of-things perspective.

[Mikolaj]

@gbaz says: "<s​clv> we could teach haddock to generate docstubs for rexported modules that just say where they are re-exported from, and that might suffice as a start, then later teach hackage-server to make use of that to find links.
<s​clv> alternately, we could teach just hackage-server to pull out re-exported modules to a distinct section of the displaytree or maybe make them a smaller font to indicate what's going on"