diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 19afa95..e497115 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -27,6 +27,16 @@ jobs: - name: Build run: go build ./... + - name: Command docs up-to-date + run: | + go generate ./... + if [ -n "$(git status --porcelain -- docs/commands)" ]; then + echo "::error::Command docs in docs/commands/ are out of date. Run 'go generate ./...' and commit the result." + git status --short -- docs/commands + git diff -- docs/commands + exit 1 + fi + commits: name: Commit messages runs-on: ubuntu-latest diff --git a/DEVELOPING.md b/DEVELOPING.md index 208cd57..4da9d3b 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -30,6 +30,16 @@ Commit messages follow [Angular commit conventions](https://github.com/angular/a conform enforce --commit-msg-file .git/COMMIT_EDITMSG ``` +## Command docs + +Per-command reference under `docs/commands/` is generated from the cobra command tree. Regenerate after changing the public-facing interface: + +```bash +task docs # or: go generate ./... +``` + +The generator lives at `tools/docgen/main.go`. + ## Releasing Releases are triggered by pushing a semver tag. The CI workflow builds 5-platform binaries, generates a changelog via `git-cliff`, and publishes a GitHub release. diff --git a/README.md b/README.md index 97a17bd..9abaee0 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,10 @@ git checkout -b feat-login ## Reference +### Commands + +Full per-command reference (flags, usage, subcommand tree) is auto-generated from the CLI itself and lives in [docs/commands/bight.md](docs/commands/bight.md). You can also run `bight help ` locally. + ### Config file `bight install` generates a starter config, but you can hand-edit `.bight.yml` at any time: diff --git a/Taskfile.yml b/Taskfile.yml index 72dddc9..8249b4a 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -35,6 +35,11 @@ tasks: - git push - git push --tags + docs: + desc: Regenerate per-command Markdown reference under docs/commands/ + cmds: + - go generate ./... + # Help and info default: desc: Show available tasks diff --git a/docs/commands/bight.md b/docs/commands/bight.md new file mode 100644 index 0000000..df4cd2a --- /dev/null +++ b/docs/commands/bight.md @@ -0,0 +1,19 @@ +## bight + +Patch .env files on git branch checkout + +### Options + +``` + --config string Path to config file (default: .bight.yml) + -h, --help help for bight +``` + +### SEE ALSO + +* [bight doctor](bight_doctor.md) - Validate bight setup and config +* [bight install](bight_install.md) - Write post-checkout hook into .git/hooks/ +* [bight post-checkout](bight_post-checkout.md) - Called by git post-checkout hook +* [bight run](bight_run.md) - Manually apply env patching for the current branch +* [bight uninstall](bight_uninstall.md) - Remove post-checkout hook from .git/hooks/ + diff --git a/docs/commands/bight_doctor.md b/docs/commands/bight_doctor.md new file mode 100644 index 0000000..61b6565 --- /dev/null +++ b/docs/commands/bight_doctor.md @@ -0,0 +1,24 @@ +## bight doctor + +Validate bight setup and config + +``` +bight doctor [flags] +``` + +### Options + +``` + -h, --help help for doctor +``` + +### Options inherited from parent commands + +``` + --config string Path to config file (default: .bight.yml) +``` + +### SEE ALSO + +* [bight](bight.md) - Patch .env files on git branch checkout + diff --git a/docs/commands/bight_install.md b/docs/commands/bight_install.md new file mode 100644 index 0000000..4735fb3 --- /dev/null +++ b/docs/commands/bight_install.md @@ -0,0 +1,24 @@ +## bight install + +Write post-checkout hook into .git/hooks/ + +``` +bight install [flags] +``` + +### Options + +``` + -h, --help help for install +``` + +### Options inherited from parent commands + +``` + --config string Path to config file (default: .bight.yml) +``` + +### SEE ALSO + +* [bight](bight.md) - Patch .env files on git branch checkout + diff --git a/docs/commands/bight_post-checkout.md b/docs/commands/bight_post-checkout.md new file mode 100644 index 0000000..7c4d1fb --- /dev/null +++ b/docs/commands/bight_post-checkout.md @@ -0,0 +1,24 @@ +## bight post-checkout + +Called by git post-checkout hook + +``` +bight post-checkout [flags] +``` + +### Options + +``` + -h, --help help for post-checkout +``` + +### Options inherited from parent commands + +``` + --config string Path to config file (default: .bight.yml) +``` + +### SEE ALSO + +* [bight](bight.md) - Patch .env files on git branch checkout + diff --git a/docs/commands/bight_run.md b/docs/commands/bight_run.md new file mode 100644 index 0000000..152fe52 --- /dev/null +++ b/docs/commands/bight_run.md @@ -0,0 +1,25 @@ +## bight run + +Manually apply env patching for the current branch + +``` +bight run [flags] +``` + +### Options + +``` + --dry-run Print what would be written without modifying any files + -h, --help help for run +``` + +### Options inherited from parent commands + +``` + --config string Path to config file (default: .bight.yml) +``` + +### SEE ALSO + +* [bight](bight.md) - Patch .env files on git branch checkout + diff --git a/docs/commands/bight_uninstall.md b/docs/commands/bight_uninstall.md new file mode 100644 index 0000000..5073975 --- /dev/null +++ b/docs/commands/bight_uninstall.md @@ -0,0 +1,24 @@ +## bight uninstall + +Remove post-checkout hook from .git/hooks/ + +``` +bight uninstall [flags] +``` + +### Options + +``` + -h, --help help for uninstall +``` + +### Options inherited from parent commands + +``` + --config string Path to config file (default: .bight.yml) +``` + +### SEE ALSO + +* [bight](bight.md) - Patch .env files on git branch checkout + diff --git a/go.mod b/go.mod index ac6cef8..dbf854f 100644 --- a/go.mod +++ b/go.mod @@ -9,6 +9,9 @@ require ( ) require ( + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/spf13/pflag v1.0.9 // indirect + go.yaml.in/yaml/v3 v3.0.4 // indirect ) diff --git a/go.sum b/go.sum index 6dbc4a3..25973ec 100644 --- a/go.sum +++ b/go.sum @@ -1,13 +1,16 @@ +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0= github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY= github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/main.go b/main.go index 2d36c39..a405afb 100644 --- a/main.go +++ b/main.go @@ -1,3 +1,5 @@ +//go:generate go run ./tools/docgen + package main import ( diff --git a/tools/docgen/main.go b/tools/docgen/main.go new file mode 100644 index 0000000..6eeb07a --- /dev/null +++ b/tools/docgen/main.go @@ -0,0 +1,32 @@ +package main + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/AndrewADev/bight/cmd" + "github.com/spf13/cobra/doc" +) + +func main() { + outDir := "docs/commands" + if len(os.Args) > 1 { + outDir = os.Args[1] + } + + if err := os.MkdirAll(outDir, 0o755); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } + + root := cmd.Root() + root.DisableAutoGenTag = true + + if err := doc.GenMarkdownTree(root, outDir); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } + + fmt.Printf("wrote command docs to %s\n", filepath.Clean(outDir)) +}