ローカルで pkg.go.dev 形式のドキュメントを閲覧する

Go を書くとき公開されている API や、そのコメントに不足や余分がないかチェックするために GoDoc を使っていた。特にプライベートパッケージはインターネットからドキュメントを参照できないため、GoDoc をローカルで起動し、チェックしていた。

syfm.hatenablog.com

ただ、Go modules が登場し、GoDoc から pkg.go.dev へ移行したため、pkg.go.dev と GoDoc のどちらも使っているような状況になっていた。 また、GoDoc には Go modules 関連機能がなかったり、pkg.go.dev にはどんどん新機能が入るのに対し GoDoc には実装されなかったりと違いが大きくなってきた。

そこで godoc コマンドのようにローカルで pkg.go.dev 形式のドキュメントを見ることができないかを調べた結果、golang.org/x/pkgsite に含まれているコマンドで実現できるようだった。

pkg.go.dev

golang.org/x/pkgsite が OSS となったのは 2020 年 6 月頃で、2021 年 2 月頃に pkgsite コマンドが追加されており、簡単にローカルでドキュメントを見ることができるようになっていた。

インストールは go install でできるが、Go のバージョンによっては特定の commit をチェックアウトしてインストールする必要がある。

$ cd pkgsite

# Go 1.18
$ git checkout 9ffe8b928e4fbd3ff7dcf984254629a47f8b6e63

# Go 1.17
$ git checkout 4d836c6a652cde92f433967680dfd6171a91ec12

$ go install ./cmd/pkgsite

使い方は非常にシンプルで、ドキュメントを表示したいモジュールのディレクトリへ移動し、以下のコマンドを実行するだけで良い。 デフォルトで localhost:8080 で起動するが、このあたりの挙動はコマンドライン引数で変更できる。 なお、pkg.go.dev と違い、検索といった一部の機能は利用できない。

$ pkgsite

これで GoDoc と同じように pkg.go.dev 形式でドキュメントを閲覧できるようになり、便利になった 👏