Add flag to direct documentation to given location

[LiisiKerik]

--docdir and --htmldir flags do not affect the location of documentation that is generated by cabal haddock.

To reproduce the bug I have a minimal project with the following structure:

Test
  Test
    Test.hs
  Test.cabal

Test.hs is an empty module:

{-|
Description: Test

Test
-}
module Test.Test () where

Test.cabal:

cabal-version: 3.0
name: Test
version: 0.0.0
library
  build-depends: base
  exposed-modules: Test.Test

I would assume that the following flags would affect the location of documentation and put it in Test/Docs next to the source folder and the cabal file. But they don't:

cabal haddock --docdir Docs
cabal haddock --docdir=Docs
cabal haddock --htmldir Docs
cabal haddock --htmldir=Docs

My operating system: Windows 10
cabal: 3.2.0.0
ghc: 8.10.1

[Mikolaj]

Thank you for the report. So where is the documentation landing, if not where you expect it? Does creating the directory by hand help?

Could you install cabal-install-3.8.1.0-rc1, as describe here https://discourse.haskell.org/t/cabal-3-8-pre-released/, and verify that the bug persists? Also. a newer GHC could help, at least 8.10.7, to be obtained from ghcup as well.

[ulysses4ever]

There are several issues at play here. Also, just FYI, the cabal version doesn't matter (I checked that HEAD does roughly the same).

1. --docdir's documentation says:

   installation directory for documentation

   You're not installing anything (cabal haddock --help says right away: Build Haddock documentation), so the flag is irrelevant. Arguably, cabal should warn you that the flag has no effect. This would be hard to fix though, I imagine (maybe I'm wrong): there's not much precedent for analysing consistency of flags in cabal, I think.

   Same applies for --htmldir.

2. What you may have used instead of those flags is --builddir=Docs. Unfortunately, you'll get the same ugly chain of directories as you would with the default (dist-newstyle).

Is there a way to install only docs? So that --docdir applies but nothing is installed globally, just the docs are copied from the builddir to a given docdir. Something along the lines of cabal install --only-documentation. Sounds viable but I don't think it's possible today.

[Mikolaj]

Thank you for the analysis. Hackage (at the bottom of https://hackage.haskell.org/upload) seems content to recommend --builddir. Is the "chain of directories" the only problem with that?

[ulysses4ever]

The reason I assumed the chain of directories is the problem is the Reddit thread from apparently the same author: https://www.reddit.com/r/haskellquestions/comments/vi0tcm/how_to_redirect_cabal_haddock_output_to_a

Also, the docs could be improved. We can't substitute it with references to Hackage pages on the bug tracker. And for a casual user the relationship between cabal and Hackage is not apparent, so these references can be surprising.

[LiisiKerik]

Is there really no flag that would allow the user to redirect the docs to a location of their choice?

[Mikolaj]

Yes, I think so. But the feature request is reasonable and a patch would probably be accepted. after some UI bikeshedding (e.g., --only-documentation sounds good).