urfave_cli_docs

README

CLI docs generator

For urfave-based applications.

$ go get github.com/tarampampam/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 docs
// +build docs

package main

import (
	"os"

	"github.com/tarampampam/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:

package example

// 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.

Documentation

Index

• func PrepareMultilineString(s string) string
• type App
  • func NewApp(app *cli.App, appPath string) App
• type Command
  • func PrepareCommands(commands []*cli.Command, appPath, parentCommandName string, level uint) []Command
• type Flag
• type Flags
  • func PrepareFlags(flags []cli.Flag) Flags

Functions

func PrepareMultilineString

func PrepareMultilineString(s string) string

PrepareMultilineString prepares a string (removes line breaks).

Types

type App

type App struct {
	AppPath                     string
	Name                        string
	Usage, UsageText, ArgsUsage string
	Description                 string
	GlobalFlags                 Flags
	Commands                    []Command
}

func NewApp

func NewApp(app *cli.App, appPath string) App

NewApp creates a new App struct.

type Command

type Command struct {
	AppPath                     string
	Name                        string
	Aliases                     []string
	Usage, UsageText, ArgsUsage string
	Description                 string
	Category                    string
	Flags                       Flags
	SubCommands                 []Command
	Level                       uint
}

func PrepareCommands

func PrepareCommands(commands []*cli.Command, appPath, parentCommandName string, level uint) []Command

PrepareCommands converts CLI commands into a structs for the rendering.

type Flag

type Flag struct {
	Name       string
	Aliases    []string
	Usage      string
	TakesValue bool
	Default    string
	EnvVars    []string
}

type Flags

type Flags []Flag

func PrepareFlags

func PrepareFlags(flags []cli.Flag) Flags

PrepareFlags converts CLI flags into a structs for the rendering.