Repository navigation
Description
Goal: every action has a user-manual chapter in docs/user, generated from its action.yml and checked in CI; docs/dev describes the project as it is; and the manual is published (#179).
Where we stand (verified 2026-09-28)
Next: PR 4 (#191), the cross-cutting chapters: getting started with migration, how the actions compose, containers, versioning and security, with the templates and container READMEs as signposts. #192, the docs/dev rewrites, can run alongside it.
- PR 1, the restructure into
docs/useranddocs/dev, merged as docs: move developer docs to docs/dev and remove stale docs (#178, PR 1 of 5) #182. PR 2 (docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter #189), the generator, the drift checks in the harness gate and thesetup-environmentchapter, merged as docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter (#178 PR 2) #204. Writing that chapter found that bumpingcache-versiondid not rebuild the environment (setup-environment: bumping cache-version does not give a fresh Conda environment #205), fixed in fix(setup-environment): bumping cache-version builds a fresh Conda environment (#205) #206, and the canary test of that fix found that a restore mixed two environments (setup-environment: a restored Conda environment mixes the cached one with the one setup-miniconda just created #209), fixed in fix(setup-environment): a restored Conda environment is an exact copy of the cache (#209) #210. PR 3 (docs(manual): chapters for the remaining seven actions, and delete QUICK-REFERENCE.md #190), the other seven action chapters and their signposts, merged as docs(manual): chapters for the other seven actions, and delete QUICK-REFERENCE.md (#190) #213:QUICK-REFERENCE.mdis gone, and the gate fails for an action without a chapter. Fact-checking those chapters against the code found three code problems, filed as preview-netlify, preview-cloudflare: change detection lists lectures the pull request did not change #215, preview-cloudflare: deploy-url assumes the project's pages.dev address is its name #216 and build-lectures: html-copy-notebooks flattens the notebooks, so a nested page's download link leads nowhere #217; the chapters describe the code as it stands and link each one. PRs 4 and 5 are sub-issues docs(manual): cross-cutting chapters, signpost the templates and container READMEs, delete MIGRATION-GUIDE and CONTAINER-GUIDE #191 and docs(dev): rewrite ARCHITECTURE and TESTING as the current design, trim PLAN, and replace copilot-instructions with AGENTS.md #192, and docs: publish the user manual to GitHub Pages with the standard QuantEcon docs theme #179 (publishing) comes last. It is blocked on a standard QuantEcon docs theme, which has no issue. - The Checklist at the end of this body predates the sub-issues; the sub-issue list is now the authority on membership, order and state.
Why
Someone adopting these actions has no single place that answers "which action do I use for this, how do I set it up, and what does it accept?".
docs/is mostly developer material.ARCHITECTURE.mdis design rationale;FUTURE-DEVELOPMENT.mdis a roadmap;GPU-AMI-SETUP.mdcovers runner infrastructure.MIGRATION-GUIDE.mdis a one-off playbook for converting lecture repos.QUICK-REFERENCE.mdis the nearest thing to a user reference, but it is a cheat sheet and carries known errors (docs: reconcile action READMEs and templates with the shipped code #109, docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99).docs/README.mdis an index. The repo root addsPLAN.md,TESTING.md,CONTRIBUTING.mdandPROJECT-OPTIMIZE-PREVIEWS.md, which are also maintainer-facing.
- The user-facing reference is spread over the per-action READMEs. That is eight files of 177–308 lines, each structured differently. They drift from each
action.yml: docs: reconcile action READMEs and templates with the shipped code #109 lists documented inputs that do not exist, inputs that exist but are missing, and a link to an action that was removed. - The docs are large and overlapping. PLAN item 10 counts roughly 4,900 doc lines for about 1,600 lines of action code, with four overlapping indexes.
What the manual covers
One chapter per action, all following the same template:
- What it does, and when to use it. Also when not to: for example
publish-gh-pagesagainstdeploy-cloudflare, andpreview-netlifyagainstpreview-cloudflare. - Requirements: runner or container, Node, the
permissions:block, secrets, and any one-time setup outside GitHub (the Netlify site, Pages settings, the Cloudflare Worker and Access checklist). - Inputs: name, required or not, default, and accepted values.
- Outputs, and when each one is set.
- Examples: a minimal workflow and a realistic one, each with its
permissions:block (docs: reconcile action READMEs and templates with the shipped code #109 found examples that 403 without one). - Behaviour: what it checks, what fails the job, cache keys, and the artifacts it produces.
- Troubleshooting.
That is eight chapters: setup-environment, build-lectures, build-jupyter-cache, restore-jupyter-cache, preview-netlify, preview-cloudflare, publish-gh-pages, and deploy-cloudflare (#163, #177).
Cross-cutting chapters:
- Getting started: choosing actions for a lecture repo, the standard CI / cache / publish set in
templates/, and migrating an existing repo. - How the actions compose: cache build → restore → build → preview or publish.
- Containers: which image to use and what is in it (from
docs/CONTAINER-GUIDE.mdand the container READMEs). - Versioning:
@v0against exact pins, and how releases reach consumers. - Security: fork PRs, secrets, and why
pull_request_targetmust not be used (fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105).
Keeping it true
#109 is what hand-maintained tables turn into. The input and output tables are generated from each action.yml, with a CI check that fails when the manual no longer matches. Examples pass actionlint in CI and link to the templates/ rather than copying them. Details are in decision 5.
Decisions (2026-09-24)
1. Audience
QuantEcon lecture-repo maintainers, written so it does not rely on insider knowledge.
- Every setup step is spelled out: no "ask X for the token", and nothing that exists only in a repo the reader may not be able to open.
- The manual opens by saying the actions are built for QuantEcon lecture repos and are on 0.x. Outside use is fine but unsupported. There is no separate path for outside users.
- The repo is public, so nothing in the manual carries account details. That includes the
deploy-cloudflareAccess checklist.
2. Format and home
GitHub-flavoured Markdown, read on GitHub, in two trees: docs/user (the manual) and docs/dev (developer docs). No built site for now.
Publishing to GitHub Pages with the standard QuantEcon docs theme is #179. That issue also records the test builds (Jupyter Book 1 and mystmd) behind this decision.
These writing rules keep #179 cheap:
- no strikethrough;
${{ … }}only inside backticks;- anything outside
docs/, directories especially, linked by its absolute GitHub URL; - file names unique within
docs/user.
GitHub alerts (> [!NOTE]) are allowed.
3. Per-action READMEs
Chapters live at docs/user/actions/<action>.md. Each <action>/README.md becomes a signpost.
- The signpost holds only the action's name, its
description:fromaction.yml, and links to the chapter and to the manual's index. It has no inputs and no examples. - Signposts are generated (decision 5).
- Content that exists only in READMEs today moves into the chapters:
- the Netlify and Cloudflare setup guides
- the Cloudflare vs Netlify comparison
- the
publish-gh-pagesmigration notes - the
deploy-cloudflareAccess checklist
4. Existing docs
Rule for both trees: the docs describe the project as it is: how to use it (docs/user), and how it is designed and maintained (docs/dev). They do not catalogue history. That means no dated status blocks, no "corrected on" notes, no struck-through finished items and no resolved questions. History lives in CHANGELOG.md, in issues and PRs, and in git.
| Today | Goes to |
|---|---|
docs/QUICK-REFERENCE.md |
Deleted. Content moves into the action chapters. Its one-screen action table becomes docs/user/README.md. |
docs/MIGRATION-GUIDE.md |
Deleted. The general steps and rollback become a docs/user chapter, "Migrating an existing repo". The per-repo notes move to PLAN's rollout section, because they describe rollout state and go stale. |
docs/CONTAINER-GUIDE.md, and the user-facing parts of containers/README.md, containers/quantecon/README.md and containers/quantecon-build/README.md |
A docs/user containers chapter. The container READMEs become signposts. Their Development, Automated Builds and Testing sections move to docs/dev. build-containers.yml gains '!containers/**/README.md' in paths:, so README edits stop rebuilding and pushing both :latest images. That is safe because the Dockerfiles copy only environment.yml. It is READMEs rather than all .md because the smoke-test fixture's pages are Markdown and must still trigger the build. |
docs/ARCHITECTURE.md |
docs/dev, rewritten as the current design. Its user-facing "how the actions fit together" material feeds the composition chapter. "Open Questions (Resolved)", "Success Criteria", "Migration Path" and the stale performance targets go. |
docs/GPU-AMI-SETUP.md |
docs/dev. How to run setup-environment on the AMI goes to that action's chapter. Whether the AMI build doc moves to QuantEcon/infrastructure is a separate question. |
containers/VALIDATION.md |
docs/dev/CONTAINER-VALIDATION.md. |
TESTING.md |
docs/dev, rewritten as how testing works now (harness, fixtures, canary). The dated status, phases, rollout plan and success metrics go. |
PLAN.md |
docs/dev, trimmed to current priorities, consumers, rollout state and dependency policy. |
docs/FUTURE-DEVELOPMENT.md |
Deleted. Ideas that are still live become issues. |
PROJECT-OPTIMIZE-PREVIEWS.md |
Deleted. #92 and its sub-issues hold the work. Any current design reasoning moves to docs/dev. |
docs/README.md |
Deleted. docs/user/README.md and docs/dev/README.md are the two indexes; GitHub shows each when its folder is opened. |
templates/README.md |
Signpost. Its content moves to Getting started. |
.github/copilot-instructions.md |
Deleted. Anything still useful moves to a general AGENTS.md at the root. It follows the same rule, and points at docs/dev rather than repeating it. |
README.md, CHANGELOG.md, CONTRIBUTING.md, LICENSE |
Stay at the root. The README's Documentation section points at docs/user and docs/dev. |
tests/README.md |
Stays. |
Notes on the moves:
- Moves use
git mv, so history is kept. - Moving
PLAN.mdbreaks existing links toblob/main/PLAN.md, because GitHub does not redirect moved files. That is accepted. - The harness gate's
IGNOREDlist and its self-test name the moved root files. They are updated to the new paths, andAGENTS.mdis added to the list. - This absorbs all of PLAN item 10.
5. Keeping it true
action.ymlis the single source for per-input and per-output facts. Its descriptions are written for readers, including accepted values and when each output is set. The generator copies them verbatim. Chapter prose covers behaviour, not per-input facts.- Generated content. All of it is committed, between
<!-- BEGIN GENERATED: … -->and<!-- END GENERATED -->markers:- each chapter's Inputs table (name, required, default, description) and Outputs table
- each signpost README, in full
- the action table in
docs/user/README.md
- Generator.
scripts/generate-docs.py, written in Python 3 with PyYAML. Its--checkmode prints the diff and fails. PyYAML is pinned in a requirements file under Dependabot's pip ecosystem. - Examples.
- The realistic example is a link to the template that uses the action, not a copy.
- The minimal example is a short, complete workflow with its
permissions:block. - Checks:
- actionlint runs on
templates/*.ymland on every complete workflow in ayamlblock indocs/user. It is installed as a pinned release with a checksum, becauseactionlint-pyships only an sdist. - Every
quantecon/actions/<x>@…step in the docs and templates uses only inputs that exist in thataction.yml, and supplies every required one. - Every complete example has a
permissions:block.
- actionlint runs on
- Where the checks run. In the harness
gatejob, beside the template pin-drift check from fix(actions): #107 correctness batch and #109 code items #173. A docs-only PR matchesIGNOREDand skips every other job. The gate also fails when an action directory has no chapter.
Running actionlint on .github/workflows/ is out of scope.
6. Sequencing
The sweep starts now that the open PRs are settled. #176 and #174 have merged, and #144 will not be merged.
- deploy-cloudflare: support public sites with an explicit
visibilityinput #177 does not hold up the sweep. Thedeploy-cloudflarechapter is written for what is onmain:require-access, as released in v0.12.0. The PR for deploy-cloudflare: support public sites with an explicitvisibilityinput #177 then updates the chapter along with the code. - The sweep is the five PRs in the checklist below. They land in order 1 → 4, with PR 5 running alongside PRs 2–4.
7. Which version the manual describes
main. The manual's index and each chapter header say:
This describes
main. For the version you pin, open the manual at that tag. Changes not yet released are under[Unreleased]in the CHANGELOG.
Automatically marking unreleased inputs can come later if the gap causes confusion. That would mean comparing against the latest release named in the CHANGELOG, not against v0, because moving v0 is only a tag push and would turn the next unrelated PR red.
Relationship to existing issues
- docs: reconcile action READMEs and templates with the shipped code #109, docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106 and docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99. Their fixes are on
main(docs: 2026.06 baseline, measured image sizes, and READMEs reconciled with the shipped code (#106, #109, #99) #175, fix(actions): #107 correctness batch and #109 code items #173), so the manual starts from corrected facts. - deploy-cloudflare: publish private sites to a Cloudflare Worker behind Access, and prove they are gated #163, feat: deploy-cloudflare — publish private sites to a Worker behind Access, and prove they are gated (#163) #176 and deploy-cloudflare: support public sites with an explicit
visibilityinput #177. Thedeploy-cloudflarechapter is written frommain. deploy-cloudflare: support public sites with an explicitvisibilityinput #177's PR updates it forvisibility. - docs: publish the user manual to GitHub Pages with the standard QuantEcon docs theme #179. Publishing the manual to GitHub Pages.
- Optimize preview builds: phased plan for the fastest PR previews (tracking) #92. Holds the preview-optimisation plan once
PROJECT-OPTIMIZE-PREVIEWS.mdis deleted. - Docs: guidance on composite actions vs reusable workflows (+ env-test harness proposal) #29 (PLAN item 11). Its contributor guidance belongs in
CONTRIBUTING.mdordocs/dev. It is not part of this issue. - PLAN item 10. Absorbed (decision 4).
Checklist
- Decide audience, format and home, READMEs, existing docs, drift checks, sequencing and version (above)
- PR 1 — restructure (docs: move developer docs to docs/dev and remove stale docs (#178, PR 1 of 5) #182).
git mvthe developer docs intodocs/devand fix links.- Delete
FUTURE-DEVELOPMENT.md(live ideas filed as issues first),PROJECT-OPTIMIZE-PREVIEWS.mdanddocs/README.md. - Update the gate's
IGNOREDlist and self-test, addingAGENTS.md. - Add
'!containers/**/README.md'tobuild-containers.yml.
- PR 2 — tools and one worked chapter (docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter (#178 PR 2) #204).
- The generator and its checks in the
gatejob, actionlint, and the requirements file. - The chapter template.
- The
setup-environmentchapter and its signpost.
- The generator and its checks in the
- PR 3 — the remaining action chapters (docs(manual): chapters for the other seven actions, and delete QUICK-REFERENCE.md (#190) #213).
- Signpost READMEs for each.
- Delete
QUICK-REFERENCE.md. - Enable the every-action-has-a-chapter check.
- PR 4 — cross-cutting chapters.
- Getting started (with migration), composition, containers, versioning and security.
- Templates and container READMEs become signposts.
- Delete
MIGRATION-GUIDE.mdandCONTAINER-GUIDE.md. - Point the root README and the CONTRIBUTING doc-update matrix at the manual.
- PR 5 —
docs/devrewrites.- ARCHITECTURE, TESTING and the PLAN trim.
AGENTS.mdreplaces.github/copilot-instructions.md.
Activity
docs: move developer docs to docs/dev, remove stale docs (#178 PR 1) (#…
quantecon-services commentedon Sep 24, 2026
This issue is now the user manual's Project tracker (QEP-6). The five-PR checklist in the body is mapped onto native sub-issues, in plan order:
setup-environmentchapter: docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter #189.publish-gh-pages' release assets as a stable format.docs/devrewrites andAGENTS.md: docs(dev): rewrite ARCHITECTURE and TESTING as the current design, trim PLAN, and replace copilot-instructions with AGENTS.md #192. It runs alongside PRs 2–4 and carries docs: sweep to the Anaconda 2026.06 baseline and measured container sizes #106's three trim leftovers.The
documentationlabel has moved to the sub-issues; under QEP-2 a sub-issue parent carries no Type label.The body is unchanged, because its decisions are the spec for the sub-issues. To fully conform to QEP-6, it would still need the checklist section replaced by a pointer to the sub-issue list, plus a goal line and a
## Where we stand (verified …)stamp. I left that edit for a human rather than rewrite the body programmatically.Generated by Claude Code
docs(plan): refresh after v0.12.0 closed the July 2026 audit; finish …
docs(manual): doc generator and drift checks, the chapter template, a…
docs(manual): chapters for the other seven actions, and delete QUICK-…
docs(manual): the cross-cutting chapters, and signposts for the templ…
docs(dev): CONTAINER-VALIDATION.md describes the lecture matrix as it…
docs(dev): ARCHITECTURE and TESTING as the current design, PLAN trimm…
mmcky commentedon Nov 10, 2026
All four of this tracker's work items are done: #189 (the generator and drift checks), #190 (the action chapters), #191 (the cross-cutting chapters) and #192 (the
docs/devrewrites).docs/usernow has a chapter for each of the 11 actions,restore-gh-pagesincluded, generated from itsaction.ymland checked in CI. Publishing the manual to GitHub Pages is #179, deferred until QuantEcon's docs theme exists, and it stays open on its own. Closing.Claude Code (on behalf of mmcky)