cabal haddock overhaul planning ticket

[mpickering]

It has come to my attention that the cabal haddock command could do with some work.

Related issues

• Can't access __HADDOCK_VERSION__ #10818
• cabal haddock rebuilds (all?) the dependencies since cabal-install-3.9.0.0 (or 3.8?) #8707
• Come up with a way to build documentation for a package without rebuilding a lot #10111
• Feature request: enable --enable-documentation by default #7462
• Haddock recompilation avoidance #9177

The first thing to do is to clarify the confusion in the codebase about what --enable-documentation means. At the moment it does two separate things.

1. Build HTML documentation for a component
2. Build the component with the -haddock option.

Requiring (1) implies (2) but not vice versa. A package can be built with -haddock, but documentation not generated yet. It is important to decouple these two concepts inside cabal so that a user can express which combination they want to use.

Further to this, the switch which turns on -haddock is not implemented correctly, since ./Setup configure doesn't accept an --enable-documentation option, to indicate that the component should be built with documentation.

Task 1: Implement --enable-documentation as a configure time option for ./Setup.
Task 2: Distinguish between requesting (1) and (2) in cabal-install.

---

Consider an issue such as #10818, here the user wishes to build documentation with different options to their
normal compilation. In this situation

The configuration step of Cabal should therefore record after the build phase, which artifact will have the suitable information in for generating documentation.

• This will typically be the normal .hi files, when no extra haddock options are passed.
• If a user wishes to pass different options when compiling in the "haddock" way, a simple "-fno-code" compilation pass can be performed, to produce specific interfaces for generation.

Task 3: Record in the output of ./Setup configure, which interface file way the

In order to implement task 3, the decision needs to be taken earlier about using -dynamic-too, -haddock etc.

Task 3a: Record in the output of ./Setup configure the build combinations which ./Setup build should use to produce the artifacts.

---

Running cabal haddock should use the --no-compilation flag from haddock when available, and just read information from an interface file. First cabal haddock runs the build phase, which ensures that the artifact which contains the documentation is available.

The "no-compilation" flag will just read interface files, and mean we can remove much complexity from the command which tries to either guess what build did (now decided by configure), or stop haddock from recompiling modules (provided by --no-compilation).

Task 4: Use --no-compilation for cabal haddock when supported.

---

Then we consider issues such as #8707, there is a tension about whether when running cabal haddock, you should require documentation for all your dependencies, so that hyperlinks work.

Both uses are valid, but it should be possible to configure this behaviour in the normal global/project/local configuration options.

Task 5: Add a flag to control the transitive behavior of cabal haddock.

---

Finally, we should make the build graph more fine-grained so that building documentation for packages does not force you to rebuild everything.

A good first step for this would be to separate the .html and haddock index generation from the building of the package. Then you can build a package with -haddock, and later generate the .html from that if you need it.
This will fix well into Task 4.

Task 6: Separate documentation building from package building in the build graph.

---

Comments on this plan would be welcome from anyone who has opened any of the other ticket!

[Mikolaj]

A kind ping goes to the authors of the mentioned and related tickets @LeventErkok @phadej @michaelpj @Bodigrim @FinleyMcIlwaine and to @Kleidukos and @ulysses4ever.

Speaking for myself: great analysis and I'd love many or all of these changes, my only worry being backward compatibility, but that can be tackled separately for each PR that comes of this work.

[michaelpj]

I would add: really making the haddock commands project-aware. We have haddock-project now, which is great, but it seems non-ideal to me that there are two different commands here.

[Kleidukos]

@michaelpj It's non-ideal that haddock-project is also very new and we cannot reasonably use its code paths instead of the ones for the haddock subcommand. But the world is a succession of non-ideal situations, and most of them have a good reason for being so.

[michaelpj]

Sure - but if we're talking about an "overhaul", than improving that seems possibly in scope.