Skip to content

Docs: sweep stale references and inconsistencies (#40) - #66

Merged
mmcky merged 3 commits into
mainfrom
docs/consistency-sweep
Jun 16, 2026
Merged

mmcky merged 3 commits into
mainfrom
docs/consistency-sweep

Conversation

@mmcky

@mmcky mmcky commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Closes #40 (D24–D34) — fixes dead references and inconsistencies across the docs.

Dead/stale references fixed

  • D24containers/VALIDATION.md described a three-stage builder pipeline (test-html-builder.yml, …) that doesn't exist → replaced with the real test-containers-lectures.yml + test-container.yml.
  • D25build-jupyter-cache/README.md referenced a non-existent cache-standard.yml.
  • D26docs/ARCHITECTURE.md repo tree listed non-existent Dockerfile.gpu / environment-gpu.yml → replaced with the real quantecon + quantecon-build layout.
  • D30 — refreshed the stale README status line.
  • D33 — fixed a mangled code fence in TESTING.md.
  • D29 — documented failure-artifact-name (and corrected output-dir) in QUICK-REFERENCE.md.
  • D28MIGRATION-GUIDE.md no longer presents the non-container path as the recommendation.
  • Bonus — README usage examples used @main → switched to @v0 (the C1 sweep only touched @v1).

Previously-flagged judgment calls — now resolved

  • D27 (container sizes) — measured, not guessed. Pulled both images (amd64) and read the sizes: lean 7.14 GB / full 8.34 GB on disk; 2.85 GB / 3.24 GB compressed pull. The old "lean ~3 GB vs full ~8 GB" was mixing metrics (compressed-lean vs on-disk-full), implying a size gap that doesn't exist — LaTeX + the scientific stack dominate both, so "lean" is only modestly smaller. All size mentions now state both metrics explicitly.
  • D31 (consuming-repo list) — removed. Per maintainer, the per-repo list is a maintenance burden; replaced with a pointer to QuantEcon/meta#321, which will track it centrally.

Notes

  • D32 (duplicate build-time tables) turned out moot — VALIDATION.md has no build-time table.
  • Docs-only; no action behavior changes.

Closes #40

🤖 Generated with Claude Code

- 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>
Copilot AI review requested due to automatic review settings June 16, 2026 06:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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, @v0 usage examples, container layout/sizing notes).
  • Fixed a broken markdown code fence in TESTING.md and 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).

Comment thread docs/ARCHITECTURE.md Outdated
Comment thread docs/ARCHITECTURE.md Outdated
- 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
mmcky force-pushed the docs/consistency-sweep branch from 4f69e98 to 3fb1ebd Compare June 16, 2026 07:05
@mmcky
mmcky merged commit 340028e into main Jun 16, 2026
@mmcky
mmcky deleted the docs/consistency-sweep branch August 7, 2026 04:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation sweep: stale references and inconsistencies

2 participants