gold

README

Gold is an experimental Go local docs server and Go docs generation tool.

(Demo and FAQ)

Installation

Run go get -u go101.org/gold to install (and update) Gold.

If the tool name gold conflicts with another tool with the same name you are using, you can run go get -u go101.org/gold/godoge instead to install Gold as as godoge.

Features

• Show type implemention relations.
• Show promoted selectors, even on unexported embedded fields.
• Rich code view experience (good for studying Go projects without opening IDEs).
• JavaScript-off friendly.
• Support generating static HTML docs pages (good for package developers to host docs of their packages).

This tool is still in its early phase. More features will be supported from time to time.

Limitations

Go Toolchain 1.13+ is needed to build and run Gold.

This project uses the golang.org/x/tools/go/packages package to parse code. The golang.org/x/tools/go/package is great, but it also has a shortcoming: there are no ways to get module/package downloading/preparing progress.

All packages must compile okay to get their docs shown.

Testing packages are excluded currently.

Code examples in docs are not shown currently.

Usage

Start the docs server:

• Run gold . or gold to show docs of the package in the current directory (and all its dependency packages).
• Run gold ./... to show docs of all packages under the current directory (and all their dependency packages).
• Run gold std to show docs of standard packages.

Each of the above commands will open a browser window automatically. We can use the -s or -silent flags to turn off the behavior.

Generate static HTML docs pages (the -dir flag is optional in this mode, its default value is .):

• gold -gen -dir=generated
• gold -gen -dir=generated ./...
• gold -gen -dir=generated std

We can run gold -dir=. from the HTML docs generation directory to view the generated docs.

Analyzation Cases

The following results are got on a machine with an AMD-2200G CPU (4 cores 4 threads) and sufficient memory. Go Toolchain 1.14.3 is used in the analyzations.

Before running the gold ./... command, the go build ./... command is run to ensure that all involved modules/packages are fetched to local machine and verify cgo tools (if needed) have been installed.

Project	Package Count	Analyzation Time	Final Used Memory	Notes
go-sdl2 v0.4.4	47	1.3s	200M	(need run go mod init github.com/veandco/go-sdl2 before running Gold)
bolt v1.3.1	51	1.6s	140M
tview rev:823f280	102	2s	200M	(run gold . instead of gold ./...)
gorilla/websocket v1.4.2	118	1.8s	337M
gio rev:3314696	119	3.1s	1G
nats-server v2.1.7	136	2.3s	400M	(need run go mod vendor before running Gold)
badger v2.0.3	145	2.2s	350M
Gold v0.0.1	151	2.5s	400M	(run gold . instead of gold ./...)
pion/webrtc v2.2.9	189	2.1s	400M
goleveldb v1.0.0	193	2.7s	600M
standard packages v1.15	199	2.6s	400M
ebiten v1.11.1	214	2.1s	472M
tailscale v0.98.0	275	2.5s	539M
etcd v3.4.7	391	3.5s	700M	(need run go mod vendor before running Gold)
go-ethereum v1.9.14	459	5.5s	1.3G
minio RELEASE.2020-05-16T01-33-21Z	639	5.1s	1.2G
terraform v0.12.25	777	5.7s	1.5G
consul v1.7.3	803	7.2s	1.9G
vitess v6.0.20-20200525	905	7.1s	1.7G
istio 1.6.0	1860	10.7s	2.8G
kubernetes v1.18.2	2821	16.3s	4G

There are still some famous projects failing to build (with the go build ./... command, at May 27th, 2020), such as docker, gvisor and traefik, so Gold is unable to build docs for them.

There are also some projects not using go modules, such as hashicorp/nomad and openshift/origin, and GOPROXY doesn't take effect for the go mod init command (as of Go Toolchain 1.14), so I couldn't build docs for these projects on my machine (this is my network problem, it might work on your machine).