Cabal: How do I haddock with new-build?

[ezyang]

Summary. There are a few ways to do it:

1. The most straightforward approach is to introduce Haddock as an extra "target" that can be applied to a component. There is a major downside to this approach, which is that you have to rebuild the _libraries_ when you want to rebuild the Haddocks (because they count as separate "packages" from the perspective of the store). As an addendum to this, you could have some configuration option to stop transitively building Haddock at some point, to avoid thrashing the store (in case you only care about Haddocks for inplace.)
2. A better solution is to somehow treat the Haddock documentation as a separate component that can be installed separately.

---

I see code to do it (c.f. HaddockDefaultComponents), but I don't see anywhere which constructs this?

[ezyang]

CC @dcoutts

[ezyang]

Edit. See @hamishmack's comment below.

We can work around the problem by running cabal act-as-setup -- haddock --builddir=dist-newstyle/packagename-0.1 (or if you have a Custom build, invoke your setup script directly.) (It doesn't seem you can call cabal haddock directly; the reconfiguring code is too smart for its own good.)

[acfoltzer]

This workaround seems to require having run cabal configure already, unfortunately.

[ezyang]

Err, just to double check, did you run cabal act-as-setup -- haddock, and not cabal haddock? (The emailed copy of this ticket has the wrong instructions; I edited it to fix it.)

[hamishmack]

The --builddir needs to point to the subdirectory for the package:

cabal new-build
cabal act-as-setup -- haddock --builddir=dist-newstyle/build/package-name-0.1

Also keep in mind that if your cabal.project file is in a parent directory dist-newstyle will also be in that directory.

[ezyang]

Oh yes, thank you for the correction @hamishmack !

[acfoltzer]

Ah, yeah, I should have tried that based on the copy workaround. That does indeed work without needing a cabal configure.

And as soon as I get this workaround going, I realize that what is more important to us for this feature is to lift this command to the metaproject level. It would be great to run cabal new-haddock in a directory with cabal.project and watch dist-newstyle fill with the docs from all the packages.

[jaccokrijnen]

How do I run haddock on installed packages in my global store?

[ezyang]

@jaccokrijnen We recently merged a draft new-haddock build but I don't know if it rebuilds things in the global store with Haddock.