how come the README example configures with --disable-documentation?

[bmillwood]

setup/README.md

Line 165 in f5975f0

cabal configure --enable-tests --enable-benchmarks --disable-documentation

It goes on to build documentation anyway. Is it something to do with the dependency cache?

(This is a documentation request, unless it's a mistake, in which case this is a bug report :) )

[andreasabel]

Hi Ben @bmillwood,
this is a stumbling stone in the cabal UI.
--disable-documentation only states that the documentation for the dependencies should not be built, and will not be linked in the documentation of the targets of cabal haddock.

Does this answer your question?

[bmillwood]

Hi Ben @bmillwood, this is a stumbling stone in the cabal UI. --disable-documentation only states that the documentation for the dependencies should not be built, and will not be linked in the documentation of the targets of cabal haddock.

Does this answer your question?

In this run, it seems like cabal decided to build (at least many of) the docs for the dependencies at the haddock step anyway: https://github.com/bmillwood/bluesky-tools/actions/runs/12623008445/job/35171545170

But this is after the cache is saved, so the dependency docs don't get cached, and I imagine my haddock step would take 5 minutes every time, whereas if I built the dependency docs at the same time as building the dependencies, I think they would get cached.

Am I better off enabling documentation, or did I miss something?

[andreasabel]

Odd.

Am I better off enabling documentation, or did I miss something?

This it at least worth an experiment.

Another experiment would be to pass --disable-documentation again on the command line to cabal haddock, maybe the setting from cabal.project.local (generated by cabal configure) isn't picked up by cabal haddock.

If you do these experiments, please let me know, so I can update my advice accordingly!

[bmillwood]

Thanks. I'll probably get around to doing some tests at some point but right now my thing works for me so it's unlikely to be high priority :)

I forgot to mention it last time but I did already try passing --enable-documentation in this run: https://github.com/bmillwood/bluesky-tools/actions/runs/12623081607/job/35171688430

It's a little hard to draw firm conclusions from this because of course even identically configured runs can differ in performance because of the changing state of the cache, but feel free to browse through the rest of my runs here if you'd find that useful or interesting: https://github.com/bmillwood/bluesky-tools/actions

[andreasabel]

This issue could also be a regression in cabal-3.14

• Haddock recompilation avoidance haskell/cabal#9177
• Come up with a way to build documentation for a package without rebuilding a lot haskell/cabal#10111

Actually, I think it is still this regression:

• Consider reverting default usage of --enable-documentation in cabal haddock haskell/cabal#8725

The documentation: False in cabal.project.local seems to be ignored by cabal haddock, you have to pass --disable-documentation on the command line.

[andreasabel]

Please review

• Model workflow: pass --disable-documentation to cabal haddock #109