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.

Sign up for GitHub

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: display table of contents (TOC) in command documentation #38073

Closed
dmitshur opened this issue Mar 25, 2020 · 7 comments
Closed

x/pkgsite: display table of contents (TOC) in command documentation #38073

dmitshur opened this issue Mar 25, 2020 · 7 comments
Labels
FeatureRequest FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input
Milestone
pkgsite/unplanned

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Mar 25, 2020 •
edited

What is the URL of the page with the issue?

https://pkg.go.dev/cmd/go

Screenshot

image

What did you do?

Visited command documentation. As an example, see https://pkg.go.dev/cmd/go, but this applies to any command (package with name "main").

What did you expect to see?

A table of contents, like on https://golang.org/cmd/go:

image

What did you see instead?

No table of contents.

This is a feature request to have feature parity with previous documentation rendering on golang.org and the godoc package documentation viewer.

/cc @julieqiu
@dmitshur dmitshur added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. FeatureRequest pkgsite labels Mar 25, 2020
@dmitshur dmitshur added this to the Unreleased milestone Mar 25, 2020
@julieqiu julieqiu mentioned this issue Mar 25, 2020
Closed
19 tasks
@myitcv
Copy link
Member

myitcv commented Mar 25, 2020

A table of contents, like on https://golang.org/cmd/go:

Did you perhaps intend for the comparison here to be with https://godoc.org/cmd/go?

@dmitshur
Copy link
Contributor Author

dmitshur commented Mar 25, 2020 •
edited

I meant to compare with golang.org (powered by x/tools/godoc). godoc.org (powered by github.com/golang/gddo) doesn't implement this feature.

Some implementation notes.

golang.org renders (via x/tools/godoc package) the table of contents on the frontend via a generateTOC function here:

pkg.go.dev does not need to do this on the frontend, it can render a table of contents on the backend (together with the where all of package documentation rendering currently happens).

This table of contents is applicable only for commands; library packages already have an index (the one that lists all the functions, types, methods, etc.) which serves as a table of contents.

x/tools/godoc uses a div named "manual-nav" to disable the frontend from generating a table of contents for non-commands. See:

@dmitshur dmitshur changed the title go.dev: display table of contents in command documentation go.dev: display table of contents (TOC) in command documentation Mar 25, 2020
@julieqiu julieqiu added the UX Issues that involve UXD/UXR input label Mar 25, 2020
@julieqiu julieqiu changed the title go.dev: display table of contents (TOC) in command documentation x/pkgsite: display table of contents (TOC) in command documentation Jun 15, 2020
@julieqiu julieqiu mentioned this issue Jun 15, 2020
Closed
@gopherbot
Copy link

Change https://golang.org/cl/288552 mentions this issue: internal/experiment: create command-toc experiment

@gopherbot
Copy link

Change https://golang.org/cl/288553 mentions this issue: content,internal/godoc: add table of contents to command pages

@jamalc jamalc self-assigned this Feb 1, 2021
gopherbot pushed a commit to golang/pkgsite that referenced this issue Feb 1, 2021
@jamalc
internal/experiment: create command-toc experiment
ad9abe5 
Creates an experiment to enable the table of contents
for command documention pages.

For golang/go#38073

Change-Id: I192a1b523b6df0c96dc16602a6fc8898c7ad2069
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/288552
Trust: Jamal Carvalho <jamal@golang.org>
Run-TryBot: Jamal Carvalho <jamal@golang.org>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
@jamalc jamalc reopened this Feb 2, 2021
@jamalc
Copy link

jamalc commented Feb 17, 2021

Here is a mockup of the TOC feature.

Screen Shot 2021-02-17 at 11 10 25 AM

@hyangah
Copy link
Contributor

hyangah commented Feb 18, 2021 •
edited

Index and "Jump to" feature for command documentation would be nice too.

@jamalc
Copy link

jamalc commented Feb 18, 2021

@hyangah that's a good idea, would you file that under a new issue? We'll need some discussion and UX review to figure out how it would work.

@jamalc jamalc closed this as completed Feb 18, 2021
@golang golang locked and limited conversation to collaborators Feb 18, 2022
@rsc rsc unassigned jamalc Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FeatureRequest FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite UX Issues that involve UXD/UXR input
Projects
None yet
Milestone
pkgsite/unplanned
Development

No branches or pull requests
6 participants
@dmitshur @myitcv @hyangah @julieqiu @gopherbot @jamalc