How to serve documentation using godoc together with go modules?

Question

It seems that the godoc tool is not Go modules aware.

A simple godoc -goroot=. serves the project files, but it does not generate documentation for the packages. I tested it from withing the projects source directory, where also the go.mod and go.sum module files are stored.

How to generate documentation for all packages inside a Go module - outside of $GOPATH?

In the release notes of Go 1.12 is written that the godoc tool will not be included in future Go releases and will only be available via go get after Go 1.12. One should use the Go go doc command. However, go doc does not generate "nice to read" HTML pages. Is there an alternative for documentation generation from Go source code which outputs HTML or Markdown?

Answer 1

The issue isn't modules so much as GOPATH. There's a github issue thread that discusses this in more detail: https://github.com/golang/go/issues/26827

That thread has evolved a workaround that uses a docker container to run a godoc server with GOPATH set to the base of your dev tree. That godoc server will serve docs for all of the packages in your dev tree, regardless of whether they have a go.mod yet or not.

Here's a version of the workaround that I just posted in that thread this morning -- modify $devbase (or pass it in as $1) to point at the base of your tree:

#!/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"

You'll note that I'm also using the gohack tool -- it manages the 'replace' lines in go.mod for you so imports will find your local version of a module even if it's not pushed to a server yet. There's otherwise nothing special about $devbase -- pointing it at $HOME/src should work just as well, for instance.

Answer 2

Apparently it has been fixed here https://github.com/golang/go/issues/33655

All I had to do was to upgrade go to version 1.14 and then running godoc in my directory with go modules works.

The godoc command should run in module mode whenever the go command runs in module mode. So godoc should run go env GOMOD with the same environment and working directory, and interpret the result.

If the result of go env GOMOD is an empty string, then GOPATH mode is being used, and godoc will behave the way it used to with GOPATH and it will only look in the GOPATH directory.