Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/pkgsite: auto-expand left sidebar #40577

Open
jayconrod opened this issue Aug 4, 2020 · 9 comments
Open

x/pkgsite: auto-expand left sidebar #40577

jayconrod opened this issue Aug 4, 2020 · 9 comments

Comments

@jayconrod
Copy link
Contributor

@jayconrod jayconrod commented Aug 4, 2020

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

Screen Shot 2020-08-04 at 5 47 03 PM

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.

@gopherbot gopherbot added this to the Unreleased milestone Aug 4, 2020
@mrg0lden
Copy link

@mrg0lden mrg0lden commented Aug 5, 2020

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
Copy link

@salewski salewski commented Aug 6, 2020

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
Copy link
Contributor Author

@jayconrod jayconrod commented Aug 10, 2020

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.


Screen Shot 2020-08-10 at 11 30 08 AM

@rakyll
Copy link
Member

@rakyll rakyll commented Aug 11, 2020

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
Copy link
Contributor

@zombiezen zombiezen commented Aug 11, 2020

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
Copy link
Contributor Author

@jayconrod jayconrod commented Aug 19, 2020

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

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Aug 19, 2020

/cc @spf13 @fflewddur for product / UXR input

@andybons
Copy link
Member

@andybons andybons commented Aug 20, 2020

  • 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
Copy link
Contributor Author

@jayconrod jayconrod commented Aug 20, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
9 participants
You can’t perform that action at this time.