-- Leo's gemini proxy
-- Connecting to log.pfad.fr:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini; charset=utf-8
> I updated this post after updating large parts of vanitydoc (it can now serve the documentation of the current module and generate static files of multiple modules at once).
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 that 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 to 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:
However I wasn't delighted with any of those solutions, so I developed 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 generation of Gemtext (for gemini hosting)
inclusion of the `VCS Autodiscovery` meta tags
The last point is an RFC that aims at increasing interoperability between software forges and third-party tools:
To show an example of interoperability, consider one of my other packages:
code.pfad.fr/risefront
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 preview the documentation of the module of the current folder, simply run `vanitydoc` (it does not rely on `go list` since March 2023):
go run code.pfad.fr/vanitydoc@latest
To generate the static files, a JSON file must be prepared. Its format is documented in the README:
The package requires go 1.19 for compilation (it uses the new go/doc package)
I am currently happy with this package and plan to use it as-is. It could be improved in multiple ways, however, I havn't found 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 (done in March 2023).
The generated documentation is for the current build tags. Generate all sets of build tags under specific URLs.
Document the version that 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)!
📅 2022-12-02
-- Response ended
-- Page fetched on Tue May 14 20:09:09 2024