Generated documentation website visual layout (navigation)

[flip111]

On the generated documentation website there is this GROUP BY PACKAGE checkbox. It's a bit funny UI.

What about instead of a single Index in the navigation bar (top right), there will be two items instead Modules and Packages?

[f-f]

I moved this issue into Spago, as this is part of the Halogen app that we add on top of the generated docs. Sources is here and PRs are most welcome 🙂

[f-f]

I don't have an opinion on the proposed change as of now, I think I'd need to see it visualised

[flip111]

[CharlesTaylor7]

I agree the layout is a bit funky. For now it could be adapted to just be the list of modules. The grouping is not actually by package, but just into 3 groups: "local package", "builtins", and "everything else". I don't find those broad groupings very useful.

[f-f]

IIRC previously it would actually group by package?
I think having it always grouped by package would be the most useful - sometimes I look for the package, sometimes I look for the module. We should load the page with the list of packages, and expand to the list of modules when clicking on an arrow next to it. Maybe have an "expand all" button too.

[flip111]

We should load the page with the list of packages, and expand to the list of modules when clicking on an arrow next to it. Maybe have an "expand all" button too.

Great idea 👍

[f-f]

This is very close to what the previous Spago/docs-search did. I think the "group by package" feature broke in the migration, because it was more useful then - this picture is generated from the aff repo with Spago 0.21.0 and PureScript 0.14.9:

We'd keep a similar vibe, but with an arrow next to the package that lets you expand to the list of modules. Right now that heppens when you click on a package, but we should instead redirect to the readme of the package, just like in pursuit.

We'd also take away the checkbox for grouping by package because we'd always group by package like this, and add an "Expand/contract all" button to expand all the module lists in the packages.

[CharlesTaylor7]

This is very close to what the previous Spago/docs-search did. I think the "group by package" feature broke in the migration, because it was more useful then

I'm glad you brought this up. I did some sleuthing last night, and got it to split by packages again. I'll followup in the PR thread, with details.

We'd keep a similar vibe, but with an arrow next to the package that lets you expand to the list of modules.
...
We'd also take away the checkbox for grouping by package because we'd always group by package like this, and add an "Expand/contract all" button to expand all the module lists in the packages.

These are good changes. 👍

Right now that heppens when you click on a package, but we should instead redirect to the readme of the package, just like in pursuit.

Are we likely to have local copies of readmes?
I know npm publish always includes README.md, does spago publish do this too?

I ask, because I wanna keep spago docs as a feature that doesn't require an internet connection. If I'm online I'm usually reaching for Pursuit, instead.

[f-f]

Are we likely to have local copies of readmes?

We are. This is not yet a thing (not sure if we even have an issue for this), but we would like to enforce the presence of a README for Registry packages, so that we can embed them in the archives and Pursuit doesn't have to fetch them from somewhere else, but can access them offline.

Adding a "package page" would get us one step closer to "Pursuit in PureScript" as well 🙂