generating docs for subcommands§

Author: timbastin

cmd/doc-gen/main.go

@@ -7,6 +7,7 @@ import (
 	"regexp"
 
 	"github.com/l3montree-dev/devguard/cmd/devguard-scanner/commands"
+	"github.com/spf13/cobra"
 	"github.com/spf13/cobra/doc"
 )
 
@@ -58,6 +59,46 @@ func postProcessMarkdown(filename string) {
 	}
 }
 
+// generateDocsForCommand recursively generates docs for a command and all its subcommands
+func generateDocsForCommand(cmd *cobra.Command, outDir string) {
+	identity := func(s string) string { return s }
+	emptyStr := func(s string) string { return "" }
+
+	// Print to stdout first
+	err := doc.GenMarkdownCustom(cmd, os.Stdout, emptyStr)
+	if err != nil {
+		slog.Error("could not generate markdown documentation", "err", err, "cmd", cmd.Name())
+		return
+	}
+
+	// Generate markdown for this command
+	filename := filepath.Join(outDir, cmd.Name()+".md")
+	f, err := os.Create(filename)
+	if err != nil {
+		slog.Error("could not create file", "err", err, "file", filename)
+		return
+	}
+
+	err = doc.GenMarkdownCustom(cmd, f, identity)
+	f.Close()
+	if err != nil {
+		slog.Error("could not write markdown", "err", err, "file", filename)
+		return
+	}
+
+	// Post-process the file
+	postProcessMarkdown(filename)
+
+	// Recursively generate docs for subcommands
+	for _, subCmd := range cmd.Commands() {
+		// Skip hidden commands
+		if subCmd.Hidden {
+			continue
+		}
+		generateDocsForCommand(subCmd, outDir)
+	}
+}
+
 func main() {
 	// check if no arguments were provided
 	if len(os.Args) < 2 {
@@ -67,38 +108,8 @@ func main() {
 			return
 		}
 
-		// Generate docs with custom settings to disable "SEE ALSO" section
+		// Generate root command doc first
 		identity := func(s string) string { return s }
-		emptyStr := func(s string) string { return "" }
-
-		for _, cmd := range commands.RootCmd.Commands() {
-			// Generate markdown for each command
-			err := doc.GenMarkdownCustom(cmd, os.Stdout, emptyStr)
-			if err != nil {
-				slog.Error("could not generate markdown documentation", "err", err, "cmd", cmd.Name())
-				continue
-			}
-
-			// Write to file
-			filename := filepath.Join("docs/scanner", cmd.Name()+".md")
-			f, err := os.Create(filename)
-			if err != nil {
-				slog.Error("could not create file", "err", err, "file", filename)
-				continue
-			}
-
-			err = doc.GenMarkdownCustom(cmd, f, identity)
-			f.Close()
-			if err != nil {
-				slog.Error("could not write markdown", "err", err, "file", filename)
-				continue
-			}
-
-			// Post-process: remove "devguard-scanner " prefix from headline and remove SEE ALSO
-			postProcessMarkdown(filename)
-		}
-
-		// Generate root command doc separately
 		rootFilename := filepath.Join("docs/scanner", "devguard-scanner.md")
 		rootFile, err := os.Create(rootFilename)
 		if err != nil {
@@ -113,6 +124,15 @@ func main() {
 			}
 		}
 
+		// Generate docs for all commands (including nested subcommands)
+		for _, cmd := range commands.RootCmd.Commands() {
+			// Skip hidden commands
+			if cmd.Hidden {
+				continue
+			}
+			generateDocsForCommand(cmd, "docs/scanner")
+		}
+
 		return
 	}
 }

docs/scanner/fetch-links.md

@@ -0,0 +1,28 @@
+## intoto fetch-links
+
+Fetch links for a given supply chain
+
+```shell
+devguard-scanner intoto fetch-links [flags]
+```
+
+### Options
+
+```shell
+      --apiUrl string          The devguard api url (default "api.devguard.org")
+      --assetName string       The asset name to use
+  -h, --help                   help for fetch-links
+      --supplyChainId string   The supply chain id to fetch the links for
+      --token string           The token to use to authenticate with the devguard api
+```
+
+### Options inherited from parent commands
+
+```shell
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+```

docs/scanner/help.md

@@ -0,0 +1,33 @@
+## intoto help
+
+Help about any command
+
+### Synopsis
+
+Help provides help for any command in the application.
+Simply type intoto help [path to command] for full details.
+
+```shell
+devguard-scanner intoto help [command] [flags]
+```
+
+### Options
+
+```shell
+  -h, --help   help for help
+```
+
+### Options inherited from parent commands
+
+```shell
+      --apiUrl string            The devguard api url
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+      --supplyChainId string     The supply chain id to use. If empty, tries to extract the current commit hash.
+      --token string             The token to use for in-toto
+```

docs/scanner/run.md

@@ -0,0 +1,29 @@
+## intoto run
+
+
+
+```shell
+devguard-scanner intoto run [flags]
+```
+
+### Options
+
+```shell
+      --apiUrl string                    The URL of the devguard API
+  -h, --help                             help for run
+      --step string                      The step to run
+      --supplyChainOutputDigest string   If defined, sends this digest to devguard. This should be the digest of the whole supply chain.
+```
+
+### Options inherited from parent commands
+
+```shell
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --supplyChainId string     The supply chain id to use. If empty, tries to extract the current commit hash.
+      --token string             The token to use for in-toto
+```

docs/scanner/setup.md

@@ -0,0 +1,28 @@
+## intoto setup
+
+Setup in-toto
+
+```shell
+devguard-scanner intoto setup [flags]
+```
+
+### Options
+
+```shell
+  -h, --help   help for setup
+```
+
+### Options inherited from parent commands
+
+```shell
+      --apiUrl string            The devguard api url
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+      --supplyChainId string     The supply chain id to use. If empty, tries to extract the current commit hash.
+      --token string             The token to use for in-toto
+```

docs/scanner/start.md

@@ -0,0 +1,28 @@
+## intoto start
+
+Start in-toto recording
+
+```shell
+devguard-scanner intoto start [flags]
+```
+
+### Options
+
+```shell
+  -h, --help   help for start
+```
+
+### Options inherited from parent commands
+
+```shell
+      --apiUrl string            The devguard api url
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+      --supplyChainId string     The supply chain id to use. If empty, tries to extract the current commit hash.
+      --token string             The token to use for in-toto
+```

docs/scanner/stop.md

@@ -0,0 +1,29 @@
+## intoto stop
+
+Stop in-toto recording
+
+```shell
+devguard-scanner intoto stop [flags]
+```
+
+### Options
+
+```shell
+  -h, --help            help for stop
+      --output string   The output file name. Default is the <step>.link.json name
+```
+
+### Options inherited from parent commands
+
+```shell
+      --apiUrl string            The devguard api url
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+      --supplyChainId string     The supply chain id to use. If empty, tries to extract the current commit hash.
+      --token string             The token to use for in-toto
+```

docs/scanner/verify.md

@@ -0,0 +1,29 @@
+## intoto verify
+
+Verify a supply chain
+
+```shell
+devguard-scanner intoto verify [flags]
+```
+
+### Options
+
+```shell
+  -h, --help                   help for verify
+      --layoutKey string       Path to the layout key
+      --supplyChainId string   Supply chain ID
+      --token string           Token
+```
+
+### Options inherited from parent commands
+
+```shell
+      --apiUrl string            The devguard api url
+      --assetName string         The asset name to use
+      --generateSlsaProvenance   Generate SLSA provenance for the in-toto link. The provenance will be stored in <stepname>.provenance.json. It will be signed using the intoto token.
+      --ignore stringArray       The ignore patterns for the in-toto link (default [.git/**/*])
+  -l, --logLevel string          Set the log level. Options: debug, info, warn, error (default "info")
+      --materials stringArray    The materials to include in the in-toto link. Default is the current directory (default [.])
+      --products stringArray     The products to include in the in-toto link. Default is the current directory (default [.])
+      --step string              The name of the in-toto link
+```