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/tools/cmd/godoc: reduce scope to display documentation only, remove the rest of golang.org website #32011

Closed
dmitshur opened this issue May 13, 2019 · 10 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@dmitshur
Copy link
Contributor

The 4th milestone described in #29206 (comment) was:

Reduce x/tools/cmd/godoc to be the minimal version (since the website can now be run out of x/website).

Now that the golang.org website is served by the x/website subrepo, progress can be made on this.

This is the issue tracking that task.

@dmitshur dmitshur added the NeedsFix The path to resolution is known, but the work has not been done. label May 13, 2019
@dmitshur dmitshur added this to the Unreleased milestone May 13, 2019
@dmitshur dmitshur self-assigned this May 13, 2019
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
@dmitshur
Copy link
Contributor Author

dmitshur commented Nov 13, 2019

This is the current godoc web server tree:

http://localhost:6060/		main landing page
http://localhost:6060/doc/	serve from $GOROOT/doc - spec, mem, etc.
http://localhost:6060/src/	serve files from $GOROOT/src; .go gets pretty-printed
http://localhost:6060/cmd/	serve documentation about commands
http://localhost:6060/pkg/	serve documentation about packages
			(idea is if you say import "compress/zlib", you go to
			http://localhost:6060/pkg/compress/zlib)

I am considering resolving this issue by implementing the following new tree:

http://localhost:6060/		redirect to /pkg/
http://localhost:6060/doc/	display a page moved notice
    (the rest is unchanged)

The http://localhost:6060/doc/ notice would say something like:

Please find documentation for the Go programming language at https://golang.org/doc/, or use the golangorg command to serve the golang.org website locally.

The golang.org website has moved into the golang.org/x/website repository. The scope of the godoc command is being narrowed to just serving Go package documentation.

After some time, the /doc/ handler can be removed altogether.

/cc @andybons Do you think it's worth also including a link to https://golang.google.cn/doc/ in the "page moved notice" for people who cannot access the golang.org website?

@dmitshur
Copy link
Contributor Author

As I was prototyping a fix for this, it became more clear it should be viable to move more quickly and simply remove the /doc/ tree altogether, without any kind of intermediate message. The reason this should be viable is because we can remove all links to /doc/ from the navigation bar:

image

Since there won't be any links to /doc/, people can't get there. I don't think many people make bookmarks for things at http://localhost:6060.

The new web server tree plan is:

http://localhost:6060/		redirect to /pkg/
http://localhost:6060/src/	serve files from $GOROOT/src; .go gets pretty-printed
http://localhost:6060/cmd/	serve documentation about commands
http://localhost:6060/pkg/	serve documentation about packages
			(idea is if you say import "compress/zlib", you go to
			http://localhost:6060/pkg/compress/zlib)

@gopherbot
Copy link

Change https://golang.org/cl/207777 mentions this issue: cmd/godoc, godoc/static: remove remnants of golang.org website

@gopherbot
Copy link

Change https://golang.org/cl/208259 mentions this issue: cmd/godoc: delete unused autocert hooks

gopherbot pushed a commit to golang/tools that referenced this issue Nov 21, 2019
The autocert.go file in x/tools was deleted in CL 162400, but some
related variables were left behind. This change deletes them, since
they are unused by now. (If you're feeling déjà vu, it's likely
because this was done in x/website in CL 197957.)

Updates golang/go#29206
Updates golang/go#32011

Change-Id: I070f711e8bbc7b54f1d169571356fdc24bc00137
Reviewed-on: https://go-review.googlesource.com/c/tools/+/208259
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@Li-ReDBox
Copy link

Hi @dmitshur current godoc has lost navigation bar which has caused inconveniences. For example, after viewing the document of one package, I have to change the url to http://localhost:6060/pkg/ in the address bar to go back to the index.

Also, even help, project and etc are reachable, they are not visible.

Are these in transition into x/website?

@dmitshur
Copy link
Contributor Author

dmitshur commented Mar 11, 2020

@Li-ReDBox Thanks for reporting.

You should still have the option of going to the index by clicking the "Go Documentation Server" text in the top left corner, as before. Additionally, navigating to just http://localhost:6060/ is fine and will redirect you to http://localhost:6060/pkg/ automatically.

Also, even help, project and etc are reachable, they are not visible.

I don't completely understand, maybe you can elaborate and show a screenshot? This is what you should see:

image

If that's not what you're seeing, maybe your godoc binary is out of date and needs to be rebuilt?

Are these in transition into x/website?

x/website is concerned only with the code necessary to serve the golang.org website and some of its subdomains in production. godoc still lives in x/tools at its original location.

@Li-ReDBox
Copy link

Thanks @dmitshur for taking time to reply to me.

Thanks for the tip for going back to package index page. Should have guessed.

I was expecting to see a navigation bar saw in previous versions
image to give me a convenient way to go to doc page at least. As for doc page, it still exists but if someone runs godoc first time, it is not clear there are lots of useful information accessible locally:
image

I am very glad to know godoc will not be removed. It is a very useful tool. Thanks.

@gopherbot
Copy link

Change https://golang.org/cl/300394 mentions this issue: godoc/static: link to golang.org for content moved out of Go root

@gopherbot
Copy link

Change https://golang.org/cl/296373 mentions this issue: godoc: delete GoogleCN logic

gopherbot pushed a commit to golang/tools that referenced this issue Mar 12, 2021
The GoogleCN code is specific to the code for golang.org,
which no longer uses golang.org/x/tools/godoc.

For golang/go#32011.

Change-Id: If13e3ed93d57f9d8a6c0f8a09b8343567dd6c0b1
Reviewed-on: https://go-review.googlesource.com/c/tools/+/296373
Trust: Russ Cox <rsc@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/tools that referenced this issue Mar 30, 2021
More of the golang.org website content has moved from the Go tree to
the x/website repository in CL 291711, resulting in broken links or
otherwise missing resources in godoc. None of it is affecting godoc's
core functionality, but it's good to fix broken links, so link to the
resources served by golang.org for now.

If it becomes important to make these resources available while godoc
is running offline, that can be done later. (It will be easier once
we can start relying on //go:embed for all supported Go versions.)

Include a local copy of a favicon.ico since the one in Go root is no
longer there as of CL 300549.

For golang/go#32011.

Change-Id: If5bd8e61b72dd9ca1db469d9121e43742846c115
Reviewed-on: https://go-review.googlesource.com/c/tools/+/300394
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
gopls-CI: kokoro <noreply+kokoro@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
Trust: Dmitri Shuralyov <dmitshur@golang.org>
@gopherbot
Copy link

Change https://golang.org/cl/313097 mentions this issue: godoc/static: add gopher/pkg.png image

gopherbot pushed a commit to golang/tools that referenced this issue May 7, 2021
Replace the link to the gopher pkg.png from an online location
to a local file.

This will prevent any privacy issue on godoc so that there is no ping anymore to golang.org
when opening private documentation generated by godoc.

Another benefit is that it allows the image to load when godoc is used offline.

Last the img is placed to the upper section.

For golang/go#32011.

Change-Id: I1459bf2613251e3e12404087ea9083b64a4f70c2
GitHub-Last-Rev: c32ef95
GitHub-Pull-Request: #315
Reviewed-on: https://go-review.googlesource.com/c/tools/+/313097
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
gopls-CI: kokoro <noreply+kokoro@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Cherry Mui <cherryyz@google.com>
@golang golang locked and limited conversation to collaborators May 7, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

3 participants