Golds -Go 101

Golds is an experimental Go local docs server, a Go docs generator, and a Go code reader.

• Demo: docs and source code of standard packages (generated with GOEXPERIMENT=arenas,jsonv2 golds -gen -nouses -only-list-exporteds -render-doclinks -theme=dark std).

• Code is hosted on Github. Any feedback, including PR and bug reports, are welcome.

• Please follow @zigo_101 to get the latest news of Golds (and all kinds of Go details/facts/tips/etc.).

Run go install go101.org/golds@latest to install Golds. If the tool program name golds conflicts with another tool with the same name you are using, you can run any of the following commands to install Golds as a program with a different name:

• Go docs generator: run go install go101.org/golds/godoge@latest

• Go code reader: run go install go101.org/golds/gocore@latest

• Go local docs (mainly for legacy. gold was the old default program name of Golds): run go install go101.org/golds/gold@latest

You may also clone this project firstly, then run the go install command in the respective program folders to install Golds as golds, godoge, or gocore.

(NOTE: Go commands will install produced binaries into the Go binary installation path specified by the GOBIN environment variable, which defaults to the path of the bin subfolder under the first path specified in the GOPATH environment variable, which defaults to the path of the go subfolder under the path specified by the HOME environment variable. Please specify the Go binary installation path in the PATH environment variable to run Golds commands successfully.)

The main usage of Golds is to start a local docs server for a project, to either read package docs or study source code of the project. We can

• run golds . to show docs of the package in the current directory (and all its dependency packages).

• run golds ./... to show docs of all the package under the current directory (and all their dependency packages).

• run golds toolchain (or golds cmd) to show docs of official toolchain packages.

• run golds std to show docs of standard packages. std can be mixed with any one of the above three arguments.

• run golds aPackage[/...][@aVersion] to show docs of the specified packages (and all their dependency packages).

• run golds foo.go bar.go baz.go to show docs of the specified files (and all their 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.

The second usage of Golds is to generate static HTML doc pages for a project, with the -gen option:

• golds -gen -dir=generated -nouses .

• golds -gen -dir=generated -nouses ./...

• golds -gen -dir=generated -nouses std

The -dir option is optional and its default value is .(the working directory). The -nouses option used here is to generate docs with moderate sizes.

The option -source-code-reading is used to control how to generate source code pages. Available values:

• plain: 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).

• highlight: only highlight keywords and basic literals (no code navigations).

• rich: rich code reading experience.

• external: link to external code host websites (try its best, use highlight when failed).

The option -allow-network-connection specifies whether or not network connections are allowed in determining external code host websites.

Options to control generated docs sizes:

• -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).

• -source-code-reading=plain

• -only-list-exporteds: don't list unexported package-level code elements in package-details pages.

• -compact is a shortcut of the combination of the above compact docs generation options.

• Using -source-code-reading=external along with -compact will further reduce the generated docs size.

The size of the docs generated by golds -gen -compact ./... is about 1/6 of golds -gen ./... and about 1/2 of golds -gen -nouses ./.... The size of the docs generated by golds -gen -compact -source-code-reading=external ./... is about 1/6 of golds -gen -compact ./....

The -wdpkgs-listing option is used to specify how to list the packages in the working directory. Available values include

• general (the default, list them with others by alphabetical order)

• promoted (list them before others)

• solo (list them without others)

The -render-doclinks option is used to control whether or not to render links in docs.

The -theme option is used to control page styling Supported values include auto (default), light and dark. The auto value is equivalent to light plus custom styling set in the UserConfigDir/golds/custom.css file (if it exists).

The third usage of Golds is to serve files within a directory ("Golds" also means Go local directory server). For example, we can run golds -dir=. (or simply golds) from the HTML docsgeneration directory to view the generated docs in browser. The -s and -silent options also work in this mode.

The golds command recognizes the GOOS and GOARCH environment variables.

Tapir, the author of Go 101, has been on writing the Go 101 series books since 2016 July. New contents will be continually added to the books (and the go101.org website) from time to time. Tapir is also an indie game developer. You can also support Go 101 by playing Tapir's games:

• Color Infection (★★★★★), a physics based original casual puzzle game. 140+ levels.
• Rectangle Pushers (★★★★★), an original casual puzzle game. Two modes, 104+ levels.
• Let's Play With Particles, a casual action original game. Three mini games are included.