Consider reverting default usage of `--enable-documentation` in cabal haddock

[arybczak]

I was bitten by #8707 and I had no idea what was going on, had to search the issue tracker to find it.

Looks like now cabal haddock will with default settings (i.e. no documentation: True in the config file or --disable-documentation passed explicitly) lead to rebuild of all dependencies.

What is worse, if someone doesn't want to enable documentation: True, there seems to be no way to permanently disable this behavior.

This looks like a quite bad UX change to me.

Can this please be reverted? Or resolved in a better way.

PRs in question:

• cabal haddock imply enable-documentation #8259
• unbreak cabal haddock --disable-documentation #8330

[ulysses4ever]

As the author of the change in question, I'm happy with reverting, if people think that it's really annoying (and by the looks of it, they do).

[Mikolaj]

We've also had a lot of ticket from people bitten by the inverse default. Especially newcomers, and they need any help they can get. How can we resolve this in a better way? @arybczak: what would mollify you, for example?

[arybczak]

Well, for example having a way to disable this with a seting in ~/.cabal/config would work.

The issue here is that the new behavior can't be disabled without passing --disable-documentation to cabal haddock every time you invoke it.

[mouse07410]

I'm not sure it would be good to revert - for example, I always build documentation (and have documentation = True in the global config).

[arybczak]

for example, I always build documentation (and have documentation = True in the global config).

Great, then you're not affected by this change at all. Why would you be against the revert then?

EDIT: Another option would be changing documentation to True as a default. I just don't understand the rationale of having this unconditionally enabled in this specific case, especially since the global configuration file, judging by the amount of options it has, lets you configure everything under the sun.

[Bodigrim]

I find it extremely annoying to explain people, especially less experienced ones, that just cabal haddock is not enough and they must double down on their intention to build documentation with cabal haddock --enable-documentation. The sensible default behaviour is not to make users to ask you twice. Power users can always supply --disable-documentation.

[gbaz]

Agreed. I think this might be irritating the first time, but subsequently, as long as the versions don't change, then all those built haddocks will be cached and available, which on the whole will be handy. I'm certainly open to adding a global setting for controlling this as well though...

[andreasabel]

Does documentation: False in the cabal.project file work, @arybczak ?

[arybczak]

Power users can always supply --disable-documentation.

No, power users should be able to disable this in the configuration file.

might be irritating the first time, but subsequently, as long as the versions don't change

In reality they do almost every time you do cabal update.

Does documentation: False in the cabal.project file work, @arybczak ?

It doesn't. That's the crux of a problem. There is currently no way to override this behavior (other than passing --disable-documentation on the command line every single time).

Again, the problem here is not that this change is bad, it's that it's unconditionally enabled there is not way to disable it.

I see two potential solutions:

• Enabling documentation: True by default and reverting cabal haddock imply enable-documentation #8259.
• Providing another ~/.cabal/config option haddock-documentation with a default True that controls whether --enable-documentation is passed to cabal haddock so that it can be disabled.

[mouse07410]

A few naive questions.

1. Placing documentation: False in cabal.project should work, so, if it doesn't - it's probably a bug? And fixing it should resolve this issue?
2. Why would anybody invoke cabal haddock, if not for documentation?
3. If a user does not want documentation in general - why not set documentation: False in ~/.cabal/config, which presumably alleviates the problem?

[arybczak]

Placing documentation: False in cabal.project should work, so, if it doesn't - it's probably a bug?

Perhaps. But why should it work for cabal.project, but not for ~/.cabal/config?

Why would anybody invoke cabal haddock, if not for documentation?

Did you try running cabal haddock without --enable-documentation? You still get the haddock for your package, but without links to external packages. For some people (like me) it's sufficient.

[gbaz]

My understanding of the global level "documentation: False" is that it is supposed to control whether or not haddocks are run on packages as they are built in general. It is not supposed to determine if we recursively generate documentation for sub-dependencies of an individual package where we have already opted into asking for docs.

Again though, I think having a global opt-out of this flag would be a good thing, and a welcome PR. However, given the arguments both ways, circling around reverting the existing change seems like it won't be very fruitful.