I'm missing godoc for local packages after converting to modules.

[Hotei]

Could use a little help figuring out how to attack the following problem:

I normally run godoc locally with $godoc -http=":6060"& and then browse it with chrome. 

 Many years ago that method broke for a while as godoc was "reinvented" but then it came back pretty much the same as before.  A few weeks ago I converted a lot of old code to use modules.  Now that I've converted my local packages tree to modules I find that the same godoc code I've been using with no problem  before can only find the packages in the official source 1.16.* tree.  I don't know if this is a bug or a feature but if possible I'd like to find a way so that the old method still works.  Is there a work-around?  Sorry if this ground has been covered before. There's no error message to reference, just the absence of my source  (and that of others from golang.org, github.com etc) in the listing.  It's possible I'm not using the latest & greatest godoc but it has moved around a bit the last few years so I'm not 100% sure what the canonical version is right now.  Any help appreciated.  I also wish godoc handled programs (as opposed to just packages) but I can work around that where necessary.  Thanks in advance.

David

[Kurtis Rader]

On Sat, Mar 27, 2021 at 4:55 PM Hotei <hote...@gmail.com> wrote:

Could use a little help figuring out how to attack the following problem:

I normally run godoc locally with $godoc -http=":6060"& and then browse it with chrome. 

 Many years ago that method broke for a while as godoc was "reinvented" but then it came back pretty much the same as before.  A few weeks ago I converted a lot of old code to use modules.  Now that I've converted my local packages tree to modules I find that the same godoc code I've been using with no problem  before can only find the packages in the official source 1.16.* tree.  I don't know if this is a bug or a feature but if possible I'd like to find a way so that the old method still works.  Is there a work-around?  Sorry if this ground has been covered before. There's no error message to reference, just the absence of my source  (and that of others from golang.org, github.com etc) in the listing.  It's possible I'm not using the latest & greatest godoc but it has moved around a bit the last few years so I'm not 100% sure what the canonical version is right now.

I use golang.org/x/tools/cmd/godoc, documentation at https://pkg.go.dev/golang.org/x/tools/cmd/godoc. AFAIK that is the canonical version. It honors the GOPATH env var.

On my system I set that to ~/go and the godoc server shows me all the packages anchored below $GOPATH/src as well as the Go stdlib. I don't know how, or even if it is possible, to have a single godoc server handle multiple modules anchored outside of the GOPATH directory. In fact, just setting GOPATH to the root of a Go project outside of the usual GOPATH directory, and which uses modules, causes the godoc server to complain and not serve any documentation for the project. Also, rather annoyingly, you can't just create a symlink from $GOPATH/src/whatever to the actual directory containing the project. That is, godoc doesn't appear to honor symlinks in $GOPATH/src. I had to actually copy one of the projects I work on whose source is not beneath $GOPATH/src rather than create a symlink to it. That seems like a bug to me; even if you ignore that having to create a symlink in the first place is undocumented.

--

Kurtis Rader

Caretaker of the exceptional canines Junior and Hank

[Kevin Chadwick]

I found you had to cd to each directory with a .mod file and run it there. A global option would be nice to know about.

[Hotei]

Clarification.  As mentioned earlier, $GOPATH is supposed to go away in the (possibly near) future so one of my main goals is to get it working outside the $GOPATH tree.  At present my solution has been to copy my source tree (about 4 GB) to a "non-module-aware" go ecosystem on a different machine and browse over my local network to the old godoc version there.    While it works (for the moment) it's not a very efficient or maintainable solution.  The possibility of easy to maintain documentation has always been one of go's strengths thanks to gofmt and godoc.  Hate to lose half that advantage if there's a way around it.

David Rook

[Sean Liao]

Assuming a recent enough version of `godoc`, running it from within a module should include the documentation for the standard library (standard library section), that module, and all its dependencies (third party section)

Expected output should be similar to:

$ godoc

using module mode; GOMOD=/home/arccy/testrepo-337/go.mod

It doesn't handle documentation across multiple, unrelated modules, but you could work around it by defining a dummy package & module with imports to the modules you wish to include (use replace to point to the local version) and running `godoc` from the dummy module

[Hotei]

Thanks to all for assistance with this!

 

Got it working with (perhaps) the most recent version - though once again it looks to have moved from the path(s) mentioned above.  Part of my problem was not looking specifically for the "Third Party" section since before my code had all been lumped in at the top with the standard library sections.  That's an improvement I agree.  Also not mentioned specifically is there exist both a package and a command by the name godoc.  You need to compile them separately - paying attention to the need to "go generate" the static section of the package first.  It had been a while since I last had to do this so it took awhile to (re)discover the secret sauce ingredients.

While I'm still hoping to eventually see programs added to the godoc feature set I'm at least back to where we were before I started the module experiment.  So far it looks like a pretty straight forward - though a bit labor intensive in my case.

David