docs: add cmd docs (#2184)

* docs: add cmd docs

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

* docs: cmd docs

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

* fix: num cpus

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

* docs: improve some things

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

* fix: improve docs

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

* fix: script

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>

.gitignore

@@ -9,4 +9,4 @@ site/
 www/docs/static/releases.json
 .vercel
 completions/
-.vscode/
+.vscode/

cmd/build.go

@@ -68,7 +68,7 @@ func newBuildCmd() *buildCmd {
 	cmd.Flags().BoolVar(&root.opts.skipValidate, "skip-validate", false, "Skips several sanity checks")
 	cmd.Flags().BoolVar(&root.opts.skipPostHooks, "skip-post-hooks", false, "Skips all post-build hooks")
 	cmd.Flags().BoolVar(&root.opts.rmDist, "rm-dist", false, "Remove the dist folder before building")
-	cmd.Flags().IntVarP(&root.opts.parallelism, "parallelism", "p", runtime.NumCPU(), "Amount tasks to run concurrently")
+	cmd.Flags().IntVarP(&root.opts.parallelism, "parallelism", "p", 0, "Amount tasks to run concurrently (default: number of CPUs)")
 	cmd.Flags().DurationVar(&root.opts.timeout, "timeout", 30*time.Minute, "Timeout to the entire build process")
 	cmd.Flags().BoolVar(&root.opts.singleTarget, "single-target", false, "Builds only for current GOOS and GOARCH")
 	cmd.Flags().StringVar(&root.opts.id, "id", "", "Builds only the specified build id")
@@ -104,7 +104,10 @@ func buildProject(options buildOpts) (*context.Context, error) {
 }
 
 func setupBuildContext(ctx *context.Context, options buildOpts) error {
-	ctx.Parallelism = options.parallelism
+	ctx.Parallelism = runtime.NumCPU()
+	if options.parallelism > 0 {
+		ctx.Parallelism = options.parallelism
+	}
 	log.Debugf("parallelism: %v", ctx.Parallelism)
 	ctx.Snapshot = options.snapshot
 	ctx.SkipValidate = ctx.Snapshot || options.skipValidate

cmd/completion.go

@@ -7,40 +7,50 @@ type completionCmd struct {
 }
 
 func newCompletionCmd() *completionCmd {
-	var root = &completionCmd{}
-	var cmd = &cobra.Command{
+	root := &completionCmd{}
+	cmd := &cobra.Command{
 		Use:   "completion [bash|zsh|fish]",
-		Short: "Print shell autocompletion scripts for goreleaser",
-		Long: `To load completions:
+		Short: "Prints shell autocompletion scripts for GoReleaser",
+		Long: `Allows you to setup your shell to autocomple GoReleaser commands and flags.
 
-Bash:
+#### Bash
 
-$ source <(goreleaser completion bash)
+	$ source <(goreleaser completion bash)
 
-# To load completions for each session, execute once:
-Linux:
-  $ goreleaser completion bash > /etc/bash_completion.d/goreleaser
-MacOS:
-  $ goreleaser completion bash > /usr/local/etc/bash_completion.d/goreleaser
+To load completions for each session, execute once:
 
-Zsh:
+##### Linux
 
-# If shell completion is not already enabled in your environment you will need
-# to enable it.  You can execute the following once:
+	$ goreleaser completion bash > /etc/bash_completion.d/goreleaser
 
-$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+##### MacOS
 
-# To load completions for each session, execute once:
-$ goreleaser completion zsh > "${fpath[1]}/_goreleaser"
+	$ goreleaser completion bash > /usr/local/etc/bash_completion.d/goreleaser
 
-# You will need to start a new shell for this setup to take effect.
+#### ZSH
 
-Fish:
+If shell completion is not already enabled in your environment you will need to enable it.
+You can execute the following once:
 
-$ goreleaser completion fish | source
+	$ echo "autoload -U compinit; compinit" >> ~/.zshrc
 
-# To load completions for each session, execute once:
-$ goreleaser completion fish > ~/.config/fish/completions/goreleaser.fish
+To load completions for each session, execute once:
+
+	$ goreleaser completion zsh > "${fpath[1]}/_goreleaser"
+
+You will need to start a new shell for this setup to take effect.
+
+#### Fish
+
+	$ goreleaser completion fish | source
+
+To load completions for each session, execute once:
+
+	$ goreleaser completion fish > ~/.config/fish/completions/goreleaser.fish
+
+**NOTE**: If you are using an official GoReleaser package, it should setup autocompletions for you out of the box.
+
+### Usage
 `,
 		SilenceUsage:          true,
 		DisableFlagsInUseLine: true,

cmd/docs.go

@@ -0,0 +1,35 @@
+package cmd
+
+import (
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+type docsCmd struct {
+	cmd *cobra.Command
+}
+
+func newDocsCmd() *docsCmd {
+	root := &docsCmd{}
+	cmd := &cobra.Command{
+		Use:                   "docs",
+		Short:                 "Generates GoReleaser's command line docs",
+		SilenceUsage:          true,
+		DisableFlagsInUseLine: true,
+		Hidden:                true,
+		Args:                  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root.cmd.Root().DisableAutoGenTag = true
+			return doc.GenMarkdownTreeCustom(root.cmd.Root(), "www/docs/cmd", func(_ string) string {
+				return ""
+			}, func(s string) string {
+				return "/cmd/" + strings.TrimSuffix(s, ".md")
+			})
+		},
+	}
+
+	root.cmd = cmd
+	return root
+}

cmd/release.go

@@ -34,9 +34,9 @@ type releaseOpts struct {
 }
 
 func newReleaseCmd() *releaseCmd {
-	var root = &releaseCmd{}
+	root := &releaseCmd{}
 	// nolint: dupl
-	var cmd = &cobra.Command{
+	cmd := &cobra.Command{
 		Use:           "release",
 		Aliases:       []string{"r"},
 		Short:         "Releases the current project",
@@ -71,7 +71,7 @@ func newReleaseCmd() *releaseCmd {
 	cmd.Flags().BoolVar(&root.opts.skipSign, "skip-sign", false, "Skips signing the artifacts")
 	cmd.Flags().BoolVar(&root.opts.skipValidate, "skip-validate", false, "Skips several sanity checks")
 	cmd.Flags().BoolVar(&root.opts.rmDist, "rm-dist", false, "Remove the dist folder before building")
-	cmd.Flags().IntVarP(&root.opts.parallelism, "parallelism", "p", runtime.NumCPU(), "Amount tasks to run concurrently")
+	cmd.Flags().IntVarP(&root.opts.parallelism, "parallelism", "p", 0, "Amount tasks to run concurrently (default: number of CPUs)")
 	cmd.Flags().DurationVar(&root.opts.timeout, "timeout", 30*time.Minute, "Timeout to the entire release process")
 	cmd.Flags().BoolVar(&root.opts.deprecated, "deprecated", false, "Force print the deprecation message - tests only")
 	_ = cmd.Flags().MarkHidden("deprecated")
@@ -103,7 +103,10 @@ func releaseProject(options releaseOpts) (*context.Context, error) {
 }
 
 func setupReleaseContext(ctx *context.Context, options releaseOpts) *context.Context {
-	ctx.Parallelism = options.parallelism
+	ctx.Parallelism = runtime.NumCPU()
+	if options.parallelism > 0 {
+		ctx.Parallelism = options.parallelism
+	}
 	log.Debugf("parallelism: %v", ctx.Parallelism)
 	ctx.ReleaseNotes = options.releaseNotes
 	ctx.ReleaseHeader = options.releaseHeader

cmd/root.go

@@ -27,9 +27,9 @@ func (cmd *rootCmd) Execute(args []string) {
 	}
 
 	if err := cmd.cmd.Execute(); err != nil {
-		var code = 1
-		var msg = "command failed"
-		var eerr = &exitError{}
+		code := 1
+		msg := "command failed"
+		eerr := &exitError{}
 		if errors.As(err, &eerr) {
 			code = eerr.code
 			if eerr.details != "" {
@@ -48,10 +48,10 @@ type rootCmd struct {
 }
 
 func newRootCmd(version string, exit func(int)) *rootCmd {
-	var root = &rootCmd{
+	root := &rootCmd{
 		exit: exit,
 	}
-	var cmd = &cobra.Command{
+	cmd := &cobra.Command{
 		Use:           "goreleaser",
 		Short:         "Deliver Go binaries as fast and easily as possible",
 		Version:       version,
@@ -73,6 +73,7 @@ func newRootCmd(version string, exit func(int)) *rootCmd {
 		newCheckCmd().cmd,
 		newInitCmd().cmd,
 		newCompletionCmd().cmd,
+		newDocsCmd().cmd,
 	)
 
 	root.cmd = cmd

go.sum

@@ -170,6 +170,7 @@ github.com/coreos/etcd v3.3.13+incompatible/go.mod h1:uF7uidLiAD3TWHmW31ZFd/JWoc
 github.com/coreos/go-semver v0.3.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3EedlOD2RNk=
 github.com/coreos/go-systemd v0.0.0-20190321100706-95778dfbb74e/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
 github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
+github.com/cpuguy83/go-md2man/v2 v2.0.0 h1:EoUDS0afbrsXAZ9YQ9jdu/mZ2sXgT1/2yyNng4PGlyM=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -474,6 +475,7 @@ github.com/prometheus/tsdb v0.7.1/go.mod h1:qhTCs0VvXwvX/y3TZrWD7rabWM+ijKTux40T
 github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg=
 github.com/rogpeppe/fastuuid v1.1.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
 github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
+github.com/russross/blackfriday/v2 v2.0.1 h1:lPqVAte+HuHNfhJ/0LC98ESWRz8afy9tM/0RK8m9o+Q=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/sassoftware/go-rpmutils v0.0.0-20190420191620-a8f1baeba37b h1:+gCnWOZV8Z/8jehJ2CdqB47Z3S+SREmQcuXkRFLNsiI=
@@ -483,6 +485,7 @@ github.com/sergi/go-diff v1.0.0/go.mod h1:0CfEIISq7TuYL3j771MWULgwwjU+GofnZX9QAm
 github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
 github.com/sergi/go-diff v1.2.0 h1:XU+rvMAioB0UC3q1MFrIQy4Vo5/4VsRDQQXHsEya6xQ=
 github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
+github.com/shurcooL/sanitized_anchor_name v1.0.0 h1:PdmoCO6wvbs+7yrJyMORt4/BmY5IYyJwS/kOiWx8mHo=
 github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
 github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo=
 github.com/sirupsen/logrus v1.4.1/go.mod h1:ni0Sbl8bgC9z8RoU9G6nDWqqs/fq4eDPysMBDgk/93Q=

scripts/cmd_docs.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+set -e
+
+SED="sed"
+if which gsed >/dev/null 2>&1; then
+	SED="gsed"
+fi
+
+rm -rf www/docs/cmd/*.md
+go run . docs
+"$SED" \
+	-i'' \
+	-e 's/SEE ALSO/See also/g' \
+	-e 's/^## /# /g' \
+	-e 's/^### /## /g' \
+	-e 's/^#### /### /g' \
+	-e 's/^##### /#### /g' \
+	./www/docs/cmd/*.md

www/docs/cmd/goreleaser.md

@@ -0,0 +1,19 @@
+# goreleaser
+
+Deliver Go binaries as fast and easily as possible
+
+## Options
+
+```
+      --debug   Enable debug mode
+  -h, --help    help for goreleaser
+```
+
+## See also
+
+* [goreleaser build](/cmd/goreleaser_build)	 - Builds the current project
+* [goreleaser check](/cmd/goreleaser_check)	 - Checks if configuration is valid
+* [goreleaser completion](/cmd/goreleaser_completion)	 - Prints shell autocompletion scripts for GoReleaser
+* [goreleaser init](/cmd/goreleaser_init)	 - Generates a .goreleaser.yml file
+* [goreleaser release](/cmd/goreleaser_release)	 - Releases the current project
+

www/docs/cmd/goreleaser_build.md

@@ -0,0 +1,33 @@
+# goreleaser build
+
+Builds the current project
+
+```
+goreleaser build [flags]
+```
+
+## Options
+
+```
+  -f, --config string      Load configuration from file
+  -h, --help               help for build
+      --id string          Builds only the specified build id
+  -p, --parallelism int    Amount tasks to run concurrently (default: number of CPUs)
+      --rm-dist            Remove the dist folder before building
+      --single-target      Builds only for current GOOS and GOARCH
+      --skip-post-hooks    Skips all post-build hooks
+      --skip-validate      Skips several sanity checks
+      --snapshot           Generate an unversioned snapshot build, skipping all validations and without publishing any artifacts
+      --timeout duration   Timeout to the entire build process (default 30m0s)
+```
+
+## Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+## See also
+
+* [goreleaser](/cmd/goreleaser)	 - Deliver Go binaries as fast and easily as possible
+

www/docs/cmd/goreleaser_check.md

@@ -0,0 +1,25 @@
+# goreleaser check
+
+Checks if configuration is valid
+
+```
+goreleaser check [flags]
+```
+
+## Options
+
+```
+  -f, --config string   Configuration file to check
+  -h, --help            help for check
+```
+
+## Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+## See also
+
+* [goreleaser](/cmd/goreleaser)	 - Deliver Go binaries as fast and easily as possible
+

www/docs/cmd/goreleaser_completion.md

@@ -0,0 +1,68 @@
+# goreleaser completion
+
+Prints shell autocompletion scripts for GoReleaser
+
+## Synopsis
+
+Allows you to setup your shell to autocomple GoReleaser commands and flags.
+
+### Bash
+
+	$ source <(goreleaser completion bash)
+
+To load completions for each session, execute once:
+
+#### Linux
+
+	$ goreleaser completion bash > /etc/bash_completion.d/goreleaser
+
+#### MacOS
+
+	$ goreleaser completion bash > /usr/local/etc/bash_completion.d/goreleaser
+
+### ZSH
+
+If shell completion is not already enabled in your environment you will need to enable it.
+You can execute the following once:
+
+	$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions for each session, execute once:
+
+	$ goreleaser completion zsh > "${fpath[1]}/_goreleaser"
+
+You will need to start a new shell for this setup to take effect.
+
+### Fish
+
+	$ goreleaser completion fish | source
+
+To load completions for each session, execute once:
+
+	$ goreleaser completion fish > ~/.config/fish/completions/goreleaser.fish
+
+**NOTE**: If you are using an official GoReleaser package, it should setup autocompletions for you out of the box.
+
+## Usage
+
+
+```
+goreleaser completion [bash|zsh|fish]
+```
+
+## Options
+
+```
+  -h, --help   help for completion
+```
+
+## Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+## See also
+
+* [goreleaser](/cmd/goreleaser)	 - Deliver Go binaries as fast and easily as possible
+

www/docs/cmd/goreleaser_init.md

@@ -0,0 +1,25 @@
+# goreleaser init
+
+Generates a .goreleaser.yml file
+
+```
+goreleaser init [flags]
+```
+
+## Options
+
+```
+  -f, --config string   Load configuration from file (default ".goreleaser.yml")
+  -h, --help            help for init
+```
+
+## Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+## See also
+
+* [goreleaser](/cmd/goreleaser)	 - Deliver Go binaries as fast and easily as possible
+

www/docs/cmd/goreleaser_release.md

@@ -0,0 +1,35 @@
+# goreleaser release
+
+Releases the current project
+
+```
+goreleaser release [flags]
+```
+
+## Options
+
+```
+  -f, --config string           Load configuration from file
+  -h, --help                    help for release
+  -p, --parallelism int         Amount tasks to run concurrently (default: number of CPUs)
+      --release-footer string   Load custom release notes footer from a markdown file
+      --release-header string   Load custom release notes header from a markdown file
+      --release-notes string    Load custom release notes from a markdown file
+      --rm-dist                 Remove the dist folder before building
+      --skip-publish            Skips publishing artifacts
+      --skip-sign               Skips signing the artifacts
+      --skip-validate           Skips several sanity checks
+      --snapshot                Generate an unversioned snapshot release, skipping all validations and without publishing any artifacts
+      --timeout duration        Timeout to the entire release process (default 30m0s)
+```
+
+## Options inherited from parent commands
+
+```
+      --debug   Enable debug mode
+```
+
+## See also
+
+* [goreleaser](/cmd/goreleaser)	 - Deliver Go binaries as fast and easily as possible
+

www/mkdocs.yml

@@ -94,9 +94,14 @@ nav:
   - customization/source.md
   - customization/templates.md
   - customization/upload.md
+- Command Line Usage:
+    - goreleaser: cmd/goreleaser.md
+    - goreleaser init: cmd/goreleaser_init.md
+    - goreleaser check: cmd/goreleaser_check.md
+    - goreleaser build: cmd/goreleaser_build.md
+    - goreleaser release: cmd/goreleaser_release.md
+    - goreleaser completion: cmd/goreleaser_completion.md
 - deprecations.md
-- sponsors.md
-- contributing.md
 - Cookbooks:
   - About: cookbooks/index.md
   - Blog Posts: cookbooks/blog-posts.md
@@ -107,6 +112,8 @@ nav:
   - cookbooks/release-a-library.md
   - cookbooks/semantic-release.md
   - cookbooks/upload-to-bintray.md
+- sponsors.md
+- contributing.md
 - links.md
 
 markdown_extensions: