haddock-project fixes #8919

coot · 2023-04-25T20:36:28Z

This PR includes three commits which later haddock-project command:

use UnitId instead of package name
changed default haddock-project options (fixes The index.html that are supposed to be produced by cabal haddock-project are not here. #8843)
build dependencies so their haddocks are available in the store (fixes haddock-project --local does not copy non-boot dependencies to output dir #8958)

QA Notes:

`cabal haddock-project`

Running cabal haddock-project should create documentation folder ./haddocks which contains:

./haddocks/<package-name> folder for every dependency of the project; in particular ./haddocks/<package-name>/<package-name>.haddock should be present;
./haddocks/index.html;
./haddocks/quick-jump.min.js

When serving the ./haddocks folder with http server the index page should list all the local packages. Using quick jump from the index page should allow to find any identifier found in any of the local packages, when viewing documentation of one of them quick jump should allow to jump to any identifier of that package. All entities should be linked, e.g. if you find IO in the documentation, it should lead you to base documentation of IO.

`cabal haddock-project --hackage`

Running cabal haddock-project --hackage should create documentation folder ./haddocks which only contains documentation of local packages. Identifiers from dependencies should be linked to hackage.

Please include the following checklist in your PR:

Patches conform to the coding conventions.
Any changes that could be relevant to users have been recorded in the changelog.
The documentation has been updated, if necessary.
Include manual QA notes if your PR relates to cabal-install.

Bonus points for added automated tests!

coot · 2023-04-26T07:01:38Z

@Kleidukos do you know a package published on Hackage which is using visible sublibraries? I haven't found any among recent uploads.

coot · 2023-04-26T07:05:29Z

haskell/hackage-server#1119 is still open...

Mikolaj · 2023-04-26T08:14:33Z

The CI failure seem to be expected at this point?

I've tentatively marked it for backport to 3.10 branch, since it fixes (semi-) regressions and it's not a huge risky PR.

coot · 2023-04-26T10:24:02Z

The CI failure seem to be expected at this point?

It's unexpected. I'll try to reproduce it locally.

coot · 2023-04-26T17:39:49Z

Looking closer, these CI failures are expected. I changed the log output of the cabal haddock command. It no longer reports that haddock created index.html file if it didn't received --gen-index file.

`--gen-index`	result
present	log location of the `index.html` file created
not present	log directory location of the documentation

coot · 2023-04-26T18:09:19Z

@Mikolaj do you want me to create a PR against the 3.10 branch?

Mikolaj · 2023-04-26T18:11:46Z

@Mikolaj do you want me to create a PR against the 3.10 branch?

No, thank you. Mergify will do this automatically for us and I sincerely hope there won't be any conflicts.

coot · 2023-04-26T18:21:48Z

nice :), there shouldn't be any.

Kleidukos · 2023-04-29T10:51:00Z

@Kleidukos do you know a package published on Hackage which is using visible sublibraries? I haven't found any among recent uploads.

@coot I don't even know if it's allowed. Hackage doesn't seem to support it?

ulysses4ever · 2023-04-29T13:28:31Z

haskell/hackage-server#1119 is still open...

It is but a comment there
haskell/hackage-server#1119 (comment) says it should work. Just no one tried it...

cabal-install/src/Distribution/Client/CmdHaddockProject.hs

Kleidukos

Good for me!

coot · 2023-05-20T11:46:28Z

I pushed one more commit to fix #8958.

ulysses4ever · 2023-05-20T12:10:51Z

@coot could you add a test that ensures that dependencies are handled correctly?

coot · 2023-05-20T18:10:18Z

yes, I am planning to do that.

Mikolaj

After a quick look, LGTM, but a more thorough review would be welcome.

Whether we backport is up to @Kleidukos.

Kleidukos · 2023-06-29T11:42:00Z

@Mergifyio backport 3.10

mergify · 2023-06-29T11:42:04Z

backport 3.10

✅ Backports have been created

#9088 haddock-project fixes (backport #8919) has been created for branch 3.10 but encountered conflicts

Kleidukos · 2023-06-29T11:43:05Z

@julialongtin would you like to perform the QA procedure on this PR? :)

ulysses4ever · 2023-07-01T14:09:37Z

@coot you reached 2 approvals now, so you can put the merge-me label when you feel like it and hand it over to the bot (it will wait for 2 days before merge as usual). Thank you for your contribution and also for addressing my comments in particular!

coot · 2023-07-02T09:25:45Z

Thanks @ulysses4ever, @Kleidukos & @Mikolaj for cooperation.

Mikolaj · 2023-07-03T16:40:30Z

Thank you, @coot. That's a long struggle, but many people waited years for these features and here they are finally, more and more usable.

coot · 2023-07-05T06:29:25Z

Shouldn't mergify do its job by now?

ulysses4ever · 2023-07-05T09:55:51Z

I think you commented before the full 48 hours passed. And now the timer is probably reset. But let's fix it.

Mikolaj · 2023-07-05T18:38:19Z

@Mergifyio refresh

mergify · 2023-07-05T18:38:23Z

refresh

✅ Pull request refreshed

Mikolaj · 2023-07-05T18:40:26Z

It says "Unable to update: user coot is unknown. Please make sure coot has logged in Mergify dashboard."

What was that about?

ulysses4ever · 2023-07-05T18:42:31Z

In the failure like this (" ❌ Queue: Embarked in merge train"), rebase is usually the way to go (Mergify fails to rebase a PR from a non-admin user on its own). "Refresh" works better when the bot thinks that some checks are not satisfied.

ulysses4ever · 2023-07-05T18:42:59Z

@mergify rebase

This patch fixes a bug where a sublibrary overwrites a library directory. This leads to overwriting `*.haddock` files, which results in missing entries in various indexes (e.g. the html index, quicksearch).

This patch makes `haddock-project` use `--local` option by default. Since its the default, it is removed. Also `--gen-index`, `--gen-contents`, `--hyperlinked-source` and `--quickjump` are removed since they are always turned on. Added a haddock-project test.

`haddock-project` command need to build the project so that haddocks of the dependencies are available in the store. Fixes #8958.

mergify · 2023-07-05T18:43:11Z

rebase

✅ Branch has been successfully rebased

coot requested a review from Kleidukos April 25, 2023 20:37

coot marked this pull request as ready for review April 25, 2023 20:42

coot force-pushed the coot/haddock-package-fixes branch from 4ad4ab9 to 5e24585 Compare April 26, 2023 07:00

Mikolaj added cabal-install: cmd/haddock attention: needs-backport 3.12 labels Apr 26, 2023

coot force-pushed the coot/haddock-package-fixes branch from 5e24585 to 076f70c Compare April 26, 2023 18:07

coot force-pushed the coot/haddock-package-fixes branch 3 times, most recently from dbebb68 to 53cc424 Compare April 26, 2023 20:41

Mikolaj added the attention: needs-review label Apr 27, 2023

coot force-pushed the coot/haddock-package-fixes branch 2 times, most recently from e0b461a to ec1027a Compare April 29, 2023 09:14

Kleidukos requested changes May 8, 2023

View reviewed changes

cabal-install/src/Distribution/Client/CmdHaddockProject.hs Outdated Show resolved Hide resolved

coot force-pushed the coot/haddock-package-fixes branch from ec1027a to 4d2e7bd Compare May 13, 2023 20:09

Kleidukos approved these changes May 14, 2023

View reviewed changes

coot mentioned this pull request May 20, 2023

haddock-project --local does not copy non-boot dependencies to output dir #8958

Closed

coot force-pushed the coot/haddock-package-fixes branch from ce698df to 24c4c07 Compare May 21, 2023 13:15

ulysses4ever removed their request for review June 29, 2023 06:15

Mikolaj approved these changes Jun 29, 2023

View reviewed changes

coot added the merge me Tell Mergify Bot to merge label Jul 2, 2023

ulysses4ever added merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days and removed attention: needs-review labels Jul 5, 2023

coot added 3 commits July 5, 2023 18:43

haddock-project: use UnitId instead of package names

1840bca

This patch fixes a bug where a sublibrary overwrites a library directory. This leads to overwriting `*.haddock` files, which results in missing entries in various indexes (e.g. the html index, quicksearch).

Build dependencies with haddock-project

2c597e8

`haddock-project` command need to build the project so that haddocks of the dependencies are available in the store. Fixes #8958.

ulysses4ever force-pushed the coot/haddock-package-fixes branch from d74a550 to 2c597e8 Compare July 5, 2023 18:43

mergify bot merged commit a93d693 into master Jul 5, 2023

mergify bot deleted the coot/haddock-package-fixes branch July 5, 2023 21:07

mergify bot mentioned this pull request Jul 5, 2023

haddock-project fixes (backport #8919) #9088

Closed

ulysses4ever mentioned this pull request Jul 17, 2023

Remove --cabal-file option #9123

Merged

5 tasks

This was referenced Aug 25, 2023

Add changelogs for 3.10.2.0 #9207

Merged

haddock-packages fixes #9213

Merged

Mikolaj removed the attention: needs-backport 3.12 label Apr 8, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

haddock-project fixes #8919

haddock-project fixes #8919

coot commented Apr 25, 2023 •

edited by Kleidukos

Loading

coot commented Apr 26, 2023

coot commented Apr 26, 2023

Mikolaj commented Apr 26, 2023

coot commented Apr 26, 2023

coot commented Apr 26, 2023

coot commented Apr 26, 2023

Mikolaj commented Apr 26, 2023 •

edited

Loading

coot commented Apr 26, 2023

Kleidukos commented Apr 29, 2023

ulysses4ever commented Apr 29, 2023

Kleidukos left a comment

coot commented May 20, 2023

ulysses4ever commented May 20, 2023

coot commented May 20, 2023

Mikolaj left a comment

Kleidukos commented Jun 29, 2023

mergify bot commented Jun 29, 2023 •

edited

Loading

Kleidukos commented Jun 29, 2023

ulysses4ever commented Jul 1, 2023

coot commented Jul 2, 2023

Mikolaj commented Jul 3, 2023

coot commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023 •

edited

Loading

Mikolaj commented Jul 5, 2023

mergify bot commented Jul 5, 2023

Mikolaj commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023

mergify bot commented Jul 5, 2023

haddock-project fixes #8919

haddock-project fixes #8919

Conversation

coot commented Apr 25, 2023 • edited by Kleidukos Loading

QA Notes:

cabal haddock-project

cabal haddock-project --hackage

coot commented Apr 26, 2023

coot commented Apr 26, 2023

Mikolaj commented Apr 26, 2023

coot commented Apr 26, 2023

coot commented Apr 26, 2023

coot commented Apr 26, 2023

Mikolaj commented Apr 26, 2023 • edited Loading

coot commented Apr 26, 2023

Kleidukos commented Apr 29, 2023

ulysses4ever commented Apr 29, 2023

Kleidukos left a comment

Choose a reason for hiding this comment

coot commented May 20, 2023

ulysses4ever commented May 20, 2023

coot commented May 20, 2023

Mikolaj left a comment

Choose a reason for hiding this comment

Kleidukos commented Jun 29, 2023

mergify bot commented Jun 29, 2023 • edited Loading

✅ Backports have been created

Kleidukos commented Jun 29, 2023

ulysses4ever commented Jul 1, 2023

coot commented Jul 2, 2023

Mikolaj commented Jul 3, 2023

coot commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023 • edited Loading

Mikolaj commented Jul 5, 2023

mergify bot commented Jul 5, 2023

✅ Pull request refreshed

Mikolaj commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023

ulysses4ever commented Jul 5, 2023

mergify bot commented Jul 5, 2023

✅ Branch has been successfully rebased

coot commented Apr 25, 2023 •

edited by Kleidukos

Loading

`cabal haddock-project`

`cabal haddock-project --hackage`

Mikolaj commented Apr 26, 2023 •

edited

Loading

mergify bot commented Jun 29, 2023 •

edited

Loading

ulysses4ever commented Jul 5, 2023 •

edited

Loading