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: 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

Comments

@dmitshur
Copy link
Contributor

@dmitshur dmitshur commented Mar 25, 2020

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

@myitcv
Copy link
Member

@myitcv 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 dmitshur commented Mar 25, 2020

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 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 removed this from the Unreleased milestone Jul 31, 2020
@julieqiu julieqiu added this to the pkgsite/design-2020 milestone Jul 31, 2020
@julieqiu julieqiu removed this from the pkgsite/design-2020 milestone Nov 19, 2020
@julieqiu julieqiu added this to the pkgsite/unplanned milestone Nov 19, 2020
@gopherbot
Copy link

@gopherbot gopherbot commented Feb 1, 2021

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

@gopherbot
Copy link

@gopherbot gopherbot commented Feb 1, 2021

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
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>
@gopherbot gopherbot closed this in a9a10d0 Feb 1, 2021
@jamalc jamalc reopened this Feb 2, 2021
@jamalc
Copy link

@jamalc 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 hyangah commented Feb 18, 2021

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

@jamalc
Copy link

@jamalc 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 Feb 18, 2021
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
6 participants