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

Open
dmitshur opened this issue Mar 25, 2020 · 2 comments
Open

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

dmitshur opened this issue Mar 25, 2020 · 2 comments

Comments

@dmitshur
Copy link
Member

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