docs(manual): chapters for the other seven actions, and delete QUICK-REFERENCE.md (#190)

.github/copilot-instructions.md

@@ -19,7 +19,7 @@ This repository provides **reusable GitHub Actions** for building QuantEcon lect
 | **Container usage** | [docs/CONTAINER-GUIDE.md](../docs/CONTAINER-GUIDE.md) |
 | **GPU AMI setup** | [docs/dev/GPU-AMI-SETUP.md](../docs/dev/GPU-AMI-SETUP.md) |
 | **Testing validation** | [docs/dev/TESTING.md](../docs/dev/TESTING.md) |
-| **Quick reference** | [docs/QUICK-REFERENCE.md](../docs/QUICK-REFERENCE.md) |
+| **Using the actions, one chapter each** | [docs/user/README.md](../docs/user/README.md) |
 | **Release process** | [CONTRIBUTING.md](../CONTRIBUTING.md) |
 | **Version history** | [CHANGELOG.md](../CHANGELOG.md) |
 
@@ -60,8 +60,8 @@ Before merging action changes:
 
 ### Documentation Updates
 When changing actions, update:
-- Action's `README.md` (inputs/outputs)
-- `docs/QUICK-REFERENCE.md` (if inputs added)
+- The action's `action.yml` descriptions, then run `python3 scripts/generate-docs.py` (inputs/outputs)
+- The action's chapter, `docs/user/actions/<action>.md` (what it does)
 - `CHANGELOG.md` (user-facing changes)
 - `docs/dev/PLAN.md` (if affects migration status)
 

.github/workflows/test-actions.yml

@@ -263,9 +263,10 @@ jobs:
           [ "$drift" -eq 0 ] || exit 1
           echo "✅ templates/ third-party pins match .github/workflows/ ($checked checked)"
 
-      # #178, decision 5: the user manual's Inputs and Outputs tables, its
-      # action table and the signpost READMEs are generated from each
-      # action.yml, and its examples are checked against them. In the gate for
+      # #178, decision 5: every action has a chapter in the user manual; its
+      # Inputs and Outputs tables, the action table and the signpost READMEs
+      # are generated from each action.yml, and the manual's examples are
+      # checked against them. In the gate for
       # the reason the pin check above is: a docs-only PR matches IGNORED and
       # skips every other job. PyYAML is the pin in scripts/requirements.txt,
       # installed into a venv because the runner's Python is externally managed.
@@ -290,7 +291,7 @@ jobs:
           tar -xzf "$RUNNER_TEMP/$tarball" -C "$RUNNER_TEMP/actionlint" actionlint
           "$RUNNER_TEMP/actionlint/actionlint" -version
 
-      - name: Check the manual's generated tables match each action.yml
+      - name: Check every action has a chapter, and the manual's generated tables match each action.yml
         run: |
           "$RUNNER_TEMP/docs-venv/bin/python" scripts/generate-docs.py --check
 
@@ -1710,7 +1711,7 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      # The Node the READMEs tell hosted-runner callers to set up, and the major
+      # The Node the manual tells hosted-runner callers to set up, and the major
       # the QuantEcon containers ship.
       - uses: actions/setup-node@v7
         with:

CHANGELOG.md

@@ -33,6 +33,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   under `containers/` still triggers a build: the smoke-test fixture's pages are Markdown. (#178)
 
 ### Documentation
+- **User manual** (#178): every action has its chapter. `build-lectures`, `build-jupyter-cache`,
+  `restore-jupyter-cache`, `preview-netlify`, `preview-cloudflare`, `publish-gh-pages` and
+  `deploy-cloudflare` get theirs in `docs/user/actions/`, and their READMEs become generated
+  signposts. What only the READMEs held moves into the chapters: the Netlify and Cloudflare Pages
+  setup guides; the comparison of the two, now kept to what the actions do, since provider pricing
+  is not something this repository can keep current; the preview actions' note, from #143, that they
+  deploy nothing on events other than `pull_request`; the `publish-gh-pages` migration notes; and
+  the `deploy-cloudflare` Access checklist, with no account details. The `publish-gh-pages` chapter
+  documents the release assets, the archive, its SHA-256 checksum and the manifest, as a contract
+  that a release changes only with a CHANGELOG entry (#27). `docs/QUICK-REFERENCE.md` is removed:
+  its action table is the manual's index, and the rest is in the chapters. The harness gate now
+  fails when an action has no chapter. (#190)
+- **The seven actions' `action.yml` descriptions** are rewritten for readers, since the manual
+  copies them verbatim, and corrected where they, or the READMEs, were wrong:
+  - `restore-jupyter-cache`'s `path` said a different path restores the cache into a directory
+    the build does not read. The path is part of what identifies a cache, so any path but
+    `_build` finds none of the caches `build-jupyter-cache` saves.
+  - The `build-jupyter-cache` README listed a third, bare `build-` fallback key, which
+    `restore-jupyter-cache` no longer uses. The chapters give the two it does.
+  - The preview READMEs said change detection needs `fetch-depth: 0`. The actions fetch the pull
+    request's base and head commits themselves.
+  - The `preview-cloudflare` setup guide now asks for a token with Cloudflare Pages Edit alone,
+    not the broader "Edit Cloudflare Workers" template.
+  - `deploy-cloudflare`'s `account-subdomain` example no longer names a real account, and its
+    refusal message points at the chapter's setup checklist instead of the README.
+  - The caches save execution time only when the book sets `execute_notebooks: cache`, which the
+    `build-jupyter-cache` and `restore-jupyter-cache` chapters now require. Sphinx re-reads every
+    page of a fresh checkout, so the old claim that it rewrites only the changed pages is gone.
+  - `restore-jupyter-cache`'s `save-cache` reaches every pull request when saved from a branch,
+    so the chapter keeps it to pull-request builds, and a re-run, which matches its own key
+    exactly, saves nothing.
+  - Three limits in the code are documented, and filed: the preview actions' change detection
+    lists lectures changed on the base branch after the pull request branched off (#215);
+    `preview-cloudflare` builds its URLs from `project-name`, which is wrong when Cloudflare gives
+    the project another `pages.dev` address (#216); and `html-copy-notebooks` copies the notebooks
+    flat, so the download link of a page in a subdirectory leads nowhere (#217).
+  - Both QuantEcon images trust every directory for git, so the `build-lectures` chapter's
+    "dubious ownership" handling is for other images only. (#190)
 - **`preview-netlify`, `preview-cloudflare` READMEs**: the Security sections said a notification
   is logged whenever the deploy is skipped. That holds only for Dependabot and fork PRs. On any
   event other than `pull_request`, both actions skip change detection, the deploy and the PR
@@ -83,6 +121,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `cname:` in six consumers, a permanent `preview-cloudflare` step in the canary). (#187)
 
 ### Fixed
+- **`deploy-cloudflare`**: when a hostname serving the Worker is found ungated, the error said to
+  turn Access on or turn off the Worker's `workers.dev` route. With the route off its preview URLs
+  stay on, which wrangler itself warns may leave them public, so the message now says to turn off
+  both the route and the preview URLs. (#190)
 - **`setup-environment`**: bumping `cache-version` builds a fresh Conda environment, as it was
   documented to. It was in the exact cache key but in neither `restore-keys` fallback, and the
   first fallback matched the same environment file under any version, so a bump restored the

CONTRIBUTING.md

@@ -122,12 +122,13 @@ skipped job reports success to a required check). If the harness should ignore a
 extend `IGNORED` in that job; it is an ignore list, so anything unrecognised runs the harness
 rather than silently passing.
 
-The `gate` job also checks the user manual, so a docs-only PR is checked too. The input and output
-tables in `docs/user/actions/`, the action table in `docs/user/README.md` and the README of every
-action with a chapter are generated from each `action.yml` by `scripts/generate-docs.py`, and the
-gate fails when a committed copy no longer matches: run the script and commit what it writes. It
-also checks every example in `docs/user` and `templates/` against the `action.yml` files, for
-`permissions:`, and with actionlint. [docs/dev/CHAPTER-TEMPLATE.md](docs/dev/CHAPTER-TEMPLATE.md)
+The `gate` job also checks the user manual, so a docs-only PR is checked too. Every action has a
+chapter in `docs/user/actions/`. The chapters' input and output tables, the action table in
+`docs/user/README.md` and every action's README are generated from each `action.yml` by
+`scripts/generate-docs.py`, and the gate fails when a committed copy no longer matches, or when an
+action has no chapter: run the script and commit what it writes. It also checks every example in
+`docs/user` and `templates/` against the `action.yml` files, for `permissions:`, and with
+actionlint. [docs/dev/CHAPTER-TEMPLATE.md](docs/dev/CHAPTER-TEMPLATE.md)
 lists the checks and how to run them locally.
 
 ### Breaking Changes
@@ -175,8 +176,8 @@ Update these docs when adding features:
 | Doc | Update When |
 |-----|-------------|
 | The action's `action.yml` descriptions, then run `python3 scripts/generate-docs.py` | Any input or output change |
-| The action's chapter, `docs/user/actions/<action>.md`, or its `README.md` while it has no chapter | A change in what the action does |
-| `docs/QUICK-REFERENCE.md` | New inputs added |
+| The action's chapter, `docs/user/actions/<action>.md` | A change in what the action does |
+| A chapter for it, from `docs/dev/CHAPTER-TEMPLATE.md`, and its place in `ORDER` in `scripts/generate-docs.py` | A new action |
 | `docs/MIGRATION-GUIDE.md` | Workflow patterns change |
 | `docs/dev/PLAN.md` | A backlog item or tracked issue opens, closes or changes scope; a consumer changes the ref it pins |
 

README.md

@@ -191,7 +191,6 @@ We're in the `0.x` development phase (pre-1.0.0). Reference the actions with:
 - **[docs/user/](./docs/user/README.md)** - User manual: what each action does, how to set it up, and every input and output
 - **[docs/CONTAINER-GUIDE.md](./docs/CONTAINER-GUIDE.md)** - Quick start with containers
 - **[docs/MIGRATION-GUIDE.md](./docs/MIGRATION-GUIDE.md)** - Migrating lecture repositories
-- **[docs/QUICK-REFERENCE.md](./docs/QUICK-REFERENCE.md)** - Action reference
 - **[docs/dev/](./docs/dev/README.md)** - Developer docs: design, testing, container validation, the GPU AMI, and the work plan
 
 ## Getting Started