vanitydoc command - code.pfad.fr/vanitydoc
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]
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].
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"
},
"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 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.
gddo
simple.css
go-import
VCS Autodiscovery RFC
Files
http.go
ideas.go
json.go
main.go
Directories
autodiscovery
package autodiscovery is an implementation of the [VCS Autodiscovery RFC].
template
package template generates documentation for a given package.
Forge
https://codeberg.org/pfad.fr/vanitydoc
git clone
https://codeberg.org/pfad.fr/vanitydoc.git
git@codeberg.org:pfad.fr/vanitydoc.git