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: redesign - the pkg.go.dev/<path> page #41586

Open
julieqiu opened this issue Sep 23, 2020 · 2 comments
Open

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

julieqiu opened this issue Sep 23, 2020 · 2 comments

Comments

@julieqiu
Copy link
Contributor

@julieqiu julieqiu commented Sep 23, 2020

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

  • #36791: modules with no package at the root directory are shown awkwardly
  • #37351: ?tab=doc is added automatically
  • #37912: add import / imported by count
  • #38087: rethink module page
  • #38513: show README of subpackage in overview tab
  • #39218: add repository link on documentation page
  • #40942: support versions tab for directory view
  • #38596: subdirectories are missing for nested modules
@julieqiu julieqiu closed this Sep 23, 2020
@gopherbot gopherbot added the pkgsite label Sep 23, 2020
@gopherbot gopherbot added this to the Unreleased milestone Sep 23, 2020
@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 label Sep 23, 2020
@mvdan
Copy link
Member

@mvdan 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
Contributor Author

@julieqiu julieqiu 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?

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.

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
3 participants
You can’t perform that action at this time.