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

Jump to bottom

x/pkgsite: redesign - the pkg.go.dev/<path> page #41586

Closed
julieqiu opened this issue Sep 23, 2020 · 4 comments
Closed

x/pkgsite: redesign - the pkg.go.dev/<path> page #41586

julieqiu opened this issue Sep 23, 2020 · 4 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite
Milestone
pkgsite/design-2020

Comments

@julieqiu
Copy link
Member

julieqiu commented Sep 23, 2020 •
edited

We'll be redesigning pkg.go.dev based on feedback received over the last year. This is the first in a series of issues about plans for the pkgsite/design-2020 milestone. Comment below with any feedback or suggestions related to this issue!

Overview

We will redesign the pkg.go.dev/<path> page such that information is organized around a path. A path represents a directory in a particular version of a module. A path may be a package, the root of a module, and/or contain subdirectories.

Currently, the landing page for a given path differs for each of these cases, even when a path fits into more than one case. For example, golang.org/x/tools (a module) has two landing pages - pkg.go.dev/mod/golang.org/x/tools shows the overview tab and pkg.go.dev/golang.org/x/tools shows the subdirectories tab. golang.org/x/tools/go (a subdirectory) shows the subdirectories tab and golang.org/x/tools/go/packages (a package) shows the doc tab.

These different pages will become a single page in the new design.

Design

The changes to the pkg.go.dev/<path> page described below are motivated by wanting to make the page consistently useful and predictable. Here's a preview of what that page will look like:

gif showing overview of pkg.go.dev/<path> page

Note: The images shown in this issue are mocks, so the data may not accurately represent the exact contents of a given package.

1. Single URL for all paths

Each pkg.go.dev/<path> page will display information for that path, regardless of its type.

The existing “/mod” namespace will be deprecated. Requests to pkg.go.dev/mod/<path>[@version] will be redirected to pkg.go.dev/<path>.

The default page will not have a tab query param.

2. Consistent landing page

To create a consistent landing page, content on the doc, overview and subdirectories tabs will be consolidated into a single page. A pkg.go.dev/<path> page will always display at least one of the following:

  • README
  • Documentation
  • Source Files
  • Directories

If a path does not have content for one of these sections, that section will be omitted from the page.

3. README section

image

Currently, the overview tab only shows the README if present at the module root. By organizing information around a path, we plan to display the README section, only if a README is present at that path.

For example, pkg.go.dev/go-hep.org/x/hep@v0.27.0 will display github.com/go-hep/hep/blob/v0.27.0/README.md, and pkg.go.dev/go-hep.org/x/hep/hplot@v0.27.0 will display https://github.com/go-hep/hep/blob/v0.27.0/hplot/README.md in the README section.

On the other hand, pkg.go.dev/net/http will not display a README section, because one does not exist at that path. The first section displayed on that page will be the documentation section.

4. Documentation section

image

The documentation section will be described in more detail in #41587.

5. Source Files and Directories sections

image

The UI for source files and directories will be similar to the existing layout. The Directories section will display both subdirectories and nested modules relative to the current path.

We are also exploring using a tree structure in the directories section, since some pages have lots of subdirectories (example: subdirectories tab for cloud.google.com/go). This will be discussed in a later issue.

Related Issues
@gopherbot gopherbot added this to the Unreleased milestone Sep 23, 2020
@julieqiu julieqiu mentioned this issue Sep 23, 2020
Closed
@julieqiu julieqiu changed the title x/pkgsite: <this issue is a placeholder for a future issue> x/pkgsite: redesign - the pkg.go.dev/<path> page Sep 23, 2020
@julieqiu julieqiu reopened this Sep 23, 2020
@julieqiu julieqiu added the NeedsFix The path to resolution is known, but the work has not been done. label Sep 23, 2020
@mvdan
Copy link
Member

mvdan commented Sep 24, 2020

If a path is also the root of a module, could you clarify how the UI would look for that case? What if it's both the root of a module and the package - which information would show up by default?

Also, I assume you're using the term "directory" to mean either "package" or "module". I think that might be confusing to users, because some/module/v2 might not actually be a directory anywhere, since the /v2 would just be a product of semantic import versioning. There, the directory would just be some/module. So I still think that talking about "paths" is the simplest and most well understood; the distinction then is whether paths are for packages, or for modules. And you still have the concept of sub-paths.

@julieqiu
Copy link
Member Author

julieqiu commented Sep 24, 2020 •
edited

If a path is also the root of a module, could you clarify how the UI would look for that case? What if it's both the root of a module and the package - which information would show up by default?

Regardless of whether the path is a package or a module, we'll be displaying the contents as described under 2. Consistent landing page. Label(s) will be displayed next to the title in the header to indicate what the path type is.

To give a few examples:

  • pkg.go.dev/mvdan.cc/sh/v3 (a module), will show the README and Directories sections, with a module label in the header.

  • pkg.go.dev/github.com/russross/blackfriday/v2 (a package and a module) will show the README, Documentation, and Source files sections, with a module and a package label in the header. It doesn't have any subdirectories, otherwise the Directories section would be shown as well.

  • pkg.go.dev/golang.org/x/tools/cmd/godoc (a command) will show the Documentation and Source files sections, with a command label in the header. It doesn't have a README or subdirectories, otherwise those sections would be shown as well.

So I still think that talking about "paths" is the simplest and most well understood; the distinction then is whether paths are for packages, or for modules. And you still have the concept of sub-paths.

Thanks for the suggestion! Edited the issue above to use "path" instead of "directory" where applicable.

@julieqiu julieqiu mentioned this issue Oct 9, 2020
Closed
@julieqiu
Copy link
Member Author

A preview of the redesign is now available on beta.pkg.go.dev! Give it a try, and please file an issue for any bugs.

See #41585 (comment) also for instructions on how to run the beta site locally.

This was referenced Oct 29, 2020
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Closed
@julieqiu
Copy link
Member Author

This is now live on pkg.go.dev!

See #41585 (comment) for details.

@julieqiu julieqiu mentioned this issue Nov 17, 2020
Closed
@julieqiu julieqiu mentioned this issue Dec 23, 2020
Open
@golang golang locked and limited conversation to collaborators Nov 10, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. pkgsite
Projects
None yet
Milestone
pkgsite/design-2020
Development

No branches or pull requests
3 participants
@mvdan @julieqiu @gopherbot