Skip to content
develop
Go to file
Code

README.md

Gold is a Go local docs server, a Go docs generator, and a Go code reader. It tries to extract as much information as possible from Go code to help gophers understand, study and use Go packages.

Installation

Run go get -u go101.org/gold to install (and update) Gold. (The GO111MODULE enviroment variable might need to be set as on temporarily to utilize the GOPROXY setting, depending on your Go Toolchain version and the directory in which the installation command runs.)

Note, if the tool program name gold conflicts with another tool with the same name you are using, you can run any of the following commands to install Gold as a program with a different name:

  • Go docs generator
    go get -u go101.org/gold/godoge
  • Go code reader
    go get -u go101.org/gold/gocore
  • Go local docs server
    go get -u go101.org/gold/golds

If for any reason the go get way doesn't work, you may also clone this project firstly, then run the go install command in the respective program folders to install Gold as gold, godoge, gocore, or golds.

Features

  • Supports listing exported types not only by alphabet, but also by popularity, which is good to understanding some packages exporting many types.
  • Supports listing unexported types, which is good to read some packages.
  • Rich package-level type/value information collection:
    • Shows type implemention relations (demo 1 and demo 2).
    • Shows method implementation relations (demo).
    • Shows promoted selectors, even on unexported embedded fields (demo).
    • Shows as-parameters-of and as-results-of function/method list (including interface methods).
    • Shows the package-level value lists of a package-level type.
    • Shows uses of package-level declared types/constants/variables/functions (by clicking the type/const/var/func keywords).
  • Smooth code view experiences (good for studying Go projects without opening IDEs):
    • Click a local identifier to highlight all the occurences of the identifier.
    • Click a use of a non-local identifier to jump to the declaration of the non-local identifier.
    • Click the name of a field or a method in its declaration to show its uses (only for package-level named struct types now).
    • Click the name of a method specified in an interface type declaration to show the methods implementing it (only for package-level named interface types now)..
  • Shows code statistics (demo).
  • Supports generating static HTML docs pages, to avoid rebuilding the docs later. This is good for package developers to host docs of their own packages. (The docs of standard packages are generated within about 7 seconds, and the docs of the kubernetes project packages are generated within about one minute.)
  • All functionalities are implemented locally, no external websites are needed.
  • Just fell free to open any number of pages in new browser windows as needed.
  • JavaScript-off friendly. No tracing, no auto external websites visiting.

(NOTE: This tool is still in its early experimental phase. More new features will be added from time to time in future versions.)

Limitations

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

This project uses the golang.org/x/tools/go/packages package to parse code. The golang.org/x/tools/go/package 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.

Only a code snapshot is analyzed. When code changes, a new analyzation is needed from scratch.

Testing packages are excluded currently.

Code examples in docs are not shown currently.

Usage

Start the docs server:

  • Run 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.
  • Run gold aPackage to show docs of the specified package (and all its dependency packages).

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

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

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

The above commands will generated the full docs of specified packages. The following options are available to generate compact docs:

  • -nouses: don't generate identifier-uses pages (identifier-uses pages will occupy about 9/10 of the total page count and 2/3 of the full docs size).
  • -plainsrc: generate simpler source code pages (no highlighting and no code navigations to reduce the total page size by 1/6 of the full docs size).

The size of the docs generated by gold -gen -nouses -plainsrc ./... is about 1/6 of gold -gen ./....

The -emphasize-wdpkgs option is used to list the packages within the working directory before other packages in the first page (for HTML docs generation mode only).

We can run gold -dir=. (or simply gold) from the HTML docs generation directory to view the generated docs in browser. (Gold also means Go local directory server. The -s or -silent options also work in this mode.)

The gold command recognizes the GOOS and GOARCH environment variables.

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
imgui-go v2.5.0 35 1.2s 125M
gotk3 rev:030ba00 40 3s 305M
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
nucular rev:b1fe9b2 97 2s 250M
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.14 199 2.6s 400M
Pebble rev:284ba06 200 2.2s 500M
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
nomad v0.12.4 897 7.5s 2.1G
istio 1.6.0 1860 10.7s 2.8G
openshift/origin rev:5022f83 2640 16.1s 4G
kubernetes v1.18.2 2821 16.3s 4G

About

An experimental Go local docs server/generator and code reader implemented with some fresh ideas.

Topics

Resources

License

Languages

You can’t perform that action at this time.