search

abhinav / doc2go

Your Go project's documentation, to-go.
https://abhinav.github.io/doc2go
Apache License 2.0
83 stars 5 forks source link

Source linking #73

Open abhinav opened 1 year ago

abhinav commented 1 year ago

We should add opt-in support for linking to source code for a package. This will likely need a -pkg-doc-style thing for documentation generated from multiple repositories, but it also needs an easy way for common cases where the code is hosted in a GitHub/GitLab/SourceHut/etc. repository.

Related: https://github.com/golang/gddo/wiki/Source-Code-Links https://pkg.go.dev/about#source-links

oliverpool commented 7 months ago

I just found out about this great project!

I developed something similar myself https://code.pfad.fr/vanitydoc/ (however the scope of my tool is much much smaller than yours).

For source-code linking, I based my logic on https://git.sr.ht/~ancarda/vcs-autodiscovery-rfc/tree/HEAD/RFC.md and exported a dedicated package: https://code.pfad.fr/vanitydoc/autodiscovery/

Maybe it can serve as inspiration for your tool.

maxatome commented 6 months ago

Hi,

perhaps something like:

-pkg-src-link auto|PACKAGE=URL_TMPL

multiple -pkg-src-link occurrences may be passed. If at least one -pkg-src-link auto occurs and an encountered package does not match any -pkg-src-link PACKAGE=… then the URL is built from a generic template handling GitHub/GitLab/SourceHut/etc.

URL_TMPL should use the following vars:

Pitfall: passed PACKAGEs can overlap, so each encountered package has to match the longest PACKAGE.

doc2go -pkg-src-link aaa/bbb/ccc=http://A… -pkg-src-link aaa/bbb=http://B…

aaa/bbb/ccc/ddd → in aaa/bbb/ccc → http://A…
aaa/bbb/eee     → in aaa/bbb     → http://B…
abhinav commented 6 months ago

Thanks @oliverpool, I intend to look at that when I implement this. Auto-discovery does sound quite nice from the UX POV, but I also don't want network requests to be the default. It may have to be an opt-in.

@maxatome, that is along the lines of what I was thinking for this feature! doc2go already has a -pkg-doc flag that follows a similar pattern.

The template will probably also want a variable for import path of the file package relative to the PACKAGE specified in PACKAGE=TMPL. This would allow something like -pkg-src example.com/foo='https://github.com/example/foo-go/blob/{{.PackageRelativePath}}/{{.File}} (or whatever form GitHub takes). I was planning for the variables to take inspiration from how go-source links are specified in meta tags, and perhaps with built-in support for GitHub, GitLab, SourceHut, etc.

Pitfall: passed PACKAGEs can overlap, so each encountered package has to match the longest PACKAGE.

Not a concern! doc2go already implements that for pkg-doc. It's quite straightforward: given import path aaa/bbb/ccc/ddd, pick the closest ancestor with a template specified.

All that said, I don't have an immediate prediction for when this functionality will be available. It'll happen when free time and inspiration align—or if someone else is willing to contribute it.

oliverpool commented 6 months ago

but I also don't want network requests to be the default

The code.pfad.fr/vanitydoc/autodiscovery/ package does not do any network request. It simply stores the standard URL for well-known forges:

vcs, err := autodiscovery.New("github", "https://github.com/abhinav/doc2go", "main")
vcs.LineURL(path, ref, line) // gives you the URL to view the given file at the given line
abhinav commented 6 months ago

Oh, excellent! That fills in the "built-in support for GitHub, GitLab, SourceHut, etc." bit above. I'm sorry, I must've misread the RFC—I saw the meta tags mentioned and I assumed "oh, so this has to make requests to get this information, similarly to go-source/go-import meta tags."

oliverpool commented 6 months ago

Yes, I mis-explained it: those meta tags should be exposed by doc2go (and can be consumed by other tools). But you can also use the value of those tags to also make a link to the source code directly (that's at least how I do it in vanitydoc :)