你如何为使用 godoc 作为网页的 go 程序提供简单的文档？

Question

我试图将特定的本地 go 文件作为文档网页提供，但无法做到。

official godoc documentation 说：

使用 -http 标志（即 godoc 命令），它作为 Web 服务器运行并将文档显示为网页。

user_me$ godoc -http=:6060

这确实会创建类似于 go 页面的内容，但它不会呈现我想要呈现的特定文件。所以我尝试提供我想要的文件名：

user_me$ godoc -http=:6000 hello.go

但是，它只是回复：

usage: godoc package [name ...]
    godoc -http=:6060
  -ex=false: show examples in command line mode
  -goroot="/usr/local/go": Go root directory
  -html=false: print HTML in command-line mode
  -http="": HTTP service address (e.g., ':6060')
  -httptest.serve="": if non-empty, httptest.NewServer serves on this address and blocks
  -index=false: enable search index
  -index_files="": glob pattern specifying index files;if not empty, the index is read from these files in sorted order
  -index_throttle=0.75: index throttle value; 0.0 = no time allocated, 1.0 = full throttle
  -links=true: link identifiers to their declarations
  -maxresults=10000: maximum number of full text search results shown
  -notes="BUG": regular expression matching note markers to show
  -play=false: enable playground in web interface
  -q=false: arguments are considered search queries
  -server="": webserver address for command line searches
  -src=false: print (exported) source in command-line mode
  -tabwidth=4: tab width
  -templates="": directory containing alternate template files
  -timestamps=false: show timestamps with directory listings
  -url="": print HTML for named URL
  -v=false: verbose mode
  -write_index=false: write index to a file; the file name must be specified with -index_files
  -zip="": zip file providing the file system to serve; disabled if empty

我也试过了：

user_me$ godoc -url="localhost:8080" hello.go

但是没有用。

我也试过了：

godoc -server=localhost:8080 hello.go

但它回复了：

2014/07/01 10:45:56 open /usr/local/go/src/pkg/hello.go: no such file or directory

我什至尝试自己生成 html 内容：

godoc -html hello.go > hello.html

与上述相同的错误。

我也试过（因为它抱怨 pkg 目录中没有文件）：

godoc -html -goroo=$GOPATH hello.go > hello.html

最后，我放弃了。我不知道这个 godoc 是如何工作的。我安装了 hello.go 程序，以便工作区的 pkg 文件中有一些内容。您如何使用您的代码文档生成网页？

Answer 1

godoc 对包和类型名称进行操作，而不是文件名。

例如了解io/ioutil包：

• 文本输出：godoc io/ioutil

• 只是ReadAll 函数：godoc io/ioutil ReadAll

• 在 HTML 中：godoc -html io/ioutil ReadAll

• 在浏览器中：

  • godoc -http=:6060
  • 点击包并从那里导航
  • 或直接去http://localhost:6060/pkg/io/ioutil#ReadAll

要查看您自己代码的文档，必须将其包含在您的GOPATH 中。

假设您的GOPATH 包含$HOME/go/src，并且您感兴趣的文件是$HOME/go/src/hey/world/doc.go，您将运行：

godoc hey/world

...或以 HTTP 模式启动 godoc 并浏览到 http://localhost:6060/pkg/hey/world

Answer 2

默认情况下，godoc 查看它通过 $GOROOT 和 $GOPATH 找到的包。因此，鉴于您的包在 Go 工作区中，即在 GOPATH 中，您可以运行

godoc fmt

打印出 fmt 包的文档。

如果您想为位于$GOPATH/src/github.com/abcd/foo 位置的包foo 生成文档，您应该运行

godoc github.com/abcd/foo

使用-http 标志，godoc 作为 Web 服务器运行并将文档显示为网页。

godoc -http=:6060

现在在浏览器中导航到http://localhost:6060/pkg/github.com/abcd/foo 以将文档作为网页查找。

-play 标志可用于在 Web 界面中启用 Playground。

Answer 3

显示为您自己的代码生成的 HTML 文档

步骤1）在命令行启动文档Web服务器，即：

C:\>godoc -http=:6060

第 2 步）打开浏览器并使用您的代码所在文件夹的显式 url。

URL 结构来自您的 GOPATH 下的文件夹名称。

例如：

如果我的 GOPATH 是 c:\go 并且我在 c:\go\src\myfolder\mysubfolder 中有代码

我将使用的 URL 是 http://localhost:6060/pkg/myfolder/mysubfolder，这将显示其中的 .go 文件的 HTML 页面

您也可以使用 URL http://localhost:6060/pkg/myfolder，其中将包含指向 mysubfolder 的链接

注意事项：

• 我不确定如何在http://localhost:6060/pkg 级别查看您的本地代码，也许您看不到
• 可以“指定其他路径”，所以我认为它不必是src 文件夹，请参阅https://blog.golang.org/godoc-documenting-go-code

Answer 4

单独运行godoc 对我有用，但速度很慢，因为它 为标准库中的每个包生成文档，而我只 关心我正在处理的本地软件包。为此，如果您的包位于名为 something 的文件夹中，您可以移动 文件夹，使其看起来像这样：

godoc/src/something

然后，转到godoc 文件夹，然后运行

godoc -goroot .

然后，浏览到localhost:6060。

Answer 5

在 linux 上，假设您已经 cd'd 进入要阅读其文档的软件包。

如果你正在使用 go 模块，你可以运行下面的命令

godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -m)

它使用-m 标志来获取包路径，即使根模块目录不包含任何.go 文件。

如果你还没有使用模块，你可以运行，

godoc -http=:6060 & xdg-open http://localhost:6060/pkg/$(go list -f "{{.ImportPath}}")

请注意，与-m 不同，如果目录中没有.go 文件，此命令将无法正常工作。

查看go list 子命令帮助https://golang.org/pkg/cmd/go/internal/list/