Three new books, Go Optimizations 101, Go Details & Tips 101 and Go Generics 101 are published now. It is most cost-effective to buy all of them through this book bundle in the Leanpub book store.

Golds

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

Features and Limitations

Please read the project home page for details.

Installation

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:

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

Usages

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

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:

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:

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:

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

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.

FAQ

What does Golds mean?

"Golds" is an abbreviation of Go local docs server. It also means Go local directory server.

Why Golds?

I didn't find a Go tool showing type implementation relations, so I decided to write one. During achieving this, I got many new ideas which form the tool to the final Golds design.

I also have some different design opinions from the official godoc program developers, such as the manner of listing factory functions.

Golds also tries to fix some other shortcomings of godoc and go doc, such as this, this and this.

Is Golds recommended to run locally?

Yes. But if you do want to serve your package docs on Internet, it is best to serve the generated HTML static doc pages to lower the server cost.

What are the requirements to run Golds?

If a Go project needs cgo, then a proper C/C++ compiler is needed.

Some projects might need large memory capacity to analyze. For example, the recommended memory capacity to analyze the Kubernetes project is 8G+. However, 500M to 2G memory is okay for most Go projects.

(more articles ↡)

The Go 101 project is hosted on Github. Welcome to improve Go 101 articles by submitting corrections for all kinds of mistakes, such as typos, grammar errors, wording inaccuracies, description flaws, code bugs and broken links.

If you would like to learn some Go details and facts every serveral days, please follow Go 101's official Twitter account @zigo_101.

Tapir, the author of Go 101, has been on writing the Go 101 series books and maintaining the go101.org website since 2016 July. New contents will be continually added to the book and the website from time to time. Tapir is also an indie game developer. You can also support Go 101 by playing Tapir's games (made for both Android and iPhone/iPad):
Individual donations via PayPal are also welcome.

Articles in this book: