Build haddock documentation of a cabal project

I've been working on a new cabal command: haddock-project which allows to build cabal documentation of a cabal project which possibly consists of multiple packages. This is often useful when you are working on a larger project which contains multiple packages and you either don't want to or you cannot publish them on hackage.

Currently the final pull request is under review. The line of work which lead to this started with many changes to the haddock command:

haddock has two modes of operation. It is used to build documentation and render it either as html or latex, and secondly it can be used build content page together with a html and quickjump indexes. The content page contains can include a custom prologue followed by a tree of modules. That's not the same page as the landing page on hackage, but it will look familiar for you, for example here is base package content page.

haddock can now build the content page with a consistent html and quickjump index of all local packages, where all header links point to the top level page / index and probably most important where all the links can be resolved either locally or to hackage. If there are multiple packages, the content page will contain a module tree per package, and haddock allows to control which packages are visible. cabal haddock-project uses this to only show trees of local packages, without listing module trees of dependencies (e.g. base package). See here for a sample.

The cabal haddock-project requires haddock-2.26.1, which isn't yet published. However, the pull request fixes the --with-haddock option which allows to configure which haddock command to use. If you want to try it, you will also need to pass --lib option which points to the haddock-api/resources directory (once haddock-2.26.1 is distributed with one of the future versions of ghc, neither --with-haddock nor --lib will be necessary).

cabal haddock-project can either build a self contained directory or a directory which links to hackage. In the first case you will need to run: 

cabal haddock-project     \
  --with-haddock=$HADDOCK \ # point to haddock-2.26.1
  --lib=$HADDOCK_LIB      \ # point to haddock-api/resources
  --local
This command will build ./haddocks directory which you can serve with a http server. It will contain documentation of all the local packages and its dependencies. You can even control which dependencies should be included via documentation option. A self contained directory can be useful when you need or want to work offline. In the future, we could also add a flag which would allow to build quickjump index which contains references to all the dependencies not just local packages. If you want to link to documentation published on hackage then you can use: 
 cabal haddock-project     \
   --with-haddock=$HADDOCK \ # point to haddock-2.26.1
   --lib=$HADDOCK_LIB      \ # point to haddock-api/resources
   --hackage
Both --local and --hackage are meta-options. They imply --gen-content, --gen-index, --quickjump and --hyperlinked-source, the --hackage flag also implies a correct value for --html-location. If you have custom needs you could avoid using either --local or --hackage and provide the exact flags you need.

I hope this will be also useful to you as it is for the excellent Haskell team I am working with at IOG. We have some Haskell positions open to work on various parts of the cardano project: