Self-hosting go documentation on vanity URL

December 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.

Introducing vanitydoc

code.pfad.fr/vanitydoc

The vanitydoc command has the following features:

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:

code.pfad.fr/risefront

code.pfad.fr/risefront

godocs.io/code.pfad.fr/risefront

https://codeberg.org/pfad.fr/risefront

Basic usage

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

Requirements

Future work

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:

Feel free to send a patch on codeberg or by email to contribute to this package (licensed under BSD-3-Clause)!