blog

SEAN K.H. LIAO

docs

One nice thing about Go code is that docs are consistent, for all public code, go to pkg.go.dev, type in the import path (or append directly to the url), and have docs. No wondering how to navigate the funky webpage, or even trying to find one, if it's public, it's there.

old way

But what about your private code? Previously, you'd run godoc in your GOPATH, and it'd serve everything in there, plus the standard library. But it's GOPATH and has no concept of versioning.

There's also gddo, for the extra scale needed to run godoc.org.

pkgsite

The new way is to run a private version of pkg.go.dev, the project is called pkgsite.

run

You need a database to do this, specifically postgres. Also migrations, and maybe redis, and a worker? why is this so hard. How do you even get data into the database?

TODO: figure out how to do this, docker-compose up is not enough

direct

If you have an internal proxy serving all your code, pkgsite can serve directly from that, bypassing the need for a database.

warning: pretty much the only thing that works is viewing the docs for packages that you know the exact url for. Search, navigating to subdirectories in modules, source code links all don't work.

git clone https://go.googlesource.com/pkgsite
cd pkgsite
go build golang.org/x/pkgsite/cmd/frontend
./frontend -bypass_license_check -direct_proxy
local directory

There's also the experimental command to more or less do what godoc did: serve local directories without versions:

git clone https://go.googlesource.com/pkgsite
cd pkgsite
go build golang.org/x/pkgsite/cmd/pksite
./pkgsite /path/to/module1,path/to/module2/,...