x/pkgsite: auto-expand left sidebar

[jayconrod]

What is the URL of the page with the issue?

Any package, for example, https://pkg.go.dev/net/http?tab=doc

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36

Screenshot

What did you expect to see?

This may be more of a personal preference than a bug, so feel free to close...

Before the sidebar was introduced, the first thing I usually did when reading package documentation was to click the Index. This provided a great overview of all the definitions in the package, which is helpful when I don't know the name of the definition I want.

Index has been replaced by the navigation sidebar on the left. I think this is generally a good idea: it's nice to have it visible after clicking through to a definition. However, Functions and Types are not expanded by default within the sidebar, so reading through definitions requires extra clicks on small disclosure triangles. Would it be possible to expand these by default?

What did you see instead?

Functions and Types are not expanded.

[mrg0lden]

I wish variables were listed as well, just like types and functions, with types' methods and functions expanded as well.

There's another annoying CSS thing. Currently the navigation has overflow-y: scroll which shows an ugly scroll bar even when it's not needed.

Picture

I suggest it gets removed. The default behavior will be the scrollbar appearance once the content exceeds the element height (which could be set to something like 80vh or calc(100vh - var(--navbar-height))).

I also suggest using something like simplebar or overlayScrollbars which provides a much nicer looking scrollbar (for the navigation part) without sacrificing the default scrolling behavior.

[salewski]

Having the functions, types, and (possibly) variables in the sidebar expanded by default would make it easier to get a sense of the API at a glance. Still, it would be no substitute for the Index we know and love from godoc.org because full function signatures cannot fit comfortably into a sidebar.

Because the Index view contains so much high value content in a condensed form, there's often no need to drill any deeper. This is increasingly true over time as one becomes more familiar with a given API.

There's a related conversation happening in issue #40612 for including an Index-like view.

[jayconrod]

Another example where this causes problems: top-level functions that return a type declared in the package are grouped together with that type, which makes them hard to find when the index is collapsed.

Let's suppose I'm looking for a function in net/http that sends a GET request. I'd expand the Functions section on the left side bar to see if there's anything that sounds like it might help.

Unfortunately, the Get function is not listed there. Get has the signature func(string) (*Response, error), so it's grouped together with Response under Types. I would not have thought to look there.

---

[rakyll]

This UI change is really making it hard to navigate the package docs. Package index is an entry point for many users. The index serves as a summary of what's in the package. Users often CTRL+F to search for symbols and go through the entire list to have an understanding of what package provides. Having to manually expand the list is breaking how we use the package index fundamentally.

[zombiezen]

On the search side, perhaps the sidebar could grow a search bar to make the "F" hotkey functionality more discoverable?

+1 for some kind of expand/collapse all button even with that.

[jayconrod]

@julieqiu @andybons Gentle ping. Would be good to know what you're thinking for this.

[julieqiu]

/cc @spf13 @fflewddur for product / UXR input

[andybons]

• Functions and types are now expanded by default as of https://golang.org/cl/248183. My guess is that we haven’t deployed that change yet and/or the documentation needs to be reprocessed.
• The fix to not show the scrollbar when there’s nothing to scroll has also landed.

There’s a lot of other feedback in this bug. May be worth splitting that out to separate issues. The original issue of not having the functions and types be expanded by default has been fixed (just not deployed).

[jayconrod]

Thanks @andybons. I agree that separate issues should be filed for other feedback. I'll open a new issue for grouping functions and types. EDIT: #40927