docs.yml

name: Documentation

on:
  push:
    branches: [main]
    paths:
      - "**.md"
      - "docs/**"
      - ".github/workflows/docs.yml"
      - "CHANGELOG.md"
      - "CONTRIBUTING.md"
      - "CLAUDE.md"
  pull_request:
    branches: [main]
    paths:
      - "**.md"
      - "docs/**"
      - ".github/workflows/docs.yml"
      - "CHANGELOG.md"
      - "CONTRIBUTING.md"
      - "CLAUDE.md"

# Cancel previous runs of the same workflow
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true

jobs:
  # Check markdown files for issues
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install markdownlint-cli
        run: npm install -g markdownlint-cli

      - name: Lint markdown files
        run: |
          markdownlint '**/*.md' \
            --ignore node_modules \
            --ignore target \
            --ignore docs/site \
            --disable MD013 MD033 MD041
        continue-on-error: true # Don't fail CI for markdown issues

  # Build MkDocs documentation
  mkdocs:
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-mkdocs-material

      - name: Install MkDocs and dependencies
        run: |
          pip install mkdocs mkdocs-material

      - name: Build documentation
        run: |
          cd docs
          mkdocs build --strict

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: docs-site
          path: docs/site
          retention-days: 1

  # Check for broken links in documentation
  link-check:
    name: Check Links
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Link Checker
        uses: lycheeverse/lychee-action@v2
        with:
          args: >
            --verbose
            --no-progress
            --skip-missing
            --max-retries 3
            --timeout 30
            --exclude-path target
            --exclude-path node_modules
            --exclude-path .git
            --exclude-path docs/site
            --exclude "https://github.com/redis-developer/redisctl/pull/.*"
            --exclude "https://github.com/redis-developer/redisctl/issues/.*"
            .
        continue-on-error: true # Don't fail CI for broken external links

  # Validate that Rust documentation builds
  doc-validation:
    name: Validate Rust Docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Install Rust
        uses: dtolnay/rust-toolchain@7b1c307e0dcbda6122208f10795a713336a9b35a # stable
        with:
          toolchain: stable

      - name: Cache cargo registry
        uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2.7.8
        with:
          prefix-key: "v1-rust"
          shared-key: "doc"
          cache-targets: false

      - name: Check that API docs build
        run: cargo doc --workspace --no-deps --all-features

  # Status check for documentation
  docs-status:
    name: Documentation Status
    runs-on: ubuntu-latest
    needs: [markdown-lint, mkdocs, link-check, doc-validation]
    if: always()
    steps:
      - name: Documentation checks complete
        run: |
          echo "Documentation checks completed"
          echo "Markdown lint: ${{ needs.markdown-lint.result }}"
          echo "MkDocs build: ${{ needs.mkdocs.result }}"
          echo "Link check: ${{ needs.link-check.result }}"
          echo "Doc validation: ${{ needs.doc-validation.result }}"

          # Only fail if MkDocs build failed (critical)
          if [[ "${{ needs.mkdocs.result }}" != "success" ]]; then
            echo "MkDocs build failed - this is critical"
            exit 1
          fi

          echo "Documentation checks passed!"

  # Deploy documentation to redis-field-engineering/redisctl-docs
  deploy:
    name: Deploy Documentation
    runs-on: ubuntu-latest
    needs: [mkdocs]
    # Only deploy on push to main, not on PRs
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install MkDocs and dependencies
        run: |
          pip install mkdocs mkdocs-material

      - name: Build documentation
        run: |
          cd docs
          mkdocs build

      - name: Deploy to redisctl-docs
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          personal_token: ${{ secrets.DOCS_DEPLOY_TOKEN }}
          external_repository: redis-field-engineering/redisctl-docs
          publish_branch: gh-pages
          publish_dir: ./docs/site
          commit_message: "docs: update from redis-developer/redisctl@${{ github.sha }}"