如何使用 godoc 和 go 模块提供文档？答案

【问题标题】：How to serve documentation using godoc together with go modules?如何使用 godoc 和 go 模块提供文档？
【发布时间】：2019-07-22 20:35:21
【问题描述】：

似乎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 源代码生成文档的替代方法？

【问题讨论】：

“不知道 Go 模块”到底是什么意思？模块对文档没有影响。您希望它在模块方面“意识到”什么？
我希望它能够为使用 GOPATH 之外的 Go 模块管理的 Go 包生成文档。
GOROOT 和 GOPATH 不一样。您不应该将-goroot 指向您的来源。 GOROOT 应该指向你的 Go 安装。同样对于您问题的最后一部分，对第三方工具和库的请求与 Stack Overflow 无关。
Github 上的相关 cmets：github.com/golang/go/issues/26827#issuecomment-429315761。这似乎是跟踪此（尚不可用）功能的问题。另请参阅github.com/golang/go/issues/25443#issuecomment-474553586。

标签： go documentation documentation-generation go-modules

【解决方案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 应该也能正常工作。

【讨论】：

【解决方案2】：

显然这里已经修复了https://github.com/golang/go/issues/33655

我所要做的就是升级到版本 1.14，然后在我的目录中运行 godoc 并使用 go modules 。

只要go 命令在模块模式下运行，godoc 命令就应该在模块模式下运行。所以godoc 应该在相同的环境和工作目录下运行go env GOMOD，并解释结果。

如果go env GOMOD 的结果是一个空字符串，那么GOPATH 模式正在被使用，godoc 的行为方式将与GOPATH 一样，它只会在GOPATH 目录中查找.

【讨论】：