Repository navigation
docs(manual): chapters for the other seven actions, and delete QUICK-REFERENCE.md (#190) - #213
Merged
Merged
Conversation
…RENCE.md (#190) PR 3 of the user manual (#178). build-lectures, build-jupyter-cache, restore-jupyter-cache, preview-netlify, preview-cloudflare, publish-gh-pages and deploy-cloudflare each get a chapter in docs/user/actions/, from the chapter template, and their READMEs become generated signposts. - Each action.yml's input and output descriptions are rewritten for readers, since the manual copies them verbatim. They are corrected where they or the READMEs were wrong: restore-jupyter-cache's path is part of a cache's identity, so any path but _build finds nothing build-jupyter-cache saved; restore uses two build-cache fallbacks, not three; the preview actions fetch the base and head commits themselves. - README-only content moves into the chapters: the Netlify and Cloudflare Pages setup guides, their comparison (kept to what the actions do), the publish-gh-pages migration notes, and the deploy-cloudflare Access checklist, with no account details. - publish-gh-pages documents its release assets (archive, SHA-256 checksum, manifest) as a contract (#27). - docs/QUICK-REFERENCE.md is deleted, and every link to it repointed. - scripts/generate-docs.py makes a missing chapter an error, so the gate fails for an action without one. - deploy-cloudflare's refusal message points at the chapter's setup checklist instead of the README. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
…chapters #211 added a paragraph to the preview-netlify and preview-cloudflare READMEs: on any event other than pull_request, the actions skip change detection, the deploy and the comment without logging it, and succeed with empty outputs. This branch turns those READMEs into generated signposts, so they are regenerated with scripts/generate-docs.py, and the paragraph's facts move into both chapters' Behaviour sections. The CHANGELOG and PLAN conflicts were two entries added at the same place: both are kept, newest first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
#214 and this branch each put a new first entry on PLAN's "Last updated" line. Both are kept, this branch's first since it lands last, followed by #214's and then #211's. #214's #102 row and this branch's item 10 row do not overlap. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
A fact-check of the chapters against the actions, their scripts and the pinned CLIs' sources found these. Preview actions: - Change detection compares the tip of the base branch with the pull request's head, so it lists lectures changed on the base branch since the pull request branched off. The chapters and the lectures-dir and changed-files descriptions now say so; the code fix is #215. - lectures-dir is matched against paths from the repository root, so ./lectures and lectures/ match nothing. - preview-cloudflare builds its URLs from project-name, which is wrong when Cloudflare gives the project another pages.dev address. The setup guide now says to check it; the code fix is #216. - Netlify's dashboard calls a site a project: the setup steps use its words. The README's recommendation to unlink, and its table of which setup to use, are back, with an example of the comment. - The comment is looked up among the first 30 comments; the missing failure cases and messages (an unset token, no deploy URL, a missing Pages project) have troubleshooting entries; both QuantEcon images trust every directory for git, so the safe.directory advice is for other images. restore-jupyter-cache: - The caches save execution time only if the book sets execute_notebooks: cache. Sphinx re-reads every page of a fresh checkout, so the claim that it rewrites only changed pages is gone. - A different environment-update still hits through the fallback, and neither key records the container image. - save-cache: a cache saved from a branch reaches every pull request, so it is for pull-request builds only; a re-run matches its own key exactly and saves nothing; a custom key is saved once. - The execution cache's fallback can hand back outputs made with old packages; caches are also evicted when storage is full. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
…ters From the fact-check of both chapters against the actions, the gate probe and wrangler 4.139.0's source. deploy-cloudflare: - On a hostname found ungated, the chapter and the action's error message said to turn off the Worker's workers.dev route. With the route off, preview URLs stay on, and wrangler itself warns they may be public. Both now say to turn off the route and the preview URLs. - The Worker's Access setting is not shown to cover custom domains, and the action never checks them: the chapter now says to check a custom domain by hand with check-access-gate.sh. - The alias is uploaded only after the deploy and the check after it pass; the probe skips dot-directories too; worker-name cannot start or end with a dash; a require-access value other than true or false fails. - The Terraform resource names carry their cloudflare_ prefix; outside collaborators are not members, so the audience example is a member who joined for a translation or a course; the default login method is named. check-access-gate.sh's usage example uses a placeholder team. publish-gh-pages: - A tag containing / fails the release assets, after the site is live. - size_mb, like file_count, is measured before cname writes its file. - The github-token check applies only to tag-triggered runs; a release is found by its tag and created if missing; the deploy uses the job's token as well as its OIDC token. - Moving from a gh-pages branch gains the environment step for tag deploys and a link to the migration guide, and drops a reference to an input no released version had. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
From the fact-check of build-lectures and build-jupyter-cache against the actions and the sources of Jupyter Book 1.0.4, Sphinx 7.4.7, myst-nb and quantecon-book-theme 0.22.0. build-lectures: - The theme links a page's notebook with the page's directory in the path, but html-copy-notebooks copies the notebooks flat, so a nested page's link leads nowhere (#217). Both download links also start at the site's root, which breaks them on a site served under a path. - Both QuantEcon images trust every directory for git, so the dubious ownership handling applies to other images only, and it writes no git configuration file. - A rebuild over the same _build after a failed -W build reads nothing and passes, so --all is needed to see the failures again; pdflatex and jupyter run with -n, so under -W an unresolved reference fails them; ci.yml's shallow checkout dates every preview page to one commit; for another builder, build-path is the directory above its output. build-jupyter-cache: - The builders share _build/.doctrees, so a failing notebook usually fails only the first builder to run it. - The @v0 siblings behave as in the latest release, not as main does. - The failure issue names execution-report artifacts that a build which failed early never uploaded; cache-saved reports the build result, and a failed save only warns; execute_notebooks: cache is required. CHANGELOG: the corrections, the three issues they found, and the deploy-cloudflare message fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb
Open
4 of 6 tasks
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
It spans ~35 files including a CI-gated generator change and two intentional action-behavior/message changes whose gate (generate-docs.py --check and the full harness) cannot be exercised in this review environment, so human sign-off is warranted.
Review effort: Balanced
Findings: None
What changed in this PR
This is PR 3 of the user-manual effort (#178), closing #190. It adds a user-manual chapter for each of the remaining seven actions, converts each action's README.md into a generated signpost, deletes the obsolete docs/QUICK-REFERENCE.md, and makes "every action must have a chapter" a hard error in the docs generator so the CI gate fails if a chapter is missing. The seven action.yml descriptions are rewritten for readers (they are copied verbatim into the generated tables), and two intentional behavior changes accompany the docs: the deploy-cloudflare "not gated" error message and a comment in check-access-gate.sh.
Changes:
- Seven new chapters under
docs/user/actions/, with README-only content (Netlify/Cloudflare setup guides, the provider comparison,publish-gh-pagesmigration notes, the Access checklist, and the release-asset contract from #27) migrated into them. scripts/generate-docs.pynow reports a missing chapter as an error (failing--check) and always links the index table toactions/<name>.md;docs/QUICK-REFERENCE.mdis deleted and its inbound links repointed to the manual.- Reader-facing
action.ymldescription rewrites for all seven actions (plus onedeploy-cloudflareerror-message change and one shell comment), with supporting edits to CHANGELOG, PLAN, CONTRIBUTING, ARCHITECTURE, TESTING, and copilot-instructions.
| File | Description |
|---|---|
scripts/generate-docs.py |
Core code change: missing chapter is now an error; index table always links to the chapter. |
docs/user/actions/{build-lectures,build-jupyter-cache,restore-jupyter-cache,preview-netlify,preview-cloudflare,publish-gh-pages,deploy-cloudflare}.md |
Seven new manual chapters; the deliverable of this PR. |
{build-lectures,build-jupyter-cache,restore-jupyter-cache,preview-netlify,preview-cloudflare,publish-gh-pages,deploy-cloudflare}/action.yml |
Reader-facing description: rewrites; deploy-cloudflare also changes one error message. |
{…seven…}/README.md |
Regenerated signposts pointing to the chapter and manual index. |
deploy-cloudflare/check-access-gate.sh |
Comment-only update aligning with the new "turn off both" guidance. |
docs/user/README.md |
Index action table now links every chapter. |
docs/QUICK-REFERENCE.md |
Deleted; content absorbed into chapters and index. |
CHANGELOG.md, docs/dev/PLAN.md, CONTRIBUTING.md, docs/dev/ARCHITECTURE.md, docs/dev/TESTING.md, docs/dev/CHAPTER-TEMPLATE.md, .github/copilot-instructions.md, .github/workflows/test-actions.yml |
Supporting edits reflecting the deletion, the new check, and the manual structure. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Collaborator
Author
|
Replying to the Copilot overview: it reports no findings, so nothing in the code changes. On the two things it leaves for a person to check:
What's left for a person is the prose: whether the chapters read well and say what the manual should. Generated by Claude Code |
2 of 21 tasks
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 #190. PR 3 of the user manual (#178): every action now has a chapter, and the harness gate fails for an action without one.
What's in it
docs/user/actions/, fromdocs/dev/CHAPTER-TEMPLATE.md:build-lectures,build-jupyter-cache,restore-jupyter-cache,preview-netlify,preview-cloudflare,publish-gh-pagesanddeploy-cloudflare. Each action's README becomes a generated signpost to its chapter, and the index's action table links every chapter.action.ymldescriptions for all seven, rewritten for readers, since the generator copies them into the chapters' tables. Only descriptions and comments change, apart from twodeploy-cloudflareerror messages (below).preview-netlify, linked frompreview-cloudflare;pull_request;publish-gh-pagesmigration notes, as "Moving from agh-pagesbranch";deploy-cloudflareAccess checklist, with no account details.publish-gh-pageschapter gives the exact file names, the archive's layout, the checksum's format and each manifest field. It says a release changes any of them only with a CHANGELOG entry, and that the checksum and manifest names carry no tag.docs/QUICK-REFERENCE.mdis deleted. Its action table is the manual's index, and its examples, cache keys and debugging tips are in the chapters. Links to it now point at the manual.scripts/generate-docs.pyreports a missing chapter as an error, so the gate's--checkfails.Fact-checked against the code
After the first draft, each chapter was checked claim by claim against its
action.yml, the scripts, the harness, and the sources of what the actions call. That meant the pinnednetlify-cli27.9.0,wrangler4.139.0 and@actions/cache6.3.0 from npm, and Jupyter Book 1.0.4, Sphinx 7.4.7, myst-nb and quantecon-book-theme 0.22.0 from PyPI. The corrections are inbbc542b,6a1328aand1f03040. The most important:execute_notebooks: cache. Without it there is no execution cache to save or restore. Sphinx re-reads every page of a fresh checkout, so the old README claim that it rewrites only changed pages is gone.restore-jupyter-cache:pathis part of a cache's identity, so any path but_buildfinds none ofbuild-jupyter-cache's caches.environment-updatestill hits through the fallback.save-cachefrom a branch would reach every pull request, so it is for pull-request builds only.build-jupyter-cache:@v0siblings behave as in the latest release, not asmaindoes._build/.doctrees, so a failing notebook usually fails only the first builder to run it.cache-savedreports the build's result, not whether the save succeeded.build-lectures: both QuantEcon images trust every directory for git. A rebuild after a failed-Wbuild reads nothing and passes, so it needs--all.preview-*: the Netlify dashboard now says "project";lectures-dirmust be written aslectures; the comment is looked up among the first 30 comments.deploy-cloudflare: the advice for an ungated hostname was to turn off theworkers.devroute. That leaves the preview URLs public, as wrangler itself warns. The chapter and the action's error message now say to turn off both. Custom domains are checked by hand, since the action checks onlyworkers.dev. The message that refuses a first deploy now links the chapter's setup checklist, because the README that held the checklist is now a signpost.publish-gh-pages: a tag containing/fails the release assets after the site is live. Moving from agh-pagesbranch gains the environment step for tag deploys.Found and filed, not fixed here
Code problems the fact-check turned up. The chapters describe how the code behaves now and link to each issue:
preview-cloudflarebuilds its URLs fromproject-name, which is wrong when Cloudflare gives the project anotherpages.devaddress.html-copy-notebookscopies the notebooks flat, so the download link of a page in a subdirectory leads nowhere.Left out, on purpose
docs/devrewrites are PR 5 (docs(dev): rewrite ARCHITECTURE and TESTING as the current design, trim PLAN, and replace copilot-instructions with AGENTS.md #192).Checks
python3 scripts/generate-docs.py --check --check-examples --actionlint …passes. Every generated block is current, and the 45quantecon/actionssteps and 14 complete workflows it checks are all actionlint-clean.--checkfail withpublish-gh-pages has no chapter: write docs/user/actions/publish-gh-pages.md, starting from docs/dev/CHAPTER-TEMPLATE.md.#anchorindocs/, the action READMEs and the root docs resolves. Every absoluteblob/mainortree/mainlink names a path that exists.action.ymlwithmain, ignoringdescription:fields, leaves exactly two differences: the twodeploy-cloudflare::error::messages above.scripts/check-access-gate.shchanges only a usage comment, whose example now uses a placeholder team domain rather than the real one. The whole harness runs on this PR, since theaction.ymlfiles change.mainwas merged in twice, for docs: correct the statements the #143 spike disproved #211 and docs(plan): record #102 as closed by #203, and the run that exercised it #214. The only conflicts were two entries added at the same place in the CHANGELOG and PLAN, and both entries are kept.🤖 Generated with Claude Code
https://claude.ai/code/session_01FeKTxWtkzVMyPbqeSgM2Tb