# Golds

Golds（Go local docs server）是一款实验性的本地Go文档服务器、Go文档生成器以及Go代码阅读器。

- 演示地址：标准库文档和代码（使用命令`golds -gen -nouses -only-list-exporteds std`生成）。
- 项目代码托管于Github上。欢迎提交PR和发现的问题。
- 请关注官方twitter帐号@zigo_101或微信号"Go 101"来获取Golds的最新动态（以及各种关于Go语言的细节、事实和技巧等）。

### 特性和当前版本的限制

请阅读项目主页以获取详情。

### 安装

- 如果你已经在使用官方工具链1.16+版本，则可运行`go install go101.org/golds@latest`来安装Golds；
- 如果你仍在使用官方工具链1.15-版本，则可运行`go get -u go101.org/golds`来安装Golds（注意：`GO111MODULE`环境变量需要暂时设置成`on`以利用`GOPROXY`设置）。

如果程序名`golds`和其它程序冲突，也可将Golds程序安装为其它名称：

- Go docs generator
  如果你已经在使用官方工具链1.16+版本，运行`go install go101.org/golds/godoge@latest`
  如果你仍在使用官方工具链1.15-版本，运行`go get -u go101.org/golds/godoge`
- Go code reader
  如果你已经在使用官方工具链1.16+版本，运行`go install go101.org/golds/gocore@latest`
  如果你仍在使用官方工具链1.15-版本，运行`go get -u go101.org/golds/gocore`

你也可以先将此项目代码克隆下来，然后进入相应的程序目录，运行`go install`来安装此程序。

（注意：Go程序的默认安装路径为`GOBIN`环境变量设置的路径。它的默认值为`GOPATH`环境变量指定的第一个路径下的`bin`子文件夹对应的目录。`GOPATH`环境变量的默认值为当前用户HOME目录下的`go`子文件夹对应的目录。请将Go程序默认安装路径配置在`PATH`环境变量中以便从任何目录运行安装的Go程序。）

### 使用说明

Golds 的主要用途是针对一个Go项目开启一个本地文档服务器，用来查看此项目的文档和源代码。我们可以

- 运行`golds .`来查看处于当前目录下的Go库包（以及它的依赖包）的文档和代码。
- 运行`golds ./...`来查看处于当前目录下的所有Go库包（以及它们的依赖包）的文档和代码。
- 运行`golds toolchain`（或者`golds cmd`）来查看处于官方工具链中的所有Go库包（以及它们的依赖包）的文档和代码。
- 运行`golds std`来查看处于所有Go标准库包库包的文档和代码；`std`可以和上面的三个参数并用。
- 运行`golds aPackage`来查看某个库包（以及它的依赖包）的文档和代码。
- 运行`golds foo.go bar.go baz.go`来查看一些Go文件（以及它们的依赖包）的文档和代码。

上述所用命令都将自动打开一个浏览器窗口用来浏览文档和代码。我们可以使用`-s`或`-silent`选项来关闭这一行为。

Golds的第二个用途是使用`-gen`选项来生成一个项目的静态HTML文档。 比如：

- `golds -gen -dir=generated -nouses .`
- `golds -gen -dir=generated -nouses ./...`
- `golds -gen -dir=generated -nouses std`

其中的`-dir`选项的默认值为`.`（即当前目录）。 使用`-nouses`选项来避免生成的文档占用过多磁盘空间（减少特性换取空间）。

选项`-source-code-reading`用来控制如何生成源代码页面。支持的值：

- `plain`：简单朴素的代码页页面（无高亮和代码间跳转，将减少1/6的磁盘占用空间）
- `highlight`：仅仅高亮关键字和基本字面值（无代码间跳转）。
- `rich`：丰富的阅读体验。
- `external`：链接至外部代码托管网站（将尽力而为，若失败则采用highlight方式）。

选项`-allow-network-connection`用来指定在确定Go模块外部代码托管网站的时候是否可以进行网络连接。

主要的控制占用磁盘空间的选项：

- `-nouses`：不生成标识符的使用列表页面（此选项将减少2/3的磁盘占用空间）。
- `-source-code-reading=plain`
- `-only-list-exporteds`：不列出非导出包级代码要素。
- `-compact`为上面几个选项的叠加。
- 同时使用`-source-code-reading=external`和`-compact`将进一步减小最终生成的文档的磁盘占用空间。

`golds -gen -compact ./...`命令生成的文档占用的磁盘空间为`golds -gen ./...`命令的1/6，为`golds -gen -nouses ./...`命令的1/2。`golds -gen -compact -source-code-reading=external ./...`命令生成的文档占用的磁盘空间为`golds -gen -compact ./...`命令的1/5。

`-wdpkgs-listing`选项用来控制如何列出当前目录下的所有库包。它的值可以为：

- `general`（默认值，和其它依赖库包一起按照字母顺序列出）。
- `promoted`（将它们列出在其它依赖库包之前）。
- `solo`（只列出它们，不列其它依赖包）。

Golds的第三个用途是作为文件服务器（Go local directory server）。 比如我们可以运行`golds -dir=.`（或者`golds`）来在浏览其中浏览当前目录的文件。 `-s`和`-silent`选项在此用途中也有效。

`golds`命令可以识别`GOOS`和`GOARCH`环境变量。