From 2d923ecd8aaf65bdde9aa698ee390ddb69f6b218 Mon Sep 17 00:00:00 2001 From: Carlos Tadeu Panato Junior Date: Mon, 19 Sep 2022 10:16:08 +0200 Subject: [PATCH] Add command docs and job to check it (#211) * add command docs Signed-off-by: cpanato * add job to check command doc Signed-off-by: cpanato * avoid dynamic docs and expand the path later Signed-off-by: cpanato Signed-off-by: cpanato --- .github/workflows/ci.yaml | 21 ++++++++++++++ .gitignore | 1 + cr/cmd/docGen.go | 51 +++++++++++++++++++++++++++++++++ cr/cmd/package.go | 10 +------ doc/cr.md | 26 +++++++++++++++++ doc/cr_completion.md | 30 +++++++++++++++++++ doc/cr_completion_bash.md | 49 +++++++++++++++++++++++++++++++ doc/cr_completion_fish.md | 40 ++++++++++++++++++++++++++ doc/cr_completion_powershell.md | 37 ++++++++++++++++++++++++ doc/cr_completion_zsh.md | 51 +++++++++++++++++++++++++++++++++ doc/cr_index.md | 44 ++++++++++++++++++++++++++++ doc/cr_package.md | 39 +++++++++++++++++++++++++ doc/cr_upload.md | 38 ++++++++++++++++++++++++ doc/cr_version.md | 25 ++++++++++++++++ go.mod | 4 ++- go.sum | 2 ++ pkg/packager/packager.go | 12 ++++++++ 17 files changed, 470 insertions(+), 10 deletions(-) create mode 100644 cr/cmd/docGen.go create mode 100644 doc/cr.md create mode 100644 doc/cr_completion.md create mode 100644 doc/cr_completion_bash.md create mode 100644 doc/cr_completion_fish.md create mode 100644 doc/cr_completion_powershell.md create mode 100644 doc/cr_completion_zsh.md create mode 100644 doc/cr_index.md create mode 100644 doc/cr_package.md create mode 100644 doc/cr_upload.md create mode 100644 doc/cr_version.md diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 22fbfc9..a436449 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -61,6 +61,27 @@ jobs: version: v1.13.0 args: -v ci + check-docs: + name: check-docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3 + - uses: actions/setup-go@84cbf8094393cdc5fe1fe1671ff2647332956b1a # v3 + with: + go-version-file: './go.mod' + check-latest: true + + - name: generate docs + run: | + go build -o cr-bin ./cr/main.go + ./cr-bin doc-gen + git_status="$(git status --porcelain)" + if [[ ${git_status} ]]; then + echo -e 'Documentation is outdated. Please update the docs\n' + echo "${git_status}" + exit 1 + fi + golangci: name: lint runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index d12c272..1837e56 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ chart-releaser /dist /vendor .vscode +/cr-bin diff --git a/cr/cmd/docGen.go b/cr/cmd/docGen.go new file mode 100644 index 0000000..fd6460e --- /dev/null +++ b/cr/cmd/docGen.go @@ -0,0 +1,51 @@ +// Copyright The Helm Authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package cmd + +import ( + "fmt" + + "github.com/MakeNowJust/heredoc" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" +) + +var generateDocsCmd = &cobra.Command{ + Use: "doc-gen", + Short: "Generate documentation", + Long: heredoc.Doc(` + Generate documentation for all commands + to the 'docs' directory.`), + Hidden: true, + RunE: generateDocs, +} + +func generateDocs(cmd *cobra.Command, args []string) error { + fmt.Println("Generating docs...") + + err := doc.GenMarkdownTree(rootCmd.Root(), "doc") + if err != nil { + return err + } + + fmt.Println("Done.") + return nil +} + +func init() { + rootCmd.AddCommand(generateDocsCmd) + + rootCmd.DisableAutoGenTag = true +} diff --git a/cr/cmd/package.go b/cr/cmd/package.go index 4a6f70e..45373e0 100644 --- a/cr/cmd/package.go +++ b/cr/cmd/package.go @@ -15,11 +15,8 @@ package cmd import ( - "path/filepath" - "github.com/helm/chart-releaser/pkg/config" "github.com/helm/chart-releaser/pkg/packager" - "github.com/mitchellh/go-homedir" "github.com/spf13/cobra" ) @@ -55,15 +52,10 @@ func getRequiredPackageArgs() []string { } func init() { - dir, err := homedir.Dir() - if err != nil { - panic(err) - } - rootCmd.AddCommand(packageCmd) packageCmd.Flags().StringP("package-path", "p", ".cr-release-packages", "Path to directory with chart packages") packageCmd.Flags().Bool("sign", false, "Use a PGP private key to sign this package") packageCmd.Flags().String("key", "", "Name of the key to use when signing") - packageCmd.Flags().String("keyring", filepath.Join(dir, ".gnupg", "pubring.gpg"), "Location of a public keyring") + packageCmd.Flags().String("keyring", "~/.gnupg/pubring.gpg", "Location of a public keyring") packageCmd.Flags().String("passphrase-file", "", "Location of a file which contains the passphrase for the signing key. Use '-' in order to read from stdin") } diff --git a/doc/cr.md b/doc/cr.md new file mode 100644 index 0000000..84f316e --- /dev/null +++ b/doc/cr.md @@ -0,0 +1,26 @@ +## cr + +Helm Chart Repos on Github Pages + +### Synopsis + + +Create Helm chart repositories on GitHub Pages by uploading Chart packages +and Chart metadata to GitHub Releases and creating a suitable index file + + +### Options + +``` + --config string Config file (default is $HOME/.cr.yaml) + -h, --help help for cr +``` + +### SEE ALSO + +* [cr completion](cr_completion.md) - Generate the autocompletion script for the specified shell +* [cr index](cr_index.md) - Update Helm repo index.yaml for the given GitHub repo +* [cr package](cr_package.md) - Package Helm charts +* [cr upload](cr_upload.md) - Upload Helm chart packages to GitHub Releases +* [cr version](cr_version.md) - Print version information + diff --git a/doc/cr_completion.md b/doc/cr_completion.md new file mode 100644 index 0000000..2a33e06 --- /dev/null +++ b/doc/cr_completion.md @@ -0,0 +1,30 @@ +## cr completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for cr for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr](cr.md) - Helm Chart Repos on Github Pages +* [cr completion bash](cr_completion_bash.md) - Generate the autocompletion script for bash +* [cr completion fish](cr_completion_fish.md) - Generate the autocompletion script for fish +* [cr completion powershell](cr_completion_powershell.md) - Generate the autocompletion script for powershell +* [cr completion zsh](cr_completion_zsh.md) - Generate the autocompletion script for zsh + diff --git a/doc/cr_completion_bash.md b/doc/cr_completion_bash.md new file mode 100644 index 0000000..13744a0 --- /dev/null +++ b/doc/cr_completion_bash.md @@ -0,0 +1,49 @@ +## cr completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(cr completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + cr completion bash > /etc/bash_completion.d/cr + +#### macOS: + + cr completion bash > $(brew --prefix)/etc/bash_completion.d/cr + +You will need to start a new shell for this setup to take effect. + + +``` +cr completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr completion](cr_completion.md) - Generate the autocompletion script for the specified shell + diff --git a/doc/cr_completion_fish.md b/doc/cr_completion_fish.md new file mode 100644 index 0000000..2828bf2 --- /dev/null +++ b/doc/cr_completion_fish.md @@ -0,0 +1,40 @@ +## cr completion fish + +Generate the autocompletion script for fish + +### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + cr completion fish | source + +To load completions for every new session, execute once: + + cr completion fish > ~/.config/fish/completions/cr.fish + +You will need to start a new shell for this setup to take effect. + + +``` +cr completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr completion](cr_completion.md) - Generate the autocompletion script for the specified shell + diff --git a/doc/cr_completion_powershell.md b/doc/cr_completion_powershell.md new file mode 100644 index 0000000..4dda53e --- /dev/null +++ b/doc/cr_completion_powershell.md @@ -0,0 +1,37 @@ +## cr completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + cr completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +cr completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr completion](cr_completion.md) - Generate the autocompletion script for the specified shell + diff --git a/doc/cr_completion_zsh.md b/doc/cr_completion_zsh.md new file mode 100644 index 0000000..884b7ee --- /dev/null +++ b/doc/cr_completion_zsh.md @@ -0,0 +1,51 @@ +## cr completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +Generate the autocompletion script for the zsh shell. + +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 in your current shell session: + + source <(cr completion zsh); compdef _cr cr + +To load completions for every new session, execute once: + +#### Linux: + + cr completion zsh > "${fpath[1]}/_cr" + +#### macOS: + + cr completion zsh > $(brew --prefix)/share/zsh/site-functions/_cr + +You will need to start a new shell for this setup to take effect. + + +``` +cr completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr completion](cr_completion.md) - Generate the autocompletion script for the specified shell + diff --git a/doc/cr_index.md b/doc/cr_index.md new file mode 100644 index 0000000..48ea1a0 --- /dev/null +++ b/doc/cr_index.md @@ -0,0 +1,44 @@ +## cr index + +Update Helm repo index.yaml for the given GitHub repo + +### Synopsis + + +Update a Helm chart repository index.yaml file based on a the +given GitHub repository's releases. + + +``` +cr index [flags] +``` + +### Options + +``` + -b, --git-base-url string GitHub Base URL (only needed for private GitHub) (default "https://api.github.com/") + -r, --git-repo string GitHub repository + -u, --git-upload-url string GitHub Upload URL (only needed for private GitHub) (default "https://uploads.github.com/") + -h, --help help for index + -i, --index-path string Path to index file (default ".cr-index/index.yaml") + -o, --owner string GitHub username or organization + -p, --package-path string Path to directory with chart packages (default ".cr-release-packages") + --pages-branch string The GitHub pages branch (default "gh-pages") + --pages-index-path string The GitHub pages index path (default "index.yaml") + --pr Create a pull request for index.yaml against the GitHub Pages branch (must not be set if --push is set) + --push Push index.yaml to the GitHub Pages branch (must not be set if --pr is set) + --release-name-template string Go template for computing release names, using chart metadata (default "{{ .Name }}-{{ .Version }}") + --remote string The Git remote used when creating a local worktree for the GitHub Pages branch (default "origin") + -t, --token string GitHub Auth Token (only needed for private repos) +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr](cr.md) - Helm Chart Repos on Github Pages + diff --git a/doc/cr_package.md b/doc/cr_package.md new file mode 100644 index 0000000..1672605 --- /dev/null +++ b/doc/cr_package.md @@ -0,0 +1,39 @@ +## cr package + +Package Helm charts + +### Synopsis + +This command packages a chart into a versioned chart archive file. If a path +is given, this will look at that path for a chart (which must contain a +Chart.yaml file) and then package that directory. + + +If you wish to use advanced packaging options such as creating signed +packages or updating chart dependencies please use "helm package" instead. + +``` +cr package [CHART_PATH] [...] [flags] +``` + +### Options + +``` + -h, --help help for package + --key string Name of the key to use when signing + --keyring string Location of a public keyring (default "~/.gnupg/pubring.gpg") + -p, --package-path string Path to directory with chart packages (default ".cr-release-packages") + --passphrase-file string Location of a file which contains the passphrase for the signing key. Use '-' in order to read from stdin + --sign Use a PGP private key to sign this package +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr](cr.md) - Helm Chart Repos on Github Pages + diff --git a/doc/cr_upload.md b/doc/cr_upload.md new file mode 100644 index 0000000..98e59c6 --- /dev/null +++ b/doc/cr_upload.md @@ -0,0 +1,38 @@ +## cr upload + +Upload Helm chart packages to GitHub Releases + +### Synopsis + +Upload Helm chart packages to GitHub Releases + +``` +cr upload [flags] +``` + +### Options + +``` + -c, --commit string Target commit for release + -b, --git-base-url string GitHub Base URL (only needed for private GitHub) (default "https://api.github.com/") + -r, --git-repo string GitHub repository + -u, --git-upload-url string GitHub Upload URL (only needed for private GitHub) (default "https://uploads.github.com/") + -h, --help help for upload + -o, --owner string GitHub username or organization + -p, --package-path string Path to directory with chart packages (default ".cr-release-packages") + --release-name-template string Go template for computing release names, using chart metadata (default "{{ .Name }}-{{ .Version }}") + --release-notes-file string Markdown file with chart release notes. If it is set to empty string, or the file is not found, the chart description will be used instead + --skip-existing Skip upload if release exists + -t, --token string GitHub Auth Token +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr](cr.md) - Helm Chart Repos on Github Pages + diff --git a/doc/cr_version.md b/doc/cr_version.md new file mode 100644 index 0000000..e06261b --- /dev/null +++ b/doc/cr_version.md @@ -0,0 +1,25 @@ +## cr version + +Print version information + +``` +cr version [flags] +``` + +### Options + +``` + -h, --help help for version + --json print JSON instead of text +``` + +### Options inherited from parent commands + +``` + --config string Config file (default is $HOME/.cr.yaml) +``` + +### SEE ALSO + +* [cr](cr.md) - Helm Chart Repos on Github Pages + diff --git a/go.mod b/go.mod index 9a5557a..32d15af 100644 --- a/go.mod +++ b/go.mod @@ -3,6 +3,7 @@ module github.com/helm/chart-releaser go 1.19 require ( + github.com/MakeNowJust/heredoc v0.0.0-20170808103936-bb23615498cd github.com/Songmu/retry v0.1.0 github.com/google/go-github/v36 v36.0.0 github.com/magefile/mage v1.13.0 @@ -19,7 +20,6 @@ require ( require ( github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect github.com/BurntSushi/toml v1.0.0 // indirect - github.com/MakeNowJust/heredoc v0.0.0-20170808103936-bb23615498cd // indirect github.com/Masterminds/goutils v1.1.1 // indirect github.com/Masterminds/semver/v3 v3.1.1 // indirect github.com/Masterminds/sprig/v3 v3.2.2 // indirect @@ -34,6 +34,7 @@ require ( github.com/chai2010/gettext-go v0.0.0-20160711120539-c6fed771bfd5 // indirect github.com/containerd/containerd v1.6.6 // indirect github.com/containerd/continuity v0.2.2 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect github.com/cyphar/filepath-securejoin v0.2.3 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/docker/cli v20.10.17+incompatible // indirect @@ -114,6 +115,7 @@ require ( github.com/rogpeppe/go-internal v1.8.1 // indirect github.com/rubenv/sql-migrate v1.1.1 // indirect github.com/russross/blackfriday v1.6.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sergi/go-diff v1.2.0 // indirect github.com/shopspring/decimal v1.2.0 // indirect github.com/sirupsen/logrus v1.8.1 // indirect diff --git a/go.sum b/go.sum index cd3b541..6cae3b8 100644 --- a/go.sum +++ b/go.sum @@ -340,6 +340,7 @@ github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwc github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w= github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= @@ -1134,6 +1135,7 @@ github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR github.com/russross/blackfriday v1.6.0 h1:KqfZb0pUVN2lYqZUYRddxF4OR8ZMURnJIG5Y3VRLtww= github.com/russross/blackfriday v1.6.0/go.mod h1:ti0ldHuxg49ri4ksnFxlkCfN+hvslNlmVHqNRXXJNAY= github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +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/ryancurrah/gomodguard v1.2.3/go.mod h1:rYbA/4Tg5c54mV1sv4sQTP5WOPBcoLtnBZ7/TEhXAbg= github.com/ryanrolds/sqlclosecheck v0.3.0/go.mod h1:1gREqxyTGR3lVtpngyFo3hZAgk0KCtEdgEkHwDbigdA= diff --git a/pkg/packager/packager.go b/pkg/packager/packager.go index 0feb1c9..f9f478e 100644 --- a/pkg/packager/packager.go +++ b/pkg/packager/packager.go @@ -19,12 +19,14 @@ import ( "io" "os" "path/filepath" + "strings" "helm.sh/helm/v3/pkg/cli" "helm.sh/helm/v3/pkg/downloader" "helm.sh/helm/v3/pkg/getter" "github.com/helm/chart-releaser/pkg/config" + "github.com/mitchellh/go-homedir" "helm.sh/helm/v3/pkg/action" ) @@ -48,6 +50,16 @@ func (p *Packager) CreatePackages() error { helmClient.DependencyUpdate = true helmClient.Destination = p.config.PackagePath if p.config.Sign { + // expand the ~ to the full home dir + if strings.HasPrefix(p.config.KeyRing, "~") { + dir, err := homedir.Dir() + if err != nil { + panic(err) + } + + p.config.KeyRing = strings.ReplaceAll(p.config.KeyRing, "~", dir) + } + helmClient.Sign = true helmClient.Key = p.config.Key helmClient.Keyring = p.config.KeyRing