Move to src directory structure for package

[m-samland]

✨ Migrate to a src/ Directory Layout

Motivation

• Avoids accidental imports from the working directory during development and CI.
• Gives new contributors an immediate, unambiguous view of what is library code versus project infrastructure.
• Lets us install helper scripts as proper console_scripts entry-points.
• Simplifies pyproject.toml (single package-dir, cleaner Cython extension paths).
• Aligns with PyPA best-practice https://packaging.python.org/en/latest/discussions/src-layout/.

Scope

Item	Action
Package code	Move charis/ → src/charis/
Cython extensions	Update pyproject.toml/setup.py paths.
Scripts	Relocate to src/charis/scripts/ and expose via console_scripts entry-points.
Calibration data	Move to src/charis/data/; load with importlib.resources.files().
Tests	Update relative imports; ensure pytest --import-mode=importlib passes.
Docs & CI	Adjust Sphinx conf.py and CI build paths.
Deprecation shim	Add charis/__init__.py in repo root that imports from src and raises DeprecationWarning (remove after v2.0).

Implementation Checklist

• Create feature branch feat/src-layout.
• Move directories as per Scope.
• Update pyproject.toml ([tool.setuptools.packages] & [tool.setuptools.package-dir]).
• Run pip install -e . in a clean venv and confirm import charis; charis.__version__ works.
• Update and run full test suite (pytest -n auto).
• Build wheel → install in fresh venv → run buildcal and extractcube smoke tests.
• Update documentation (README quick-start, developer guide).
• Open PR, ensure CI (Linux/macOS/Windows) is green.

Back-out Plan

If blockers arise:

1. Keep feat/src-layout branch alive.
2. git checkout main, create revert/src-layout branch.
3. Reset directory tree to pre-migration state (git revert -m 1 <merge-commit>).
4. Document problem in the original issue and discuss alternative fixes.

Definition of Done

• All CI jobs pass on Python 3.10-3.13 with and without OpenMP.
• Wheels and editable installs work identically.
• User-facing commands (buildcal, extractcube, sphere_reduce via spherical) function unchanged.
• README & docs no longer reference the legacy layout.

---

Labels

enhancement • maintenance • breaking-change