vanitydoc

Documentation

Overview

vanitydoc generates go documentation as a static site (HTML and Gemtext). When hosted at the package URL, it makes the package importable by the Go tools ("vanity import path").

For instance the import path for this command is code.pfad.fr/vanitydoc and the documentation is hosted at the following URL: https://code.pfad.fr/vanitydoc

Usage:

vanitydoc { [flags] | <jsonPath> }
# or using go run:     go run code.pfad.fr/vanitydoc@latest { [flags] | <jsonPath> }
# or using nix flakes: nix run git+https://code.pfad.fr/vanitydoc { [flags] | <jsonPath> }

If no jsonPath argument is provided, a local HTTP server will be started to render the documentation on demand, taking into account the following flags:

-addr string
	listen address to expose the documentation (default "localhost:8080")
-html.template.pattern string
	Pattern for additional HTML templates
-html.template.root string
	Root folder of the additional HTML templates (default ".")
-moduleDir string
	Local path to the module to generate the documentation for (default ".")
-modulePath string
	Module path (will be read from go.mod if empty)

If a jsonPath argument is provided, the given modules will be downloaded and their documentation generated.

Example to generate this documentation

{
	"domain": "code.pfad.fr",

	"defaults": { // allows to specify defaults for all "modules" below
		// forgejo, gitsrht and github are supported
		"type": "forgejo",

		// the module name will be appended to construct the forge url
		"url_prefix": "https://codeberg.org/pfad.fr/",
		"default_branch": "main"
	},
	"max_conns_per_host": 3, // be nice with the forge when downloading archives

	"modules": {
		"vanitydoc": {}, // use all defaults for the "{domain}/vanitydoc" module
		"risefront": {
			"ref": "v1.0.0" // specify the ref to retrieve for this module
		},
		"fluhus/godoc-tricks": {
			"type": "github",
			"url": "https://github.com/fluhus/godoc-tricks",
			"default_branch": "master",
			"ref": "master",

			// github tweak to download the archive of a branch
			// (use "tags/" when "ref" is a tag)
			"archive_ref_prefix": "heads/"
		},
		"exp": {
			"type": "gitsrht",
			"url": "https://git.sr.ht/~oliverpool/exp"
		}
	},

	"html": {
		"output": "dist/http",

		// you can add your templates to customize the HTML
		"template.pattern": "header.gohtml",
		"first_clone_url_info_refs_path": "info/refs.redirect"
	},
	"gemtext": {
		"output": "dist/gmi"
	}
}

License and credits

Code is available under the BSD-3-Clause license.

Most of the templates originate from gddo (available under BSD-3-Clause). The CSS styling is achieved using simple.css by default (available under MIT). go-import meta tag as well as the meta tags proposed by the VCS Autodiscovery RFC are included in the HTML output.