build_sphinx.yml

name: "Sphinx: Render docs"

on: 
  # Runs on pushes targeting the default branch
  push:
    branches: ["main", "master"]
    tags:
      - 'v[0-9]*.*'      # v1, v1.2, v1.2.3, v2025.09.04, etc.
      - '[0-9]*\.[0-9]*\.*'  # 1, 1.2, 1.2.3, 2025.09.04, etc.  
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write
  pages: write
  id-token: write


# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # This workflow contains a single job called "build"
  build:

    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up micromamba (conda-forge + optional org channel)
        uses: mamba-org/setup-micromamba@v2
        with:
          init-shell: bash
          cache-downloads: true
          environment-name: docs
          # The python here should be coordinated with pyproj.toml. 
          # The others are a minimal set of things needed to bootstrap the build 
          # versions should be coordinated with pyproj.toml
          create-args: >-
            python=3.12
            setuptools>=68
            setuptools_scm
            numpy>2
            numpydoc
          condarc: |
            channel_priority: strict
            channels:
              - conda-forge
              - cadwr-dms   # keep if you publish your internal deps here

      - name: Overlay current checkout (no pip deps and install bdschism)
        env:
          PIP_NO_INDEX: "1"
          PIP_NO_BUILD_ISOLATION: "1"
          SETUPTOOLS_SCM_ROOT: ${{ github.workspace }}
        working-directory: ${{ github.workspace }}
        run: |
          micromamba run -n docs python -m pip install --upgrade pip
          micromamba run -n docs python -m pip install ./bdschism --no-deps --no-build-isolation -v

      - name: Install docs extras from pyproject via conda
        run: |
          micromamba run -n docs python scripts/install_docs_extras.py

      - name: Build Sphinx
        shell: bash -l {0}
        env:
          # flip to "0" if/when you want a full unmocked build
          DOCS_USE_MOCKS: "0"
          SETUPTOOLS_SCM_ROOT: ${{ github.workspace }}
        run: |
          sphinx-apidoc --force -T --templatedir ./_templates -o . ../bdschism ../bdschism/setup.py ../bdschism/tests/*
          make -C docsrc clean
          make -C docsrc html

      # Upload the built site as a Pages artifact
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/html

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages      # 👈 this resolves your 400 error
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4