CLOUDP-317123 change markup for code blocks in Atlas CLI generated docs

Author: fmenezes

.github/workflows/code-health.yml

@@ -268,8 +268,25 @@ jobs:
         with:
           config: ${{ vars.PERMISSIONS_CONFIG }}
       - uses: actions/checkout@v4
+      - name: Install ShellCheck
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y shellcheck
       - name: Run ShellCheck
-        uses: bewuethr/shellcheck-action@d01912909579c4b1a335828b8fca197fbb8e0aa4
+        run: |
+          # Find all shell scripts excluding specific patterns or directories
+          # Add exclusions by adding more -not -path patterns as needed
+          find . -name "*.sh" \
+            -not -path "./.git/*" \
+            -not -path "./docs/*" \
+            -print0 | xargs -0 shellcheck --format=gcc
+          
+          # Also check for shell scripts without .sh extension
+          find . -type f -exec grep -l '^#!/bin/\(ba\)\?sh' {} \; \
+            | grep -v '\.sh$' \
+            | grep -v './.git/' \
+            | grep -v './docs/' \
+            | xargs -r shellcheck --format=gcc
   tidy:
     runs-on: ubuntu-latest
     steps:

build/ci/check-licenses.sh

@@ -20,6 +20,7 @@ find_files() {
 	find . -not \( \
 		\( \
 		-wholename '*mock*' \
+		-o -wholename '*docs*' \
 		-o -wholename '*third_party*' \
 		\) -prune \
 		\) \

tools/cmd/docs/main.go

@@ -25,13 +25,18 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const (
+	docsPath     = "./docs/command"
+	includesPath = "./docs/command/includes"
+)
+
 func main() {
-	if err := os.RemoveAll("./docs/command"); err != nil {
+	if err := os.RemoveAll(docsPath); err != nil {
 		log.Fatal(err)
 	}
 
 	const docsPermissions = 0766
-	if err := os.MkdirAll("./docs/command", docsPermissions); err != nil {
+	if err := os.MkdirAll(includesPath, docsPermissions); err != nil {
 		log.Fatal(err)
 	}
 
@@ -43,7 +48,7 @@ func main() {
 		log.Fatal(err)
 	}
 
-	if err := cobra2snooty.GenTreeDocs(atlasBuilder, "./docs/command", cobra2snooty.WithCustomExampleFormatter(func(w io.Writer, cmd *cobra.Command) {
+	if err := cobra2snooty.GenTreeDocs(atlasBuilder, docsPath, cobra2snooty.WithCustomExampleFormatter(func(w io.Writer, cmd *cobra.Command) {
 		if isAPICommand(cmd) {
 			_, _ = w.Write([]byte(cmd.Example))
 			return

tools/cmd/docs/transformations.go

@@ -17,6 +17,8 @@ package main
 import (
 	"cmp"
 	_ "embed"
+	"fmt"
+	"os"
 	"regexp"
 	"slices"
 	"strconv"
@@ -138,9 +140,9 @@ func countExamples(examples map[string][]metadatatypes.Example) int {
 	return count
 }
 
-func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Example) string { //nolint:gocyclo // code used by CI
+func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Example) (string, error) { //nolint:gocyclo // cyclomatic complexity is high, but the code is readable and only used for documentation generation
 	if len(examples) == 0 {
-		return ""
+		return "", nil
 	}
 
 	var sb strings.Builder
@@ -159,6 +161,11 @@ func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Examp
 	exampleIdx := 0
 	for _, version := range sortedKeys(examples) {
 		for _, ex := range examples[version] {
+			source := strings.ToLower(strings.ReplaceAll(ex.Source, " ", "_"))
+			if ex.Source == "-" {
+				source = "default"
+			}
+
 			if tabs {
 				sb.WriteString("   .. tab:: ")
 				if ex.Name == "" {
@@ -174,43 +181,36 @@ func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Examp
 				sb.WriteString("\n      :tabid: ")
 				sb.WriteString(version)
 				sb.WriteString("_")
-				if ex.Source == "-" {
-					sb.WriteString("default")
-				} else {
-					sb.WriteString(strings.ToLower(strings.ReplaceAll(ex.Source, " ", "_")))
-				}
+				sb.WriteString(source)
 				sb.WriteString("\n\n")
 			}
 
 			if ex.Value != "" {
 				if tabs {
 					sb.WriteString("      ")
 				}
-				sb.WriteString("Create the file below and save it as ``payload.json``\n\n")
+				sb.WriteString(ex.Description + "\n\n")
 
 				if tabs {
 					sb.WriteString("      ")
 				}
-				sb.WriteString(".. code-block::\n\n")
-				if ex.Description != "" {
-					if tabs {
-						sb.WriteString("      ")
-					}
-					sb.WriteString("   # " + ex.Description + "\n")
-				}
+				sb.WriteString("Create the file below and save it as ``payload.json``\n\n")
 
-				lines := strings.Split(ex.Value, "\n")
-				for _, line := range lines {
-					if tabs {
-						sb.WriteString("      ")
-					}
+				includePayloadFileName := fmt.Sprintf("%s-%s-%s-payload.json", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)
+				const permissions = 0600
+				err := os.WriteFile(fmt.Sprintf("%s/%s", includesPath, includePayloadFileName), []byte(ex.Value), permissions)
+				if err != nil {
+					return "", fmt.Errorf("failed to write payload file %s: %w", includePayloadFileName, err)
+				}
 
-					sb.WriteString("   " + line + "\n")
+				if tabs {
+					sb.WriteString("      ")
 				}
+				sb.WriteString(fmt.Sprintf("   literalinclude:: /includes/%s\n", includePayloadFileName))
 				if tabs {
-					sb.WriteString("\n      ")
+					sb.WriteString("      ")
 				}
-				sb.WriteString(".. Code end marker, please don't delete this comment\n\n")
+				sb.WriteString("   :language: shell\n")
 				if tabs {
 					sb.WriteString("      ")
 				}
@@ -219,36 +219,34 @@ func buildExamples(cmd *cobra.Command, examples map[string][]metadatatypes.Examp
 				sb.WriteString("      ")
 			}
 
-			if tabs {
-				sb.WriteString("      ")
-			}
-			sb.WriteString(".. code-block::\n\n")
-			if tabs {
-				sb.WriteString("      ")
+			var cmdSB strings.Builder
+
+			cmdSB.WriteString(cmd.CommandPath())
+			cmdSB.WriteString(" --version " + version)
+			for _, flagName := range sortedKeys(ex.Flags) {
+				cmdSB.WriteString(" --" + flagName + " " + ex.Flags[flagName])
 			}
-			if ex.Description != "" {
-				sb.WriteString("   # " + ex.Description + "\n")
+			cmdSB.WriteString("\n")
+
+			includeCommandFileName := fmt.Sprintf("%s-%s-%s.sh", strings.ReplaceAll(cmd.CommandPath(), " ", "-"), version, source)
+			const permissions = 0600
+			err := os.WriteFile(fmt.Sprintf("%s/%s", includesPath, includeCommandFileName), []byte(cmdSB.String()), permissions)
+			if err != nil {
+				return "", fmt.Errorf("failed to write file %s: %w", includeCommandFileName, err)
 			}
+
 			if tabs {
 				sb.WriteString("      ")
 			}
-			sb.WriteString("   " + cmd.CommandPath())
-			sb.WriteString(" --version " + version)
-			if ex.Value != "" {
-				sb.WriteString(" --file payload.json")
-			}
-			for _, flagName := range sortedKeys(ex.Flags) {
-				sb.WriteString(" --" + flagName + " " + ex.Flags[flagName])
-			}
-			sb.WriteString("\n\n")
+			sb.WriteString(fmt.Sprintf("literalinclude:: /includes/%s\n", includeCommandFileName))
 			if tabs {
 				sb.WriteString("      ")
 			}
-			sb.WriteString(".. Code end marker, please don't delete this comment\n\n")
+			sb.WriteString(":language: shell\n")
 		}
 	}
 
-	return sb.String()
+	return sb.String(), nil
 }
 
 func updateExamples(cmd *cobra.Command) error {
@@ -262,9 +260,10 @@ func updateExamples(cmd *cobra.Command) error {
 		return nil
 	}
 
-	cmd.Example = buildExamples(cmd, cmdMetadata.Examples)
+	var err error
+	cmd.Example, err = buildExamples(cmd, cmdMetadata.Examples)
 
-	return nil
+	return err
 }
 
 func removeCommandsWithOnlyPrivatePreview(cmd *cobra.Command) {