Prepare for public release (0.3.0)

.github/workflows/main.yml

@@ -13,11 +13,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3.2.2
+      - uses: astral-sh/setup-uv@v5
         with:
-          version: "0.5.0"
-          python-version-file: ".python-version"
+          version: "0.5.29"
           enable-cache: true
+      - run: uv lock --check
       - run: uv sync
       - run: uv run --frozen ruff check
         if: success() || failure()
@@ -26,39 +26,83 @@ jobs:
       - run: uv run --frozen pyright
         if: success() || failure()
 
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.5.29"
+      - run: source ./scripts/build_docs.sh
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-html-build
+          path: docs/_build/html
+          retention-days: 14
+
   ##
 
-  get-pytorch-versions:
+  get-python-pytorch-versions:
     runs-on: ubuntu-latest
     outputs:
-      versions: ${{ steps.get-pytorch-versions.outputs.versions }}
+      versions: ${{ steps.get-versions.outputs.versions }}
     steps:
-      - name: Get PyTorch versions
-        id: get-pytorch-versions
+      - name: "Get (Python, PyTorch) versions"
+        id: get-versions
         run: |
-          VERSIONS=$(
-            curl -s https://pypi.org/pypi/torch/json | jq -r '.releases | keys[]' |
-            # remove versions <2.0; strip "patch" from versions
-            grep -v '^1\.' | grep -E '\.[0]+$' | sort -V | sed 's/\.0$//' |
-            # to JSON array
-            jq -R . | jq -sc .
+          MIN_PYTHON_VERSION=3.9
+          MIN_PYTORCH_VERSION=2.0
+
+          # Get PyTorch versions from PyPI
+          pytorch_versions=$(
+              curl -s https://pypi.org/pypi/torch/json | jq -r '.releases | keys[]' |
+              # strip "patch" from versions
+              grep -E '\.[0]+$' | sort -V | sed 's/\.0$//'
           )
-          echo "versions=$VERSIONS" >> $GITHUB_OUTPUT
-          # e.g. ["2.0","2.1","2.2","2.3","2.4"]
+
+          # For each PyTorch version, get Python versions that have builds
+          # Generate JSON list of "python,pytorch" versions
+
+          version_matrix=()
+          for pytorch_version in $pytorch_versions; do
+            # Skip if PyTorch version less than minium
+            if [[ "$(printf '%s\n' "$pytorch_version" "$MIN_PYTORCH_VERSION" | sort -V | head -n 1)" != "$MIN_PYTORCH_VERSION" ]]; then continue; fi
+
+            python_versions=$(
+              curl -s "https://pypi.org/pypi/torch/$pytorch_version/json" |
+              jq -r '.urls[].filename | select(test("manylinux1_x86_64")) | capture("(?<cp>cp[0-9]+)-") | .cp |
+              sub("cp(?<major>[0-9])(?<minor>[0-9]+)"; "\(.major).\(.minor)")'
+            )
+
+            for python_version in $python_versions; do
+              # Skip if Python version less than minium
+              if [[ "$(printf '%s\n' "$python_version" "$MIN_PYTHON_VERSION" | sort -V | head -n 1)" != "$MIN_PYTHON_VERSION" ]]; then continue; fi
+
+              version_matrix+=($python_version,$pytorch_version)
+            done
+          done
+          version_matrix=$(printf '%s\n' "${version_matrix[@]}" | jq -R . | jq -s -c .)
+
+          # Write to outputs
+          echo "versions=$version_matrix" >> $GITHUB_OUTPUT
 
   test:
     runs-on: ubuntu-latest
-    needs: get-pytorch-versions
+    needs: get-python-pytorch-versions
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.9", "3.10", "3.11", "3.12"] 
-        pytorch: ${{fromJson(needs.get-pytorch-versions.outputs.versions)}}
+        versions: ${{fromJson(needs.get-python-pytorch-versions.outputs.versions)}}
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3.2.2
+      - uses: astral-sh/setup-uv@v5
         with:
-          version: "0.5.0"
-      - if: contains('2.0,2.1,2.2', matrix.pytorch)
-        run: echo "NUMPY_VERSION=--with \"numpy<2\"" >> $GITHUB_ENV
-      - run: uv run --python ${{ matrix.python }} --with torch~=${{ matrix.pytorch }} ${{ env.NUMPY_VERSION }} pytest --verbose tests/test_ci.py
+          version: "0.5.29"
+      - run: |
+          IFS=',' read -r python_version pytorch_version <<< ${{ matrix.versions }}
+          echo "PYTHON_VERSION=$python_version" >> $GITHUB_ENV
+          echo "PYTORCH_VERSION=$pytorch_version" >> $GITHUB_ENV
+          if [[ "$pytorch_version" =~ ^2\.(0|1|2)$ ]]; then
+            echo "NUMPY_VERSION=--with \"numpy<2\"" >> $GITHUB_ENV
+          fi
+      - run: uv run --python ${{ env.PYTHON_VERSION }} --with torch~=${{ env.PYTORCH_VERSION }} ${{ env.NUMPY_VERSION }} pytest --verbose tests/test_ci.py

.github/workflows/release.yml

@@ -5,14 +5,35 @@ on:
     types: [published]
 
 jobs:
-  release:
+  release-to-pypi:
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     steps:
       - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v3
+      - uses: astral-sh/setup-uv@v5
         with:
-          version: "0.5.0"
+          version: "0.5.29"
       - run: uv build
       - run: uv publish
+
+  publish-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.5.29"
+      - run: source ./scripts/build_docs.sh
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,5 +1,8 @@
+docs/source/README.md
+docs/source/contributing.md
+docs/source/examples/scripts/
+
 torchrunx_logs/
-.pixi/
 .ruff_cache/
 .vscode/
 

CITATION.cff

@@ -9,6 +9,6 @@ authors:
     family-names: Curtin
     email: [email protected]
 repository-code: 'https://github.com/apoorvkh/torchrunx'
-url: torchrunx.readthedocs.io
-license: MIT
-year: 2024
+url: 'https://torchrun.xyz'
+license: GPL-3.0
+year: 2025

CONTRIBUTING.md

@@ -2,16 +2,18 @@
 
 We use the [`uv`](https://github.com/astral-sh/uv) package manager. Simply [install `uv`](https://github.com/astral-sh/uv#installation) and run `uv sync` in this repository to build the environment. Run `source .venv/bin/activate` to activate the environment.
 
-We use `ruff check` for linting, `ruff format` for formatting, `pyright` for static type checking, and `pytest` for testing.
-
-We build wheels with `uv build` and upload to [PyPI](https://pypi.org/project/torchrunx) with `uv publish`. Our release pipeline is powered by Github Actions.
+We use `ruff check` for linting, `ruff format` for formatting, `pyright` for static type checking, and `pytest` for testing. We expect all such checks to pass before merging changes to the main branch. We build wheels with `uv build` and upload to [PyPI](https://pypi.org/project/torchrunx) with `uv publish`. Our CI pipelines are powered by Github Actions.
 
 ## Pull Requests
 
-Make a pull request with your changes on Github and we'll try to look at soon! If addressing a specific issue, mention it in the PR, and offer a short explanation of your fix. If adding a new feature, explain why it's meaningful and belongs in __torchrunx__.
+Make a pull request with your changes on Github and we'll try to look at it soon! If addressing a specific issue, mention it in the PR, and offer a short explanation of your fix. If adding a new feature, explain why it's meaningful and belongs in **torchrunx**.
 
 ## Testing
 
 `tests/` contains `pytest`-style tests for validating that code changes do not break the core functionality of our library.
 
 At the moment, we run `pytest tests/test_ci.py` (i.e. simple single-node CPU-only tests) in our Github Actions CI pipeline (`.github/workflows/release.yml`). One can manually run our more involved tests (on GPUs, on multiple machines from SLURM) on their own hardware.
+
+## Documentation
+
+Our documentation is hosted on Github Pages and is updated with every package release. We build our documentation with [Sphinx](https://www.sphinx-doc.org): `source scripts/build_docs.sh`. The documentation will then be generated at `docs/_build/html` (and can be rendered with `python -m http.server --directory docs/_build/html`).