Come up with a way to build documentation for a package without rebuilding a lot
- Dominant language
- Haskell
- Stars
- 1.7k
- Forks
- 750
- Avg merge
- 4d 3h
- Merged PRs (30d)
- 28
Description
**Describe the feature request**
At the moment, when cabal builds a package, it decides first whether or not it will build it with documentation, and then it builds the entire package (possibly including documentation) and puts it into a single location in the cabal store. (So: the choice of whether or not to build documentation affects the store hash)
This means that deciding to build a package with documentation when it was not built before means:
1. Rebuilding that package
2. Rebuilding every downstream package (including local ones that depend on it), since we now consider it to be a different package
This is especially painful in the post-hi-haddock world, where we really _don't_ need to rebuild a package in order to build the HTML documentation for it (see discussion [here](https://github.com/haskell/cabal/pull/9177#issuecomment-2166112125)).
There are a few possible solutions:
1. Allow storing the haddock in a separate place in the store from the interface/object files. This would decouple the two, so building the haddock would just build some new things and not affect the existing things (thus preventing cabal from thinking it needs to rebuild dependent packages). See [here](https://github.com/haskell/cabal/issues/8725#issuecomment-1523244372).
2. Always build haddock for non-local packages. Now that a lot of the work is done during GHC's compilation pipeline, I think it's probably fairly cheap to do the final step of generating the docs. In an ideal world we could also do it in parallel with starting to build the next downstream package. I'm not sure how we would configure this, and maybe it's surprising.
Contributor guide
Research direction
Start by reading the discussion linked from cabal issue 10111, including issue 8725 and Cabal PR 9177, to understand the proposed store and Haddock behavior. Define and implement a selected approach so documentation can be built without rebuilding the package or its downstream dependents, then verify that both package artifacts and documentation remain usable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- haskell
- Domain
- build-system
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100