hs-doc

Project for building local haddock and hoogle for some packages

On Debian 12, some development packages need to be installed first (as root), as listed in debian-requirements.txt:

$ apt install libasound2-dev libblas-dev libbz2-dev libcairo2-dev libdbusmenu-gtk3-dev libgirepository1.0-dev libglew-dev libglib2.0-dev libgsl-dev libicu-dev liblapack-dev liblzma-dev libmariadb-dev libmysqlclient-dev libpcap-dev libpcre3-dev libpq-dev libsdl2-dev libsdl2-gfx-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libxft-dev libxrandr-dev libxss-dev libzstd-dev pkgconf protobuf-compiler

Make sure that hoogle has been installed to somewhere on your PATH. Then run these commands to build the haddock and hoogle DB:

$ stack haddock # Add "-j8 --ghc-options -j8" for possibly more parallel processing.
$ stack hoogle generate -- --local

To run the local hoogle on port 8000:

$ stack hoogle server -- --local --port 8000

There is an issue that may cause hoogle to miss documentation for built-in packages like base and binary. One workaround is to hack the associated .conf files as described in this issue comment. Another is to use the hoogle from this patch.

With GHC 9.8 and 9.10, various amazonka have trouble being processed by haddock. The workaround is:

$ stack haddock --haddock-arguments=--optghc=-XDuplicateRecordFields

This is a crude workaround as the --optghc=-XDuplicateRecordFields gets applied to non-amazonka packages, which do not need the -XDuplicateRecordFields. Apparently, stack, unlike cabal, does not allow per-package control of haddock options.

Alternative cabal-based setup with cabal-hoogle.

To generate Haddock documentation and Hoogle index:

$ cabal-hoogle generate

To serve Hoogle index:

$ cabal-hoogle run -- server --local --port 8000

This setup has a fine-grain per-package approach to passing --optghc=-XDuplicateRecordFields to Haddock.