proposal: x/tools/cmd/godoc: un-deprecate (or make pkgsite more compatible) #50229
Comments
This comment has been minimized.
This comment has been minimized.
Opened #50575 for this. |
|
Change https://golang.org/cl/378094 mentions this issue: |
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>
|
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). |
|
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. |
|
Change https://go.dev/cl/474295 mentions this issue: |
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>
|
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. |
|
This proposal has been declined as retracted. |
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
godocand it will open a socket and start listening on port 6060.x/tools/cmd/godoc is currently deprecated. The deprecation notice reads:
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 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:
Or:
The text was updated successfully, but these errors were encountered: