为整个项目生成 godoc 文档？

Question

我一直在和 godoc 搏斗，发现“go doc”更多的是从命令行提供使用帮助，例如：

go doc -cmd -u

列出包注释和任何函数（或其他实体）

go doc *function*

然后显示单个函数（或其他实体）的文档

好像有一个相关的工具叫做godoc。 godoc 似乎也基于每个包和功能生成 html。 例如

godoc -html hello

仅生成包含包注释的 html 到标准输出

godoc 是一个非常令人困惑的名字，因为我们也有 go doc！

如何为整个项目创建静态文档？

这类似于Godoc, create html for entire package，可能被误解为询问包的文档而不是项目。 我想要一个可以在原则上可能包含许多包和应用程序的项目中使用的构建步骤。

Answer 1

我一直在努力做到这一点，最后，对我有用的是

1. 确保您已安装“wget”（我使用的是 mac，所以必须使用 x-code 安装它）
2. 以 root 用户身份登录并修改名为“robots.txt”的文件以删除“Disallow : /”行，因为这会阻止 wget 递归下载站点。 “robots.txt”文件应位于 $GOROOT 路径中。

3. 打开一个 cmd 并使用以下命令启动 godocs 服务器

   godoc -http=:6060

我已将本地路径配置到此端口。 4.打开另一个cmd并运行以下命令。

wget -r -np -N -E -p -k http://localhost:6060/pkg/myproject

您可以提及项目的路径以下载整个项目的 html 文档。

Answer 2

是否有一种规范的方法可以生成文档以供离线使用，即使使用 godoc？

Go 1.12 (February 2019) 对此更清楚：

godoc 和 go doc

在 Go 1.12 中，godoc 不再具有命令行界面，而只是一个 Web 服务器。
用户应使用go doc 代替命令行帮助输出。

go doc now supports the -all flag，这将导致它打印所有导出的 API 及其文档，就像 godoc 命令行过去所做的那样。

cmd/doc：添加-all 标志以打印包的所有文档

与旧的godoc 不同，您需要-u 标志才能查看未导出的符号。
这似乎是正确的行为：它是一致的。

Answer 3

这也可以使用简单的 wget 命令来实现。示例：snippet

我也有类似的问题。我正在为我的项目使用 GitLab，我决定为 Go 项目创建和共享一些方便的 GitLab CI YAML 模板，这些模板将自动生成静态 HTML Go 文档，无需任何外部包：https://gitlab.com/tymonx/gitlab-ci

例如：Go Logger documentation

两个不错的功能：

• 嵌入式 Go 源代码文件
• 搜索框引用 GitLab

Answer 4

你可以试试Golds，这是一个替代的 Go 文档生成工具（和本地文档服务器/代码阅读器）。

在您的项目目录下，您可以运行以下任意命令为您的 Go 项目生成 HTML 文档：

• golds -gen -nouses -plainsrc -wdpkgs-listing=promoted ./...
• golds -gen -nouses -wdpkgs-listing=promoted ./...
• golds -gen -wdpkgs-listing=promoted ./...

第一个命令生成最紧凑的文档，最后一个命令生成完整的文档，其大小是紧凑文档的 6 倍。

顺便说一句，我是Golds的作者。希望这个工具能满足您的需求。