PROJECT: Exercise solution presentation — collapse by default and/or relocate to an appendix

[mmcky]

Goal

Authors should be able to keep writing a solution directly after its exercise in the source, while the build decides how the solution is presented to the reader — collapsed behind a drop-down, or relocated to a solutions section at the end of the page or book. The same authoring convention and the same two presentation options should be available in both stacks we build books with: sphinx-exercise (current lecture sites and books) and mystmd (the new stack).

Why

Reader feedback on book-dp1:

Currently solutions to exercises sit immediately after exercises, making it too tempting to look at the solution. Would it be possible to have them folded by default and open in a drop-down, similar to the lectures?

The layout that is best for authoring is not the one that is best for reading. Writing the solution next to its exercise keeps the two in sync and is easy to maintain; showing it there defeats the exercise. Today the only lever in either stack is all-or-nothing — render the solution inline, or drop it from the build entirely (hide_solutions in Sphinx, hidden: true in mystmd). We want the two options in between, chosen in config, with no change to the source.

This spans repositories, hence a tracking issue here: the Sphinx extension lives in the executablebooks org (executablebooks/sphinx-exercise, where QuantEcon maintainers have commit rights), the MyST side is our fork (QuantEcon/mystmd), and the books that need it sit in a third set of repos.

Shared design decisions (settle here, implement in the sub-issues)

The two stacks will be configured by different files, but the vocabulary and the behaviour should not drift:

Question	Proposed default
Collapsed solutions	A project-level switch making every {solution} render folded, expandable by the reader. mystmd: project.settings in myst.yml; Sphinx: conf.py / _config.yml. Same concept, same name where the config style allows.
Placement	A three-way value — inline (today's behaviour, the default), page-end (collect a page's solutions into a section at the end of that page), appendix (one generated project-level solutions page).
Composability	The two are independent and combinable — an appendix of collapsed solutions is legitimate, and neither option should assume the other is off.
Author override	An explicit per-directive setting wins over the project default in both directions: a solution deliberately shown inline must be able to opt out of a collapsed-by-default project.
Relationship to hiding	hide_solutions / hidden: true keep their current meaning. Collapsed and relocated sit between "inline" and "hidden"; they do not replace either end.
Cross-references	Numbering and references ({ref}, {numref}, {eq}, MyST cross-references) must keep resolving when a solution moves, and the exercise gets a link to its solution while the solution keeps its link back.
Non-HTML output	Collapsing is inherently an HTML concern — PDF/LaTeX renders solutions inline instead. Placement is the opposite: an appendix is the native print layout, so PDF should honour it.

Please push back on any of these in the comments; once agreed, the sub-issues implement them.

Sub-issues

• Feature: project-level default for collapsed (dropdown) solutions mystmd#94 — MyST: project-level default for collapsed (dropdown) solutions
• Feature: build-time solution placement — collect solutions into a page-end section or appendix mystmd#93 — MyST: build-time solution placement (page-end section or appendix)
• Feature request: collapse solutions by default and/or move solutions to an appendix at build time executablebooks/sphinx-exercise#84 — Sphinx: both options for the sphinx-exercise extension

Notes on the current state

• mystmd is already halfway on collapsing. SolutionRenderer in myst-to-react reads node.class and renders a <details>/<summary> callout when it contains dropdown, so :class: dropdown works per-directive today. Feature: project-level default for collapsed (dropdown) solutions mystmd#94 is therefore config plus a transform, with no theme work required.
• Neither stack has any placement machinery. Feature: build-time solution placement — collect solutions into a page-end section or appendix mystmd#93 is the larger piece of work. Starting with page-end gets most of the reading benefit without the cross-page complexity of a project-wide appendix.
• The extensions live in the mystmd monorepo. packages/myst-ext-exercise in QuantEcon/mystmd — there is no separate MyST extension repo to file against.

Follow-ups once the options ship

• Turn the chosen presentation on in the books that motivated this, starting with book-dp1.
• Decide a house default for QuantEcon lecture sites, so new books inherit it rather than each repo choosing.
• Document the options in QuantEcon.manual alongside the other build settings.