Create a chapter for CLI reference doc

[FeynmanZhou]

We can generate the CLI reference doc for Notation CLI using Cobra. I think we can add the CLI reference doc to the Notary documentation, which is similar to https://oras.land/cli_reference/. It will provide fundamental references for users based on the CLI help information.

[zr-msft]

I can add a cli-reference directory to the project for now. From there, i think the next steps are:

1. ENG team adds proper code to notation repo
2. ENG team runs command(s) to generate md doc files
3. ENG team sends md files to me to prepare for hugo publishing
4. I create a PR
5. After merging, ENG team and I sync and have a retro to figure out pain points and create a repeatable (potentially automated) process for new versions of the CLI reference docs

@FeynmanZhou @toddysm what do you think?

[FeynmanZhou]

Yeah. Thanks for the advice. I think it's doable.
We can add the first version of CLI reference docs by following the steps above.
I can also share the steps on how to generate the CLI reference doc based on the Notation CLI repo here.

[zr-msft]

@FeynmanZhou any updates on generating/sharing the initial CLI reference docs?

[FeynmanZhou]

Sorry for the late response. I generated the initial CLI reference docs using Cobra. You can download it from notation-reference-doc.zip.

Here are the steps to generate the CLI reference doc:

1. Clone the Notation CLI repo: https://github.com/notaryproject/notation.git

2. Modify the main.go as follows:

package main

import (
	"os"

	"github.com/notaryproject/notation/cmd/notation/cert"
	"github.com/notaryproject/notation/cmd/notation/policy"
	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc" // Add this line to import cobra doc lib
)

func main() {
	cmd := &cobra.Command{
		Use:          "notation",
		Short:        "Notation - a tool to sign and verify artifacts",
		SilenceUsage: true,
	}
	cmd.AddCommand(
		signCommand(nil),
		verifyCommand(nil),
		listCommand(nil),
		cert.Cmd(),
		policy.Cmd(),
		keyCommand(),
		pluginCommand(),
		loginCommand(nil),
		logoutCommand(nil),
		versionCommand(),
		inspectCommand(nil),
	)
	if err := doc.GenMarkdownTree(cmd, "/notation-reference-doc"); err != nil {    
		os.Exit(1)
	}
}

3. Create a target folder notation-reference-doc that we defined in main.go to store the initial CLI reference docs generated by Cobra.

4. Make sure Golang v1.20.x is installed locally. Then you can run this project in VS Code as follows.

6. The initial CLI reference docs are generated in notation-reference-doc: