Add solution_collapsed option to render solutions folded by default #85

Sub-issue of #84, covering the first of the two options proposed there: rendering solutions folded by default.

Motivation

Reader feedback on book-dp1, which uses exercise_style = "solution_follow_exercise":

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 (solution next to exercise) is not the one that is best for reading (solution out of sight until wanted). This option lets authors keep writing solutions inline while choosing a folded presentation at publish time.

Proposal

Updated: the design settled on making this part of the solution_follow_exercise style rather than a standalone opt-in, since that style is exactly the layout the feedback is about. solution_collapsed is therefore tri-state: unset follows exercise_style (collapsed under solution_follow_exercise), True always collapses, False never does.

The None default is necessary rather than stylistic — Sphinx cannot distinguish "unset" from "explicitly False" through the public config API, so a plain False default would leave no way to switch the style's implied collapsing back off. This is a documented behaviour change for projects on that style, with solution_collapsed = False as the one-line opt-out.

A config option, solution_collapsed, set in conf.py or _config.yml. When True it adds the dropdown class to every solution node — equivalent to writing :class: dropdown on every solution directive, which the docs already describe as the manual way to do this (docs/source/syntax.md, "Hide Content").

Research

Everything below was verified against this checkout by reading the source and running real Sphinx builds, not inferred.

The dropdown class does reach the HTML output

visit_solution_node in sphinx_exercise/nodes.py:172 emits self.starttag(node, "div", CLASS="admonition"). docutils' HTMLTranslator.starttag unions the node's own classes with the CLASS= keyword (docutils/writers/_html_base.py, the for cls in node.get('classes', []) + atts.pop('class', '').split(): loop), and it de-duplicates as it goes. Sphinx does not override starttag. So a node carrying dropdown renders as <div class="solution dropdown admonition" id="...">.

This is already visible in a committed fixture: tests/test_solution/_linked_enum_class.html is <div class="solution test-solution admonition" id="solution-label">, where test-solution came from :class: test-solution in the source.

dropdown is the correct class name

sphinx-togglebutton registers togglebutton_selector with the default value ".toggle, .admonition.dropdown". Our div carries both admonition and dropdown, so it matches (CSS selector matching is order-independent). Its JavaScript has an explicit item.classList.contains("admonition") branch for admonition-style toggling, and treats toggle-shown as "start expanded" — which gives authors a per-directive escape hatch to keep one solution open.

sphinx-design does not count as a provider. Its dropdown is a directive emitting .sd-dropdown, and its compiled stylesheet ships no rule for a bare dropdown class (verified — the only matching selector is .sd-dropdown). This matters for the warning below: Jupyter Book loads sphinx-design by default, so treating it as a provider would suppress the warning for exactly the projects that need it.

There are exactly three places solution classes are assigned

The third one is the trap, and it is where the #82 class-list bug lived. It survives only because it is a per-element substring replace rather than a hard-coded list:

new_node["classes"] = [attr.replace("solution-start", "solution") for attr in node.attributes["classes"]]

"dropdown" contains no "solution-start" substring, so it passes through untouched. Verified end-to-end: a gated pair with :class: dropdown renders <div class="solution dropdown admonition">.

No post-transform mutates solution classes.

Implementation notes

• Register with the "env" rebuild trigger, matching hide_solutions and exercise_style. The class is injected at read time and baked into the pickled doctree, so "html" would leave stale doctrees on incremental builds and the option would appear broken.
• De-duplicate. If the author already wrote :class: dropdown, blind concatenation gives classes="solution dropdown dropdown" in the doctree XML. docutils hides this in HTML output but any doctree regression fixture or downstream consumer sees it.
• Keep the default False. A True default would invalidate roughly 40 committed regression baselines across tests/test_solution/, tests/test_exercise/, tests/test_gateddirective/ and tests/test_hiddendirective/, which record classes="solution" verbatim across .sphinx4/.5/.6/.7/.8/.8.1 variants.
• LaTeX is provably unaffected. The LaTeXTranslator branch of visit_solution_node (sphinx_exercise/nodes.py:160-170) emits only \phantomsection\label{...} plus a constant \begin{sphinxadmonition}{note} from sphinx_exercise/latex.py, and never reads node["classes"]. Inline rendering is the intended non-HTML fallback, and the committed tests/test_latex/*.tex fixtures cannot change.
• Type the warning with type="exercise", subtype="solution_collapsed" so projects that supply their own .admonition.dropdown CSS can set suppress_warnings = ["exercise.solution_collapsed"]. An untyped warning is unsuppressible and makes -W builds fail for them.
• Document the interactive-output caveat. sphinx-togglebutton collapses by setting the content's height to zero rather than removing it, so outputs that measure themselves at load time (plotly, bokeh, ipywidgets, altair) render at zero size inside a collapsed solution. Static images including matplotlib are unaffected. This matters for the executable-book audience the option targets.
• Warn when the class would be inert. The extension ships no fold CSS/JS of its own — sphinx_exercise/assets/html/exercise.css has only static div.solution styling. With solution_collapsed = True and no sphinx-togglebutton loaded, solutions silently render expanded and the option looks broken. A builder-inited check gated on app.builder.format == "html" catches this without adding noise to LaTeX builds.
• sphinx_togglebutton is not currently a test dependency. It is listed only under the rtd extra in pyproject.toml; the testing extra omits it. It needs adding there to cover the no-warning path.

Acceptance criteria

• solution_collapsed = True adds dropdown to {solution} directives
• The same applies to gated {solution-start} / {solution-end} pairs
• Directive-level :class: values are preserved
• An explicit :class: dropdown is not duplicated
• :class: toggle-shown keeps an individual solution expanded
• Default False leaves all existing output and fixtures unchanged
• A warning is issued on HTML builds when no extension provides dropdown
• No warning on LaTeX builds, and no warning when sphinx-togglebutton is loaded
• Documented in docs/source/syntax.md alongside hide_solutions and exercise_style

Out of scope

Relocating solutions to an appendix — that is the other half of #84 and is tracked separately.

Related pre-existing bugs found while researching this

Now filed separately as #89, #90 and #91. These are not introduced by this change and are not fixed by it:

1. hide_solutions = True hard-crashes any build containing a gated solution. SolutionDirective.run() returns [] when hide_solutions is set (directive.py:238-239), so no solution_start_node is emitted and MergeGatedSolutions never runs — but SolutionEndDirective still returns a solution_end_node (directive.py:438), which has no visitors (__init__.py registers it with a bare app.add_node). Result: NotImplementedError: <class 'sphinx.writers.html5.HTML5Translator'> departing unknown node type: solution_end_node. Non-gated hide_solutions works correctly.
2. The per-directive :hidden: flag crashes the same way on {solution-start} and on {exercise-start}.
3. Class names containing -start are silently mangled by the gated merges. :class: quick-start on an {exercise-start} renders as quick, because MergeGatedExercises does cls.replace("-start", "") (transforms.py:162); the solution merge has the same shape.
4. There is zero test coverage for hide_solutions anywhere in the suite.