feat: add rpk documentation automation

.github/workflows/update-rpk-docs.yml

@@ -0,0 +1,279 @@
+name: Update rpk Documentation
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'rpk version tag (e.g., v26.2.0, v26.2.0-rc1) or "dev" for latest dev branch. RC versions target beta branch.'
+        required: true
+        default: 'dev'
+      diff_version:
+        description: 'Previous version for diff (optional, e.g., v26.1.9)'
+        required: false
+      draft_missing:
+        description: 'Generate draft pages for new commands'
+        required: false
+        default: 'true'
+        type: boolean
+  repository_dispatch:
+    types: [update-rpk-docs]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-rpk-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          # Must match or exceed the version in redpanda/src/go/rpk/go.mod
+          # Check with: curl -s https://raw.githubusercontent.com/redpanda-data/redpanda/dev/src/go/rpk/go.mod | grep "^go "
+          go-version: 'stable'
+
+      - name: Determine version parameters
+        id: params
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          DISPATCH_VERSION: ${{ github.event.client_payload.version }}
+          DISPATCH_DIFF_VERSION: ${{ github.event.client_payload.diff_version }}
+          DISPATCH_DRAFT_MISSING: ${{ github.event.client_payload.draft_missing }}
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+          INPUT_DIFF_VERSION: ${{ github.event.inputs.diff_version }}
+          INPUT_DRAFT_MISSING: ${{ github.event.inputs.draft_missing }}
+        run: |
+          # Handle workflow_dispatch vs repository_dispatch
+          if [ "$EVENT_NAME" = "repository_dispatch" ]; then
+            VERSION="${DISPATCH_VERSION:-dev}"
+            DIFF_VERSION="${DISPATCH_DIFF_VERSION}"
+            DRAFT_MISSING="${DISPATCH_DRAFT_MISSING:-false}"
+          else
+            VERSION="${INPUT_VERSION}"
+            DIFF_VERSION="${INPUT_DIFF_VERSION}"
+            DRAFT_MISSING="${INPUT_DRAFT_MISSING}"
+          fi
+
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "diff_version=$DIFF_VERSION" >> $GITHUB_OUTPUT
+          echo "draft_missing=$DRAFT_MISSING" >> $GITHUB_OUTPUT
+
+          # Detect RC versions (e.g., v26.2.0-rc1, 26.2.0-rc2)
+          if [[ "$VERSION" =~ -rc[0-9]+$ ]]; then
+            echo "is_rc=true" >> $GITHUB_OUTPUT
+            echo "base_branch=beta" >> $GITHUB_OUTPUT
+          else
+            echo "is_rc=false" >> $GITHUB_OUTPUT
+            echo "base_branch=main" >> $GITHUB_OUTPUT
+          fi
+
+          # Determine branch name
+          if [ "$VERSION" = "dev" ]; then
+            echo "branch_name=rpk-docs-dev-$(date +%Y%m%d)" >> $GITHUB_OUTPUT
+          else
+            echo "branch_name=rpk-docs-$VERSION" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Validate RC version against beta branch
+        if: steps.params.outputs.is_rc == 'true'
+        run: |
+          VERSION="${{ steps.params.outputs.version }}"
+
+          # Extract major.minor from version (e.g., v26.2.0-rc1 -> 26.2)
+          VERSION_MAJOR_MINOR=$(echo "$VERSION" | sed -E 's/^v?([0-9]+\.[0-9]+).*/\1/')
+
+          # Get version from beta branch antora.yml
+          BETA_VERSION=$(git show origin/beta:antora.yml | grep "^version:" | sed -E "s/^version:[[:space:]]*['\"]?([0-9]+\.[0-9]+)['\"]?.*/\1/")
+
+          echo "RC version major.minor: $VERSION_MAJOR_MINOR"
+          echo "Beta branch version: $BETA_VERSION"
+
+          if [ "$VERSION_MAJOR_MINOR" != "$BETA_VERSION" ]; then
+            echo "::error::RC version $VERSION does not match beta branch version $BETA_VERSION"
+            echo "RC releases must target the current beta version."
+            exit 1
+          fi
+
+          echo "✓ RC version $VERSION matches beta branch version $BETA_VERSION"
+
+      - name: Checkout target branch
+        run: |
+          BASE_BRANCH="${{ steps.params.outputs.base_branch }}"
+          if [ "$BASE_BRANCH" != "main" ]; then
+            echo "Checking out $BASE_BRANCH branch for RC release"
+            git checkout "$BASE_BRANCH"
+          fi
+
+      - name: Build rpk-docs command
+        id: command
+        run: |
+          # Build command - builds rpk from source using Go
+          CMD="npx doc-tools generate rpk-docs"
+
+          VERSION="${{ steps.params.outputs.version }}"
+          CMD="$CMD --ref $VERSION"
+
+          DIFF_VERSION="${{ steps.params.outputs.diff_version }}"
+          if [ -n "$DIFF_VERSION" ]; then
+            CMD="$CMD --diff $DIFF_VERSION"
+          fi
+
+          DRAFT_MISSING="${{ steps.params.outputs.draft_missing }}"
+          if [ "$DRAFT_MISSING" = "true" ]; then
+            CMD="$CMD --draft-missing"
+          fi
+
+          # Update what's-new if doing a diff
+          if [ -n "$DIFF_VERSION" ]; then
+            CMD="$CMD --update-whats-new"
+          fi
+
+          CMD="$CMD --output-dir modules/reference/pages/rpk"
+          echo "cmd=$CMD" >> $GITHUB_OUTPUT
+
+      - name: Run rpk-docs generator
+        id: generate
+        run: |
+          echo "Running: ${{ steps.command.outputs.cmd }}"
+          ${{ steps.command.outputs.cmd }} 2>&1 | tee generation-output.txt
+
+          # Extract summary for PR description
+          DIFF_FILE=$(ls -t docs-data/rpk-diff-*.json 2>/dev/null | head -1)
+          if [ -n "$DIFF_FILE" ]; then
+            echo "diff_file=$DIFF_FILE" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Check for changes
+        id: changes
+        run: |
+          git add -A
+          if git diff --staged --quiet; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "Changed files:"
+            git diff --staged --name-only | head -20
+          fi
+
+      - name: Generate PR description
+        if: steps.changes.outputs.has_changes == 'true'
+        id: pr_body
+        run: |
+          VERSION="${{ steps.params.outputs.version }}"
+          DIFF_VERSION="${{ steps.params.outputs.diff_version }}"
+
+          # Start building PR body
+          cat > pr-body.md << 'HEADER'
+          ## Summary
+
+          Automated update of rpk CLI documentation.
+
+          HEADER
+
+          # Add version info
+          if [ "$VERSION" = "dev" ]; then
+            echo "**Source**: \`dev\` branch (pre-release)" >> pr-body.md
+          else
+            echo "**Version**: \`$VERSION\`" >> pr-body.md
+          fi
+
+          if [ -n "$DIFF_VERSION" ]; then
+            echo "**Diff against**: \`$DIFF_VERSION\`" >> pr-body.md
+          fi
+
+          echo "" >> pr-body.md
+
+          # Add diff summary if available
+          DIFF_FILE="${{ steps.generate.outputs.diff_file }}"
+          if [ -n "$DIFF_FILE" ] && [ -f "$DIFF_FILE" ]; then
+            echo "## Changes detected" >> pr-body.md
+            echo "" >> pr-body.md
+
+            # Extract counts from diff JSON
+            NEW_CMDS=$(jq -r '.summary.newCommands // 0' "$DIFF_FILE")
+            REMOVED_CMDS=$(jq -r '.summary.removedCommands // 0' "$DIFF_FILE")
+            NEW_FLAGS=$(jq -r '.summary.newFlags // 0' "$DIFF_FILE")
+            REMOVED_FLAGS=$(jq -r '.summary.removedFlags // 0' "$DIFF_FILE")
+            CHANGED_DEFAULTS=$(jq -r '.summary.changedDefaults // 0' "$DIFF_FILE")
+
+            if [ "$NEW_CMDS" -gt 0 ]; then
+              echo "- **New commands**: $NEW_CMDS" >> pr-body.md
+              echo "" >> pr-body.md
+              jq -r '.details.newCommands[]? | "  - \`\(.path)\`"' "$DIFF_FILE" >> pr-body.md 2>/dev/null || true
+              echo "" >> pr-body.md
+            fi
+
+            if [ "$REMOVED_CMDS" -gt 0 ]; then
+              echo "- **Removed commands**: $REMOVED_CMDS" >> pr-body.md
+              echo "" >> pr-body.md
+              jq -r '.details.removedCommands[]? | "  - \`\(.path)\`"' "$DIFF_FILE" >> pr-body.md 2>/dev/null || true
+              echo "" >> pr-body.md
+            fi
+
+            if [ "$NEW_FLAGS" -gt 0 ]; then
+              echo "- **New flags**: $NEW_FLAGS" >> pr-body.md
+            fi
+
+            if [ "$REMOVED_FLAGS" -gt 0 ]; then
+              echo "- **Removed flags**: $REMOVED_FLAGS" >> pr-body.md
+            fi
+
+            if [ "$CHANGED_DEFAULTS" -gt 0 ]; then
+              echo "- **Changed defaults**: $CHANGED_DEFAULTS" >> pr-body.md
+            fi
+
+            echo "" >> pr-body.md
+          fi
+
+          # Add file change summary
+          echo "## Files changed" >> pr-body.md
+          echo "" >> pr-body.md
+          echo "\`\`\`" >> pr-body.md
+          git diff --staged --stat | tail -20 >> pr-body.md
+          echo "\`\`\`" >> pr-body.md
+          echo "" >> pr-body.md
+
+          # Add footer
+          cat >> pr-body.md << 'FOOTER'
+          ## Automation
+
+          Generated by [rpk-docs automation](https://github.com/redpanda-data/docs-extensions-and-macros/tree/main/tools/rpk-docs).
+
+          Review the changes and merge when ready.
+          FOOTER
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ steps.params.outputs.branch_name }}
+          base: ${{ steps.params.outputs.base_branch }}
+          title: "docs: update rpk CLI documentation (${{ steps.params.outputs.version }})"
+          body-path: pr-body.md
+          commit-message: "docs: update rpk CLI documentation for ${{ steps.params.outputs.version }}"
+          delete-branch: true
+          labels: |
+            documentation
+            automated
+
+      - name: No changes detected
+        if: steps.changes.outputs.has_changes == 'false'
+        run: |
+          echo "No documentation changes detected for version ${{ steps.params.outputs.version }}"

.github/workflows/validate-docs-data.yml

@@ -0,0 +1,71 @@
+---
+name: Validate docs-data files
+on:
+  pull_request:
+    paths:
+      - 'docs-data/rpk-overrides.json'
+      - 'docs-data/rpk-overrides.schema.json'
+      - 'docs-data/property-overrides.json'
+  push:
+    branches: [main]
+    paths:
+      - 'docs-data/rpk-overrides.json'
+      - 'docs-data/rpk-overrides.schema.json'
+      - 'docs-data/property-overrides.json'
+
+jobs:
+  validate-rpk-overrides:
+    name: Validate rpk-overrides.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install AJV CLI
+        run: npm install -g ajv-cli ajv-formats
+
+      - name: Validate rpk-overrides.json against schema
+        run: |
+          echo "Validating docs-data/rpk-overrides.json against docs-data/rpk-overrides.schema.json..."
+          ajv validate \
+            --spec=draft2020 \
+            -s docs-data/rpk-overrides.schema.json \
+            -d docs-data/rpk-overrides.json \
+            -c ajv-formats \
+            --strict=false \
+            --all-errors
+
+      - name: Schema validation passed
+        if: success()
+        run: echo "rpk-overrides.json validates successfully against the schema."
+
+  validate-property-overrides:
+    name: Validate property-overrides.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate property-overrides.json syntax
+        run: |
+          echo "Checking docs-data/property-overrides.json is valid JSON..."
+          if jq empty docs-data/property-overrides.json 2>/dev/null; then
+            echo "property-overrides.json is valid JSON."
+          else
+            echo "::error::property-overrides.json contains invalid JSON syntax"
+            exit 1
+          fi
+
+      - name: Check for required fields
+        run: |
+          echo "Checking property-overrides.json structure..."
+          # Verify it's an object with expected top-level keys
+          if jq -e 'type == "object"' docs-data/property-overrides.json > /dev/null; then
+            echo "property-overrides.json has correct structure."
+          else
+            echo "::error::property-overrides.json must be a JSON object"
+            exit 1
+          fi