Repository navigation
Description
Blocked by
Blocked by #45 — that issue documents how to preview/render the Quarto site
locally (quarto preview, quarto render from quarto/). This issue builds
automation on top of that manual workflow, so it should not be worked until
#45's documentation has landed and the manual steps are confirmed correct.
Purpose
Automate publishing of the Quarto site (quarto/) on push to main,
following the same render → freeze → publish pattern used by
INGEOTEC/AprendizajeComputacional:
a local script renders the notebooks and verifies the committed _freeze/
cache is in sync before anything is pushed, and GitHub Actions publishes
straight from that frozen cache — without installing the scientific Python
stack in CI.
Observed pattern (AprendizajeComputacional)
_quarto.ymlsetsexecute: freeze: auto, so Quarto only re-executes a
page whose source changed since its_freeze/entry was committed.scripts/render.pyis run locally (inside the devcontainer, which has
Quarto installed) before pushing. It:- installs any missing rendering dependencies from
requirements.txt, - runs
quarto renderover the site, - verifies every page's frozen result the way Quarto's freeze mechanism
reads it: source hash matches, and every figure the frozen markdown
references actually exists under_freeze/, - warns if the local Quarto version differs from the one pinned in the
publish workflow, - reports which paths changed (
_freeze/+ any changed pages) so the
author knows what togit add/commit.
- installs any missing rendering dependencies from
.github/workflows/publish.ymltriggers onpushto the default branch
(plusworkflow_dispatch), installs only Quarto (no Python/conda), and
runsquarto-dev/quarto-actions/publish@v2targetinggh-pages. Because
the freeze cache is already committed and in sync, CI never needs to
execute notebook code itself.
CompStats already has execute: freeze: auto in quarto/_quarto.yml and a
tracked quarto/_freeze/ cache, so this issue is about adding the missing
pieces (the local render/verify script and the push-triggered, freeze-only
publish job), not introducing freezing from scratch.
Plan
-
Add
scripts/render.py(repo root), adapted from
AprendizajeComputacional's version for CompStats's site shape
(quarto/index.ipynb+quarto/pages/*.ipynb, listed from thenavbar
entries inquarto/_quarto.ymlrather than a book's chapter list):--verify-onlyto just check the committed cache,--force [pages...]to drop frozen results and re-execute,--skip-depsto skip therequirements.txtinstall check,- checks the local
quarto --versionagainst the version pinned in
.github/workflows/publish.yml, - verifies each notebook's
_freeze/<page>/execute-results/html.json
hash matches the current source and that referenced
_freeze/<page>/figure-html/*assets exist, - prints
git status --porcelainforquarto/_freezeand the notebooks
at the end, so the author knows exactly what to commit.
-
Update
.github/workflows/publish.yml:- trigger on
push: branches: [main]in addition to the existing
workflow_dispatch, - add a
concurrencygroup (e.g.website) withcancel-in-progress, - drop the
conda-incubator/setup-minicondastep and the full
numpy/scipy/scikit-learn/... install — CI will rely entirely on the
committed freeze cache, - keep
quarto-dev/quarto-actions/setup@v2(pin the same version
scripts/render.pychecks against) and replace the manual
quarto publish gh-pages --no-browsershell step with
quarto-dev/quarto-actions/publish@v2targetinggh-pages. - CompStats's pages don't use Mermaid diagrams, so the headless-Chrome
setup step from AprendizajeComputacional's workflow is not needed here.
- trigger on
-
Document the local step: note in the repo (README or
CONTRIBUTING-style doc, alongside whatever Documentar cómo previsualizar el sitio Quarto y la documentación de docs/ desde develop #45 adds) that
python scripts/render.pymust be run and its output committed
(quarto/_freeze/+ any changed notebook) before merging tomain,
since pushing tomainnow publishes automatically from whatever freeze
cache is committed at that point. -
Verify end-to-end: on a branch, deliberately change a notebook,
runscripts/render.py, commit the updated freeze cache, merge to
main, and confirm thepublish.ymlrun picks up the change and
deploys without installing Python.
Activity
Formalize documentation, CI and PyPI publishing (#48, #49, #50) (#51)
mgraffg commentedon Nov 20, 2026
Absorbed by #50, implemented in #51, merged into develop. Commit 8608cbb.
Develop (#52)
Develop (#53)