haunt98 / golds

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

Golds 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.

• Demo of the generated docs for standard packages (generated with golds -gen -nouses -only-list-exporteds std).
• Please follow @Go100and1 to get the latest news of Golds (and Go details/facts/tips/etc.).

Installation & Usages

The module path of this project is go101.org/golds and the default Go program name is golds. For more information about installation and usages, please visit this page on Go101.org.

Main Features

• JavaScript-off friendly, though the experience is a little richer if JavaScript is on. No tracing, no auto external websites visiting.
• Lists types not only by alphabet, but also by popularity (only available when JavaScript is on), which is good to understanding some packages with many types declared.
• Supports listing unexported types and values, which is helpful to understand some packages.
• Treats main packages as same as library packages.
• Rich package-level type/value information collection:
  • Shows type implementation 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 lists (including interface methods).
  • Shows the package-level value list of a package-level type.
  • Shows uses of package-level declared types/constants/variables/functions (by clicking the type/const/var/func keywords).
  • Press p (package), e (examples), t (types), f (functions), v (variables), c (constants), and a (all) to toggle doc expand/collapse statuses (only available when JavaScript is on).
• Smooth code view experiences (good for studying Go projects without opening IDEs):
  • Click a local identifier to highlight all the occurrences 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). If the name represents a method, in the uses page, click the (method) text to show which interface methods the method implements.
  • 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). In the method-implementation page, click each the name of an interface method to show the uses of the interface method.
• Shows code statistics (demo).
  • Click some of the SVG pictures to show corresponding toppest list.
• 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 10 seconds, and the docs of the kubernetes project packages are generated within about 100 seconds.)
• All functionalities are implemented locally, no external websites are needed (except explicitly required by you).
• Just fell free to open any number of pages in new browser windows as needed.

(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 build and run Golds.

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.

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 golds ./... 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 Golds)
bolt v1.3.1	51	1.6s	140M
nucular rev:b1fe9b2	97	2s	250M
tview rev:823f280	102	2s	200M	(run golds . instead of golds ./...)
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 Golds)
badger v2.0.3	145	2.2s	350M
Golds v0.0.1	151	2.5s	400M	(run golds . instead of golds ./...)
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
dominikh/go-tools rev:919f4c9	235	4.5s	465M
tailscale v0.98.0	275	2.5s	539M
etcd v3.4.7	391	3.5s	700M	(need run go mod vendor before running Golds)
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
Traefik v2.3.0	1199	8.9s	2G	(need generate bindata before running Golds)
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