Add CLI documentation

.github/workflows/docs.yaml

@@ -9,14 +9,15 @@ on:
       - internal/api/pb/**
       # The TF provider docs may change in other ways (e.g. schema), but this should be ok in most cases
       - internal/terraform/examples/**
+      - internal/cli/**/commands.go
   pull_request:
     branches:
       - main
     paths:
       - docs/**
       - internal/api/pb/**
       - internal/terraform/examples/**
-
+      - internal/cli/**/commands.go
 
 jobs:
   build:
@@ -56,6 +57,8 @@ jobs:
         run: task tf-docs-generate
       - name: Generate protobuf docs
         run: task pb-docs-generate
+      - name: Generate CLI docs
+        run: task cli-docs-generate
 
       - name: Install dependencies
         run: npm ci

Taskfile-cli-docs.yml

@@ -0,0 +1,149 @@
+# https://taskfile.dev
+
+version: '3'
+
+tasks:
+  cli-docs-generate:
+    desc: Generate CLI documentation in docs/
+    env:
+      OUT_DIR: ./docs/docs/cli/reference
+    cmds:
+      - |
+        set -euo pipefail
+
+        mkdir -p "$OUT_DIR"
+
+        function generate_docs() {
+          local path=("$@")
+          local filename="${path[*]}"
+          local cmd_name="${path[*]}"
+          local help_output
+
+          help_output=$(go run ./cmd/bx2cloud "${path[@]}" -h 2>&1)
+
+          local subcmds
+          subcmds=$(echo "$help_output" | awk '
+            /subcommands:$/ { in_section=1; next }
+            /^[^[:space:]]+.*:$/ { in_section=0 }
+            in_section { gsub(/^[[:space:]]+/, ""); print }
+          ')
+
+          if [[ ${#path[@]} -eq 0 ]]; then
+            echo "Extracting top-level help: bx2cloud"
+            echo "$help_output" > "$OUT_DIR/global.md"
+          elif [[ -z "$subcmds" ]]; then
+            local file_path="${OUT_DIR}/$(echo "${filename}" | tr ' ' '_').md"
+            echo "Extracting help for command: bx2cloud ${cmd_name}"
+            echo "$help_output" > "$file_path"
+          fi
+
+          while read -r sub; do
+            [[ -z "$sub" ]] && continue
+            generate_docs "${path[@]}" "$sub"
+          done <<< "$subcmds"
+        }
+
+        generate_docs
+      - |
+        set -euo pipefail
+
+        generate_flags_table() {
+          local source_file="$1"
+          local flags_block
+          flags_block=$(awk '/^flags:/{found=1; next} found' "$source_file")
+          if [[ -n "$flags_block" && "$(echo "$flags_block" | xargs | tr '[:upper:]' '[:lower:]')" != "none" ]]; then
+            echo "## Flags"
+            echo ""
+            echo "| Flag | Type | Description | Default |"
+            echo "|------|------|-------------|---------|"
+            printf "%s\n" "$flags_block" | awk '
+              function output_flag() {
+                  if (name == "") return;
+                  default_val = "";
+                  if (match(description, /\(default "([^"]*)"\)/, m)) {
+                      default_val = m[1];
+                      gsub(/\(default "[^"]*"\)/, "", description);
+                  } else if (match(description, /\(default ([^)]*)\)/, m)) {
+                      default_val = m[1];
+                      gsub(/\(default [^)]*\)/, "", description);
+                  }
+                  gsub(/^[ \t]+|[ \t]+$/, "", description);
+                  gsub(/<[^>]+>/, "`&`", description);
+                  type_cell = (type == "") ? "" : "`" type "`";
+                  printf "| `%s` | %s | %s | %s |\n", name, type_cell, description, default_val;
+              }
+              /^[[:space:]]*-/ {
+                  output_flag();
+                  name = $1;
+                  type = (NF > 1) ? $2 : "";
+                  description = "";
+                  next;
+              }
+              /^[[:space:]]{2,}/ {
+                  line_content = $0;
+                  gsub(/^[ \t]+/, "", line_content);
+                  description = (description == "") ? line_content : description " " line_content;
+              }
+              END { output_flag(); }
+            '
+          fi
+        }
+
+        for file in "$OUT_DIR"/*.md; do
+          echo "Processing $file..."
+          {
+            if [[ "$(basename "$file")" == "global.md" ]]; then
+              echo "---"
+              echo "title: \"Global flags\""
+              echo "sidebar_position: 1"
+              echo "custom_edit_url: null"
+              echo "---"
+              echo "# Global flags"
+              echo ""
+              echo "These flags can be used with any command."
+              echo ""
+              echo "## Usage"
+              echo ""
+              echo "\`\`\`"
+              echo "bx2cloud -t 127.0.0.1:9876 version"
+              echo "\`\`\`"
+              echo ""
+            else
+              content=$(<"$file")
+              cmd_line=$(echo "$content" | grep -m 1 '^bx2cloud .*:') || {
+                echo "❌ Error: Could not find 'bx2cloud command:' line in '$file'. Aborting." >&2
+                exit 1
+              }
+              cmd=$(echo "$cmd_line" | cut -d':' -f1)
+              desc=$(echo "$cmd_line" | cut -d':' -f2- | sed 's/^ *//')
+              usage_line=$(echo "$content" | grep '^usage:' || echo "")
+              usage_command=""
+              if [[ -n "$usage_line" ]]; then
+                usage_command=$(echo "$usage_line" | cut -d':' -f2- | sed 's/^ *//')
+              fi
+              echo "---"
+              echo "title: \"${cmd#bx2cloud }\""
+              echo "custom_edit_url: null"
+              echo "---"
+              echo "# $cmd"
+              echo ""
+              echo "$desc"
+              echo ""
+              if [[ -n "$usage_command" ]]; then
+                echo "## Usage"
+                echo ""
+                echo "\`\`\`"
+                echo "$usage_command"
+                echo "\`\`\`"
+                echo ""
+              fi
+            fi
+            generate_flags_table "$file"
+          } > "$file.tmp"
+          if [[ -s "$file.tmp" ]]; then
+              mv "$file.tmp" "$file"
+          else
+              rm -f "$file.tmp"
+          fi
+        done
+      - "echo '{\"position\": 99, \"label\": \"Reference\", \"link\": { \"type\": \"generated-index\", \"title\": \"CLI reference\", \"slug\": \"cli/reference\" }}' > $OUT_DIR/_category_.json"

Taskfile.yml

@@ -2,7 +2,18 @@
 
 version: "3"
 
+includes:
+  cli-docs:
+    taskfile: ./Taskfile-cli-docs.yml
+    flatten: true
+
 tasks:
+  docs-generate:
+    desc: Generate documentation in docs/
+    deps:
+      - pb-docs-generate
+      - tf-docs-generate
+      - cli-docs-generate
   pb-generate:
     desc: Generate Go protobuf and gRPC code
     dir: internal/api/pb
@@ -55,23 +66,30 @@ tasks:
   tf-docs-generate:
     desc: Generate Terraform provider documentation in docs/
     cmds:
-      - go run -modfile tools/go.mod github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-dir ./cmd/terraform-provider-bx2cloud --provider-name bx2cloud --examples-dir ../../internal/terraform/examples --rendered-website-dir ../../docs/docs/terraform/autogenerated
+      - go run -modfile tools/go.mod 
+        github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate 
+        --provider-dir ./cmd/terraform-provider-bx2cloud 
+        --provider-name bx2cloud 
+        --examples-dir ../../internal/terraform/examples 
+        --rendered-website-dir ../../docs/docs/terraform/reference
       - task: tf-docs-docusaurify
 
   tf-docs-docusaurify:
     desc: Adjust documentation generated by tfplugindocs to docusaurus supported attributed
+    env:
+      OUT_DIR: ./docs/docs/terraform/reference
     vars:
       DATA_SOURCES:
-        sh: find docs/docs/terraform/autogenerated/data-sources -name '*.md'
+        sh: find ./docs/docs/terraform/reference/data-sources -name '*.md'
       RESOURCES:
-        sh: find docs/docs/terraform/autogenerated/resources -name '*.md'
+        sh: find ./docs/docs/terraform/reference/resources -name '*.md'
     cmds:
-      - "echo '{\"position\": 99, \"label\": \"Reference\", \"link\": { \"type\": \"generated-index\", \"title\": \"Terraform provider reference\" }}' > ./docs/docs/terraform/autogenerated/_category_.json"
-      - "mv ./docs/docs/terraform/autogenerated/index.md ./docs/docs/terraform/autogenerated/provider.md"
-      - "sed -i '/^page_title:/c\\title: Provider\\nsidebar_position: 1\\ncustom_edit_url: null' ./docs/docs/terraform/autogenerated/provider.md"
-      - "echo '{\"position\": 2, \"label\": \"Data sources\"}' > ./docs/docs/terraform/autogenerated/data-sources/_category_.json"
-      - "echo '{\"position\": 3, \"label\": \"Resources\"}' > ./docs/docs/terraform/autogenerated/resources/_category_.json"
+      - "echo '{\"position\": 99, \"label\": \"Reference\", \"link\": { \"type\": \"generated-index\", \"title\": \"Terraform provider reference\", \"slug\": \"terraform/reference\" }}' > $OUT_DIR/_category_.json"
+      - "mv $OUT_DIR/index.md $OUT_DIR/provider.md"
+      - "sed -i '/^page_title:/c\\title: Provider\\nsidebar_position: 1\\ncustom_edit_url: null' $OUT_DIR/provider.md"
+      - "echo '{\"position\": 2, \"label\": \"Data sources\"}' > $OUT_DIR/data-sources/_category_.json"
+      - "echo '{\"position\": 3, \"label\": \"Resources\"}' > $OUT_DIR/resources/_category_.json"
       - for: { var: DATA_SOURCES }
         cmd: "sed -i -E 's/^page_title: \"([^ ]+).*$/title: \"\\1\"\\ncustom_edit_url: null/' {{.ITEM}}"
       - for: { var: RESOURCES }
-        cmd: "sed -i -E 's/^page_title: \"([^ ]+).*$/title: \"\\1\"\\ncustom_edit_url: null/' {{.ITEM}}"
+        cmd: "sed -i -E 's/^page_title: \"([^ ]+).*$/title: \"\\1\"\\ncustom_edit_url: null/' {{.ITEM}}"

docs/.gitignore

@@ -20,7 +20,10 @@ yarn-debug.log*
 yarn-error.log*
 
 # Terraform provider docs should be autogenerated upon deployment to ensure that they are up to date
-docs/terraform/autogenerated/
+docs/terraform/reference/
 
 # gRPC docs should be autogenerated upon deployment to ensure that they are up to date
-docs/api/grpc-reference.*
+docs/api/grpc-reference.*
+
+# CLI docs should be autogenerated upon deployment to ensure that they are up to date
+docs/cli/reference/

docs/docs/cli/installation.md

@@ -18,10 +18,10 @@ It's possible to download a pre-built binary of the CLI from [GitHub releases](h
 
 A container image is available on [Docker Hub](https://hub.docker.com/r/benasbudrys/bx2cloud-cli).
 
-As an example, running `bx2cloud container list` can be achieved with:
+As an example, try running `bx2cloud version`:
 
 ```sh
-docker run --rm benasbudrys/bx2cloud-cli -t <api-ip>:<api-port> container list
+docker run --rm benasbudrys/bx2cloud-cli -t <api-ip>:<api-port> version
 ```
 
 ### 3. Building from source