CI: Python Stubs (#578)

Build CI to generate and update `.pyi` files, which are stub
implementations of all pybind11 exposed Python bindings. We can
automatically use these stubs for:

- ipython / Jupyter / IDE auto completion
- Sphinx autodocs (instead of writing every doc string twice)

.github/update_stub.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# Copyright 2021-2024 The ImpactX Community
+#
+# This script updates the .pyi stub files for documentation and interactive use.
+# To run this script, the Python bindings of ImpactX need to be installed
+# and importable.
+#
+# Authors: Axel Huebl
+# License: BSD-3-Clause-LBNL
+#
+set -eu -o pipefail
+
+# we are in the source directory, .github/
+this_dir=$(cd $(dirname $0) && pwd)
+
+pybind11-stubgen --exit-code -o ${this_dir}/../src/python/ impactx

.github/workflows/stubs.yml

@@ -0,0 +1,84 @@
+name: 🔄 Update Stub Files
+
+on: [push, pull_request]
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.head_ref }}-subs
+  cancel-in-progress: true
+
+jobs:
+  # Build and install libamrex as AMReX CMake project
+  stubs:
+    name: Stubs
+    runs-on: ubuntu-22.04
+    env:
+      CC: gcc
+      CXX: g++
+      CXXFLAGS: "-O1"
+      OMP_NUM_THREAD: 4
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Pull Remote Changes
+      if: github.event_name == 'push' && github.repository == 'ECP-WarpX/impactx' && github.ref == 'refs/heads/development'
+      run: git pull
+
+    - uses: actions/setup-python@v4
+      name: Install Python
+      with:
+        python-version: '3.9'
+
+    - name: Dependencies
+      run: |
+        .github/workflows/dependencies/gcc-openmpi.sh
+        python3 -m pip install -U pip setuptools wheel
+        python3 -m pip install -U pip mpi4py pytest pybind11-stubgen pre-commit
+
+    - name: Set Up Cache
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/ccache
+        key: ccache-${{ github.workflow }}-${{ github.job }}-git-${{ github.sha }}
+        restore-keys: |
+             ccache-${{ github.workflow }}-${{ github.job }}-git-
+
+    - name: Build & Install
+      run: |
+        export CCACHE_COMPRESS=1
+        export CCACHE_COMPRESSLEVEL=10
+        export CCACHE_MAXSIZE=200M
+        ccache -z
+
+        cmake -S . -B build            \
+          -DCMAKE_VERBOSE_MAKEFILE=ON  \
+          -DImpactX_PYTHON=ON          \
+          -DMPIEXEC_POSTFLAGS="--use-hwthread-cpus"
+        cmake --build build -j 4 --target pip_install
+
+        ccache -s
+        du -hs ~/.cache/ccache
+
+    - name: Update Stubs
+      run: |
+        .github/update_stub.sh
+
+    - name: Run pre-commit cleanup
+      run: |
+        git add .
+        pre-commit run -a || true
+        git add .
+
+    - name: Update Install
+      run: |
+        cmake --build build -j 4 --target pip_install
+
+    - name: Unit tests
+      run: |
+        mpiexec -np 1 python3 -m pytest tests/python/
+
+    - uses: stefanzweifel/git-auto-commit-action@v5
+      name: Commit Updated Stub Files
+      if: github.event_name == 'push' && github.repository == 'ECP-WarpX/impactx' && github.ref == 'refs/heads/development'
+      with:
+        commit_message: Update Stub Files

docs/requirements.txt

@@ -8,6 +8,7 @@ breathe
 # docutils 0.17 breaks HTML tags & RTD theme
 # https://github.com/sphinx-doc/sphinx/issues/9001
 docutils<=0.16
+pybind11-stubgen  # type hints in pyi files
 pygments
 recommonmark
 sphinx>=2.0

docs/spack.yaml

@@ -22,6 +22,7 @@ spack:
   - py-sphinx
   - py-breathe
   - py-recommonmark
+  - py-pybind11-stubgen
   - py-pygments
   - py-sphinx-copybutton
   - py-sphinx-design