Reducing comments

.gitea/ci-image/Dockerfile

@@ -1,26 +1,16 @@
-# Custom CI image for the arm64 (Raspberry Pi) Gitea Actions runner.
+# Custom CI image for the arm64 (Raspberry Pi) Gitea Actions runner,
+# since the official sagemath/sagemath image is amd64-only.
 #
-# The official sagemath/sagemath image is amd64-only; conda-forge's `sage`
-# package is the one place SageMath is actually published for linux-aarch64,
-# so this bakes it (plus the lint/test tools) into a single image, built and
-# pushed once rather than reinstalled on every CI run.
-#
-# Build & push (run directly on the Pi, or any arm64 machine with Docker):
+# Build & push commands:
 #   docker build -t gitea.piribauer.ch/julian/sage-ci:latest -f .gitea/ci-image/Dockerfile .
 #   docker login gitea.piribauer.ch -u julian
 #   docker push gitea.piribauer.ch/julian/sage-ci:latest
-#
-# Rebuild and re-push whenever this Dockerfile changes (e.g. bumping the sage
-# version) or the pinned tool versions need updating.
 
 FROM condaforge/miniforge3:latest
 
 RUN mamba install -y -c conda-forge sage ruff pytest \
     && mamba clean -afy
 
-# actions/checkout@v4 (and other JS-based actions) run via `node` inside this
-# container -- act_runner doesn't inject a runtime of its own when a custom
-# `container:` image is set, so one has to be present here.
 RUN mamba install -y -c conda-forge nodejs \
     && mamba clean -afy
 

.gitea/preparse.sh

@@ -1,18 +1,7 @@
 #!/usr/bin/env bash
-# Reproduces the CI "Preparse .sage files" step locally, so `ruff check` sees
-# the same generated *.sage.py files that the pipeline lints. Run this before
-# `ruff check --no-respect-gitignore .` to catch issues that only show up in
-# the generated output.
-#
-# Uses the sage.repl.preparse.preparse_file() Python API directly rather than
-# the `sage --preparse` CLI flag: the conda-forge `sage` binary used in CI is
-# a cut-down entry point that doesn't support `--preparse` (or `--python`) at
-# all, unlike the official sagemath CLI. Whichever `python` on PATH can
-# actually `import sage.repl` is used to run it -- in CI that's the conda
-# env's own `python`; locally (official sage install) it's `sage --python`.
-#
-# The generated files are gitignored; clean them up afterwards with:
-#   git clean -x sage/ playground/
+
+# This script is run in the CI container to preparse all .sage files into .sage.py files
+# and can also be run locally for local linting/testing.
 
 set -e
 

.gitea/workflows/ci.yml

@@ -9,9 +9,7 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
-    # Custom image (see .gitea/ci-image/Dockerfile): the official
-    # sagemath/sagemath image is amd64-only and this runner is arm64, and
-    # ruff/pytest are baked in here so jobs don't reinstall them every run.
+    # Custom image (see .gitea/ci-image/Dockerfile)
     container:
       image: gitea.piribauer.ch/julian/sage-ci:latest
 
@@ -20,18 +18,9 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Preparse .sage files
-        # Turns each *.sage file into real Python (*.sage.py) so ruff can
-        # parse it, and prepends the `from sage.all import *` that `sage`
-        # normally injects at runtime, so Sage's globals (ZZ, var, matrix, ...)
-        # resolve instead of looking like undefined names.
         run: .gitea/preparse.sh
 
       - name: ruff check
-        # --no-respect-gitignore: *.sage.py is gitignored (it's generated, see
-        # the previous step) but that's exactly what we need to lint here.
-        # `python` here is the conda env's own interpreter -- it already has
-        # sage/ruff/pytest importable, `sage --python` isn't a real flag on
-        # the conda-forge sage CLI.
         run: python -m ruff check --no-respect-gitignore .
 
   test:

pyproject.toml

@@ -3,33 +3,15 @@ line-length = 120
 target-version = "py311"
 
 [tool.ruff.lint]
+# E: pycodestyle errors, F: pyflakes (undefined/unused names), I: isort (import order), W: pycodestyle warnings
 select = ["E", "F", "I", "W"]
 ignore = [
     "E501", # symbolic-math expressions routinely exceed a "normal" line length
 ]
 
 [tool.ruff.lint.per-file-ignores]
-# *.sage.py is generated by `sage --preparse` from *.sage sources.
-# - F403/F405/F821/E741: Sage's runtime injects hundreds of globals (ZZ, var,
-#   matrix, LatticePolytope, ...) via `from sage.all import *` before
-#   executing these files, so plain static analysis can't see where names
-#   come from.
-# - E402/E702/I001: Sage's preparser itself emits an import-then-semicolon-
-#   joined-constants preamble (e.g. `_sage_const_1 = Integer(1); ...`) ahead
-#   of the file's own imports; that's Sage's boilerplate, not this project's
-#   code style.
-# - W291/W293: the preparser replaces every integer literal with
-#   `_sage_const_N ` (trailing space included) to preserve token boundaries,
-#   so trailing-whitespace warnings fire mechanically on almost every line
-#   with a number in it -- not something `ruff format` could fix anyway,
-#   since it wouldn't change the .sage source that generated it.
-# - W292: whether the reconstructed file ends in a real trailing newline
-#   depends on how many blank lines the preparser appends, which varies by
-#   Sage version -- not something worth pinning tool versions over.
+# *.sage.py is preparser output: star-import globals, semicolon preamble, and literal-substitution artifacts trip static analysis.
 "*.sage.py" = ["F403", "F405", "F821", "E741", "E402", "E702", "I001", "W291", "W293", "W292"]
 
-# tests/test_smoke.py does `from sage.all import *` and `load(...)` a .sage
-# file to get at its classes -- the same dynamic-namespace situation as
-# *.sage.py above, just in a hand-written file: ruff can't see that
-# Polytope/ToricPolytope/etc. come from the loaded file.
+# test_smoke.py star-imports sage.all and loads a .sage file, so ruff can't see where its names come from.
 "tests/test_smoke.py" = ["F403", "F405"]