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

Question

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

The official godoc documentation says:

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?

Answer 1

On linux, and assuming you have cd'd into the package of which you want to read the documentation.

if you are using go modules, you can run below command

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

It uses the -m flag to get the package path even though the root module directory does not contain any .go file.

If you are not yet using modules, you can run,

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

Note that unlike -m this command will not work appropriately if there is no .go files into the directory.

Check the go list subcommand help at https://golang.org/pkg/cmd/go/internal/list/

Answer 2

Running godoc on its own worked for me, but was really slow because it generates docs for every single package in the standard library, while I only care about the local package that I am working on. To that end, if your package is in a folder called something, you can move the folder so that it looks like this:

godoc/src/something

Then, go to the godoc folder, and run

godoc -goroot .

Then, browse to localhost:6060.

Answer 3

To show HTML doc generated for your own code

Step 1) At command line start up the document web server, that is:

C:\>godoc -http=:6060

Step 2) Open a browser and use an explicit url the folder your code is.

The URL structure comes from the folder names under your GOPATH.

For example:

If my GOPATH is c:\go and I have code in c:\go\src\myfolder\mysubfolder

The URL I would uses is http://localhost:6060/pkg/myfolder/mysubfolder and this would show an HTML page for the .go files in there

Also you can use URL http://localhost:6060/pkg/myfolder, which will have a link to mysubfolder

Notes:

• I'm not sure how to see your local code at the the http://localhost:6060/pkg level, maybe you can't
• It is possible to "specify additional paths" so I don't think it has to be the src folder, see https://blog.golang.org/godoc-documenting-go-code

Answer 4

By default, godoc looks at the packages it finds via $GOROOT and $GOPATH. So given that your package is in Go workspace i.e in GOPATH, you can run

godoc fmt

which prints out documentation for fmt package.

If you want to generate docs for your package foo which is in $GOPATH/src/github.com/abcd/foo location, you should run

godoc github.com/abcd/foo

With the -http flag, godoc runs as a web server and presents the documentation as a web page.

godoc -http=:6060

Now navigate to http://localhost:6060/pkg/github.com/abcd/foo in browser to find docs as web page.

The -play flag can be used to enable playground in web interface.

Answer 5

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