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?

Euglena

"not Go modules aware" meaning what exactly? Modules have no impact on documentation. What do you expected it to be "aware" of in regarding to modules? – Jeanmariejeanna

I expected it to generate documentation for Go packages managed with Go modules outside of the GOPATH. – Hoodlum

GOROOT and GOPATH aren't the same. You shouldn't be pointing -goroot at your source. GOROOT should be pointing at your Go installation. Also to the last part of your question, requests for third-party tools and libraries are off-topic for Stack Overflow. – Jeanmariejeanna

Related comments on Github: github.com/golang/go/issues/26827#issuecomment-429315761. That appears to be the issue tracking this (as yet unavailable) feature. See also github.com/golang/go/issues/25443#issuecomment-474553586. – Coterminous

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.

Mas

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.

Macknair