haddock-project command by coot · Pull Request #8162 · haskell/cabal

coot · 2022-05-24T18:50:02Z

Fixes #7669, also fixes --with-haddock support which is useful when testing a newer version of haddock than the one distributed with ghc.

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.

Please also shortly describe how you tested your change. Bonus points for added tests!

coot · 2022-05-24T19:01:24Z

This PR can be reviewed patch by patch. Currently it's missing:

hoogle support
hiding modules from dependencies in the main page; and
~~support quickjump for installed packages~~
test how it integrates with:

--haddock-html-location 'https://hackage.haskell.org/package/$pkg-$version/docs'

Mikolaj · 2022-05-30T17:23:50Z

I think it's the same Validate / Validate windows-latest ghc-8.0.2 (pull_request) job failing non-deterministically in may PRs (though the log details differ from time to time). Let's keep track and disable it if it repeats. For now, let me restart the failing jobs.

Edit: no, actually last time it was Validate windows-latest ghc-8.6.5 that failed.

Mikolaj · 2022-05-30T17:47:42Z

This time the error at least seems related to haddock...

coot · 2022-06-04T13:24:27Z

All tests are green 🟢

Mikolaj · 2022-06-04T15:14:50Z

All tests are green green_circle

Congrats. We'll review RSN.

Kleidukos

This is a big PR! Thank you very much for this work. :)

Kleidukos · 2022-06-04T16:39:54Z

@Mikolaj I would be most comfortable if we could advertise this for the next release candidate of 3.8 :)

ulysses4ever · 2022-06-04T16:44:38Z

A little late bikeshedding here. I'm not a big fan of flags/commands differing in one letter, e.g. haddock vs. haddocks. Not only it's easy to misspell, but it's harder to remember the difference. I'd prefer it be called something like haddock-project.

This is not a hard stop for me, no way. Wanted to throw it in to see if anyone is sympathetic to the idea.

Kleidukos · 2022-06-04T16:57:57Z

Indeed there is merit to this review

Mikolaj · 2022-06-04T20:37:39Z

@Mikolaj I would be most comfortable if we could advertise this for the next release candidate of 3.8 :)

How likely is this to break things not related to haddock?

Kleidukos · 2022-06-04T21:14:17Z

@Mikolaj It's a thousand lines PR, and since we can't easily rollback stuff like a SAAS, I'd rather have our beta-testers try it out before we settle on the final release. ;)

gbaz · 2022-06-04T22:40:27Z

I think the timing is wrong for the first 3.8 release sadly. We declared it was feature complete over a month ago, and we've released a candidate that, barring urgent bug fixes or regressions, is intended to be the same as the final 3.8 release.

This work looks really useful and I'm excited to have it in. But I think, given the size involved, and the need for giving people time to really test and use such functionality, that this should be milestoned for the following release of cabal-install.

Kleidukos · 2022-06-05T05:42:25Z

Sorry my English was at fault here, my preoccupation was to have this feature beta-tested before shipped in a release. The fact that it's not 3.8 is not a problem, but I feared that there wouldn't be another RC if this feature was integrated into 3.8

merijn · 2022-06-13T10:12:14Z

I don't have sufficient rights to add a label, so I'll just say it's ready :)

Did it for you :)

Added: * `haddockIndex`: passed as '--use-index' to 'haddock' * `haddockBaseUrl` : passed as '--base-url' to haddock'

This is useful for passing arguments to `haddock-project` command which will create haddocks for all the components, together with a consistent index.

We need 'renderArgs' to work when we create an index. In this case some of the options will not be set.

Added arguments: * 'argGenContents': haddocks' '--gen-contents' * 'argGenIndex': haddocks' '--gen-index' * 'argPrologueFile': haddocks' '--prologue' but unlike '--argPrlogue' it passes the file name not the prologue text itself.

The 'haddock-project' command can be used to create haddocks of all components together with indexes (html, quickjump) and the content page.

This allows to test against a newer version of haddock than one that comes with `ghc`, even with head of `haddock` repository.

It was broken in various ways :/ * The CmdHaddock (and CmdHaddockProject) have to restore the paths set with 'haddockProgramPath' (or 'haddockProjectProgramPath'); * haddock is not by default in 'ProgramDb'; We need to add it first, otherwise 'reconfigure' will not update its path. * 'setupHsHaddockFlags', need to store haddock location in 'haddockProgramPaths. This patch also adds 'haddockProjectProgramPath' and 'haddockProjectProgramArgs' to 'HaddockProjectFlags' which are passed to 'CmdHaddockProject'.

…mand Haddock-2.26.1 allows to configure whether modules from a given interface file should be visible on the generated content page. We make visible only modules which come from local packages.

Generated haddocks will have valid links to packages distributed with GHC, e.g. `base`, `bytestring`, `array`, etc.

It is supported at least from `haddock-2.16`.

By passing `--haddock-html-location` one can link to haddocks to documentation published on hackage. However one can use it or `--base-url`. The latter will build self contained directory of haddock documentation.

Mikolaj · 2022-06-13T14:41:25Z

I don't have sufficient rights to add a label, so I'll just say it's ready :)

Apologies, that's an oversight. It will be an honour for our team if you accept the repo invite I've just sent.

coot force-pushed the coot/haddocks branch 2 times, most recently from 8b1239e to c3668b9 Compare May 25, 2022 07:08

coot mentioned this pull request May 25, 2022

Use visibility to decide which interfaces are included in quickjump haskell/haddock#1490

Merged

Kleidukos self-requested a review May 25, 2022 18:52

coot mentioned this pull request May 26, 2022

Allow to hide interfaces when rendering multiple components haskell/haddock#1487

Merged

coot force-pushed the coot/haddocks branch from c3668b9 to 024d9fe Compare May 28, 2022 05:53

coot mentioned this pull request May 28, 2022

Use new haddock multi-package support #7669

Closed

coot force-pushed the coot/haddocks branch from 024d9fe to 6e90609 Compare May 29, 2022 06:54

coot marked this pull request as ready for review May 29, 2022 06:55

coot force-pushed the coot/haddocks branch 3 times, most recently from 6bacfe5 to fce52ba Compare May 30, 2022 06:51

Mikolaj self-requested a review May 30, 2022 17:27

coot force-pushed the coot/haddocks branch 2 times, most recently from 46e33c6 to ee40652 Compare June 4, 2022 10:07

Mikolaj added the attention: needs-review label Jun 4, 2022

Kleidukos approved these changes Jun 4, 2022

View reviewed changes

Mikolaj added this to the Considered for 3.8 milestone Jun 4, 2022

coot added 19 commits June 13, 2022 10:12

Refactor Distribution.Simple.Haddock.haddocks

905b30d

Extend HaddockFlags

1023d65

Added: * `haddockIndex`: passed as '--use-index' to 'haddock' * `haddockBaseUrl` : passed as '--base-url' to haddock'

Added HaddockProjectFlags

5737f11

This is useful for passing arguments to `haddock-project` command which will create haddocks for all the components, together with a consistent index.

Relaxed preconditions of parsePureArgs and renderArgs

6d8adf1

We need 'renderArgs' to work when we create an index. In this case some of the options will not be set.

Extended HaddocksArgs

396c354

Added arguments: * 'argGenContents': haddocks' '--gen-contents' * 'argGenIndex': haddocks' '--gen-index' * 'argPrologueFile': haddocks' '--prologue' but unlike '--argPrlogue' it passes the file name not the prologue text itself.

Added createHaddockIndex

e01c9f1

Added haddock-project command

b329163

The 'haddock-project' command can be used to create haddocks of all components together with indexes (html, quickjump) and the content page.

Added support for --haddock-lib option of the haddock-project command

7564f50

This allows to test against a newer version of haddock than one that comes with `ghc`, even with head of `haddock` repository.

Added support for hoogle for the haddock-project command

095244c

Added support to visible / hidden modules for the haddock-project com…

3e6e651

…mand Haddock-2.26.1 allows to configure whether modules from a given interface file should be visible on the generated content page. We make visible only modules which come from local packages.

Added support for installed packages for the haddock-project command

6269f74

Generated haddocks will have valid links to packages distributed with GHC, e.g. `base`, `bytestring`, `array`, etc.

Pass --package-name & --package-version to haddock

c0e6d01

It is supported at least from `haddock-2.16`.

Support --haddock-html-location

f035633

By passing `--haddock-html-location` one can link to haddocks to documentation published on hackage. However one can use it or `--base-url`. The latter will build self contained directory of haddock documentation.

Added --local and --hackage options for haddocks command

6e40a8b

Added experimental warning to the haddocks command.

a5e9c12

Haddocks command requires haddock-2.26.1

b8fb12a

Added changelog entry for this PR

88078b4

Added documentation of haddocks command.

eee9bac

andreabedini force-pushed the coot/haddocks branch from 3aaf98a to eee9bac Compare June 13, 2022 10:12

mergify Bot merged commit c024065 into haskell:master Jun 13, 2022

coot deleted the coot/haddocks branch June 13, 2022 14:43

coot changed the title ~~Haddocks command~~ haddock-project command Jun 13, 2022

Mikolaj mentioned this pull request Jul 27, 2022

Generating haddocks sometimes produces "doc-index.json does not exist" #8326

Open

Mikolaj removed this from the Considered for 3.10 milestone Jul 27, 2022

coot mentioned this pull request Sep 29, 2022

Links to dependencies broken in published Haddocks IntersectMBO/ouroboros-network#2138

Closed

michaelpj mentioned this pull request Oct 10, 2022

Include standalone haddock derivation for a project input-output-hk/haskell.nix#737

Open

brendanhay mentioned this pull request May 1, 2023

Update README.md and remove references to Bazel brendanhay/amazonka#906

Merged

Conversation

coot commented May 24, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coot commented May 24, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mikolaj commented May 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mikolaj commented May 30, 2022

Uh oh!

coot commented Jun 4, 2022

Uh oh!

Mikolaj commented Jun 4, 2022

Uh oh!

Kleidukos left a comment

Choose a reason for hiding this comment

Uh oh!

Kleidukos commented Jun 4, 2022

Uh oh!

ulysses4ever commented Jun 4, 2022

Uh oh!

Kleidukos commented Jun 4, 2022

Uh oh!

Mikolaj commented Jun 4, 2022

Uh oh!

Kleidukos commented Jun 4, 2022

Uh oh!

gbaz commented Jun 4, 2022

Uh oh!

Kleidukos commented Jun 5, 2022

Uh oh!

merijn commented Jun 13, 2022

Uh oh!

Mikolaj commented Jun 13, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

coot commented May 24, 2022 •

edited

Loading

coot commented May 24, 2022 •

edited

Loading

Mikolaj commented May 30, 2022 •

edited

Loading