How to get Haddock for Hackage to generate correctly?

Learn
1

There are a few resources I’ve found that point out how to generate Haddocks for Hackage:

They all say you should generate Haddocks with

cabal haddock ... --haddock-for-hackage --enable-doc

but when I do this half of the documentation is missing. Compare:

You can see that all the function documentation is missing from the latter. EDIT: I’ve now uploaded the fixed version, so it not longer exhibits the bad behaviour.

What’s weird is that when I run the cabal haddock command locally it also generates bluefin-internal documentation, because it’s a dependency, and that documentation is correct. Now bluefin just re-exports identifiers from bluefin-internal, but somehow the documentation is not getting pulled over too. Furthermore, if I run cabal haddock without --haddock-for-hackage, everything is fine.

The documentation is generated correctly when Hackage does it, so I guess I must be missing a flag or some other form of configuration. Does anyone know what?

EDIT: The --help says:

 --haddock-for-hackage          Collection of flags to generate documentation

but it’s not clear what flags --haddock-for-hackage stands in for so I can’t play around with those to debug. Does anyone know what the collection of flags is?

3 Likes
2

It seems to be mostly this:

1 Like
3

Thanks! Based on that I ran this command line and all the documentation was fine:

cabal haddock bluefin \
   --haddock-all \
   --enable-doc \
   --haddock-hoogle \
   --haddock-html \
   --haddock-hyperlink-source \
   --haddock-quickjump

Can you see anything I’ve obviously missed? (I should try the location and contents flags, but I assumed they wouldn’t make any difference.)

EDIT: It seems that I can get the docs to build properly by doing this:

cabal clean
cabal haddock bluefin                                      
cabal haddock bluefin --enable-doc --haddock-for-hackage

You can see the properly-built documentation at Bluefin.State.

If I don’t have the intermediate cabal haddock bluefin then I get the earlier version without the function docs. Somehow something in the intermediate run must store some state that the latter run can pick up. I would be interested to know how the Hackage docbuilder does this.

EDIT: This seems to be what the Hackage builder uses: hackage-server/exes/BuildClient.hs at 8ce96799395253ffd45ff8c85bb25423acb98e57 · haskell/hackage-server · GitHub. To my surprise, it doesn’t use --haddock-for-hacked and goes via cabal v1-install.

1 Like
4

See:
Document online Setup.hs haddock --for-hackage by mpilgrem · Pull Request #11325 · haskell/cabal

2 Likes