There is no documentation on hackage! What do I do?

If you are a Haskell user you for sure know and use Haskell open source repository, Hackage. Hackage is not only useful as a software repository, but as a handy way of checking documentation. Reading signatures, comments, etc. is the primary way to approach and study a library.

Sometimes the Hackage server fails (or lags behind in) building documentation (example). Being confronted by black links can be frustrating, but what can we do?

The recipe

The fix is simple, instead or relying on a third party to build your documentation, build it locally.

• First step: open your ~/.cabal/config and look for a line which looks like

  -- documentation: False

  and change it to

  documentation: True

• Then rebuild your Haskell world (will take some time!)

  cabal install world --reinstall --force-reinstalls

  (or just wipe your old installation and start over)

• Finally open your .bashrc and add this line

  alias ghdoc='x-www-browser ~/.cabal/share/doc/i386-linux-ghc-7.10.2/index.html'

  Change i386 and 7.10.2 to mach your intallation (if you are not sure check ~/.cabal/share/doc, it should be the only directory there.

Now you can type ghdoc in your terminal and -bam!-, here you have all the documentation at your fingertips, quickly loaded, matching your installed packages, working even when you are offline!

No more Hackage blues.

Sandboxex/Stack/Hoogle

• If you are using a cabal sandbox, the relative (from sandbox root) path to index.html is (thanks to Imants Cekusins for the tip):

  .cabal-sandbox/share/doc/$arch-$os-$compiler/index.html

• If you are usint stack instead of cabal, building/browsing offline documentation gets a bit more complicated. Check Patrick Redmond's instructions for a detailed explanation.

• If you need an offline Hoogle too, just cabal install hoogle, hoogle generate and add this to your ~/.ghci (I stole this from John Wiegley):

  :def hoogle \x -> return $ ":!hoogle -q --colour -n 10 \"" ++ x ++ "\""
  :def hdoc \x -> return $ ":!hoogle --info \"" ++ x ++ "\""

  Now you can query hoogle straight from ghci:

  λ> :hoogle [a] -> Int
  Searching for: [a] -> Int
  Prelude length :: [a] -> Int

• What about cabal new-build, you ask? There is an open ticket.