haddock-project support public sublibraries #9821

coot · 2024-03-19T19:24:23Z

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).

coot · 2024-03-21T18:02:41Z

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?

ulysses4ever · 2024-03-22T12:59:32Z

Try removing ~/.cabal maybe.

coot · 2024-03-22T17:24:57Z

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.

coot · 2024-03-22T17:26:17Z

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

Kleidukos

I'd appreciate if you wrote QA notes to ensure that this PR does for others what you expect it to.

Otherwise I don't see anything blocking. :)

Kleidukos · 2024-04-02T20:18:05Z

Cabal/src/Distribution/Simple/BuildPaths.hs

+    LSubLibName sublib_name ->
+      prettyShow (packageName pkg_descr) ++ "-" ++ prettyShow sublib_name
+    _ -> prettyShow (packageName pkg_descr)
+-- TODO: how Hackage should deal with sublibraries?


How do we resolve this question? Do you want to ask gbaz?

Yes, this needs to be considered.

I see two choices:

each sublibrary is available from it's own page;

All public sublibraries are available on the main library page

The former might be cumbersome (since making a revision of each sublibrary will need to make a revision of all of them).

For the latter one might be able to use cabal haddock-project --hackage maybe with some modifications to write a directory containing haddocks of all sublibraries which can be served by hackage. This might be not only more ergonomic but also the simplest way to support public sublibraries on hackage.

desclaimer: I have never contributed to hackage so please take my word with a grain of salt 😄.

^ ping @gbaz

The former might be cumbersome (since making a revision of each sublibrary will need to make a revision of all of them).

What do you mean by "revision" in this sentence? A cabal file revision on Hackage is a package-level thing so it would affect all package's libraries.

I mean package revisions Hackage. I was considering if a sublibrary is exposed on its own, e.g. hackage.com/package/mypackage-sublibrary while the main library is served from hackage.com/package/mypackage.

But if we publish sublibraries as part of the package, e.g. hackage.com/package/mypackage/sublibrary then it will be more consistent. Also finding sublibraries of a package will be simpler if links to them will be rendered on the package page.

I think mypackage/sublibrary is the correct option here.

@coot what's the final word on this?

I haven't changed it from mypackage-sublibrary to mypackage/sublibrary. We'll need to pass a different --base-url for sublibraries, but I already do that for test components and executables, so it's doable.

@coot cool, I'd love this to be documented somewhere so that we don't forget it exists

I adjusted the paths, but there's more work either on cabal side or hackage side. If we have a LIB with a sublibrary SUBLIB, then LIB docs will be placed under LIB-0.1.0.0/doc/html/LIB and the documentation of the sublibrary will be placed under LIB-0.1.0.0/l/SUBLIB/doc/html/LIB/SUBLIB/.

There are various options from here to get sublibrary support on hackage:

use haddock-project on hackage - this might require some changes to haddock-project;

copy the sublibrary documentation to the right place;

as above, but let cabal do that. This might require changing the directory layout of dist-newstyle to be consistent (e.g. drop the l/t subdirs).

I think the first option is the best one - but this is outside of this PR anyway.

coot · 2024-04-02T21:43:32Z

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

coot · 2024-04-02T21:53:40Z

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.

andreabedini · 2024-06-25T07:31:35Z

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?

Kleidukos · 2024-06-25T10:04:13Z

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

andreabedini · 2024-06-25T11:03:22Z

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

coot · 2024-06-28T15:51:25Z

@Kleidukos I addressed your comments regarding hackage.

Kleidukos

Alright, let's get this merged. :)

I'm excited to use it and see which bugs we've missed. ❤️

Thanks for the work @coot

Cabal/src/Distribution/Simple/Haddock.hs

The main library must use the package name rather than `UnitId`, otherwise the links from other sublibraries will not work.

This commit makes haddock-project handle sublibraries. The commit changes how `cabal haddock` works, changing the layout in the `dist-newstyle` folder. With this change `haddock` subcommand will install `package:sublib` component in a directory `package-sublib` under `l/sublib/doc/html/`.

When running haddock-project `extra-doc-files` should be copied to a subdirectories of the `argOutputDir` corresponding to the component. This doesn't affect `haddock` command.

Haddock should know the sublibrary name rather than just the package. For sublibraries `package_name:sublib_name` is used. The name is recorded in the `.haddock` file and used when haddock creates the `index.html` file, e.g. when called by `haddock-project` command.

`--use-unicode` is added to `cabal haddock` and `cabal haddock-project`. One cannot simply use `--haddock-option="--use-unicode"` because it makes haddock to fail when building indexes.

Link test suites & benchmarks from the index.html; Provide the right `--base-url` flag for them.

coot · 2024-06-28T18:11:30Z

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

geekosaur · 2024-11-14T00:55:50Z

Should this have closed #9577?

ulysses4ever · 2024-11-14T01:14:14Z

@geekosaur I think so

coot added cabal-install: cmd/haddock cabal-install: cmd/haddock-project labels Mar 19, 2024

coot force-pushed the coot/haddock-project-sublibs branch 4 times, most recently from f9874c3 to 898ff64 Compare March 20, 2024 19:16

coot force-pushed the coot/haddock-project-sublibs branch 2 times, most recently from 31b34fa to 0bd944e Compare March 22, 2024 09:15

coot force-pushed the coot/haddock-project-sublibs branch 2 times, most recently from 291e98b to 223839d Compare March 22, 2024 16:49

coot marked this pull request as ready for review March 22, 2024 17:27

coot force-pushed the coot/haddock-project-sublibs branch 4 times, most recently from 7ed8b05 to f13915c Compare March 23, 2024 12:40

carbolymer mentioned this pull request Mar 26, 2024

Fix haddocks generation - now using nix IntersectMBO/cardano-cli#445

Merged

3 tasks

coot mentioned this pull request Mar 28, 2024

haddock-project links documentation of local packages to hackage #9852

Open

coot requested a review from andreabedini March 30, 2024 10:53

coot changed the title ~~coot/haddock project sublibs~~ haddock project sublibs Apr 1, 2024

coot changed the title ~~haddock project sublibs~~ haddock-project support public sublibraries Apr 1, 2024

coot requested a review from Kleidukos April 2, 2024 19:23

Kleidukos requested changes Apr 2, 2024

View reviewed changes

coot force-pushed the coot/haddock-project-sublibs branch 2 times, most recently from 9a5b6a7 to 320b408 Compare April 6, 2024 19:48

coot force-pushed the coot/haddock-project-sublibs branch 4 times, most recently from 7008c7d to 2be7de9 Compare June 28, 2024 15:18

Kleidukos self-requested a review June 28, 2024 16:10

Kleidukos approved these changes Jun 28, 2024

View reviewed changes

geekosaur approved these changes Jun 28, 2024

View reviewed changes

coot added 7 commits June 28, 2024 19:53

haddock-project: fixed main library name

21f67d0

The main library must use the package name rather than `UnitId`, otherwise the links from other sublibraries will not work.

haddock-project: copy extra-doc-files to the right directory

446975f

When running haddock-project `extra-doc-files` should be copied to a subdirectories of the `argOutputDir` corresponding to the component. This doesn't affect `haddock` command.

haddock: added --use-unicode flag

727757b

`--use-unicode` is added to `cabal haddock` and `cabal haddock-project`. One cannot simply use `--haddock-option="--use-unicode"` because it makes haddock to fail when building indexes.

haddock: refactored prologue args

f6bd501

haddock-project: test suites and benchmarks

27e3ea6

Link test suites & benchmarks from the index.html; Provide the right `--base-url` flag for them.

coot force-pushed the coot/haddock-project-sublibs branch from 2be7de9 to fb68bc4 Compare June 28, 2024 18:10

coot added the merge me Tell Mergify Bot to merge label Jun 28, 2024

haddock-project: added changelog.d entry

b118edb

coot force-pushed the coot/haddock-project-sublibs branch from fb68bc4 to b118edb Compare June 30, 2024 15:51

coot merged commit 8466a8f into master Jun 30, 2024
57 checks passed

coot deleted the coot/haddock-project-sublibs branch June 30, 2024 20:39

coot mentioned this pull request Jul 1, 2024

Refactored package structure: use sublibraries input-output-hk/io-sim#115

Merged

mergify bot added the merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days label Jul 2, 2024

geekosaur mentioned this pull request Nov 14, 2024

Generate haddock for multiple (sub)libraries at once #9577

Closed

haddock-project support public sublibraries #9821

haddock-project support public sublibraries #9821

Uh oh!

Conversation

coot commented Mar 19, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

QA Notes

Uh oh!

coot commented Mar 21, 2024

Uh oh!

ulysses4ever commented Mar 22, 2024

Uh oh!

coot commented Mar 22, 2024

Uh oh!

coot commented Mar 22, 2024

Uh oh!

Kleidukos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coot commented Apr 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coot commented Apr 2, 2024

Uh oh!

andreabedini commented Jun 25, 2024

Uh oh!

Kleidukos commented Jun 25, 2024

Uh oh!

andreabedini commented Jun 25, 2024

Uh oh!

coot commented Jun 28, 2024

Uh oh!

Kleidukos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coot commented Jun 28, 2024

Uh oh!

Uh oh!

geekosaur commented Nov 14, 2024

Uh oh!

ulysses4ever commented Nov 14, 2024

Uh oh!

Uh oh!

coot commented Mar 19, 2024 •

edited

Loading

coot commented Apr 2, 2024 •

edited

Loading