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

Question

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

该负责人godoc文件说:

使用-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 包的文档。

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

godoc github.com/abcd/foo

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

godoc -http=:6060

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

该-play标志可用于在 Web 界面中启用游乐场。