在 Go 模块中如何使用 godoc 提供文档？

在 Go 模块中使用 godoc 生成文档时，可能会遇到工具不支持模块的问题。虽然 go doc 命令不能生成 HTML 页面，但可以采用解决方法来使用 docker 容器运行 godoc 服务器。通过设置 gopath 为开发树的根目录，godoc 服务器可以为开发树中的所有包提供文档，无论其是否包含 go.mod。

godoc 工具似乎不支持 Go 模块。

一个简单的 godoc -goroot=. 提供项目文件，但它不会生成包的文档。我在项目源目录中对其进行了测试，其中还存储了 go.mod 和 go.sum 模块文件。

如何为 Go 模块内的所有包生成文档 - $GOPATH 之外？

Go 1.12 的发行说明中写道，godoc 工具将不会包含在未来的 Go 版本中，并且只能在 Go 1.12 之后通过 go get 获得。应使用 Go go doc 命令。但是，go doc 不会生成“易读”的 HTML 页面。 是否有其他方法可以从输出 HTML 或 Markdown 的 Go 源代码生成文档？

解决方案

问题不在于模块，而在于 gopath。有一个 github 问题线程更详细地讨论了这个问题：https://github.com/golang/go/issues/26827

该线程已经发展了一种解决方法，使用 docker 容器来运行 godoc 服务器，并将 gopath 设置为开发树的基础。该 godoc 服务器将为您的开发树中的所有包提供文档，无论它们是否有 go.mod。

这是我今天早上刚刚在该线程中发布的解决方法的一个版本 - 修改 $devbase （或将其作为 $1 传递）以指向树的底部：

#!/bin/bash 

set -x  # optional

devbase=$HOME/gohack
port=6060

docker run \
    --rm \
    -e "GOPATH=/tmp/go" \
    -p 127.0.0.1:$port:$port \
    -v $devbase:/tmp/go/src/ \
    --name godoc \
    golang \
    bash -c "go get golang.org/x/tools/cmd/godoc && echo http://localhost:$port/pkg/ && /tmp/go/bin/godoc -http=:$port"

您会注意到，我还使用了 gohack 工具——它为您管理 go.mod 中的“替换”行，因此即使模块尚未推送到服务器，导入也会找到您的本地版本的模块。 $devbase 在其他方面没有什么特别的——例如，将它指向 $home/src 也应该同样有效。

好了，本文到此结束，带大家了解了《在 Go 模块中如何使用 godoc 提供文档？》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！