Open Mikolaj opened 2 years ago
Does this give a solution https://github.com/haskell/haddock/pull/547? Could somebody research and experiment?
Quick skimming suggests that a workaround may be to use v1-haddock
. This doesn’t sound fun of course.
@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:
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).
With cabal haddock --enable-doc --haddock-for-hackage
I get the dreaded #8326 — even on cabal
master
, and I'm not sure what to do about it. That's GHC 9.2.3 (and its haddock).
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).
@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?
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?
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?
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.
@gbaz says: "<sclv> 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. <sclv> 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"
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.