tarampampam / urfave-cli-docs

📚 CLI usage docs generator (markdown)

CLI docs generator

⚠ This package is deprecated. Use urfave/cli/v3 instead.

For urfave-based applications.

$ go get gh.tarampamp.am/urfave-cli-docs@latest

Usage example

Add to your README.md file the following lines:

<!--GENERATED:CLI_DOCS-->
<!--/GENERATED:CLI_DOCS-->

Next, create a file generate_readme.go:

//go:build ignore
// +build ignore

package main

import (
	"os"

	"gh.tarampamp.am/urfave-cli-docs/markdown"

	"example"
)

func main() {
	var app = example.NewApp() // <-- your app here

	// generate markdown documentation for the app
	docs, err := markdown.Render(app)
	if err != nil {
		panic(err)
	}

	const readmeFilePath = "./readme.md"

	// read readme file
	readme, err := os.ReadFile(readmeFilePath)
	if err != nil {
		panic(err)
	}

	const start, end = "<!--GENERATED:CLI_DOCS-->", "<!--/GENERATED:CLI_DOCS-->"

	// replace the documentation section in the readme file
	updated, err := markdown.ReplaceBetween(start, end, string(readme), docs)
	if err != nil {
		panic(err)
	}

	// write the updated readme file
	if err = os.WriteFile(readmeFilePath, []byte(updated), 0664); err != nil {
		panic(err)
	}
}

Then, create a file generate.go for generating the documentation:

//go:build docs
// +build docs

package example

import _ "gh.tarampamp.am/urfave-cli-docs/markdown"

// Run using `go generate -tags docs ./...`

// Generate CLI usage documentation and write it to the README.md file (between special tags).
//go:generate go run generate_readme.go

And run code generation:

$ go generate -tags docs ./...

Viola! Now, open your readme file and watch the result. Example can be found here.