search

golang / gddo

Go Doc Dot Org
https://godoc.org
BSD 3-Clause "New" or "Revised" License
1.1k stars 265 forks source link

support Go modules #567

Open hajimehoshi opened 6 years ago

hajimehoshi commented 6 years ago

For example, I'd like to see https://godoc.org/github.com/hajimehoshi/vgotest/v2 available.

tav commented 6 years ago

It'd be great to have basic support for Go modules, so that if anyone goes to the GitHub version of docs for a repo which is using vanity import paths, e.g. https://godoc.org/github.com/peerbase/peerbase/bytesize, it would try to read a go.mod file at the repo root, and redirect to that subpath on godoc.org instead, i.e. https://godoc.org/peerbase.net/go/bytesize ?

This should prevent people from seeing the non-canonical docs and import paths when projects have stopped using canonical import comments...

DeedleFake commented 6 years ago

It would also be nice if the interface said what version it was displaying docs for, possibly with the ability to pull up the docs for specific versions as well.

izgeri commented 5 years ago

I would love to be able to build / view godocs interactively locally. Since we moved to using Go modules, my github repo is no longer in my GOROOT or GOPATH, but I want to be able to call godoc -http=:6060 from my source dir and have it generate godocs.

The workaround right now appears to be:

and then it "works". It would be great if it could just work from the dir I'm in without this hack.

Or maybe this comment belongs in golang/go#26827

urandom2 commented 5 years ago

@izgeri

Considering the deprecation warning on godoc, you may consider avoiding it.

@dmitris

Has this feature been assigned or would you all be interested in community assistance[0] in design/implementation? I would imagine the community would like this to close before the 1.13 release.

Questions

Version

Should packages display the value that customers would expect to see in a go.mod and where should this go?

Do we need to show docs for old version? This will be harder, and should be unnecessary if semver is used correctly.

Prefetch

Since modules are atomic units, should we fetch all the packages and preload them into redis?

Segmentation

We should be able to break this work up by VCS provider to prevent a massive CL, so as long as there are no breaking changes. However deploy ought block till they are all ready, to provide a unified UX to consumers.

Timeline

Is it required to get this by the 1.13 drop?

Libraries

Should we vendor the stdlib module code, reimplement what we need, or consume from somewhere else?

Replace

Should replace directives modify import links?

Module

Should we display the go.mod or go.sum data? Should this be a new section at the module root? Should this be a section inside every package?

0] For clarity, yes I am offering.

dolmen commented 5 years ago

@arnottcr

I would imagine the community would like this to close before the 1.13 release.

dolmen commented 5 years ago

I have a Go module that has gone to v2 and it now appears on godoc.org with an incorrect import path that doesn't contain v2: https://godoc.org/github.com/blueboardio/cldr

nicksnyder commented 5 years ago

https://godoc.org/github.com/nicksnyder/go-i18n just released v2 and has similar problems.

Sean-Der commented 5 years ago

This hit Pion as well

@dmitshur it looks like godoc isn't maintained. Is this on any Go team internal roadmaps at all? I would be happy to help with this.

I don't want my work to get thrown away if someone else already plans to do this.

darkfeline commented 5 years ago

Another bit of missing support: it seems that gddo does not support this in go help importpath:

When using modules, an additional variant of the go-import meta tag is
recognized and is preferred over those listing version control systems.
That variant uses "mod" as the vcs in the content value, as in:

    <meta name="go-import" content="example.org mod https://code.org/moduleproxy">

This tag means to fetch modules with paths beginning with example.org
from the module proxy available at the URL https://code.org/moduleproxy.
See 'go help goproxy' for details about the proxy protocol.
dmitshur commented 5 years ago

@Sean-Der The current godoc.org website supports Go packages that are functional in GOPATH mode. As you pointed out, if a package is available only in module mode but not in GOPATH mode, it won't show up on godoc.org.

It was mentioned in the https://blog.golang.org/modules2019 blog post (in the Module Discovery section), we are working on a new discovery site that has been designed with version support in mind and will be able to display documentation for packages that are available only in module mode.

@julieqiu gave a "Finding Dependable Go Packages" talk at GothamGo 2019 (video, slides) that discusses an aspect of the discovery site, and it included some early mockups of the discovery site at the end. You can see them starting with slide 92.

It will also support the "mod" VCS type that @darkfeline mentioned above.

Sean-Der commented 5 years ago

Fantastic, that is really exciting! Those wireframes look great.

thanks for the inside scoop @dmitshur that information is super helpful for everyone here :)

firelizzard18 commented 4 years ago

From @julieqiu's slides, subscribe to golang/go#33654 for updates and go to https://golang.org/s/discovery-tester-signup to try it out.