为整个项目生成 godoc 文档？

Question

我一直在研究 godoc，发现“go doc”更适合从命令行提供使用帮助，例如：go doc -cmd -u列出包注释和任何函数（或其他实体）go doc *function*然后显示单个功能（或其他实体）的文档似乎有一个相关的工具叫做godoc。godoc 似乎也在每个包和函数的基础上生成 html。例如godoc -html hello生成仅包含包注释的 html 到标准输出godoc是一个非常令人困惑的名字，因为我们也有go doc ！如何为整个项目创建静态文档？这类似于Godoc，为整个包创建 html，这可能被误解为询问包的文档而不是项目。我想要一个可以在原则上可能包含许多包和应用程序的项目中使用的构建步骤。

Answer 1

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

Go 1.12（2019 年 2 月）对此更清楚：

godoc和go doc

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

go doc现在支持-allflag，这将导致它打印所有导出的 API 及其文档，就像以前的godoc命令行一样。

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

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

Answer 2

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

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 3

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

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

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

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

• golds -gen -wdpkgs-listing=提升./...

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

Answer 4

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

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

示例：Go Logger 文档

两个不错的功能：

• 嵌入式 Go 源代码文件

• 搜索框引用了 GitLab