docs

README

Welcome to urfave/cli-docs/v3

urfave/cli-docs/v3 is an extended documentation library for use with urfave/cli/v3.

Start using

1. Add the dependency to your project

 go get github.com/urfave/cli-docs/v3@latest

1. Add it as import

 import (
+  docs "github.com/urfave/cli-docs/v3"
 )

1. Now use it e.g. to generate markdown document from a command

package main

import (
    "context"
    "fmt"
    "os"

    docs "github.com/urfave/cli-docs/v3"
    cli "github.com/urfave/cli/v3"
)

func main() {
    app := &cli.Command{
        Name:  "greet",
        Usage: "say a greeting",
        Action: func(ctx context.Context, c *cli.Command) error {
            fmt.Println("Greetings")
            return nil
        },
    }

    md, err := docs.ToMarkdown(app)
    if err != nil {
        panic(err)
    }

    fi, err := os.Create("cli-docs.md")
    if err != nil {
        panic(err)
    }
    defer fi.Close()
    if _, err := fi.WriteString("# CLI\n\n" + md); err != nil {
        panic(err)
    }
}

This will create a file cli-docs.md with content:

# CLI

# NAME

greet - say a greeting

# SYNOPSIS

greet

**Usage**:

```
greet [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]
```

Examples

Some examples of the cli generated using this markdown

• https://woodpecker-ci.org/docs/cli

Documentation

Index

• Variables
• func ToJSON(cmd *cli.Command) ([]byte, error)
• func ToMan(cmd *cli.Command) (string, error)
• func ToManWithSection(cmd *cli.Command, sectionNumber int) (string, error)
• func ToMarkdown(cmd *cli.Command) (string, error)
• func ToTabularMarkdown(cmd *cli.Command, appPath string) (string, error)
• func ToTabularToFileBetweenTags(cmd *cli.Command, appPath, filePath string, startEndTags ...string) error
• type CLICommand
• type CLIFlag

Variables

var (
	//go:embed markdown.md.gotmpl
	MarkdownDocTemplate string

	//go:embed markdown_tabular.md.gotmpl
	MarkdownTabularDocTemplate string
)

Functions

func ToJSON

func ToJSON(cmd *cli.Command) ([]byte, error)

func ToMan

func ToMan(cmd *cli.Command) (string, error)

ToMan creates a man page string for the `*cli.Command` The function errors if either parsing or writing of the string fails.

func ToManWithSection

func ToManWithSection(cmd *cli.Command, sectionNumber int) (string, error)

ToMan creates a man page string with section number for the `*cli.Command` The function errors if either parsing or writing of the string fails.

func ToMarkdown

func ToMarkdown(cmd *cli.Command) (string, error)

ToMarkdown creates a markdown string for the `*cli.Command` The function errors if either parsing or writing of the string fails.

func ToTabularMarkdown

func ToTabularMarkdown(cmd *cli.Command, appPath string) (string, error)

ToTabularMarkdown creates a tabular markdown documentation for the `*cli.Command`. The function errors if either parsing or writing of the string fails.

func ToTabularToFileBetweenTags

func ToTabularToFileBetweenTags(cmd *cli.Command, appPath, filePath string, startEndTags ...string) error

ToTabularToFileBetweenTags creates a tabular markdown documentation for the `*App` and updates the file between the tags in the file. The function errors if either parsing or writing of the string fails.

Types

type CLICommand

type CLICommand struct {
	Name        string       `json:"name"`
	Aliases     []string     `json:"aliases,omitempty"`
	Usage       string       `json:"usage,omitempty"`
	UsageText   []string     `json:"usageText,omitempty"`
	Description string       `json:"description,omitempty"`
	ArgsUsage   string       `json:"argsUsage,omitempty"`
	Category    string       `json:"category,omitempty"`
	Version     string       `json:"version,omitempty"`
	Hidden      bool         `json:"hidden,omitempty"`
	Flags       []CLIFlag    `json:"flags,omitempty"`
	Commands    []CLICommand `json:"commands,omitempty"`
}

type CLIFlag

type CLIFlag struct {
	Name       string   `json:"name"`
	Aliases    []string `json:"aliases,omitempty"`
	Usage      string   `json:"usage,omitempty"`
	Type       string   `json:"type,omitempty"`
	Default    string   `json:"default,omitempty"`
	TakesValue bool     `json:"takesValue"`
	EnvVars    []string `json:"envVars,omitempty"`
	Hidden     bool     `json:"hidden,omitempty"`
	Required   bool     `json:"required,omitempty"`
}