rebuilding haddock docs

Simon Marlow marlowsd at
Mon Aug 9 08:14:03 EDT 2010

On 26/07/2010 12:43, David Waern wrote:
> 2010/7/26 Mark Lentczner<markl at>:
>> I thought it would be good to regenerate all the haddock documentation on my
>> system with the new haddock. This would give me a nice big corpus of output
>> to look at and see how it feels. It would also be nice if, after we release
>> new haddock, if we could give people a script that they could run and it
>> would do this for them.(*)
> Yes, that would be nice. One could try to make use of "cabal install
> <package>  --reinstall --enable-documentation" to do that somehow. Not
> sure if it'd work perfectly though - one might run into trouble with
> packages that come with GHC (like base). And perhaps it's a bad idea
> to re-install the packages completely.

This really isn't possible for the core packages that GHC ships - 
ghc-prim and base can't be built by Cabal, I think (although there's no 
reason in principle that they couldn't be, as far as I know it just 
doesn't work at the moment).

Do the anchors have to change, or would it be possible to make them 

In the past when the .haddock format changes we have tried to degrade 
gracefully, still producing documentation but without the features that 
were enabled by the format change.


>> As far as I can see, there really is no way to run haddock manually for a
>> real package. There are just too many command line options that have to be
>> calculated in just the same way cabal does. (I figured this out by replacing
>> my haddock with a wrapper that dumped all the arguments, and then let cabal
>> reinstall a package I had.)
> You can use cabal install -v N to see how cabal invokes Haddock (don't
> remember which N to use).
>> So, seems like the plan would be:
>> 1. use ghc-pkg to get a list of all install packages and versions.
>> 2. for each package:
>> 2.1 cabal unpack<package>-<version>
>> 2.2 cd<package>-<version>
>> 2.3 cabal configure
>> 2.4 cabal haddock --with-haddock=<new-haddock>
>> 2.5 move dist/doc/html/<package>  to some new doc tree
>> 2.6 cd ..
>> 3. run haddock --gen-contents --gen-index reading all the interface files
>> from the doc tree
> Perhaps see with Duncan if this is a good way to do it. I think I've
> seen tickets in the cabal-install trac for installing only parts of a
> package (e.g. profiling). Perhaps Duncan's plan is to be able to use
> "cabal install" to only install documentation? In that case it would
> perhaps be better to implement that than to write a script.
> FYI, cabal install --enable documentation does the last step (3) also.
>> (*) Here's an issue: If we don't give users a script for rebuilding their
>> docs, then when they install new packages, after upgrading haddock, new and
>> old docs won't cross link, because the anchors changed.
> We've already done similar things in the past. Each time the .haddock
> file format changes Haddock can't read already-installed packages that
> has the old format. In practice most people just use the Haddock
> version that comes with GHC, so they get docs built from the ground up
> with that version.
> Perhaps more people will switch to a new standalone version of Haddock
> this time, though. And they will get broken links, rather than no
> links (which was the case when we changed the .haddock file format).
> So it's a little bit worse this time. So I'm  all for a way to rebuild
> all the docs and it's also a really useful feature in general.
> However, I'd ideally like to see it integrated in cabal-install.
> Perhaps it's even easier to implement it that way, too.

More information about the Haddock mailing list