Self-hosting go documentation on vanity URLDecember 2, 2022 on Olivier's log
Go packages are identified by their import path. This import path usually starts with the URL where the code is hosted, but it can also be another domain which informs the go tool where the actual code can be downloaded (so-called "vanity import paths"). Using a domain you control is great because it allows for the code fo be moved between software forges without any disruption for people using the package.
There are already a couple of packages able to automatically generate html with the right meta tags:
4d63.com/vangen (static html, with links to repo and doc)
code.rocketnine.space/tslocum/godoc-static (static godoc)
go.yhsif.com/vanity (redirects to pkg.go.dev)
kkn.fi/vanity (redirects to pkg.go.dev)
However I wasn't delighted with any of those solutions, so I developped my own.
The vanitydoc command has the following features:
- static generation of HTML
- inclusion of the `go-import` meta tags (obviously)
- dark and light theme
- static gemeration of Gemtext (for gemini hosting)
- inclusion of the `VCS Autodiscovery` meta tags
The last point is a RFC which aims at increasing interoperability between software forges and third party tool:
VCS Autodiscovery RFC
To show an example of interoperability, consider one of my other package:
- its import path is a vanity URL, which is a static site serving the latest documentation of the package (accessible via https and gemini protocols thanks to sourcehut pages)
- the presence of the meta tags, allows godocs.io (alternative to pkg.go.dev) to generate links to the source code
- while the actual source code is hosted on codeberg
To generate the documentation for a module, simply list the packages using `go list -json` and pipe them to `vanitydoc`:
go list -json="Dir,ImportPath,Doc,Module" ./... | \ go run code.pfad.fr/vanitydoc@latest -html=dist/html -gemtext=dist/gmi gitea://codeberg.org/pfad.fr/risefront
- The package requires go 1.19 for compilation (it uses the new go/doc package)
I am currently happy of this package and plan to use it as-is. It could be improved in multiple ways, however I didn't find an elegant solution to the following problems yet:
- Listing the packages currently requires the go toolchain. Figure out a way to compile "go list" inside the package.
- The generated documentation is for the current build tags. Generate all sets of builds tags under specific URLs.
- Document the version which was used to generate the documentation (golang.org/x/tools/go/vcs package is missing cmd/go/internal/vcs.Cmd.Status)
Feel free to send a patch on codeberg or by email to contribute to this package (licensed under BSD-3-Clause)!