haskell / haskell/cabal

haddock-project links documentation of local packages to hackage

Open
#9,852 0 comments 0 reactions 0 assignees View on GitHub
cabal-install: cmd/haddock-project
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**Describe the bug**
The `cabal haddock-project --hackage` (as of #9821, but likely earlier as well) links documentation of local dependencies to hackage, e.g. if there are two library components `package:mainlib` and `package:sublib` where the former depends on the latter the links created for `package:mainlib` to `package:sublib` will point to hackage version of `package:sublib` not the documentation that is created locally. This is not a bug, but rather a surprising behaviour.

**Expected behaviour**

I think the user expects that the links will be towards the local copy available under the `./haddocks` directory (the default where `haddock-project` puts documentation of components local to the project).

**Design considerations**
When `cabal` invokes `haddock` it does so by calling `act-as-setup`, which is spawning a new process. In particular, all the information gathered in `EllaboratedConfiguredPackage` is lost, and when `haddock` is invoked it only has access to `InstalledPackageInfo`s. This means that we have no information whether a dependency is a local component to the project or not, which is needed to correctly pass `--read-interface` haddock options.

If we new that an `InstalledPackageInfo` comes from a local package we could pass the file location of the right `.haddock` interface, but extending `InstalledPackageInfo` doesn't seem to be the right choice, because that information depends on the package we are compiling not on the installed package.

So another option to solve this is to pass extra arguments to `act-as-setup -- haddock` which includes all the required `--read-interface` options for a given package, and thus construct them in the phase when we have access to `EllaboratedConfiguredPackage` rather than when this information is lost.

**System information**
- Operating system
- `cabal`, `ghc` versions

**Additional context**
Add any other context about the problem here.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.