diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d9d5d46 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +# Welcome to urfave/cli + +[![GoDoc](https://godoc.org/github.com/urfave/cli?status.svg)](https://pkg.go.dev/github.com/urfave/cli/v2) +[![codebeat](https://codebeat.co/badges/0a8f30aa-f975-404b-b878-5fab3ae1cc5f)](https://codebeat.co/projects/github-com-urfave-cli) +[![Go Report Card](https://goreportcard.com/badge/urfave/cli)](https://goreportcard.com/report/urfave/cli) +[![codecov](https://codecov.io/gh/urfave/cli/branch/main/graph/badge.svg)](https://codecov.io/gh/urfave/cli) + +`urfave/cli` is a simple, fast, and fun package for building command line apps in Go. The +goal is to enable developers to write fast and distributable command line applications in +an expressive way. + +These are the guides for each major supported version: + +- [`v2`](./v2/) +- [`v1`](./v1/) + +In addition to the version-specific guides, these other documents are available: + +- [`CONTRIBUTING`](./CONTRIBUTING/) +- [`RELEASING`](./RELEASING/) diff --git a/docs/migrate-v1-to-v2.md b/docs/migrate-v1-to-v2.md index c555468..7c703c8 100644 --- a/docs/migrate-v1-to-v2.md +++ b/docs/migrate-v1-to-v2.md @@ -1,6 +1,4 @@ -Migration Guide: v1 to v2 -=== - +# Migration Guide: v1 to v2 v2 has a number of breaking changes but converting is relatively straightforward: make the changes documented below then resolve any @@ -11,25 +9,6 @@ If you find any issues not covered by this document, please post a comment on [Issue 921](https://github.com/urfave/cli/issues/921) or consider sending a PR to help improve this guide. - - - * [Flags before args](#flags-before-args) - * [Import string changed](#import-string-changed) - * [Flag aliases are done differently](#flag-aliases-are-done-differently) - * [EnvVar is now a list (EnvVars)](#envvar-is-now-a-list-envvars) - * [Actions returns errors](#actions-returns-errors) - * [cli.Flag changed](#cliflag-changed) - * [Commands are now lists of pointers](#commands-are-now-lists-of-pointers) - * [Lists of commands should be pointers](#lists-of-commands-should-be-pointers) - * [Appending Commands](#appending-commands) - * [GlobalString, GlobalBool and its likes are deprecated](#globalstring-globalbool-and-its-likes-are-deprecated) - * [BoolTFlag and BoolT are deprecated](#booltflag-and-boolt-are-deprecated) - * [&cli.StringSlice{""} replaced with cli.NewStringSlice("")](#clistringslice-replaced-with-clinewstringslice) - * [Replace deprecated functions](#replace-deprecated-functions) - * [Everything else](#everything-else) - - - # Flags before args In v2 flags must come before args. This is more POSIX-compliant. You diff --git a/docs/v1/manual.md b/docs/v1/index.md similarity index 96% rename from docs/v1/manual.md rename to docs/v1/index.md index dd22bdb..6f568b7 100644 --- a/docs/v1/manual.md +++ b/docs/v1/index.md @@ -1,35 +1,4 @@ -cli v1 manual -=== - - - -- [Getting Started](#getting-started) -- [Examples](#examples) - * [Arguments](#arguments) - * [Flags](#flags) - + [Placeholder Values](#placeholder-values) - + [Alternate Names](#alternate-names) - + [Ordering](#ordering) - + [Values from the Environment](#values-from-the-environment) - + [Values from files](#values-from-files) - + [Values from alternate input sources (YAML, TOML, and others)](#values-from-alternate-input-sources-yaml-toml-and-others) - + [Precedence](#precedence) - * [Subcommands](#subcommands) - * [Subcommands categories](#subcommands-categories) - * [Exit code](#exit-code) - * [Combining short options](#combining-short-options) - * [Bash Completion](#bash-completion) - + [Enabling](#enabling) - + [Distribution](#distribution) - + [Customization](#customization) - * [Generated Help Text](#generated-help-text) - + [Customization](#customization-1) - * [Version Flag](#version-flag) - + [Customization](#customization-2) - + [Full API Example](#full-api-example) - * [Migrating to V2](#migrating-to-v2) - - +# v1 guide ## Getting Started diff --git a/docs/v2/manual.md b/docs/v2/index.md similarity index 95% rename from docs/v2/manual.md rename to docs/v2/index.md index b480dd6..9c26100 100644 --- a/docs/v2/manual.md +++ b/docs/v2/index.md @@ -1,51 +1,4 @@ -cli v2 manual -=== - - - -- [Migrating From Older Releases](#migrating-from-older-releases) -- [Getting Started](#getting-started) -- [Examples](#examples) - * [Arguments](#arguments) - * [Flags](#flags) - + [Placeholder Values](#placeholder-values) - + [Alternate Names](#alternate-names) - + [Ordering](#ordering) - + [Values from the Environment](#values-from-the-environment) - + [Values from files](#values-from-files) - + [Values from alternate input sources (YAML, TOML, and others)](#values-from-alternate-input-sources-yaml-toml-and-others) - + [Required Flags](#required-flags) - + [Default Values for help output](#default-values-for-help-output) - + [Precedence](#precedence) - * [Subcommands](#subcommands) - * [Subcommands categories](#subcommands-categories) - * [Exit code](#exit-code) - * [Combining short options](#combining-short-options) - * [Bash Completion](#bash-completion) - + [Default auto-completion](#default-auto-completion) - + [Custom auto-completion](#custom-auto-completion) - + [Enabling](#enabling) - + [Distribution and Persistent Autocompletion](#distribution-and-persistent-autocompletion) - + [Customization](#customization) - + [ZSH Support](#zsh-support) - + [ZSH default auto-complete example](#zsh-default-auto-complete-example) - + [ZSH custom auto-complete example](#zsh-custom-auto-complete-example) - + [PowerShell Support](#powershell-support) - * [Generated Help Text](#generated-help-text) - + [Customization](#customization-1) - * [Version Flag](#version-flag) - + [Customization](#customization-2) - * [Timestamp Flag](#timestamp-flag) - * [Full API Example](#full-api-example) - - - -## Migrating From Older Releases - -There are a small set of breaking changes between v1 and v2. -Converting is relatively straightforward and typically takes less than -an hour. Specific steps are included in -[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). Also see the [pkg.go.dev docs](https://pkg.go.dev/github.com/urfave/cli/v2) for v2 API documentation. +# v2 guide ## Getting Started @@ -1714,3 +1667,11 @@ func wopAction(c *cli.Context) error { return nil } ``` + +## Migrating From Older Releases + +There are a small set of breaking changes between v1 and v2. +Converting is relatively straightforward and typically takes less than +an hour. Specific steps are included in +[Migration Guide: v1 to v2](../migrate-v1-to-v2.md). Also see the [pkg.go.dev docs](https://pkg.go.dev/github.com/urfave/cli/v2) for v2 API documentation. + diff --git a/mkdocs-requirements.txt b/mkdocs-requirements.txt new file mode 100644 index 0000000..94dae76 --- /dev/null +++ b/mkdocs-requirements.txt @@ -0,0 +1,4 @@ +mkdocs +mkdocs-material +mkdocs-git-revision-date-localized-plugin +pygments diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..c963d37 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +# NOTE: the mkdocs dependencies will need to be installed out of +# band until this whole thing gets more automated: +# +# pip install -r mkdocs-requirements.txt +# + +site_name: urfave/cli +site_url: https://cli.urfave.org/ +repo_url: https://github.com/urvafe/cli +edit_uri: edit/main/docs/ +nav: + - Home: index.md + - v2 Manual: v2/index.md + - v1 Manual: v1/index.md +theme: + name: material + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-4 + name: dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-7 + name: light mode +plugins: + - git-revision-date-localized + - search +# NOTE: this is the recommended configuration from +# https://squidfunk.github.io/mkdocs-material/setup/extensions/#recommended-configuration +markdown_extensions: + - abbr + - admonition + - attr_list + - def_list + - footnotes + - meta + - md_in_html + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - pymdownx.highlight + - pymdownx.inlinehilite + - pymdownx.keys + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde