pkg-doc auto-discovery

[abhinav]

The idea for this came from #73.

Go defines go-import meta tags for how to find a Go module, and go-source for how to link to the source code from pkg.go.dev if the host isn't a known host.

A similar go-doc tag could be standardized for alternative documentation sources used by the package, and could be used during cross-package linking. Even without support in the upstream pkgsite, this will be useful for users of doc2go to be able to specify where to find their static documentation.

All other details TBD.

[oliverpool]

~This is exactly the goal of https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/HEAD/RFC.md: add some <meta tags in the HTML of your package, so that compatible tools (like https://godocs.io/) can know where to look for the actual code source.~

Edit: Mis-read the comment :see_no_evil:

[abhinav]

Sorry, clarification: This one isn't for source code, but for Go documentation.

When you generate documentation with doc2go for example.com/foo/..., documentation for all types within foo/... will be in the same generated website, so it uses relative links for those. But if you have a type that references bar.Whatever defines in example.com/bar, it won't know how to link to example.com/bar. It defaults to pkg.go.dev as fallback, providing the -pkg-doc flag to override on a per-package basis. For example, if you're using doc2go or vanitydoc for example.com/bar, hosted at https://internal.mycompany/bar, then you can do -pkg-doc example.com/bar=https://internal.mycompany.bar/{{ ... }} when generating docs for foo/... to have that link generated correctly.

This issue is toying with the idea of auto-discovery on that end. It's possible that the meta tags you propose can be expanded to support documentation for specific symbols at specific import paths as well.

[oliverpool]

Oh yes, I mis-read your first post (my turn :smile: ).

A similar go-doc tag could be standardized.

Standardization would be nice, however I think having enough people take interest into that will be challenging (especially when "simply" prefixing the import-path with pkg.go.dev works 99% of the time).

I would be very interested for code editors to support this. In VSCode any "view doc" link (like the import path) points to pkg.go.dev. It would be interesting to know if the developers of the go extension might be interested by such a feature before implementing it.

[abhinav]

Standardization would be nice, however I think having enough people take interest into that will be challenging

Agreed. I think it's a long shot to get any upstream support for this (once there's actually a proposal, that is).

That said, even without standardization, I think this would be useful even if only doc2go supports it. Combined with #74, it would just work for public packages that use doc2go—without any configuration.