go - 如何使用 godoc 与 go 模块一起提供文档？

Question

看来godoc工具不是Go modules意识到。

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

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

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

Answer 1

问题不在于模块，而在于 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 也应该同样有效。