-- Leo's gemini proxy
-- Connecting to log.pfad.fr:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini; charset=utf-8
Solderpunk proposed an "OFFLine-FIRst SOftware CHallenge" for March, to develop and share some software which is offline-first:
> The spirit of OFFLFIRSOCH is to identify those tasks which you routinely use some online service for, not because the task is in any fundamental way one which needs to be done online, but just because that is the path of least resistance.
At first, I struggled to find any interesting project, then it hit me hard when I realized that vanitydoc was completely on the opposite side of "offline-first". Vanitydoc is a tool to generate static documentation for go modules, to be hosted at the import path URL.
I then realized that I could hack the newly introduced "local http documentation server" feature, to make it "useful offline as well", instead of always looking up the documentation on pkg.go.dev (since no one except me uses vanitydoc).
The first straightforward hack (without any code change) is to point the vanitydoc server to the stdlib folder (which is in the "src" subfolder of the "go env GOROOT" path). Once running, this gives a nice way to read the documentation of the standard library without going online.
go run code.pfad.fr/vanitydoc@latest $(go env GOROOT)/src # you can now visit http://localhost:8080/net/http#NewRequestWithContext # for the doc of net/http.NewRequestWithContext
This is already quite useful (and forced me to make some improvements to vanitydoc to be on par with pkg.go.dev), but we can go a step further.
All go modules that are used by local projects are cached locally. The location can be retrieved by running "go env GOMODCACHE". Inside this folder, there is a "cache/download" subfolder that contains all downloaded Go modules in zip files.
So I implemented a "-gomodcache" flag to serve the documentation of those modules, using the same URL structure as pkg.go.dev.
go run code.pfad.fr/vanitydoc@latest -gomodcache=$(go env GOMODCACHE) $(go env GOROOT)/src # you can now visit http://127.0.0.1:8080/code.pfad.fr/vanitydoc # for the doc of vanitydoc (the stdlib doc is still available, of course)
I then drafted a systemd service and socket files to automatically start the vanitydoc server on the first request on 127.0.103.111:80 (which I aliased to "pkg" in my hosts file). You can find it in the "contrib" folder (adjust the hard-coded folders to your needs).
So I can now visit http://pkg/code.pfad.fr/vanitydoc/ in my browser and see the documentation without needing an internet connection!
The Go language server gopls can display links to the documentation from within your editor. Unfortunately, it only allows the https:// scheme for now, so I raised an issue to allow the http:// scheme. And there I learned that the development version of gopls can already serve the documentation locally!
So from a utilitarian perspective, all of this was likely in vain (which should have been expected, given the name of the tool...). Anyway, I enjoyed the ride (and learned about the Go AST on the way), so thank you Solderpunk for the challenge!
PS: If anyone is still interested in vanitydoc, please let me know, so that I have an excuse to learn how to make a package (Arch Linux will likely be my first attempt, since I use it daily).
📅 2024-03-24
-- Response ended
-- Page fetched on Tue May 14 00:49:51 2024