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