Golds

GoldsGo 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库包(以及它们的依赖包)的文档和代码; toolchain和上面两个参数(../...)互斥。
  • 运行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命令可以识别GOOSGOARCH环境变量。