go/doc: cross-package doc links don't work

[randall77]

If I change the doc string of (*bytes.Buffer).ReadFrom from containing io.EOF to containing [io.EOF], I expect godoc to render that with an appropriate clickable link to the documentation for io.EOF.

It renders a link but the link doesn't work. When running godoc locally on :6060, the link is http://localhost:6060/io#EOF when it should be http://localhost:6060/pkg/io#EOF.

This page (the Doc links section) says it should work. In fact, this is the exact example shown for this feature.

Intra-package doc links seem to work.

@rsc

[seankhliao]

This is a difference between url paths used by pkgsite vs godoc (which was deprecated some time ago). Note the server referenced in the second paragraph of the linked doc is pkgsite

[randall77]

I cannot figure out how to run pkgsite using my local filesystem as the source for the stdlib. When I ask for the docs for a stlib package, pkgsite downloads the stdlib from std@latest, which I guess is tip. How do I convince it to show me the docs for a CL I'm working on?

[cespare]

@randall77 reading https://pkg.go.dev/golang.org/x/pkgsite/cmd/pkgsite it sounds like pointing the -gorepo flag at your repo might work? (I haven't tried.)

[randall77]

That didn't work, unfortunately.

[seankhliao]

cc @jba

[cespare]

I think the pkgsite issue is #57742.

I ran into the godoc bug too just now. Since pkgsite is such a poor replacement for godoc for local/private usage, perhaps we should undeprecate it (#50229) and fix bugs like this.

[gopherbot]

Change https://go.dev/cl/477335 mentions this issue: godoc: fix cross-package doc links

[navytux]

I also use godoc to browse local code with pre-published edits and hit this issue. As https://github.com/golang/go/issues/59056 suggest I tried to use pkgsite instead and it still does not work as flawlessly as godoc for local use case.

@aarzilli, thanks for your patch at https://go.dev/cl/477335. I refreshed it to be applicable to recent x/tools as

--- a/godoc/godoc.go
+++ b/godoc/godoc.go
@@ -348,7 +348,10 @@ func isDigit(ch rune) bool {
 func comment_htmlFunc(info *PageInfo, comment string) string {
        // TODO(gri) Provide list of words (e.g. function parameters)
        //           to be emphasized by ToHTML.
-       return string(info.PDoc.HTML(comment))
+       pkg := info.PDoc
+       p := pkg.Printer()
+       p.DocLinkBaseURL = "/pkg"
+       return string(p.HTML(pkg.Parser().Parse(comment)))
 }

 // sanitizeFunc sanitizes the argument src by replacing newlines with

and it works just ok - the links to other packages now work well.

Is there any reason why the fix in https://go.dev/cl/477335 was not considered to be merged?

[jba]

Is there any reason why the fix in https://go.dev/cl/477335 was not considered to be merged?

We're just behind on pksite fixes.