Golds

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

  • 演示地址：标准库文档和代码（使用命令golds -gen -nouses -only-list-exporteds std生成）。
  • 项目代码托管于Github上。欢迎提交PR和发现的问题。
  • 请关注官方twitter帐号@Go100and1或微信号”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环境变量。