diff --git a/.github/workflows/update-docs-cli.yml b/.github/workflows/update-docs-cli.yml new file mode 100644 index 000000000..ca4220986 --- /dev/null +++ b/.github/workflows/update-docs-cli.yml @@ -0,0 +1,77 @@ +# Copyright The Notary Project 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 +# +# http://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. + +name: update-cli-docs + +on: + push: + branches: + - main + paths: + - 'cmd/notation/**' + +permissions: + contents: write + pull-requests: write + +jobs: + update-cli-docs: + name: Update CLI Documentation + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + + - name: Set up Go + uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5.5.0 + with: + go-version-file: 'go.mod' + check-latest: true + + - name: Generate CLI documentation + run: make cli-docs + + - name: Get commit metadata + id: commit-metadata + run: | + echo "sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT + echo "date=$(git show -s --format=%ci HEAD)" >> $GITHUB_OUTPUT + echo "author=$(git show -s --format='%an' HEAD)" >> $GITHUB_OUTPUT + + - name: Create pull request + uses: peter-evans/create-pull-request@5618a875e3f59ed17e5d3bf7a6fa0ee3ac66c3e3 # v7.1.0 + with: + commit-message: | + docs: auto-generate CLI reference documentation + + Generated from commit ${{ steps.commit-metadata.outputs.sha }} + branch: auto-update-cli-docs + delete-branch: true + title: 'docs: auto-update CLI reference documentation' + body: | + ## Description + + This PR updates the CLI reference documentation to reflect changes in the command-line interface. + + ## Source Commit + + - **SHA**: ${{ steps.commit-metadata.outputs.sha }} + - **Date**: ${{ steps.commit-metadata.outputs.date }} + - **Author**: ${{ steps.commit-metadata.outputs.author }} + + --- + *This PR was automatically generated by the [update-cli-docs workflow](https://github.com/${{ github.repository }}/blob/main/.github/workflows/update-docs-cli.yml).* + labels: | + documentation + automated pr + draft: false diff --git a/.gitignore b/.gitignore index b8aae6046..dd1e9da35 100644 --- a/.gitignore +++ b/.gitignore @@ -22,3 +22,4 @@ test/e2e/coverage.txt **/covcounters.* **/covmeta.* dist/ +docs/cli/ diff --git a/Makefile b/Makefile index a2e8fe596..4ebb6c1b7 100644 --- a/Makefile +++ b/Makefile @@ -98,3 +98,8 @@ install-notation: bin/notation ## installs the notation cli .PHONY: install-docker-% install-docker-%: bin/docker-% cp $< ~/.docker/cli-plugins/ + +.PHONY: cli-docs +cli-docs: ## generate CLI reference documentation + @echo "Generating CLI documentation..." + @go run -tags=gendoc ./cmd/notation ./docs/cli diff --git a/cmd/notation/doc.go b/cmd/notation/doc.go new file mode 100644 index 000000000..9a8e4abd2 --- /dev/null +++ b/cmd/notation/doc.go @@ -0,0 +1,46 @@ +//go:build gendoc + +// Copyright The Notary Project 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 +// +// http://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 main + +import ( + "fmt" + "os" + + "github.com/spf13/cobra/doc" +) + +func main() { + if len(os.Args) < 2 { + fmt.Fprintf(os.Stderr, "Usage: %s \n", os.Args[0]) + os.Exit(1) + } + + outputDir := os.Args[1] + + if err := os.MkdirAll(outputDir, 0755); err != nil { + fmt.Fprintf(os.Stderr, "Error creating output directory: %v\n", err) + os.Exit(1) + } + + cmd := NewRootCommand() + + if err := doc.GenMarkdownTree(cmd, outputDir); err != nil { + fmt.Fprintf(os.Stderr, "Error generating documentation: %v\n", err) + os.Exit(1) + } + + fmt.Printf("Successfully generated CLI documentation in %s\n", outputDir) +} diff --git a/cmd/notation/main.go b/cmd/notation/main.go index b88661a02..0ac5270cb 100644 --- a/cmd/notation/main.go +++ b/cmd/notation/main.go @@ -1,3 +1,5 @@ +//go:build !gendoc + // Copyright The Notary Project Authors. // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -17,58 +19,10 @@ import ( "context" "os" "os/signal" - - "github.com/notaryproject/notation-go/dir" - "github.com/notaryproject/notation/v2/cmd/notation/blob" - "github.com/notaryproject/notation/v2/cmd/notation/cert" - "github.com/notaryproject/notation/v2/cmd/notation/internal/flag" - "github.com/notaryproject/notation/v2/cmd/notation/plugin" - "github.com/notaryproject/notation/v2/cmd/notation/policy" - "github.com/spf13/cobra" ) func run() error { - cmd := &cobra.Command{ - Use: "notation", - Short: "Notation - a tool to sign and verify artifacts", - SilenceUsage: true, - PersistentPreRun: func(cmd *cobra.Command, args []string) { - // unset registry credentials after read the value from environment - // to avoid leaking credentials - os.Unsetenv(flag.EnvironmentUsername) - os.Unsetenv(flag.EnvironmentPassword) - - // update Notation config directory - if notationConfig := os.Getenv("NOTATION_CONFIG"); notationConfig != "" { - dir.UserConfigDir = notationConfig - } - - // update Notation cache directory - if notationCache := os.Getenv("NOTATION_CACHE"); notationCache != "" { - dir.UserCacheDir = notationCache - } - - // update Notation Libexec directory (for plugins) - if notationLibexec := os.Getenv("NOTATION_LIBEXEC"); notationLibexec != "" { - dir.UserLibexecDir = notationLibexec - } - }, - } - cmd.AddCommand( - blob.Cmd(), - signCommand(nil), - verifyCommand(nil), - listCommand(nil), - cert.Cmd(), - policy.Cmd(), - keyCommand(), - plugin.Cmd(), - loginCommand(nil), - logoutCommand(nil), - versionCommand(), - inspectCommand(nil), - ) - + cmd := NewRootCommand() ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt) defer cancel() return cmd.ExecuteContext(ctx) diff --git a/cmd/notation/root.go b/cmd/notation/root.go new file mode 100644 index 000000000..5f83bb369 --- /dev/null +++ b/cmd/notation/root.go @@ -0,0 +1,70 @@ +// Copyright The Notary Project 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 +// +// http://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 main + +import ( + "os" + + "github.com/notaryproject/notation-go/dir" + "github.com/notaryproject/notation/v2/cmd/notation/blob" + "github.com/notaryproject/notation/v2/cmd/notation/cert" + "github.com/notaryproject/notation/v2/cmd/notation/internal/flag" + "github.com/notaryproject/notation/v2/cmd/notation/plugin" + "github.com/notaryproject/notation/v2/cmd/notation/policy" + "github.com/spf13/cobra" +) + +func NewRootCommand() *cobra.Command { + cmd := &cobra.Command{ + Use: "notation", + Short: "Notation - a tool to sign and verify artifacts", + SilenceUsage: true, + PersistentPreRun: func(cmd *cobra.Command, args []string) { + // unset registry credentials after read the value from environment + // to avoid leaking credentials + os.Unsetenv(flag.EnvironmentUsername) + os.Unsetenv(flag.EnvironmentPassword) + + // update Notation config directory + if notationConfig := os.Getenv("NOTATION_CONFIG"); notationConfig != "" { + dir.UserConfigDir = notationConfig + } + + // update Notation cache directory + if notationCache := os.Getenv("NOTATION_CACHE"); notationCache != "" { + dir.UserCacheDir = notationCache + } + + // update Notation Libexec directory (for plugins) + if notationLibexec := os.Getenv("NOTATION_LIBEXEC"); notationLibexec != "" { + dir.UserLibexecDir = notationLibexec + } + }, + } + cmd.AddCommand( + blob.Cmd(), + signCommand(nil), + verifyCommand(nil), + listCommand(nil), + cert.Cmd(), + policy.Cmd(), + keyCommand(), + plugin.Cmd(), + loginCommand(nil), + logoutCommand(nil), + versionCommand(), + inspectCommand(nil), + ) + return cmd +} diff --git a/go.mod b/go.mod index 8274fcf13..28cb01866 100644 --- a/go.mod +++ b/go.mod @@ -10,22 +10,25 @@ require ( github.com/opencontainers/go-digest v1.0.0 github.com/opencontainers/image-spec v1.1.1 github.com/sirupsen/logrus v1.9.3 - github.com/spf13/cobra v1.9.1 - github.com/spf13/pflag v1.0.7 + github.com/spf13/cobra v1.10.2 + github.com/spf13/pflag v1.0.9 golang.org/x/term v0.34.0 oras.land/oras-go/v2 v2.6.0 ) require ( github.com/Azure/go-ntlmssp v0.0.0-20221128193559-754e69321358 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect github.com/fxamacker/cbor/v2 v2.8.0 // indirect github.com/go-asn1-ber/asn1-ber v1.5.8-0.20250403174932-29230038a667 // indirect github.com/go-ldap/ldap/v3 v3.4.11 // indirect github.com/golang-jwt/jwt/v4 v4.5.2 // indirect github.com/google/uuid v1.6.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/veraison/go-cose v1.3.0 // indirect github.com/x448/float16 v0.8.4 // indirect + go.yaml.in/yaml/v3 v3.0.4 // indirect golang.org/x/crypto v0.38.0 // indirect golang.org/x/mod v0.24.0 // indirect golang.org/x/sync v0.14.0 // indirect diff --git a/go.sum b/go.sum index 6d5698726..e4ae49659 100644 --- a/go.sum +++ b/go.sum @@ -2,6 +2,7 @@ github.com/Azure/go-ntlmssp v0.0.0-20221128193559-754e69321358 h1:mFRzDkZVAjdal+ github.com/Azure/go-ntlmssp v0.0.0-20221128193559-754e69321358/go.mod h1:chxPXzSsl7ZWRAuOIE23GDNzjWuZquvFlgA8xmpunjU= github.com/alexbrainman/sspi v0.0.0-20231016080023-1a75b4708caa h1:LHTHcTQiSGT7VVbI0o4wBRNQIgn917usHWOd6VAffYI= github.com/alexbrainman/sspi v0.0.0-20231016080023-1a75b4708caa/go.mod h1:cEWa1LVoE5KvSD9ONXsZrj0z6KqySlCCNKHlLzbqAt4= +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/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= @@ -46,14 +47,14 @@ github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJw github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +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/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ= github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= -github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo= -github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0= -github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/spf13/pflag v1.0.7 h1:vN6T9TfwStFPFM5XzjsvmzZkLuaLX+HS+0SeFLRgU6M= -github.com/spf13/pflag v1.0.7/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +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= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk= @@ -62,6 +63,8 @@ github.com/veraison/go-cose v1.3.0 h1:2/H5w8kdSpQJyVtIhx8gmwPJ2uSz1PkyWFx0idbd7r github.com/veraison/go-cose v1.3.0/go.mod h1:df09OV91aHoQWLmy1KsDdYiagtXgyAwAl8vFeFn1gMc= github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM= github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg= +go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc= +go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= golang.org/x/crypto v0.38.0 h1:jt+WWG8IZlBnVbomuhg2Mdq0+BBQaHbtqHEFEigjUV8= golang.org/x/crypto v0.38.0/go.mod h1:MvrbAqul58NNYPKnOra203SB9vpuZW0e+RRZV+Ggqjw= golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU= @@ -75,6 +78,7 @@ golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI= golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k= golang.org/x/term v0.34.0 h1:O/2T7POpk0ZZ7MAzMeWFSg6S5IpWd/RXDlM9hgM3DR4= golang.org/x/term v0.34.0/go.mod h1:5jC53AEywhIVebHgPVeg0mj8OD3VO9OzclacVrqpaAw= +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= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=