Golds

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

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

特性和当前版本的限制

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

安装

运行go install go101.org/golds@latest来安装Golds。 如果程序名golds和其它程序冲突，也可将Golds程序安装为其它名称：

• Go docs generator：运行go install go101.org/golds/godoge@latest
• Go code reader
  ：运行go install go101.org/golds/gocore@latest

你也可以先将此项目代码克隆下来，然后进入相应的程序目录，运行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[/...][@aVersion]来查看某些（共享一个路径前缀的）库包（以及它们的依赖包）的文档和代码。
• 运行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选项在此用途中也有效。

-render-doclinks选项用来控制是否渲染文档中的 MarkDown 链接。

-theme选项用来控制页面渲染风格。 目前支持 auto（默认值）、 light 和 dark。 auto 相当于 light 加上在 $UserConfigDir/golds/custom.css 文件中配置的自定义风格。

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