Use new haddock multi-package support

[michaelpj]

Haddock recently gained the ability to make nicer output for multiple packages. It would be nice if this was exposed to the user via cabal haddock, so that cabal haddock (maybe with a flag?) produced a combined set of documentation for all the packages in the project.

(I couldn't find a ticket for this exact thing before, but there are some comments

[coot]

I have an early draft of in coot/haddocks branch. An early feedback is welcome

Todo:

• check which haddocks flags should be supported
• add support for hoogle
• move haddocksCommand to its own module.
• run haddock via Distribution.Simple.Haddock.haddock
• link non-local dependencies (e.g. base, etc ...)
• integrete Allow to hide interfaces when rendering multiple components haddock#1487
• clean the branch

[michaelpj]

A design point that @coot raised

Now a question: quickjump works across all local packages, but does not work for things that are pulled from cabal's store. The question is, should it:

• allow to search local packages and all their dependencies
• allow to search only the local packages

I prefer the first one, but I see why the other might be a good idea too (e.g. if one searches for forkIO in our io-sim repo, there are two, and it really matters the one that is exported by io-sim not base). I would like the initial version to be simple, so either of these (the latter is easier to implement, the former requires parsing & rewriting a json file), so I as of implementation I prefer to start with the latter. What do you think?

My feeling is that it should search only local packages. Why? The rubric I have in my head is that what I really want is something like the way Hackage displays Haddock. That separates things by package, you certainly don't get quickjump across all packages. Since we're bundling all the project packages together, we probably can't do per-package quickjump, but "local-project only" quickjump seems fine, and probably more or less what people expect.

[coot]

@michaelpj that's a good point and that's probably should be the default. Another use case is where one can publish package and its dependencies, and quickjump is the poor man's search tool, a proper hoogle support would actually be better.

The same question about the html index. I think it should only contain names from the local package.

[coot]

@michaelpj I think this is better to solve this on the haddock side. It's currently building html index only from visible interfaces, the pr haskell/haddock#1490 applies this to quickjump as well. Still it does not limit us if we decide to make an option for indexes list all the things (both html index, json index aka quickjump or the module graph in the content page), but for that haddock should be extended, for example to properly render module graph grouped by package, quickfix to group things by package, etc.

[coot]

There's one issue though, if we link base or any other pre-build package its:

• content link,
• html index link, or
• quickjump
  will link to the base's content page / html index / quickjump; Unlike for packages that cabal will actually build (module pages of such packages will link to main content page / main index / main quickjump).

Once base becomes buildable on its own, this issue however will be solved; other solutions are rather hacks (parsing html to substitute links).

[coot]

There are two ways to build documentation of multiple packages that link things correctly:

1. using haddocks --base-url option and the haddocks command from haddock-project command #8162
2. using similar procedure haddock-project command #8162 is using, but passing --haddocks-html-location='https://hackage.haskell.org/package/$pkg-$version/docs' instead of --base-url.

In the first case one gets a ./haddocks directory which is self contained; e.g. contains haddocks of all transitive dependencies. There will be a single index & quickjump index for all local packages.

In the second case one will get a ./haddock directory which contains only local packages, and links go to hackage directly. There will be one index per package, quickjump will not cross boundaries of packages; like hackage does.

Both can be supported by the haddocks command; In light of that.

Because these two modes will be the primary usage of the haddocks command I think we should make it easy to run it in either of the two modes, e.g.

1. cabal haddocks --local for the first one
2. cabal haddocks --hackage for the second one

The second one is something more expected (it's how hackage works), but for me the first mode
is actually more useful, that's why I lean towards the first to be the default, e.g. cabal haddocks would act as cabal haddocks --local.

A self contained version is quite useful when travelling, but also since it gives access to json index of all local packages it makes it easier to jump between different local packages, finding where something comes from (even without using hoogle).

@Kleidukos, @michaelpj, @Mikolaj could you give your opinion?

[Mikolaj]

IMHO, at this early stage, the more options, the better. Let's publish both, but with a warning this is preliminary, may be broken, will change in a non-backward compatible ways and if you don't want it to vanish one day, please offer feedback in ticket NN.

[coot]

What do you mean by NN?

[Mikolaj]

What do you mean by NN?

Whichever cabal (or haddock?) ticket you decide to use for brainstorming the ultimate design of this feature or just for collecting feedback, e.g., #7669.

[coot]

I think this ticket is the best place for that.

[coot]

I wrote a short blog post about cabal haddock-project command.

[ulysses4ever]

@coot very cool! IMO it's worth advertising on the relevant media: Haskell Cafe, Discord and Reddit.

[coot]

@ulysses4ever I posted it on reddit some time ago, and I just posed it on discord and I am about to write to Haskell Caffe.

[ulysses4ever]

Very cool, thank you!