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

Jump to bottom

proposal: x/tools/cmd/godoc: un-deprecate (or make pkgsite more compatible) #50229

Closed
kevinburke opened this issue Dec 16, 2021 · 8 comments
Closed

proposal: x/tools/cmd/godoc: un-deprecate (or make pkgsite more compatible) #50229

kevinburke opened this issue Dec 16, 2021 · 8 comments
Assignees
@jamalc
Labels
FrozenDueToAge pkgsite Proposal
Projects
Proposals (old)
Milestone
Proposal

Comments

@kevinburke
Copy link
Contributor

kevinburke commented Dec 16, 2021 •
edited

I have used a local godoc browser for years now to view documentation for private and internal packages. I use it when I am on the train or a plane and have a very bad and expensive Internet connection. I also use it to preview package changes, and changes to standard library documentation. I lay out packages on disk using $GOPATH, godoc is able to read them off of disk from their $GOPATH location, and display them in my browser. Conceptually it is a very simple model because the contents on disk are the contents that appear in the browser.

godoc is very easy to run, there are no external dependencies besides the file system, you can just run godoc and it will open a socket and start listening on port 6060.

x/tools/cmd/godoc is currently deprecated. The deprecation notice reads:

Deprecated: godoc cannot select what version of a package is displayed.
Instead, use golang.org/x/pkgsite/cmd/pkgsite.

The new tool (pkgsite) is a lot more difficult to run - as I understand it, to load packages from disk you need to specify them when you start the server. It is not obvious where packages are being loaded from when you load them in your browser. I am not sure how to preview changes to documentation in the standard library because when I load the standard library, the packages are fetched over the network (even when I specify the `--gorepo flag). It is not obvious how to disable network fetch.

pkgsite --gorepo=~/go --gopath_mode $(cd $GOPATH/src && find * -type d -maxdepth 3 | grep -v '\.git')

pkgsite also has a corporate sponsor's logo displayed in the footer (Google) even when run locally. I am grateful for Google's support for the Go language but I don't think it's appropriate for everyone who wants to run the primary, supported documentation server to have to display a Google logo in their browser. I don't think it is healthy for the ecosystem for the language to be so closely associated with Google.

I guess I would be OK with two of these:

  1. Un-deprecate godoc to continue to support the use case of loading packages from disk and displaying the documentation as HTML in a browser.

Or:

  1. Build support into pkgsite to be able to load packages from a root directory on demand (instead of needing to specify all of them individually at start time).
  2. Provide a pkgsite mode that disables the network.
  3. Remove the Google logo from the pkgsite binary, or make the footer logo configurable via a command line flag.
@gopherbot gopherbot added this to the Proposal milestone Dec 16, 2021
@jba jba self-assigned this Dec 16, 2021
@go101

This comment has been minimized.

Sign in to view
@ianlancetaylor ianlancetaylor added this to Incoming in Proposals (old) Jan 5, 2022
@jba
Copy link
Contributor

jba commented Jan 12, 2022

when I load the standard library, the packages are fetched over the network (even when I specify the `--gorepo flag).

Opened #50575 for this.

@gopherbot
Copy link

Change https://golang.org/cl/378094 mentions this issue: internal/stdlib: refactor go repo logic

gopherbot pushed a commit to golang/pkgsite that referenced this issue Jan 13, 2022
@jba
internal/stdlib: refactor go repo logic
de2b308 
Add a goRepo interface, implemented for remote, local and test repos.
Functions of stdlib use a global instance that interface instead of if
statements.

Also, improve and rewrite some tests.

For golang/go#50229

Change-Id: I73641813e6c7a6bb9667f44a672e37dce964b17a
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/378094
Trust: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
@plo- plo- mentioned this issue Apr 14, 2022
Open
8 tasks
@aarzilli
Copy link
Contributor

aarzilli commented Jun 4, 2022 •
edited

FWIW I want to second the suggestion of un-deprecating godoc. The stated reason for the deprecation is that it "cannot select what version of a package is displayed" but that isn't a feature that is often useful for a tool like godoc. It also seems that the deprecation was initially added under false premises (https://go-review.googlesource.com/c/tools/+/349051/ i.e. that it didn't understand modules, which it does).

The gddo/godoc split always existed, the goal of "serving documentation for locally available packages on localhost" and of "serving any possible package on any version to anyone on the internet" are very different. I'm skeptical that pkgsite can do both well. The fact that homegrown reimplementations of godoc are springing up is proof that it currently doesn't. Plus it doesn't seem to have historically required a lot of maintenance (modulo the introduction of modules).

@aarzilli
Copy link
Contributor

aarzilli commented Jun 4, 2022

I'll add that the library that does the heavy lifting for tools/cmd/godoc, tools/godoc, is not deprecated because it doesn't have a publically available replacement. The deprecation of godoc does very little in practical terms.

@jba jba assigned jamalc and unassigned jba Jul 8, 2022
Closed
This was referenced Feb 16, 2023
Open
Open
@gopherbot
Copy link

Change https://go.dev/cl/474295 mentions this issue: cmd/pkgsite: add multi-module support, invalidation, and search

gopherbot pushed a commit to golang/pkgsite that referenced this issue Mar 14, 2023
@findleyr
cmd/pkgsite: add multi-module support, invalidation, and search
b5fdc90 
This change adds a new goPackagesModuleGetter, which uses
x/tools/go/packages to query package information for modules requested
by the pkgsite command.

Additionally, add new extension interfaces that allow getters to add
support for search and content invalidation. The go/packages getter uses
these extensions to implement search (via a simple fuzzy-matching
algorithm copied from x/tools), and invalidation via statting package
files.

Along the way, refactor slightly for testing ergonomics.

Updates golang/go#40371
Updates golang/go#50229
Fixes golang/go#54479

Change-Id: Iea91a4d6327707733cbbc4f74a9d93052f33e295
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/474295
TryBot-Result: kokoro <noreply+kokoro@google.com>
Run-TryBot: Robert Findley <rfindley@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
@adonovan adonovan mentioned this issue Mar 15, 2023
Open
@adonovan
Copy link
Member

Please try out the latest version of pkgsite, which now addresses the two primary concerns (no index, and no hot reloading).

The network access issue seems orthogonal: 'go list' and 'go build' potentially access the network, so why shouldn't the documentation viewer?

I'm going to close this for now, but feel free to re-open (or file more specific issues) as needed. Thanks.

@rsc
Copy link
Contributor

rsc commented Mar 29, 2023

This proposal has been declined as retracted.
— rsc for the proposal review group

@golang golang locked and limited conversation to collaborators Mar 28, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@jamalc jamalc

Labels
FrozenDueToAge pkgsite Proposal
Projects
No open projects
Proposals (old)
Incoming
Milestone
Proposal
Development

No branches or pull requests
9 participants
@rsc @kevinburke @aarzilli @adonovan @julieqiu @gopherbot @jamalc @jba @go101