python-ci.mkdocs.yml

name: CI/CD - MkDocs Deployment to GitHub Pages

on:
  push:
    branches:
      # - main
      - python-template

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ## Set the working directory dynamically
      working-directory: .
      PYTHONPATH: ${{ github.workspace }}/src  ## Add src to PYTHONPATH

    steps:
      ## --- Checkout Repository ---
      - name: Checkout Code
        uses: actions/checkout@v4
      ## --- Configure Git ---
      - name: Configure Git Credentials
        run: |
          git config user.name "Nhat-Thanh Nguyen"
          git config user.email nnthanh101@gmail.com
      ## --- Setup Python Environment ---
      - name: Setup Python 3.12
        uses: actions/setup-python@v5
        with:
          python-version: 3.12
      - name: Cache Dependencies
        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      ## --- Install MkDocs and Dependencies ---
      - name: Install MkDocs and Plugins
        run: |
          pip install --no-cache-dir mkdocs mkdocs-material mkdocstrings mkdocstrings[python]
      
      ## --- Install 'task' CLI ---
      - name: Install Taskfile CLI
        run: |
          sudo sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
          echo "PATH=/usr/local/bin:$PATH" >> $GITHUB_ENV  ## Add Task CLI to PATH
          task --version

      ## --- Install UV Dependency Manager ---
      - name: Install UV (Dependency Manager)
        run: |
          curl -fsSL https://astral.sh/uv/install.sh | sh
          echo "PATH=/usr/local/bin:$PATH" >> $GITHUB_ENV
          uv --version

      ## --- Install Dependencies with UV ---
      - name: Install Project Dependencies
        run: |
          echo "Setting UV link mode for compatibility..."
          export UV_LINK_MODE=copy
          uv sync --all-extras --dev --compile-bytecode  ## Install all dependencies

      ## --- Run Code Quality Checks ---
      - name: Run Code Quality Checks
        run: |
          ## task clean, lint, code_quality, test, build
          task ci
      ## --- Validate MkDocs Build ---
      - name: Validate MkDocs Build
        run: |
          mkdocs build  ## Validate the documentation build before deployment

      ## --- Build and Deploy MkDocs ---
      - name: Build & Deploy Mkdocs
        run: |
          mkdocs gh-deploy --force
        working-directory: ${{env.working-directory}}