Golds is an experimental Go local docs server, a Go docs generator, and a Go code reader.
golds -gen -nouses -only-list-exporteds -render-doclinks std
).
go install go101.org/golds@latest
go get -u go101.org/golds
(the GO111MODULE
environment variable needs to be set as on
temporarily to utilize the GOPROXY
setting).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 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
gold
was the old default program name of Golds)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 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.)
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 toolchain
(or golds cmd
) to show docs of official toolchain packages.golds std
to show docs of standard packages. std
can be mixed with any one of the above three arguments.golds aPackage[/...][@aVersion]
to show docs of the specified packages (and all their dependency packages).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.
-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.
-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.
-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.-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 ./...
.
-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 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 docs generation 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.
"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 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 shortcomings of `godoc` and `go doc`.
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.
The Go 101 프로젝트는 Github 에서 호스팅됩니다. 오타, 문법 오류, 부정확한 표현, 설명 결함, 코드 버그, 끊어진 링크와 같은 모든 종류의 실수에 대한 수정 사항을 제출하여 Go 101을 개선을 돕는 것은 언제나 환영합니다.
주기적으로 Go에 대한 깊이 있는 정보를 얻고 싶다면 Go 101의 공식 트위터 계정인 @go100and1을 팔로우하거나 Go 101 슬랙 채널에j가입해주세요.