Generate Markdown docs for cosign (sigstore#839)

Signed-off-by: Jason Hall <jasonhall@redhat.com>

.gitattributes

@@ -0,0 +1,5 @@
+# This file is documented at https://git-scm.com/docs/gitattributes.
+# Linguist-specific attributes are documented at
+# https://github.com/github/linguist.
+
+doc/cosign*.md linguist-generated=true

.github/workflows/verify-docgen.yaml

@@ -0,0 +1,30 @@
+#
+# Copyright 2021 The Sigstore 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: Docgen
+
+on: [push, pull_request]
+
+jobs:
+  docgen:
+    name: Verify Docgen
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-go@v2
+        with:
+          go-version: '1.17.x'
+      - run: ./cmd/help/verify.sh

cmd/cosign/cli/commands.go

@@ -31,7 +31,8 @@ var (
 
 func New() *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "cosign",
+		Use:               "cosign",
+		DisableAutoGenTag: true,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			if ro.OutputFile != "" {
 				out, err := os.Create(ro.OutputFile)

cmd/cosign/main.go

@@ -1,4 +1,3 @@
-//
 // Copyright 2021 The Sigstore Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");

cmd/help/main.go

@@ -0,0 +1,42 @@
+// Copyright 2021 The Sigstore 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/sigstore/cosign/cmd/cosign/cli"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	var dir string
+	root := &cobra.Command{
+		Use:          "gendoc",
+		Short:        "Generate cosign's help docs",
+		SilenceUsage: true,
+		Args:         cobra.NoArgs,
+		RunE: func(*cobra.Command, []string) error {
+			return doc.GenMarkdownTree(cli.New(), dir)
+		},
+	}
+	root.Flags().StringVarP(&dir, "dir", "d", "doc", "Path to directory in which to generate docs")
+	if err := root.Execute(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}

cmd/help/verify.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+# Copyright 2021 The Sigstore 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.
+
+set -e
+
+# Verify that generated Markdown docs are up-to-date.
+tmpdir=$(mktemp -d)
+go run cmd/help/main.go --dir "$tmpdir"
+echo "###########################################"
+echo "If diffs are found, run: go run ./cmd/help/"
+echo "###########################################"
+diff -Naur "$tmpdir" doc/