Differential Documentation with haddock

Question

If I do a cabal build on my library, then change a file, the next time I run cabal build, I only have to recompile files affected by the changes. I'm not getting the same behavior with the cabal haddock command: when I run it after changing a file, cabal/haddock ends up throwing out all of the previous work and starting from scratch. This is rather time consuming; is there a way to get differential updates to documentation?

Here's a dump of the command cabal issues to generate the documentation.

Answer 1

processModules documentation says:

Create Interfaces and a link environment by typechecking the list of modules using the GHC API and processing the resulting syntax trees.

And that is the core function of haddock. So ATM the answer your question is No.

cabal build doesn't help cabal haddock at all, as haddock type-checks modules with different parameters (e.g. __HADDOCK__ CPP variable enabled)

Making reliable incremental haddock generation is hard, as the code later in the dependency graph can alter the modules documentation previous to that point: particularly the instances listings. Probably one could dump module interfaces.

Looking at the code of processModules the first step is something that could be possible to do incrementally, rest is using global information.

Try turn verbosity to the max i.e. --haddock-options=--verbosity=2 and check how much time is spent between Creating interfaces... and Attaching instances....