docs.yml

name: Docs

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "mstar/**"
      - "pyproject.toml"
      - ".github/workflows/docs.yml"
  workflow_dispatch:

# Builds the Sphinx site and publishes it to this repo's own gh-pages branch,
# served as a GitHub Pages project page at https://mstar-project.github.io/mstar/.
# Uses the built-in GITHUB_TOKEN — no deploy key or PAT to own, rotate, or expire.
permissions:
  contents: write

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Install build dependencies
        run: |
          python -m pip install --upgrade pip
          # CPU-only torch: the API autosummary imports the package, and conf.py
          # deliberately does not mock torch (PEP 604 annotations break under mocks).
          pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 \
            --index-url https://download.pytorch.org/whl/cpu
          # Base install only; GPU-only model extras (flashinfer, transformers, ...)
          # are not needed for the narrative docs. Modules that import them at module
          # scope yield autosummary stub pages, which is acceptable for the first site.
          pip install -e .
          pip install -r docs/requirements.txt

      - name: Build HTML
        run: sphinx-build -b html docs docs/_build/html

      - name: Publish to gh-pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/_build/html
          publish_branch: gh-pages
          commit_message: "docs: publish ${{ github.sha }}"