6

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.

Community
  • 1
  • 1
Jonah
  • 15,806
  • 22
  • 87
  • 161
  • 3
    `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`. – icza May 27 '19 at 21:30
  • @icza Thanks. I tried `http://localhost:6060/pkg/gonotes` and got `cannot find package "." in: /src/gonotes`. Do I need to put my source files under `src`? Currently they're just in in the folder `gonotes`, as you can see from the terminal session I included in the OP. – Jonah May 27 '19 at 22:44
  • For that to work, your `gonotes` package would have to be inside `GOPATH/src/gonotes`. – icza May 28 '19 at 07:24
  • You can't just put your Go code into arbitrary folders. You must follow the `GOPATH` convention, for details, see [How to Write Go Code](https://golang.org/doc/code.html). – icza May 28 '19 at 09:36
  • 1
    @icza isn’t this the whole point of using go modules? so you aren’t bound to GOPATH? – Jonah May 28 '19 at 11:36
  • Not the whole point, but yes, if using modules, you don't have to use `GOPATH` (you didn't mention modules before though). But then why are you setting `GOPATH`? `GOPATH` and modules are _mutually exclusive_, see [Go Modules does not recognize files under GOPATH](https://stackoverflow.com/questions/55650450/go-modules-does-not-recognize-files-under-gopath/55650622#55650622). The `godoc` tool is not module-aware, and it is being deprecated, so for now if you want to see your package docs locally in `godoc`, you have to resort to putting their sources in an `src` folder. – icza May 28 '19 at 12:04
  • This comment is the answer to my question. Feel free to add as a proper answer. – Jonah May 28 '19 at 12:15

1 Answers1

10

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 module's:

  • 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'?

icza
  • 389,944
  • 63
  • 907
  • 827