rebuilding haddock docs

[David Waern]

2010/7/26 Mark Lentczner <markl at glyphic.com>:
> 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.

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

David