cdocs

cdocs - urfave/cli/v2 docs extension

This is an enhanced version of the ToMarkdown and ToMan methods for https://github.com/urfave/cli/v2.

cdocs also provides a helper command InstallManpageCommand that will generate a CLI command to install a man page to the system for the CLI tool.

Key differences are:

• Addition of a Table of Contents with working markdown links.
• UsageText included in generated doc files.
• InstallManpageCommand helper command.

Examples:

• gwsm
• gwvault
• gw-aws-audit

Usage

package main

import (
	"fmt"
	"log"
	"os"
	"time"

	"github.com/clok/cdocs"
	"github.com/urfave/cli/v2"
)

func main() {
	im, err := cdocs.InstallManpageCommand(&cdocs.InstallManpageCommandInput{
		AppName: "demo",
	})
	if err != nil {
		log.Fatal(err)
	}

	app := &cli.App{
		Name:     "demo",
		Version:  "0.0.1",
		Compiled: time.Now(),
		Authors: []*cli.Author{
			{
				Name:  "John Doe",
				Email: "j@doe.com",
			},
		},
		HelpName:             "demo",
		Usage:                "a demo cli app",
		EnableBashCompletion: true,
		Commands: []*cli.Command{
			{
				Name:  "s3",
				Usage: "simple S3 commands",
				Subcommands: []*cli.Command{
					{
						Name:      "get",
						Usage:     "[object path] [destination path]",
						UsageText: "it's going to get an object",
						Action: func(c *cli.Context) error {
							fmt.Println("get")
							return nil
						},
					},
				},
			},
			im,
			{
				Name:    "version",
				Aliases: []string{"v"},
				Usage:   "Print version info",
				Action: func(c *cli.Context) error {
					fmt.Println("version")
					return nil
				},
			},
		},
	}

	if os.Getenv("DOCS_MD") != "" {
		docs, err := cdocs.ToMarkdown(app)
		if err != nil {
			panic(err)
		}
		fmt.Println(docs)
		return
	}

	if os.Getenv("DOCS_MAN") != "" {
		docs, err := cdocs.ToMan(app)
		if err != nil {
			panic(err)
		}
		fmt.Println(docs)
		return
	}

	err = app.Run(os.Args)
	if err != nil {
		log.Fatal(err)
	}
}

Development

1. Fork the clok/cdocs repo
2. Use go >= 1.16
3. Branch & Code
4. Run linters 🧹 golangci-lint run
   • The project uses golangci-lint
5. Commit with a Conventional Commit
6. Open a PR