cabal new-haddock and project index

[yav]

Hello,

I can't seem to find a way to tell cabal new-haddock to put the top-level index for a package in an index common for my project (e.g., something like haddock's use-index option). Is this possible? If not, this would be a handy feature to have.

[harpocrates]

You should be able to thread options directly to Haddock via --haddock-options.

cabal new-haddock --haddock-options '--use-index=myindex.html'

[yav]

Hm, I tried this, and it doesn't seem to work in two ways:

1. adding the extra haddock-options seems to cause all libraries that I depend on to rebuild, for some reason, which does not happen if I just run new-haddock on its own
2. after much rebuilding, there does not appear to be any noticeable change, (i.e, the index file is still in the package directory). Perhaps new-haddock overwrites that setting?

Does it work for you?

[yav]

OK, @harpocrates and I figured out how to get this to work using the haddock-options, but it really would be nice if this just worked with new-haddock directly. For example, we could have a flag that indicates if you want each package to have its own contents and index, or if there should be for the project, and all documentation should be joined together.

[23Skidoo]

Would be nice if new-haddock did this out of the box. Probably requires just passing some additional arguments to haddock. The entry point for new-haddock is in Distribution.Client.CmdHaddock.

[yav]

Indeed. Currently I have a small script that does that, but there are a few problems with it, that wouldn't happen if haddock did it out of the box. In particular:

• since I have to pass extra flags, cabal ends up rebuilding a bunch of stuff, because the flags have changed, even though the flags are just about haddock, and have nothing to do with the state of the executable
  • there is a bunch of hackery I have to do to support switching versions of GHC.

[23Skidoo]

@merijn's recent work (see e.g. #5287) should help with the former.

[merijn]

HEAD should already alleviate the worst problems, since non-local dependencies don't get rebuild on spurious flag changes. #5287 is just making sure the same goes for local/in-place dependencies.

[david-christiansen]

It would also be nice if there were a command to open the project's Haddock index in a Web browser. raco docs does this for Racket, and it's very convenient.

[harpocrates]

I started doing this last night https://github.com/harpocrates/cabal/commit/5a92825449c3bf9219f9bb24f5606c11fb54712f, but ended up giving up. In particular: it looks like the per-package information needed to make the right call to haddock (where .haddock interface files are and where the HTML output is) is tied up inside an InstalledPackageInfo. I'm having a great deal of difficulty finding all of the needed InstalledPackageInfos. Some broken cases:

• a package that is new-haddock'ed before it is new-built
• an executable

Technical questions aside, there is also the question of which packages to include in the index (do we want just the packages on which we called new-haddock? do we want to include direct dependencies? etc.).

[frisbynavican]

@yav Would you share your workaround "script" here? Ticket seems dormant. Thanks!

Edit: this is my workaround for now. Plenty of room for improvement.

cabal v2-build all
haddock_interfaces=$(find . -name '*.haddock' | while read h; do echo " --read-interface=$(pwd)/$(dirname $h),$h"; done)
cabal v2-exec -- haddock ${haddock_interfaces} --gen-index --gen-contents -o top-haddock

[yav]

Yep, that's pretty much what I did, with just some extra hackery to deal with different GHC versions. The script is here:

https://raw.githubusercontent.com/GaloisInc/crucible/master/scripts/gen-doc