gh-283: set up nox for deveopers and CI

.github/workflows/test.yml

@@ -33,8 +33,14 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - run: pip install -c .github/test-constraints.txt -e '.[test]'
-      - run: pytest --cov=glass --doctest-plus
+      - name: Run doctests
+        run:
+          pipx run nox -s doctests-${{ matrix.python-version.key ||
+          matrix.python-version }} --verbose
+      - name: Run tests and generate coverage report
+        run:
+          pipx run nox -s coverage-${{ matrix.python-version.key ||
+          matrix.python-version }} --verbose
       - uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -47,7 +53,10 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - run: pipx run build
+      - name: Build SDist and wheel
+        run:
+          pipx run nox -s build-${{ matrix.python-version.key ||
+          matrix.python-version }} --verbose
 
   docs:
     name: Docs
@@ -57,7 +66,11 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - run: |
+      - name: Install dependencies
+        run: |
           sudo apt-get update
-          sudo apt-get install pandoc
-      - run: pipx run --spec '.[docs]' sphinx-build -W -b html docs _build/html
+          sudo apt-get install pando
+      - name: Build docs
+        run:
+          pipx run nox -s docs-${{ matrix.python-version.key ||
+          matrix.python-version }} --verbose

CONTRIBUTING.md

@@ -138,6 +138,52 @@ long as there have been changes.
 The current version number is automatically inferred from the last release (i.e.
 git tag), subsequent unreleased commits, and local changes, if any.
 
+## Nox
+
+`GLASS` supports running various critical commands using
+[nox](https://github.com/wntrblm/nox) to make them less intimidating for new
+developers. All of these commands (or sessions in the language of `nox`) -
+`lint`, `tests`, `coverage`, `doctests`, `docs`, and `build` - are defined in
+[noxfile.py](https://github.com/glass-dev/glass/main/noxfile.py).
+
+`nox` can be installed via `pip` using -
+
+```bash
+pip install nox
+```
+
+The default sessions (`lint` and `tests`) can be executed using -
+
+```bash
+nox
+```
+
+A particular session (for example `tests`) can be run with `nox` on all
+supported Python versions using -
+
+```bash
+nox -s tests
+```
+
+Only `tests`, `coverage`, and the `doctests` session run on all supported Python
+versions by default.
+
+To specify a particular Python version (for example `3.11`), use the following
+syntax -
+
+```bash
+nox -s tests-3.11
+```
+
+The following command can be used to deploy the docs on `localhost` -
+
+```bash
+nox -s docs -- serve
+```
+
+The `nox` environments created for each type of session on the first run is
+saved under `.nox/` and reused by default.
+
 ## Contributing workflow
 
 Every change to the repository should come out of an issue where the change is

noxfile.py

@@ -0,0 +1,72 @@
+"""Nox config."""
+
+from __future__ import annotations
+
+import nox
+
+# Options to modify nox behaviour
+nox.options.default_venv_backend = "uv|virtualenv"
+nox.options.reuse_existing_virtualenvs = True
+nox.options.sessions = ["lint", "tests"]
+
+ALL_PYTHON = ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+
+@nox.session
+def lint(session: nox.Session) -> None:
+    """Run the linter."""
+    session.install("pre-commit")
+    session.run("pre-commit", "run", "--all-files", *session.posargs)
+
+
+@nox.session(python=ALL_PYTHON)
+def tests(session: nox.Session) -> None:
+    """Run the unit and regular tests."""
+    session.install("-c", ".github/test-constraints.txt", "-e", ".[tests]")
+    session.run(
+        "pytest",
+        *session.posargs,
+    )
+
+
+@nox.session(python=ALL_PYTHON)
+def coverage(session: nox.Session) -> None:
+    """Run tests and compute coverage."""
+    session.posargs.append("--cov=glass")
+    tests(session)
+
+
+@nox.session(python=ALL_PYTHON)
+def doctests(session: nox.Session) -> None:
+    """Run the doctests."""
+    session.posargs.append("--doctest-plus=glass")
+    tests(session)
+
+
+@nox.session
+def examples(session: nox.Session) -> None:
+    """Run the example notebooks."""
+    session.install("-e", ".[examples]")
+    session.run("jupyter", "execute", "examples/**/*.ipynb", *session.posargs)
+
+
+@nox.session
+def docs(session: nox.Session) -> None:
+    """Build the docs. Pass "serve" to serve."""
+    session.install("-e", ".[docs]")
+    session.chdir("docs")
+    session.run("sphinx-build", "-M", "html", ".", "_build")
+
+    if session.posargs:
+        if "serve" in session.posargs:
+            print("Launching docs at http://localhost:8001/ - use Ctrl-C to quit")
+            session.run("python", "-m", "http.server", "8001", "-d", "_build/html")
+        else:
+            print("Unsupported argument to docs")
+
+
+@nox.session
+def build(session: nox.Session) -> None:
+    """Build an SDist and wheel."""
+    session.install("build")
+    session.run("python", "-m", "build")

pyproject.toml

@@ -141,6 +141,8 @@ lint.per-file-ignores = {"__init__.py" = [
     "T201", # print
 ], "glass*" = [
     "PLR2004", # TODO: magic-value-comparison
+], "noxfile.py" = [
+    "T201",
 ], "tests*" = [
     "ANN001", # TODO: missing-type-function-argument
     "ANN201", # TODO: issing-return-type-undocumented-public-function