go
go copied to clipboard
golang
proposal: cmd/go: doc -http should start a pkgsite instance and open a browser
The go doc command displays documentation to stdout, which is handy for quick forays for a single package or symbol, but for extended reading a browser is more convenient, as it has better typography and linked cross-references. We propose that go doc -http should start a pkgsite instance in the background (if one is not running already) and open a web browser to the correct URL for the package or symbol.
The pkgsite program is currently rather large and slow to start as it was designed as a long-lived server for a large corpus on Google Cloud. Issue #61399 tracks the work so slim it down and reduce dependencies.
Open questions:
- How should successive
go docprocesses communicate the port or pid of the running instance, and deal with server crashes? - The server would necessarily outlive the go command. Is an explicit "stop" operation necessary?
- Should the -http flag be a boolean, or an integer port? I think boolean (picking any unused port) would be more friendly.
@rsc @matloob
Similar Issues
- proposal: x/tools/cmd/godoc: un-deprecate (or make pkgsite more compatible) #50229
- x/pkgsite: improve pkgsite command #47780
- Feature request for godoc -http #509
- x/pkgsite: run locally to view documentation of a pending CL #40159
(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)
I would like know to run go doc -http, which starts a pkgsite process and opens a browser, then waits for the syscall.SIGINT signal, and when it receives the signal, first close the pkgsite process and then exit itself ,how？
We could certainly make go doc -http block until interrupted before terminating the server. And perhaps that's the least surprising interface, as many Go commands that take an -http flag block indefinitely.
This proposal has been added to the active column of the proposals project and will now be reviewed at the weekly proposal review meetings. — rsc for the proposal review group
go doc -http should open the browser (we have other go tools that do that). and it should print the URL and block until you get a ^C.
it would be slick if the browser integration could track reliably whether the last page was closed and have go doc -http exit at that point.
Have all remaining concerns about this proposal been addressed?
The proposal is to add go doc -http, which will start a server and attempt to open a browser window on the docs for a given package. If a browser successfully navigates there and then all the open browser windows close, go doc -http will exit. Otherwise it can be ^C-ed early, of course.
Based on the discussion above, this proposal seems like a likely accept. — rsc for the proposal review group
The proposal is to add go doc -http, which will start a server and attempt to open a browser window on the docs for a given package. If a browser successfully navigates there and then all the open browser windows close, go doc -http will exit. Otherwise it can be ^C-ed early, of course.
No change in consensus, so accepted. 🎉 This issue now tracks the work of implementing the proposal. — rsc for the proposal review group
The proposal is to add go doc -http, which will start a server and attempt to open a browser window on the docs for a given package. If a browser successfully navigates there and then all the open browser windows close, go doc -http will exit. Otherwise it can be ^C-ed early, of course.
Change https://go.dev/cl/628175 mentions this issue: cmd/doc: add debug support for starting pkgsite instance for docs
Change https://go.dev/cl/674437 mentions this issue: cmd/internal/doc: add doc command in its own module
Change https://go.dev/cl/674436 mentions this issue: cmd/internal/pkgsite: add godoc mode
Change https://go.dev/cl/674555 mentions this issue: cmd/doc: show page for the requested object
Change https://go.dev/cl/674556 mentions this issue: cmd/doc: use go list to determine import path if it's missing
Change https://go.dev/cl/674158 mentions this issue: cmd/doc: use golang.org/x/pkgsite/cmd/internal/doc to start server
Change https://go.dev/cl/674575 mentions this issue: cmd/internal/doc: set go.mod go version to 1.24.3
Change https://go.dev/cl/675075 mentions this issue: cmd/doc: allow go doc -http without package in current directory
Change https://go.dev/cl/675076 mentions this issue: cmd/go/internal/doc: ignore SIGINT and SIGQUIT
Change https://go.dev/cl/675235 mentions this issue: cmd/doc: add more convenient behavior for go doc -http with no args
Change https://go.dev/cl/675155 mentions this issue: cmd/go: better support for no network
Change https://go.dev/cl/678777 mentions this issue: _content/doc/go1.25: add release notes for go command features.