Golds is an experimental Go local docs server, a Go docs generator, and a Go code reader.
golds -gen -nouses -only-list-exporteds std).
go install go101.org/golds@latest
go get -u go101.org/golds(the
GO111MODULEenviroment variable needs to be set as
ontemporarily to utilize the
goldsconflicts 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 install go101.org/golds/godoge@latest
go get -u go101.org/golds/godoge
go install go101.org/golds/gocore@latest
go get -u go101.org/golds/gocore
go install go101.org/golds/gold@latest
go get -u go101.org/golds/gold
You may also clone this project firstly, then run the
go install command in the respective program folders to install Golds as
(NOTE: Go commands will install output 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.)
golds .to show docs of the package in the current directory (and all its dependency packages).
golds ./...to show docs of all the package under the current directory (and all their dependency packages).
golds toolchainto show docs of official toolchain packages (and all their dependency packages).
toolchainshould be used exclusively with the above two arguments:
golds stdto show docs of standard packages.
stdcan be mixed with any one of the above three arguments.
golds aPackagein a module aware directory to show docs of the specified package (and all its dependency packages).
golds foo.go bar.go baz.goto 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
-silent options to turn off the behavior.
golds -gen -dir=generated -nouses .
golds -gen -dir=generated -nouses ./...
golds -gen -dir=generated -nouses std
-dir option is optional and its default value is
. (the working directory).
-nouses option used here is to generate docs with moderate sizes.
-source-code-readingis 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 hightlight 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).
-allow-network-connection specifies whether or not network connections are allowed in determining external code host websites.
-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).
-only-list-exporteds: don't list unexported package-level resources in package-details pages.
-compactis a shortcut of the combination of the above compact docs generation options.
-compactwill 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 ./....
-wdpkgs-listingoption 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 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
from the HTML docs generation directory to view the generated docs in browser.
-silent options also work in this mode.
golds command recognizes the
GOARCH environment variables.
"Golds" is an abbreviation of Go local docs server. It also means Go local directory server.
I didn't find a Go tool showing type implementation relations, so I decided to write one. In doing this, I got many new ideas which form the tool to the final Golds design.
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.
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.
If you would like to learn some Go details and facts every serveral days, please follow Go 101's official Twitter account: @go100and1.
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.