CODEWITHSUNDEEP
go
Jonah
Jonah

Reputation: 16222

View package documentation locally in a browser

I want to see locally how my package documentation will look. That is, I want to see the same kind of thing you see on godoc.org, but locally.

I have a simple example folder locally, but I can't get it to work. It correctly outputs text documentation:

~/code/go/gonotes (master) $ godoc .
PACKAGE DOCUMENTATION

package gonotes
    import "."


FUNCTIONS

func Blah()
    Here is header

    Blah is function being use to test:

    - go documentation
    - blah like things

    It is nice

But if I run godoc -http=:6060, and navigate to http://localhost:6060/, I see essentially the same content I'd see on the golang.com homepage. http://localhost:6060/gonotes displays

lstat $GOROOT/gonotes: no such file or directory

Am I misunderstanding how the -http works? Is there any way to preview the http version of my docs locally?

UPDATE

I was able to get it to appear by copying the files into src/gonotes and then running:

GOPATH=/Users/jonah/code/go/gonotes godoc -http=:6060

so that the actual files were available at /Users/jonah/code/go/gonotes/src/gonotes.

This has the side effect of not showing any of the Third part libs installed in my default GOPATH, so I'd still like to find a solution that just allows me to add the current directory, as is, without adding src/curdir to it, and still have it show up.

Upvotes: 6

Views: 6384

Answers (3)

Waylander
Waylander

Reputation: 746

godoc is deprecated since 2021. This deprecation coincided with the migration from godoc.org to pkg.go.dev. Godoc does not support various documentation features and has lacking go module/workspace support and should not be used.

pkgsite is now used. In a single command, you can have your very own local pkg.go.dev documentation server running:

$ go run golang.org/x/pkgsite/cmd/pkgsite@latest -open

This will generate the documentation for the packages found in the current directory and open the documentation website in the browser. This will look similar to this:

Page that will be opened with search field and list of local packages

Either click on the links beneath the search field or search for the package you want to view the documentation of.

If you want to serve a specific module's documentation, add the path as an argument.

As an alternative to go run, you can install the pkgsite program:

$ go install golang.org/x/pkgsite/cmd/pkgsite@latest
$ pkgsite -open

Upvotes: 3

icza
icza

Reputation: 418087

In GOPATH mode

godoc -http will serve doc of all available packages, including the standard library. Worry not, your own packages are amongst them, just look again. As a shortcut, just type http://localhost:6060/pkg/your/package.

In module-aware mode

GOPATH and modules are mutually exclusive, see Go Modules does not recognize files under GOPATH. The godoc tool is not module-aware, and it is being deprecated (see deprecation warning), so for now if you want to see your package docs of modules locally in godoc, you have to resort to putting their sources in an src folder.

"Workaround" for seeing docs of modules:

  • Put the repo in a folder like /some/folder/src

  • Start godocs with godoc -goroot=/some/folder -http=:6060

See related issue: support Go modules

Also groups discussion: Is the go 1.11 godoc tool 'module-aware'?

Upvotes: 10

Larry Clapp
Larry Clapp

Reputation: 119

In 2024, to use godoc in GOPATH mode, that is, make it serve both stdlib from $GOROOT and also whatever's under $GOPATH, you have to explicitly turn off module mode:

GO111MODULE=off godoc -http=:6060

Upvotes: 1

Related Questions