docs: add a migration checklist for repos moving off the Sphinx theme - #226
Conversation
A lecture repository leaving `quantecon-book-theme` has to set up several things its Sphinx build handled another way, and no page listed them as steps. Three came with the Sphinx theme and needed no per-repo setup at all; the rest are configured today under `_config.yml` keys this theme does not read. `myst init` carries none of them across: it reads the analytics ID only from the `html` section, takes `project.github` only from a top-level `repository.url`, and never reads `sphinx.config`, which is where the lecture configs keep most of these. The page also carries the table of Sphinx theme options with no counterpart here, each with its reason, and `docs/index.md` now points its "where a Sphinx option has no counterpart" promise at that table rather than at the individual pages. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7
|
🎭 Visual regression results
Details
Skipped testsmobile-chrome › theme.spec.ts › QuantEcon theme — visual regression › without JavaScript › drawer-opens-without-javascript |
The migration page's table is where that promise now points, but the sentence also carries the PLAN.md reference the docs review rewrites in the same paragraph. Changing it in both places would only collide, so this keeps to the Pages-table row its own acceptance criteria name. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7
There was a problem hiding this comment.
🔵 Needs a closer look
The doc's correctness depends on the merge ordering of four separate unmerged PRs (#221, #222, #224, #227) — e.g. it documents launch_notebook_*/launch_colab options the current template.yml does not declare — which requires human coordination.
Pull request overview
This documentation-only PR adds docs/migrating.md, a step-by-step checklist for lecture repositories moving off the Sphinx quantecon-book-theme. It closes #209 by walking through the eleven settings the Sphinx build handled differently (licence footer, maths macros, "Last changed", launch notebooks, notebook header, {raw} source rewrite, site URL, old URLs, document language, analytics, description/keywords), naming for each what it replaces in Sphinx and what to set in MyST. It also carries the table of quantecon-book-theme options with no MyST counterpart, and wires the new page into the docs index and configuration reference.
I verified the technical claims that are already implementable against the current codebase (default lang="en" in app/i18n.ts:189, og:locale from current_language in app/seo.ts:112, description/keywords meta in the route modules, the pinned git-metadata plugin URL matching docs/git-metadata.md:17), and all internal anchors/links resolve. Note that several sections intentionally describe forward-looking state that depends on other unmerged PRs (#221 footer default, #222 {raw} rewrite script, #224 the launch_notebook_*/launch_colab options, #227 canonical/base-URL links) — the author flagged this in the description and recommends merging this PR last.
Changes:
- Add
docs/migrating.mdwith the eleven-item migration checklist and the "no counterpart" options table. - Register the new page in
docs/index.mdand addproject.description/project.keywords/project.mathrows todocs/configuration.md. - Add an
Unreleased→Addedentry inCHANGELOG.md.
File summaries
| File | Description |
|---|---|
| docs/migrating.md | New migration checklist; content correct for the post-cutover state but references launch options (launch_notebook_*, launch_colab) and a default footer that only exist once #224/#221 merge. |
| docs/index.md | Adds a "migrating" row to the Pages table. |
| docs/configuration.md | Documents project.description, project.keywords, project.math in the "Other site keys" table (verified against code). |
| CHANGELOG.md | Adds the Added entry; links the issue but omits the required PR link. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
#221, #222, #224 and #225 all landed entries under `## [Unreleased]` while this was open. This branch's entry is `### Added` like two of theirs, so it folds into that list rather than forming a second section: Added (default site footer, `{raw}` rewriter, this checklist), then main's Changed and Fixed sections unchanged. The entry also gains its PR link alongside the issue link, which is what CONTRIBUTING.md:225-227 asks for. `docs/configuration.md` auto-merged, and was checked rather than assumed: main's launch rows from #224 and this branch's `project.description`, `project.keywords` and `project.math` rows are all present, with no row duplicated. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The Site URL section read as though `site_url` is what makes the theme emit a canonical link. `site_url` has existed since 2.7.0, but no page carries a canonical link on main at all: that is #207, implemented by #227, which is still open. Without this note the section describes a feature the theme does not have, and it would only become true if this branch merged after that one -- a doc should not depend on merge order to be accurate. The wording follows the two callouts already in the file, which flag QuantEcon/mystmd#108 for the notebook header setting and QuantEcon/mystmd#113 for build-time redirects. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#221, #222, #224, #225 and #226 all landed entries under `## [Unreleased]` while this was open. This branch adds one `### Added` entry and one `### Fixed` entry, so each folds into the matching section rather than opening a second: Added (default site footer, `{raw}` rewriter, migration checklist, this canonical link), Changed (the breaking launch change), Fixed (output image centring, these base-URL head links). Both entries also gain their PR link beside the issue link, which is what CONTRIBUTING.md:225-227 asks for. `README.md`, `docs/configuration.md`, `template.yml` and `tests/visual/theme.spec.ts` auto-merged. Each was checked rather than assumed: both sides' content is present in all four. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#221, #222, #224, #225, #226 and #227 all landed entries under `## [Unreleased]` while this was open. This branch adds one `### Added` entry, so it folds into that list rather than opening a second section, and it gains its PR link beside the issue link, which is what CONTRIBUTING.md:225-227 asks for. `docs/layout.md`, `styles/quantecon.css` and `tests/visual/theme.spec.ts` auto-merged. Each was checked rather than assumed: the branch's h4 indent rule sits beside main's output-image centring rule, the branch's outline assertions beside main's footer, launch, centring and canonical tests, and the branch's h2-to-h4 documentation beside main's default-footer section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
#221, #222, #224, #225, #226, #227 and #228 all landed `[Unreleased]` entries while this was open. This branch adds a `### Fixed` entry, so it folds into main's existing Fixed section (output image centring, base-URL head links) rather than opening a second one, and it gains its PR link beside the issue link per CONTRIBUTING.md:225-227. `docs/configuration.md`, `docs/index.md` and `docs/layout.md` auto-merged, and each was checked rather than assumed: layout.md holds this branch's Header and Widths rewrites beside #228's h2-to-h4 outline text and #221's default-footer section; index.md holds #226's Pages-table row beside this branch's rewritten closing paragraph; configuration.md holds the rows from all four PRs that touched its table. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Closes #209. Documentation only — no code, no tests, no pixels.
What it adds
docs/migrating.md, covering all eleven items from the issue's table. Each names what it replaces in the Sphinx build, what to set in the MyST build, and where the detail lives:project.math, with the\epsilon→\varepsilonrecipe and the array-form rewritefetch-depth: 0on every workflow checkout that builds HTMLsettings.myst_to_ipynb.headerhtml.baseurl→site.options.site_urlzh_CN→zh-cn, plus thelanguagesYAML blockanalytics_googleproject.description/project.keywordsIt opens by saying the steps are manual:
myst initreads the analytics ID only from thehtmlsection, takesproject.githubonly from a top-levelrepository.url, and never readssphinx.config— which is where the lecture configs keep most of these.Two items carry an explicit "not shipped yet" note, as the issue asks: the notebook-header setting (QuantEcon/mystmd#108) and build-time redirects (QuantEcon/mystmd#113).
The no-counterpart table
The page carries the table of
quantecon-book-themeoptions with no counterpart here, each with a reason, anddocs/index.md's promise — "where a Sphinx option has no counterpart, its page says so" — now points at that table rather than at the individual pages.I checked the reasons rather than asserting them, and softened three I had written from assumption: the header logo really is hard-coded (
/logos/qemb-logo.png), the byline carries no label at all (soauthors_labelhas nothing to label), and forhtml_css_filesthe nearest thing is themyst-theme.cssmystmd serves at the site root — with no slot for extra scripts, which I now say plainly instead of implying parity.Also
docs/configuration.mdgainsproject.description,project.keywordsandproject.mathin the "Othersitekeys the theme uses" table, as the criteria require.Depends on the other gate PRs
The page describes #203, #204, #205 and #207 as shipped, which is right for the order the issue list is being worked but not until those merge: #221, #222, #224 and #227. If any of them changes shape in review, the matching section here needs the same edit. Worth merging this one last.
One correction that belonged elsewhere:
docs/configuration.mdstill creditedproject.githubwith "the notebook repo derivation", which #205 removes. I pushed that fix to #224's branch rather than carrying it here.🤖 Generated with Claude Code
https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7