Cabal (the library) `haddock` command does not support sublibraries

[mpilgrem]

I think that this specific issue has not been reported previously: Cabal (the tool) can build Haddock documentation for a package with a sublibrary, but Cabal (the library) cannot.

I have a simple 'toy' package my-project with a library and a sublibrary internal. Its Setup.hs is the usual:

import Distribution.Simple
main = defaultMain

internal can be private or public, and the following behaviour is the same:

Command cabal haddock (cabal-install version 3.10.2.1) in the package's root directory generates Haddock documentation for both libraries, each with their own index.html, in directories: my-package\dist-newstyle\build\x86_64-windows\ghc-9.6.3\my-package-0.1.0.0\doc\html\my-package (the main library) and my-package\dist-newstyle\build\x86_64-windows\ghc-9.6.3\my-package-0.1.0.0\l\internal\doc\html\my-package (the sublibrary).

However commands runghc Setup.hs configure, runghc Setup.hs haddock (Cabal library version 3.10.1.0) in the package's root directory generates Haddock documentation for both libraries in turn in directory dist\doc\html\my-package\, and the index.html for one library overwrites the same file for the other library.

My motivation is that Stack relies on the version of Cabal (the library) that is provided with the specified version of GHC: commercialhaskell/stack#5254.

[mpilgrem]

I have repeated the above experiment with:

• cabal --version cabal-install version 3.14.1.0, compiled using version 3.14.1.0 of the Cabal library, and GHC 9.12.1; and
• GHC 9.12.1/Cabal-3.14.1.0.

and could not reproduce it. In particular, Cabal (the library) had:

• Documentation created: dist\doc\html\testHaddockSublibrary
• Documentation created: dist\doc\html\testHaddockSublibrary\internal

So, it appears this issue may have been fixed at some point. I did not identify an express explanation in the Cabal package's change log.

[ulysses4ever]

Thanks for update! Interesting... As Brandon mentioned on matrix, the situation may have improved due to work on cabal haddock-project, which, despite the name, did touch the library too.

[hasufell]

I'm using cabal-install.

Running the following in the ghcup project:

cabal haddock --haddock-for-hackage --enable-doc --haddock-options=--quickjump

Will produce dist-newstyle/ghcup-0.1.40.0-docs.tar.gz of the last sublibrary only. It builds all docs for all sublibraries, but overwrites the docs tarball each time.

Pretty bad. See: https://hackage.haskell.org/package/ghcup-0.1.40.0

[hasufell]

@Kleidukos

[LaurentRDC]

This issue was encountered when building the documentation of vector (haskell/vector#521), visible on Hackage.

Edit : I tested locally using cabal-install 3.14.1.1 and GHC 9.10.1. cabal haddock-project correctly builds all documentation though

[ulysses4ever]

Looks pretty bad. I'm putting the high priority label.