Feature request: enable --enable-documentation by default

[Bodigrim]

Most of the time when users invoke cabal haddock, they meant to run cabal haddock --enable-documentation (to generate hyperlinks to entities from other packages). Any reason this is not a default behaviour? AFAIU this flag does not affect build plan.

[Mikolaj]

I don't see this flag in

cabal v2-haddock --builddir="$dir" --haddock-for-hackage --enable-doc

which is what the unfortunate users that depend on libraries not present on Hackage servers need to invoke to build documentation and upload it manually: https://hackage.haskell.org/upload

However, perhaps --haddock-for-hackage could override --enable-documentation. Or does it imply it? Because it definitely generates hyperlinks.

Are there any other popular uses?

[andreasabel]

@Mikolaj: In your command, is --enable-doc something different than --enable-documentation ?
(Confused.)
I am not usually passing --enable-doc with --haddock-for-hackage, is this a mistake?

Anyhow, I think having to pass --enable-documentation to cabal v2-haddock is as unexpected (and seemingly paradoxical) than having to pass --enable-tests to cabal v2-test.

[Mikolaj]

@Mikolaj: In your command, is --enable-doc something different than --enable-documentation ? (Confused.)

I've just copied it from https://hackage.haskell.org/upload. It works, because any non-ambiguous prefix of a command works.

I am not usually passing --enable-doc with --haddock-for-hackage, is this a mistake?

Anyhow, I think having to pass --enable-documentation to cabal v2-haddock is as unexpected (and seemingly paradoxical) than having to pass --enable-tests to cabal v2-test.

I agree. Frankly, I haven't tested if this is required (assuming you don't have docs enabled in any of the configs). I just copy-pasted it. If it's not required in the current stable cabal, let's fix the snippet at https://hackage.haskell.org/upload.

[Bodigrim]

@Mikolaj what kind of additional info is needed here?

[Mikolaj]

No more info is needed. I forgot to remove the label after I found out that --enable-doc is equal to --enable-documentation.

If nobody objects, let's make --enable-documentation the default in cabal haddock. That probably introduces the complexity that different commands have different defaults for the same option, but human expectations are sometimes not towards the simplest setup and UI should strive towards least surprise.

[fgaz]

Wasn't there a similar situation for --enable-tests? Can anyone find the ticket?
edit: nevermind, this is different since docs don't affect the build plan

[ulysses4ever]

@fgaz that would be #5079

[ulysses4ever]

As pointed there, enable-tests do actually affect the build plan, unlike (according to OP) enable-documentation. So the current issue is a clearer cut.

[andreasabel]

This new feature is giving me a lot of trouble in connection with

• Assertion failure on cabal build/haddock --enable-doc #8313

This is because --enable-documentation triggers the assertion reported in #8313. Typically, it looks like:

$ cabal haddock -w ghc-8.10.7
Warning: this is a debug build of cabal-install with assertions enabled.
Resolving dependencies...
Build profile: -w ghc-8.10.7 -O0
In order, the following will be built (use -v for more details):
 - clock-0.8.3 (lib) (requires build)
 - colour-2.3.6 (lib) (requires build)
Assertion failed
CallStack (from HasCallStack):
  assert, called at src/Distribution/Client/ProjectPlanning.hs:246:5 in cabal-install-3.9.0.0-inplace:Distribution.Client.ProjectPlanning

Also, --disable-documentation is ignored (that's a bug), so there is no workaround:

$ cabal haddock -w ghc-8.10.7 --disable-documentation
Warning: this is a debug build of cabal-install with assertions enabled.
Build profile: -w ghc-8.10.7 -O0
In order, the following will be built (use -v for more details):
 - clock-0.8.3 (lib) (requires build)
 - colour-2.3.6 (lib) (requires build)
Assertion failed
CallStack (from HasCallStack):
  assert, called at src/Distribution/Client/ProjectPlanning.hs:246:5 in cabal-install-3.9.0.0-inplace:Distribution.Client.ProjectPlanning

[ulysses4ever]

@andreasabel good news: the patch is easy. Bad news: I fail to test it. Details are in #8330. Really hope for someone's help!