cmd/go: doc -http should start a pkgsite instance and open a browser

[adonovan]

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 to slim it down and reduce dependencies.

Open questions:

• How should successive go doc processes 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

[gabyhelp]

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.)}

[qiulaidongfeng]

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？

[adonovan]

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.

[rsc]

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

[rsc]

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.

[rsc]

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.

[rsc]

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.

[rsc]

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.

[gopherbot]

Change https://go.dev/cl/628175 mentions this issue: cmd/doc: add debug support for starting pkgsite instance for docs