Open Bodigrim opened 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?
@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: 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
tocabal v2-haddock
is as unexpected (and seemingly paradoxical) than having to pass--enable-tests
tocabal 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.
@Mikolaj what kind of additional info is needed here?
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.
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
@fgaz that would be #5079
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.
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
@andreasabel good news: the patch is easy. Bad news: I fail to test it. Details are in #8330. Really hope for someone's help!
Most of the time when users invoke
cabal haddock
, they meant to runcabal 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.