How do you serve simple documentation for go programs using godoc as a webpage?

I was trying to serve a specific local go file as a documentation web page, but was not able to do it.

With the -http flag (i.e. the godoc command), it runs as a web server and presents the documentation as a web page.

user_me$ godoc -http=:6060

This does create something similar as the go page but it does not render the specific file that I want to render. So I tried to provide the name of the file I wanted:

user_me$ godoc -http=:6000 hello.go

However, it just replies with:

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

I also tried:

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

but it didn't work.

I also tried:

godoc -server=localhost:8080 hello.go

but it replied with:

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

I even tried just generating the html thing itself:

godoc -html hello.go > hello.html

same error as above.

I also tried (since it was complaining that there was no file in the pkg dir):

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

At the end, I gave up. I don't know how this godoc thing works. I installed the hello.go program so that I there was something in the pkg file in the workspace. How do you generate a webpage with your documentation for your code?

Solution

godoc operates on package and type names, not filenames.

For example, to learn about io/ioutil package:

text output: godoc io/ioutil
just the ReadAll function: godoc io/ioutil ReadAll
in HTML: godoc -html io/ioutil ReadAll
in the browser:
- godoc -http=:6060
- click Packages and navigate from there
- or go directly to http://localhost:6060/pkg/io/ioutil#ReadAll

To view documentation for your own code, it has to be included in your GOPATH.

Suppose your GOPATH includes $HOME/go/src, and the file you are interested in is $HOME/go/src/hey/world/doc.go, you would run:

godoc hey/world

...or start godoc in HTTP mode and browse to http://localhost:6060/pkg/hey/world