chore: linting, src layout, sphinx docs, and CI

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    name: lint + test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package + dev tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install ruff mypy pyright pytest
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: mypy
+        run: mypy src/scperteval
+      - name: pyright
+        run: pyright src/scperteval
+      - name: pytest
+        run: pytest -q
+
+  docs:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install package + docs deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install --group docs
+      - name: Build HTML docs
+        run: sphinx-build -b html -n docs docs/_build/html

.gitignore

@@ -7,10 +7,19 @@ dist/
 .venv/
 venv/
 
+# Environment
+uv.lock
+.envrc
+requirements-local.txt
+
 # Run outputs
 results/
 
 # Editor / OS
 .idea/
 .vscode/
 .DS_Store
+
+# docs
+docs/generated/
+docs/_build/

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Run `pre-commit install` once; hooks then run on every commit.
+# Update pinned revs with `pre-commit autoupdate`.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.13
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - uv sync --group docs
+        - uv run sphinx-build -M html docs docs/_build -W
+        - mv docs/_build $READTHEDOCS_OUTPUT

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial implementation of scPertEval.

CONTRIBUTORS.md

@@ -7,9 +7,9 @@ welcome. There are two paths, depending on what you're changing.
 
 If you're adding a protocol (a new metric, or a new combination of an existing metric with
 a space / centering / controls), **open a PR directly.** This is the common case and the
-whole point of the project. See [Create a protocol](README.md#create-a-protocol) for the
-two-step pattern (a pure function in `scperteval/protocols/algorithms.py` plus a row in
-`scperteval/protocols/table.py`). Adding a new building block (feature space, DE method, control
+whole point of the project. See [Create a protocol](https://github.com/Virtual-Cell-Research-Community/scPertEval/blob/main/docs/protocols.md#create-a-protocol) for the
+two-step pattern (a pure function in `src/scperteval/protocols/metrics.py` plus a row in
+`src/scperteval/protocols/table.py`). Adding a new building block (feature space, DE method, control
 source, calibrator) the same way is also welcome as a PR.
 
 Please include: