cdocs

README

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

Documentation

Overview

Example

im, err := InstallManpageCommand(&InstallManpageCommandInput{
	AppName: "demo",
})
if err != nil {
	panic(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
			},
		},
	},
}

md, _ := ToMarkdown(app)
fmt.Println(md)

man, _ := ToMan(app)
fmt.Println(man)

Index

• func InstallManpageCommand(opts *InstallManpageCommandInput) (*cli.Command, error)
• func ToMan(a *cli.App) (string, error)
• func ToMarkdown(a *cli.App) (string, error)
• type InstallManpageCommandInput

Examples

• Package

Functions

func InstallManpageCommand

func InstallManpageCommand(opts *InstallManpageCommandInput) (*cli.Command, error)

InstallManpageCommand will generate a *cli.Command to be used with a cli.App. This will install a manual page (8) to the man-db.

func ToMan

func ToMan(a *cli.App) (string, error)

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

func ToMarkdown

func ToMarkdown(a *cli.App) (string, error)

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

Types

type InstallManpageCommandInput

type InstallManpageCommandInput struct {
	AppName string `required:"true"`
	CmdName string `default:"install-command"`
	Path    string `default:"/usr/local/share/man/man8"`
	Hidden  bool   `default:"false"`
}

InstallManpageCommandInput provides an interface to pass in options for the InstallManpageCommand

- AppName is required.

- CmdName defaults to 'install-manpage'

- Path defaults to '/usr/local/share/man/man8'