• Added argLibraryName to HaddockArgs
• haddock-project: fixed main library name
• haddock-project support for sublibraries

QA Notes

Running cabal haddock-project on a package with multiple public sublibraries should create ./haddocks directory which contains the package:sublibrary haddocks in ./haddocks/package-sublibrary directory. All cross-references will be resolved to files inside ./haddocks directory. ./haddocks directory should also contain both indexes: html and quick-jump index. Both indexes should contain references to identifiers from all public sublibraries.

When using cabal haddock-project --hackage the cross-references between sublibraries will be resolved to hackage (as described in #9852).

I am getting a lot of test failures of this sort:

+Warning: Both <ROOT>/cabal.dist/home/.cabal and /home/coot/.config/cabal/config exist - ignoring the former.
+It is advisable to remove one of them. In that case, we will use the remaining one by default (unless '$CABAL_DIR' is explicitly set).

on my dev machine, I use cabal's support for xdg directory layout; is this related?

Try removing ~/.cabal maybe.

I think the ~/.cabal file comes from the test suite (I suspect it sets HOME variable in some particular way). We probably need to set some XDG env vars in the tests so cabal doesn't find the user's configuration.

btw, I don't have ~/.cabal file in my HOME directory.

@Kleidukos I added the QA Notes: and checked that it works as expected :smile:. Do you know who else could review this PR?

It might be worth noting that in an earlier version of this PR I experimented using package:sublibrary as path in ./haddocks, but there are two problems with it:

• : is an invalid character on Windows
• : when used in URLs, requires either relative or absolute paths (which can be done, even without haddock changes)

Maybe it's worth to use the : syntax as we are used to do cabal build package:sublibrary, and letting Windows users use - instead, even though it slightly complicates things. Anyway, for now, I left it outside of this PR. The drawback is that one cannot have some-package:sublib and some:package-sublib in a single project.

Ups, I forced pushed after rebasing, and then I noticed some people committed to the branch.

@andreasabel are you sure you pushed to the right branch?

Public sublibraries are a package-level concept, but here we are changing haddock-project. Why is that?

Does cabal haddock properly support public sublibraries?

Here is my quick investigation:

λ cabal haddock
Build profile: -w ghc-9.6.4 -O1
In order, the following will be built (use -v for more details):
 - tmp-pkg-0.1.0.0 (lib) (configuration changed)
 - tmp-pkg-0.1.0.0 (lib:b) (configuration changed)
Configuring library for tmp-pkg-0.1.0.0..
Configuring library 'b' for tmp-pkg-0.1.0.0..
...
Documentation created:
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/l/b/doc/html/tmp-pkg/
Documentation created:
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/doc/html/tmp-pkg/

This seems reasonable, but

λ cabal haddock --haddock-for-hackage
Build profile: -w ghc-9.6.4 -O1
In order, the following will be built (use -v for more details):
 - tmp-pkg-0.1.0.0 (lib) (configuration changed)
 - tmp-pkg-0.1.0.0 (lib:b) (configuration changed)
Configuring library for tmp-pkg-0.1.0.0..
Configuring library 'b' for tmp-pkg-0.1.0.0..
...
Documentation created:
Documentation created:
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/l/b/doc/html/tmp-pkg-0.1.0.0-docs/,
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/doc/html/tmp-pkg-0.1.0.0-docs/,
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/l/b/doc/html/tmp-pkg-0.1.0.0-docs/tmp-pkg.txt
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/doc/html/tmp-pkg-0.1.0.0-docs/tmp-pkg.txt
Documentation tarball created:
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/tmp-pkg-0.1.0.0-docs.tar.gz
Documentation tarball created:
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/tmp-pkg-0.1.0.0-docs.tar.gz

The documentation for each component's haddock is written to tarballs with the same name, racing each other.

The above is still cabal-install at work, what about Cabal?

λ cabal act-as-setup --build-type=Simple -- configure
Configuring tmp-pkg-0.1.0.0...

~/Scratchpad/tmp-pkg
λ cabal act-as-setup --build-type=Simple -- haddock --for-hackage
Preprocessing library 'b' for tmp-pkg-0.1.0.0..
Running Haddock on library 'b' for tmp-pkg-0.1.0.0..
Warning: --source-* options are ignored when --hyperlinked-source is enabled.
   0% (  0 /  2) in 'MyLibB'
  Missing documentation for:
    Module header
    someFunc (src/MyLibB.hs:3)
Documentation created: dist/doc/html/tmp-pkg-0.1.0.0-docs/,
dist/doc/html/tmp-pkg-0.1.0.0-docs/tmp-pkg.txt
Preprocessing library for tmp-pkg-0.1.0.0..
Running Haddock on library for tmp-pkg-0.1.0.0..
Warning: --source-* options are ignored when --hyperlinked-source is enabled.
   0% (  0 /  2) in 'MyLib'
  Missing documentation for:
    Module header
    someFunc (src/MyLib.hs:3)
Documentation created: dist/doc/html/tmp-pkg-0.1.0.0-docs/,
dist/doc/html/tmp-pkg-0.1.0.0-docs/tmp-pkg.txt

This also seems to write to the same directory, overwriting each components files.

From #9852:

When cabal invokes haddock it does so by calling act-as-setup, which is spawning a new process. In particular, all the information gathered in EllaboratedConfiguredPackage is lost, and when haddock is invoked it only has access to InstalledPackageInfos. This means that we have no information whether a dependency is a local component to the project or not, which is needed to correctly pass --read-interface haddock options.

I see we have Distribution.Simple.Haddock.fromPackageDescription, does that not have the information you need?

Public sublibraries are a package-level concept, but here we are changing haddock-project. Why is that?

haddock-project aims to create haddocks for all packages in a given project, including all public sublibraries.

Does cabal haddock properly support public sublibraries?

It does, but writes sublibraries to a directory which shares the same name as the main library, e.g. in your cabal haddock --for-hackage output:

/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/l/b/doc/html/tmp-pkg-0.1.0.0-docs/,
/home/andrea/Scratchpad/tmp-pkg/dist-newstyle/build/x86_64-linux/ghc-9.6.4/tmp-pkg-0.1.0.0/doc/html/tmp-pkg-0.1.0.0-docs/

both components tmp-pkg:tmp-pkg and tmp-pkg:b are written to tmp-pkg-0.1.0.0-docs. The overall path differs, but this is not good enough for cabal haddock-package, for which the last directory name must be different since the prefix is the same (e.g. ./haddocks by default).

This PR changes this behaviour. When cabal haddock-package will be invoked it will write the haddocks to ./haddocks/tmp-pkg and ./haddocks/tmp-pkg-b.

The Distribution.Simple.Haddock.haddock is using:

• fromPackageDescription
• fromLibrary
• fromExecutable

and a few other methods; fromPackageDescription is used to construct common args which are merged with args returned by the other calls when building documentation of some components of the package. I had to modify how fromLibrary works.

Dear all, could you continue the discussion? It would be a shame to let this PR bitrot!

@Mikolaj I got back to it recently :).

@jasagredo I fixed all (but one) issues you reported to me some time ago; could you double check if it works for you:

• [x] it does write the documentation on re-build
• [x] it does write the test-suites documentations
• [x] test-suites/benchmarks/executables are not linked from the main index.html
• [x] --haddock-option="--use-unicode" makes it fail before writing the index.html
• [x] --haddock-option="--use-unicode" doesn't make the html use unicode (so it is passed to the last step but not to the actual runs of haddock on source files??)
• [x] extra-doc-files are overwritten on each package compilation
• [x] references to extra-doc-files (like images) are broken because the files are one level higher up (../)
• [x] the list of units to compile is written twice to the screen. Sometimes it even those two are different
• [ ] documentation is created in pwd, not in the root of the project
• [x] test suites and benchmarks are rendered without CSS

The --haddock-option should be changed: it allows to pass custom option to haddock which is invoked in two scenarios: creating documentation and/or creating indexes - both usecases have allow distinct flags but --haddock-option passes it in both cases (this is the case of --use-unicode). We probably should have --haddock-option and --haddock-index-option - but this is outside of this PR.

Checks are all green; as far as I am concerned, it would be nice to get reviews & merge it.

More things to do:

• [x] fix passing --read-interfaces of local dependencies.
• [x] remove debug output
• [x] test inplace installation

As always I am late to the party. Looking at HaddockProjectFlags, how come the concept of project leaks into Cabal? A project is exclusively a cabal-install concept. Are we using the word "project" with different meanings?

As always I am late to the party. Looking at HaddockProjectFlags, how come the concept of project leaks into Cabal? A project is exclusively a cabal-install concept. Are we using the word "project" with different meanings?

@andreabedini it's the whole point of this experimental command: To generate the haddocks of a whole cabal project (1 or more local packages) to a single documentation artifact

Of course, but it's a cabal-install command, not a Setup.hs command. While HaddockProjectFlags is defined in Cabal.

@Kleidukos I addressed your comments regarding hackage.

I cleaned up the commit messages and updated the changelog entry.