UI for multiple public libraries

[michaelpj]

Looks like there currently isn't any, really. https://hackage.haskell.org/package/lsp-types has a second public library but there's no evidence of it on the page.

[gbaz]

mildly related #577

[ysangkok]

I can work on this after I get vouching done.

[414owen]

I'm happy to take a stab at this.

I've made changes that get the modules to show per-library. Seems to work fine.

I'd also be in favour of listing dependencies per-library on the main package page (as opposed to having to click into the easy-to-miss details section). One of the use-cases of sub-libraries it to have a lightweight core library, then separate sub-libraries for integrating into other parts of the ecosystem. For instance, I have a library that depends only on base, and a sub-library which adds instances from the semigroupoids package. I'd like to make it clear that my (main) library is lightweight.

Not sure if the view heirarchy should be:

• Modules
  • lib-a
  • lib-b
• Sigs
  • lib-a
  • lib-b

or

• lib-a
  • Modules
  • Sigs
• lib-b
  • Modules
  • Sigs

I'll play around with it and see what feels good.

[gbaz]

Great to hear you're working on the changes!

I think the second approach is better, with the caveat that we shouldn't have the "lib-a, lib-b" top level package hierarchy when there is only one exposed public library. Similarly we shouldn't have the signatures section and modules section split in the second level when there are only modules.

I'm sympathetic to wanting to have the dependencies per-library. However, for packages with many dependencies, splitting them out would make things even more cluttered than they are now. Maybe we can just highlight the details link better, and perhaps make it more descriptive?

[414owen]

Yep, that's all sensible. I'll optimise for lack of visual clutter.

If I figure out how to display the dependencies per-library in an uncluttered way, it'll be in a separate changeset anyway.

[michaelpj]

The current approach seems to be to do something like: for each top-level section, split it up by component.

This seems fine for packages with a smallish number of components, but I'm not sure it's going to scale. In particular, imagine if amazonka actually did move over to multiple public libraries. Then there would be dozens of libraries! It would then be really annoying trying to cross-reference the dependencies (2/3 of the way down one massive element) with the haddock (2/3 of the way down a different massive element).

It seems to me like it would be more scalable to have the top-level split be by component, and then have the sub-sections within that. Perhaps harder to implement nicely, though!

[414owen]

I think you're definitely onto something, at least for the pathological case.

A top-level split would also fix my qualm about dependencies not being per-library, as, if I'm picturing it correctly, the dependencies section would then also be for a specific library.

---

A top-level split could be implemented in the right-hand-side sidebar:

Not sure about the combined view yet, I imagine it being the same as after #1279.

I think it might get confusing if we display the main package page when someone clicks on one of the sublibraries...
Someone who doesn't know what's going on might think they're seeing everything, but they're stuck on a sublibrary that contains very little.

---

If it's just a space/pathological case thing, maybe we could add a quick fix by rolling up the module sections:

---

Otherwise, there are more nuclear options than these.
We could make the package page just for the package information and readme, and link to component pages, where the component page is a new thing that contains (for now, just) the module listings.

[michaelpj]

Having the sections collapsed might work, yeah. Then you can just expand the ones you care about, which isn't so bad.

I think the only truly robust solution is indeed a component page, with the package page linking to the components and showing only package-level metadata. But that's probably a lot more work.

[michaelpj]

If you want a fun example, I'm toying with merging all the plugin packages with HLS proper and publishing them together, which would mean the package would have some 28 libraries and 28 test suites. So that would be a challenge to render (although it doesn't matter so much, as HLS is mainly an executable).

POC here: haskell/haskell-language-server#3976