paperless-gpt/.github/workflows/documentation.yml

name: Documentation

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.md'
      - 'docs/**'
      - '.github/workflows/documentation.yml'
  pull_request:
    branches: [ main ]
    paths:
      - '**/*.md'
      - 'docs/**'
      - '.github/workflows/documentation.yml'

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  markdown-lint:
    name: Markdown Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

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

      - name: Check Markdown files
        run: markdownlint '**/*.md' --ignore node_modules

      - name: Check for broken links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          use-quiet-mode: 'yes'
          use-verbose-mode: 'yes'
          config-file: '.github/workflows/mlc_config.json'
          folder-path: '.'
          max-depth: -1

  api-documentation:
    name: API Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install swag
        run: go install github.com/swaggo/swag/cmd/swag@latest

      - name: Generate Swagger Documentation
        run: swag init

      - name: Check if documentation changed
        run: |
          if [[ `git status --porcelain` ]]; then
            echo "API documentation is out of date. Please run 'swag init' locally and commit the changes."
            exit 1
          fi          

  typescript-documentation:
    name: TypeScript Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install TypeDoc
        run: npm install -g typedoc

      - name: Generate TypeScript Documentation
        working-directory: ./web-app
        run: typedoc --out docs/typescript src/

      - name: Check documentation style
        working-directory: ./web-app
        run: |
          if find src -name "*.tsx" -o -name "*.ts" | xargs grep -l "@todo\|FIXME"; then
            echo "Found TODO or FIXME comments in the code. Please resolve them before merging."
            exit 1
          fi          

  spelling:
    name: Documentation Spelling
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check Spelling
        uses: streetsidesoftware/cspell-action@v5
        with:
          files: |
            **/*.md
            docs/**/*
                        
  validate-examples:
    name: Validate Code Examples
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm install markdown-code-block-runner

      - name: Validate code examples in documentation
        run: npx markdown-code-block-runner "**/*.md"

  build-wiki:
    name: Build Wiki
    needs: [markdown-lint, spelling]
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'

      - name: Build documentation
        run: |
          mdbook build docs/          

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs/book'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  check-docs-coverage:
    name: Documentation Coverage
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install doc coverage tool
        run: go install github.com/client9/misspell/cmd/misspell@latest

      - name: Check public API documentation coverage
        run: |
          COVERAGE=$(go doc -all ./... | wc -l)
          if [ "$COVERAGE" -lt 100 ]; then
            echo "Documentation coverage is below threshold"
            exit 1
          fi          

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

      - name: Check TypeScript documentation coverage
        working-directory: ./web-app
        run: |
          npm install -g typescript
          COVERAGE=$(find src -name "*.ts" -o -name "*.tsx" | xargs grep -l "@doc" | wc -l)
          if [ "$COVERAGE" -lt 50 ]; then
            echo "TypeScript documentation coverage is below threshold"
            exit 1
          fi