4

So, I am using haddock (through cabal) to generate documentation for my local Haskell package. It has no trouble hyperlinking its own local html documents to each other. However, whenever my package references a symbol from another package, it does not create the link.

Most of my outside dependencies have haddock documentation on Hackage. Is there a way to set up haddock such that it can find the documentation of Hackage and hyperlink to it?

PyRulez
  • 10,513
  • 10
  • 42
  • 87
  • 1
    If you install the package locally with documentation (see `--enable-documentation`. for `cabal`), your local docs will link to the other external packages' local docs. Regarding Hackage: when you upload your package to Hackage, docs linking to other packages on Hackage wwill automatically be created. There is no way to link your local package Hackage docs though. – Alec Sep 13 '19 at 04:01
  • @Alec I had issues building the docs for the dependencies. Could I download the ones from hackage instead of trying to build them myself? – PyRulez Sep 13 '19 at 15:53
  • 1
    Unfortunately, I don't think you can. That seems like a potentially neat feature though, so I've opened a feature request: https://github.com/haskell/haddock/issues/1086. – Alec Sep 13 '19 at 18:40
  • @Alec okay. Also, thank you! I was considering doing that myself, but just wanted to make sure it wasn't already in it. – PyRulez Sep 13 '19 at 21:39
  • @Alec This cabal command seems to say it can work with haddock, but I can't get it to work: https://cabal.readthedocs.io/en/latest/nix-local-build.html#cfg-flag---html-location – PyRulez Sep 16 '19 at 00:04

1 Answers1

3

I usually do,

cabal v2-haddock --haddock-html-location='https://hackage.haskell.org/package/$pkg-$version/docs' --haddock-hyperlink-source --haddock-quickjump

The only problem for me with this approach is that, it may link with latest packages that are not yet available on Hackage. For example, when I run this on ghc-8.8 it links to base-4.13 which hasn't been released on Hackage yet.

Pranay Sashank
  • 91
  • 4
  • When I do this, it tells me it can't find link destinations for each of those external definitions, and doesn't generate hyperlinks. Any guesses? – dfeuer Jan 23 '22 at 06:44
  • @dfeuer It's been a while since I have done this, but I believe you still need documentation built for all the dependencies. So either add `ghc-options: -haddock` to `program-default-options` section of `~/.cabal/config` file or add `documentation: True` for all packages (`package *`) in cabal.project. – Pranay Sashank Jan 24 '22 at 10:14
  • Thanks. These are external dependencies, so not part of my project. Does that mean I'll have to nuke the package database and build docs for *everything*? Or download the source for all those packages and make them part of my project temporarily? – dfeuer Jan 24 '22 at 13:04
  • You likely don't need to delete anything, just adding ``` package * documentation: True ``` in your cabal.project should be enough – Pranay Sashank Jan 24 '22 at 13:20