search

haskell / cabal

Official upstream development repository for Cabal and cabal-install
https://haskell.org/cabal
Other
1.62k stars 691 forks source link

Feature request: enable --enable-documentation by default #7462

Open Bodigrim opened 3 years ago

Bodigrim commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@Mikolaj what kind of additional info is needed here?

Mikolaj commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@fgaz that would be #5079

ulysses4ever commented 2 years ago

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 commented 2 years ago

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

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 commented 2 years ago

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