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/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
Closed

x/tools/cmd/godoc: reduce scope to display documentation only, remove the rest of golang.org website #32011

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
Unreleased

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
@dmitshur dmitshur mentioned this issue May 13, 2019
Open
@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 •
edited
Loading

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
Contributor

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

@gopherbot
Copy link
Contributor

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
@dmitshur
cmd/godoc: delete unused autocert hooks
f51c1a7 
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>
@dmitshur dmitshur mentioned this issue Dec 10, 2019
Closed
4 tasks
@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 •
edited
Loading

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

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
Contributor

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
@rsc
godoc: delete GoogleCN logic
8e4f4c8 
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
@dmitshur
godoc/static: link to golang.org for content moved out of Go root
682c7e6 
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>
@TomFreudenberg TomFreudenberg mentioned this issue May 1, 2021
Closed
@gopherbot
Copy link
Contributor

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
@TomFreudenberg @dmitshur
godoc/static: add gopher/pkg.png image
f05e912 
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
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
@dmitshur
cmd/godoc, godoc/static: remove remnants of golang.org website
7278eb5 
The canonical home for the golang.org website by now is
the golang.org/x/website/cmd/golangorg command. That is
the command that should be used to run the website locally
instead of godoc.

This change reduces the scope of x/tools/cmd/godoc to be
a minimal Go Documentation Server. It removes the remaining
pieces of the golang.org website and changes the title from
"The Go Programming Language" to "Go Documentation Server".

The web tree is modified as follows:

• The index page has been modified to redirect to /pkg/,
  which serves a list of packages.
• The /doc/ tree is removed.
• The /robots.txt and /opensearch.xml pages are removed, since
  the primary use case for godoc now is a local web server.
• The Google Analytics sections are removed from static templates,
  since it's always an empty value in local web server mode.

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

Change-Id: Id62c5f335fa2059774893ef4dcd268649278e99d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/207777
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Andrew Bonventre <andybons@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
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
Milestone
Unreleased
Development

No branches or pull requests
3 participants
@dmitshur @Li-ReDBox @gopherbot