Differential Documentation with haddock

7
votes

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.

1
haskellcabalcabal-installhaddock
I don't remember: does haddock fail to build if you link to something that doesn't exists? Like using 'MyModule' and you have no MyModule available. Because if it simply gives a warning and continue to run then the behaviour is required: any change to existing files or addition of files could modify the output of the other modules' documentation. – Bakuriu
I believe a lot of time is spent rebuilding the global index pages. A lot of time could be saved if those pages were not built. Use the -v flag with cabal to see what haddock commands are being executed. – ErikR
@Bakuriu If I add a random import ModuleDoesNotExist to the top of a file, haddock short circuits and does not output any documentation. If I force any other sort of compile error (e.g. a syntax error), haddock outputs documentation up to the module with the error, but then short circuits and does not output documentation for the rest of the modules. – crockeea
@user5402 Added link in question. – crockeea
How much time is it taking? As an experiment I built the docs for parsec with cabal haddock and it only took a few seconds. However, if I run cabal install it will take a lot longer because the global index files have to be regenerated. So how big is your code? Exactly what commands are you running and how long are these commands taking? – ErikR

1 Answers

1
votes

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....