docs.yml

name: Documentation Build and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [dev, main]

permissions:
  contents: write

jobs:
  docs:
    name: Build Documentation
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.13"

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

      - name: Build docs (strict — fail on warnings)
        run: |
          cd docs
          make html SPHINXOPTS="-W --keep-going"

      - name: Verify autodoc coverage
        run: |
          cd docs
          python -c "
          import importlib, inspect, sys
          sys.path.insert(0, '..')
          import pyepics
          public = [name for name in pyepics.__all__ if not name.startswith('_')]
          missing = []
          for name in public:
              obj = getattr(pyepics, name)
              if callable(obj) and not inspect.getdoc(obj):
                  missing.append(name)
          if missing:
              print(f'Missing docstrings: {missing}')
              sys.exit(1)
          print(f'All {len(public)} public symbols have docstrings.')
          "

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html