vanitydoc command

go install code.pfad.fr/vanitydoc@latest

vanitydoc generates go documentation as a static site (HTML and Gemtext). When served under the import path 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] <path>
# or using go run:     go run code.pfad.fr/vanitydoc@latest [flags] <path>
# or using nix flakes: nix run git+https://code.pfad.fr/vanitydoc [flags] <path>

If the <path> argument points to a folder (or is omitted), a local HTTP server will be started to render the documentation on demand of the given folder (or the current folder), taking into account the following flags:

-addr string
	listen address to expose the documentation (default "localhost:8080")
-gomodcache string
	path to the GOMODCACHE folder, for pkg.go.dev-like experience when giving the stdlib path as <path> argument
-html.template.pattern string
	pattern for additional HTML templates
-html.template.root string
	root folder of the additional HTML templates (default ".")
-modulePath string
	module path (will be read from <path>/go.mod if empty)

If the <path> argument points to a file (or "-" for stdin), the file is read as JSON, the configured modules are downloaded and their documentation generated.

Example to generate this documentation

The path to the JSON file containing the configuration should be given as argument to the executable. See the README for configuration reference.

{
	"defaults": { // allows to specify defaults for all "modules" below
		// forgejo, gitsrht, hgsrht 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"
	},

	"modules": {
		"vanitydoc": {}, // use all defaults for the module hosted at "{url_prefix}/vanitydoc"
		"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"
	},

	"max_conns_per_host": 3 // be nice with the forge when downloading module archives
}

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 default CSS styling is inspired by simple.css (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.

Source Files ¶

http.go ideas.go json.go main.go

Directories ¶

Forge ¶

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

https://codeberg.org/pfad.fr/vanitydoc.git
git@codeberg.org:pfad.fr/vanitydoc.git