Docs: sweep stale references and inconsistencies (#40) - #66
Merged
Merged
Conversation
- D24: containers/VALIDATION.md described a 3-stage builder pipeline with workflows that don't exist; replaced with the real test-containers-lectures.yml. - D25: build-jupyter-cache/README referenced a non-existent cache-standard.yml. - D26: docs/ARCHITECTURE.md listed non-existent Dockerfile.gpu / environment-gpu.yml. - D27: standardised container sizes (~3 GB lean / ~8 GB full) across README / ARCHITECTURE / CONTAINER-GUIDE; documented the lean image in the Container Guide. - D28: MIGRATION-GUIDE no longer presents the non-container path as THE recommendation. - D29: documented failure-artifact-name (and fixed output-dir) in QUICK-REFERENCE. - D30: refreshed the stale README status line. - D31: reconciled the README "Usage by Repository" list (non-exhaustive; aligned to CI). - D33: fixed a mangled code fence in TESTING.md. - Also switched the README usage examples from @main to @v0 (consistency with the documented versioning). Closes #40 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Docs-only cleanup addressing issue #40 by removing stale/dead references and aligning documentation with the repository’s current workflows, templates, and release/versioning guidance.
Changes:
- Replaced dead/fictional workflow and template references across docs with the current, real workflows/templates (e.g., container validation + cache template references).
- Standardized and refreshed documentation details (release status,
@v0usage examples, container layout/sizing notes). - Fixed a broken markdown code fence in
TESTING.mdand updated quick-reference inputs.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
TESTING.md |
Fixes a mangled code fence in troubleshooting docs. |
README.md |
Updates status line and switches usage examples to @v0; refreshes “Usage by Repository” list. |
docs/QUICK-REFERENCE.md |
Updates build-lectures example (output-dir) and documents failure-artifact-name. |
docs/MIGRATION-GUIDE.md |
Clarifies container-first recommendation while keeping setup-environment example. |
docs/CONTAINER-GUIDE.md |
Documents both container images and aligns sizing/pull-time narrative. |
docs/ARCHITECTURE.md |
Updates repo tree and container sizing, but still contains internal inconsistencies (see PR comments). |
containers/VALIDATION.md |
Replaces fictional multi-workflow pipeline description with the current testing workflows. |
CHANGELOG.md |
Adds an Unreleased entry summarizing the doc sweep. |
build-jupyter-cache/README.md |
Removes reference to a non-existent workflow template (cache-standard.yml). |
- Container sizes were guessed and mixed two metrics. Measured them (amd64): lean 7.14 GB / full 8.34 GB on disk; 2.85 GB / 3.24 GB compressed pull. Corrected README / ARCHITECTURE / CONTAINER-GUIDE to state both metrics explicitly (the old "lean ~3 GB vs full ~8 GB" compared compressed-lean to on-disk-full, implying a size gap that doesn't exist — LaTeX dominates both). - Replaced the README "Usage by Repository" per-repo list with a pointer to QuantEcon/meta#321 (tracked centrally; not a maintenance burden here). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
mmcky
added a commit
that referenced
this pull request
Jun 16, 2026
…sistency - Images bullet now lists both the full and lean images (the size bullet referenced both but the list named only the full one). - Drop the inaccurate 'cached once by GitHub Actions runners' — hosted runners are ephemeral and fetch the image each run. - Pull time '~20 seconds' was unrealistic for a ~3 GB image and contradicted the Container Guide's ~2 min; corrected to ~1-2 min on hosted runners (with self-hosted/pre-cached noted), and fixed the matching '# 20 sec' example. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…sistency - Images bullet now lists both the full and lean images (the size bullet referenced both but the list named only the full one). - Drop the inaccurate 'cached once by GitHub Actions runners' — hosted runners are ephemeral and fetch the image each run. - Pull time '~20 seconds' was unrealistic for a ~3 GB image and contradicted the Container Guide's ~2 min; corrected to ~1-2 min on hosted runners (with self-hosted/pre-cached noted), and fixed the matching '# 20 sec' example. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
mmcky
force-pushed
the
docs/consistency-sweep
branch
from
June 16, 2026 07:05
4f69e98 to
3fb1ebd
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #40 (D24–D34) — fixes dead references and inconsistencies across the docs.
Dead/stale references fixed
containers/VALIDATION.mddescribed a three-stage builder pipeline (test-html-builder.yml, …) that doesn't exist → replaced with the realtest-containers-lectures.yml+test-container.yml.build-jupyter-cache/README.mdreferenced a non-existentcache-standard.yml.docs/ARCHITECTURE.mdrepo tree listed non-existentDockerfile.gpu/environment-gpu.yml→ replaced with the realquantecon+quantecon-buildlayout.TESTING.md.failure-artifact-name(and correctedoutput-dir) inQUICK-REFERENCE.md.MIGRATION-GUIDE.mdno longer presents the non-container path as the recommendation.@main→ switched to@v0(the C1 sweep only touched@v1).Previously-flagged judgment calls — now resolved
Notes
VALIDATION.mdhas no build-time table.Closes #40
🤖 Generated with Claude Code