docs.yml

name: Documentation

on:
  push:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'README.md'
  pull_request:
    branches: [ main ]
    paths:
      - 'docs/**'
      - 'README.md'
  workflow_dispatch:

jobs:
  validate-docs:
    name: Validate Documentation
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.9'

    - name: Install markdown linter
      run: |
        npm install -g markdownlint-cli

    - name: Lint markdown files
      run: |
        markdownlint '**/*.md' --ignore node_modules --ignore .github || true

    - name: Check for broken links
      uses: gaurav-nelson/github-action-markdown-link-check@v1
      with:
        use-quiet-mode: 'yes'
        config-file: '.github/markdown-link-check-config.json'
      continue-on-error: true

  build-docs:
    name: Build Documentation
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: '3.9'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[dev]"
        pip install mkdocs mkdocs-material mkdocstrings[python]

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

    - name: Upload documentation
      uses: actions/upload-artifact@v4
      with:
        name: documentation
        path: site/