Allow to hide interfaces when rendering multiple components

[coot]

This is useful when one wishes to --gen-contents when rendering
multiple components, but one does not want to render all modules in the module graph. This
is in particular useful when adding base package to interfaces, to prevent from rendering all of its modules making the important modules hard to find. Adding base package through --read-interface is useful so links to things like IO can be resolved.

This PR changes parsing of --read-interface in backward compatible way.

[coot]

We should bump the version of haddock program, this will allow cabal to use that feature when it's available.

[Kleidukos]

@coot Do you need it in a timeline shorter than GHC 9.4?

[coot]

Do we have a chance to get cabal and haddock releases before ghc-9.4? If we do, then I think it would be nice. But it's worth to mention that if cabal's release comes before haddock's then some parts will be broken (building with documentation of dependencies, because of #1488).

[Kleidukos]

Ok, we'll coordinate with Cabal then

[Kleidukos]

@Mikolaj FYI ☝️

[Mikolaj]

Hi! That's a perfect moment, because we are going to release cabal 3.8.1 soon and we can depend on the new haddock and there is just enough time to test it a tiny bit. Would you mind creating a cabal PR?

[Mikolaj]

I forgot, and was reminded by @Kleidukos that cabal does not depend directly on haddock. Here's some brainstorming:

but GHC bundles haddock, right? so there may be an indirect dep via base?
but one can probably re-install haddock (though probably cabal plans try not to) and then, indeed, there is are no dep constrains in cabal that would prevent this
if the above is right, then indeed it's hard to expose pre-release users of cabal to new haddocks
I mean, newer than what the stable GHC bundles
we'd need to add the haddock dep, force it to be newer than bundled, include it in cabal's gitlab artifacts that users download
that sounds too risky so close to 3.8.1
any ideas?

[Mikolaj]

Sadly, it seems we need cabal to be able to work with old haddock in 9.2 and with new one in 9.4. Sounds like CPP. BTW, it would be bad if older cabal, e.g., 3.6.3 was broken with haddock from 9.4. If so, GHC 9.4 would need to advertise it requires cabal 3.8. But there's probably not enough time before 9.4 release to set it all up, given that cabal is not yet even aware of the changes. Could we slow it down or make optional or degrade gracefully in case of new haddock and old cabal?

[Mikolaj]

I've now git-grepped:

Cabal/ChangeLog.md:  * `--hyperlink-source` now uses Haddock's hyperlinker backend when
Cabal/ChangeLog.md:    Haddock is new enough, falling back to HsColour otherwise.

Cabal/src/Distribution/Simple/Haddock.hs-    when (flag haddockHoogle && version < mkVersion [2,2]) $
Cabal/src/Distribution/Simple/Haddock.hs:      die' verbosity "Haddock 2.0 and 2.1 do not support the --hoogle flag."

so apparently we can at least determine the version of haddock and act accordingly (and not via CPP).

[coot]

@Mikolaj I relay on haddock's advertised version in the same way. The only disadvantage of publishing cabal ahead of haddock, from my perspective, would be that cabal haddocks is broken. In my draft pr, I made a patch which actually makes it possible to use cabal ... --with-haddock=./haddock (which I've been using for testing), so postponing haddocks is not necessary, we can just disable it for all versions bellow 2.26.1.

[Mikolaj]

Disable what exactly for what version?

[coot]

I speaking about haddocks command in the pr (if that will be included) which requires haddock-2.26.1.

[Mikolaj]

@coot: pardon me being dense and let me rephrase and please correct me. Current master branch of cabal is not broken, right? It would be broken if your cabal PR was merged and found its way into a released cabal, but new haddock was not released by that time? And a way to prevent this breakage is to test for haddock version in the PR and disable all the functionality that doesn't work with old haddock?

[coot]

Current master branch of cabal is not broken, right?

Right, it isn't.

It would be broken if your cabal PR was merged and found its way into a released cabal, but new haddock was not released by that time?

It actually wouldn't. Today I added a requirement for the haddocks command to use haddock-2.26.1; So if cabal was released but haddock wouldn't users could either:

• wait
• compile haddock; and use --with-haddock (my PR contains a patch which fixed --with-haddock flag)

And a way to prevent this breakage is to test for haddock version in the PR and disable all the functionality that doesn't work with old haddock?

Yes

[Mikolaj]

Amazing. If there's anything we can help with on the cabal side, please make sure to let us know.

[coot]

Review haskell/cabal#8162 :)