FEAT: Add solution_after_exercise style option (#81)

* Add style_solution_after_exercise config option and improve dropdown UX

This commit adds two requested features for better solution styling:

1. New configuration option 'style_solution_after_exercise' (default: False)
   - When enabled, removes hyperlinks from solution titles
   - Displays plain text like 'Solution to Exercise 1 (Title)'
   - Useful when solutions follow exercises directly
   - Reduces confusion when using dropdown class

2. Improved dropdown button text
   - Changed 'Click to show' to 'Show' for cleaner UI
   - Changed 'Click to hide' to 'Hide'
   - Applied via CSS customization

Features:
- Backward compatible (opt-in configuration)
- Properly handles numbered/unnumbered exercises
- Supports math expressions in titles
- Comprehensive test coverage (3 new tests)
- Full documentation in syntax.md

All 113 tests pass.

* Rename config option to exercise_style for clarity

Changed configuration option name from 'style_solution_after_exercise'
to 'exercise_style' to make it clearer that this belongs to sphinx-exercise.

Changes:
- Config option: exercise_style = 'solution_follow_exercise' (was: style_solution_after_exercise = True)
- Default value: '' (empty string) instead of False
- More descriptive and namespaced for clarity in config files

This makes it clearer in configuration files that this is a
sphinx-exercise specific setting, especially when used alongside
other sphinx extensions like sphinx-proof.

Updated:
- sphinx_exercise/__init__.py
- sphinx_exercise/post_transforms.py
- tests/test_style_solution_after_exercise.py
- docs/source/syntax.md

All 113 tests pass.

* Documentation improvements and cleanup

- Renamed test file to test_exercise_style.py for consistency with new config name
- Updated CHANGELOG.md to reflect correct exercise_style configuration
- Fixed install.md to use modern pip editable install instead of deprecated setup.py
- All 113 tests pass across Python 3.11-3.13 and Sphinx 6-8

* Remove dropdown text customization from sphinx-exercise CSS

- Dropdown button text styling is better handled at theme level
- Removes CSS override for toggle-button text from exercise.css
- Updates documentation to suggest theme-level customization
- Updates CHANGELOG to reflect architectural decision

* Simplify solution titles and add order validation

- Simplified solution title to just 'Solution' when exercise_style='solution_follow_exercise'
  (instead of 'Solution to Exercise #.#' since solution follows exercise)
- Clean up redundant code in post_transforms.py title building
- Add node order tracking and validation system
  - Tracks exercise/solution node order as documents are read
  - Validates solutions follow their exercises when config is set
  - Reports helpful warnings with line numbers and labels
- Warning messages prefixed with [sphinx-exercise] for clarity
- Warnings include:
  - 'Solution X does not follow exercise Y' with line numbers
  - Cross-document reference detection
  - Only runs when exercise_style='solution_follow_exercise'
- Add comprehensive tests for order validation
- Update test assertions to check for simplified titles

* docs: update CHANGELOG and syntax docs for accuracy

- Update CHANGELOG.md to include order validation system details
- Fix syntax.md to accurately reflect simplified 'Solution' title
- Add validation behavior documentation

* fix: use 'Solution' instead of 'Solution to' when exercise_style is set

When exercise_style='solution_follow_exercise', the solution title
should be just 'Solution' not 'Solution to'. This fix updates the
directive to use the correct default title text based on the config.

- Update SolutionDirective to check exercise_style config
- Set title_text to 'Solution' when config is set
- Keep 'Solution to' for default behavior
- Update tests to expect correct 'Solution' title

Author: mmcky

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+### New ✨
+
+- Added `exercise_style` configuration option to control solution title styling
+  - Set to `"solution_follow_exercise"` to simplify solution titles to just "Solution" (no hyperlinks, no exercise references)
+  - Default is `""` (empty string) which maintains the original behavior: "Solution to Exercise #.#" with clickable hyperlink
+- Added order validation system when `exercise_style = "solution_follow_exercise"`
+  - Validates that solutions appear after their referenced exercises
+  - Validates that solutions are in the same document as their exercises
+  - Provides helpful warnings with file paths and line numbers
+  - Warnings are prefixed with `[sphinx-exercise]` for clarity
+
+### Improved 👌
+
+- Enhanced solution title styling options for better UX in lecture-style content where solutions follow exercises
+- Improved configuration option naming for better clarity when used alongside other Sphinx extensions
+- Cleaner code in `post_transforms.py` with removed redundant title building logic
+
+### Changed 🔄
+
+- Removed dropdown button text customization from `sphinx-exercise` CSS
+  - This styling is better handled at the theme level (e.g., in `quantecon-book-theme`) for consistent global behavior
+  - Projects can customize dropdown text in their theme or custom CSS if desired
+
 ## [v1.1.1](https://github.com/executablebooks/sphinx-exercise/tree/v1.1.1) (2025-10-23)
 
 ### Improved 👌

docs/source/install.md

@@ -16,5 +16,5 @@ git clone https://github.com/executablebooks/sphinx-exercise
 then run:
 
 ```bash
-python setup.py install
+pip install -e .
 ```

docs/source/syntax.md

@@ -345,6 +345,10 @@ To hide the content, simply add `:class: dropdown` as a directive option.
 
 For more use cases see [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io/en/latest/#usage).
 
+```{tip}
+To customize the dropdown toggle button text (e.g., "Show" instead of "Click to show"), add custom CSS in your theme or project. This is typically handled at the theme level for consistent styling across all toggle buttons.
+```
+
 **Example**
 
 ```{exercise}
@@ -407,6 +411,36 @@ sphinx:
 ...
 ```
 
+### Solution Title Styling
+
+By default, solution titles include a hyperlink to the corresponding exercise. This behavior can be modified using the `exercise_style` configuration option.
+
+When solutions follow exercises directly in your content (common in lecture notes), you may want to simplify the solution title. Set `exercise_style` to `"solution_follow_exercise"` to display a simplified title without hyperlinks or exercise references.
+
+For Sphinx projects, add the configuration key in the `conf.py` file:
+
+```python
+# conf.py
+exercise_style = "solution_follow_exercise"
+```
+
+For Jupyter Book projects, set the configuration key in `_config.yml`:
+
+```yaml
+...
+sphinx:
+  config:
+    exercise_style: "solution_follow_exercise"
+...
+```
+
+When `exercise_style` is set to `"solution_follow_exercise"`:
+- The solution title displays just "Solution" (plain text, no hyperlink)
+- The extension validates that solutions follow their referenced exercises and warns if they don't
+- Solutions must be in the same document as their exercises (warnings if not)
+
+When empty `""` (default), the solution title shows "Solution to Exercise #.#" with a clickable hyperlink to the exercise.
+
 ## Custom CSS or JavaScript
 
 Custom JavaScript scripts and CSS rules will allow you to add additional functionality or customize how elements are displayed. If you'd like to include custom CSS or JavaScript scripts in Jupyter Book, simply add any files ending in `.css` or `.js` under a `_static` folder. Any files under this folder will be automatically copied into the built book.

sphinx_exercise/__init__.py

@@ -87,6 +87,13 @@ def purge_exercises(app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         for label in remove_labels:
             del env.sphinx_exercise_registry[label]
 
+    # Purge node order tracking for this document
+    if (
+        hasattr(env, "sphinx_exercise_node_order")
+        and docname in env.sphinx_exercise_node_order
+    ):
+        del env.sphinx_exercise_node_order[docname]
+
 
 def merge_exercises(
     app: Sphinx, env: BuildEnvironment, docnames: Set[str], other: BuildEnvironment
@@ -103,6 +110,16 @@ def merge_exercises(
             **other.sphinx_exercise_registry,
         }
 
+    # Merge node order tracking
+    if not hasattr(env, "sphinx_exercise_node_order"):
+        env.sphinx_exercise_node_order = {}
+
+    if hasattr(other, "sphinx_exercise_node_order"):
+        env.sphinx_exercise_node_order = {
+            **env.sphinx_exercise_node_order,
+            **other.sphinx_exercise_node_order,
+        }
+
 
 def init_numfig(app: Sphinx, config: Config) -> None:
     """Initialize numfig"""
@@ -127,31 +144,143 @@ def copy_asset_files(app: Sphinx, exc: Union[bool, Exception]):
             copy_asset(path, str(Path(app.outdir).joinpath("_static").absolute()))
 
 
+def validate_exercise_solution_order(app: Sphinx, env: BuildEnvironment) -> None:
+    """
+    Validate that solutions follow their referenced exercises when
+    exercise_style='solution_follow_exercise' is set.
+    """
+    # Only validate if the config option is set
+    if app.config.exercise_style != "solution_follow_exercise":
+        return
+
+    if not hasattr(env, "sphinx_exercise_node_order"):
+        return
+
+    logger = logging.getLogger(__name__)
+
+    # Process each document
+    for docname, nodes in env.sphinx_exercise_node_order.items():
+        # Build a map of exercise labels to their positions and info
+        exercise_info = {}
+        for i, node_info in enumerate(nodes):
+            if node_info["type"] == "exercise":
+                exercise_info[node_info["label"]] = {
+                    "position": i,
+                    "line": node_info.get("line"),
+                }
+
+        # Check each solution
+        for i, node_info in enumerate(nodes):
+            if node_info["type"] == "solution":
+                target_label = node_info["target_label"]
+                solution_label = node_info["label"]
+                solution_line = node_info.get("line")
+
+                if not target_label:
+                    continue
+
+                # Check if target exercise exists in this document
+                if target_label not in exercise_info:
+                    # Exercise is in a different document or doesn't exist
+                    docpath = env.doc2path(docname)
+                    path = str(Path(docpath).with_suffix(""))
+
+                    # Build location string with line number if available
+                    location = f"{path}:{solution_line}" if solution_line else path
+
+                    logger.warning(
+                        f"[sphinx-exercise] Solution '{solution_label}' references exercise '{target_label}' "
+                        f"which is not in the same document. When exercise_style='solution_follow_exercise', "
+                        f"solutions should appear in the same document as their exercises.",
+                        location=location,
+                        color="yellow",
+                    )
+                    continue
+
+                # Check if solution comes after exercise
+                exercise_data = exercise_info[target_label]
+                exercise_pos = exercise_data["position"]
+                exercise_line = exercise_data.get("line")
+
+                if i <= exercise_pos:
+                    docpath = env.doc2path(docname)
+                    path = str(Path(docpath).with_suffix(""))
+
+                    # Build more informative message with line numbers
+                    if solution_line and exercise_line:
+                        location = f"{path}:{solution_line}"
+                        msg = (
+                            f"[sphinx-exercise] Solution '{solution_label}' (line {solution_line}) does not follow "
+                            f"exercise '{target_label}' (line {exercise_line}). "
+                            f"When exercise_style='solution_follow_exercise', solutions should "
+                            f"appear after their referenced exercises."
+                        )
+                    elif solution_line:
+                        location = f"{path}:{solution_line}"
+                        msg = (
+                            f"[sphinx-exercise] Solution '{solution_label}' does not follow exercise '{target_label}'. "
+                            f"When exercise_style='solution_follow_exercise', solutions should "
+                            f"appear after their referenced exercises."
+                        )
+                    else:
+                        location = path
+                        msg = (
+                            f"[sphinx-exercise] Solution '{solution_label}' does not follow exercise '{target_label}'. "
+                            f"When exercise_style='solution_follow_exercise', solutions should "
+                            f"appear after their referenced exercises."
+                        )
+
+                    logger.warning(msg, location=location, color="yellow")
+
+
 def doctree_read(app: Sphinx, document: Node) -> None:
     """
     Read the doctree and apply updates to sphinx-exercise nodes
     """
 
     domain = cast(StandardDomain, app.env.get_domain("std"))
 
+    # Initialize node order tracking for this document
+    if not hasattr(app.env, "sphinx_exercise_node_order"):
+        app.env.sphinx_exercise_node_order = {}
+
+    docname = app.env.docname
+    if docname not in app.env.sphinx_exercise_node_order:
+        app.env.sphinx_exercise_node_order[docname] = []
+
     # Traverse sphinx-exercise nodes
     for node in findall(document):
         if is_extension_node(node):
             name = node.get("names", [])[0]
             label = document.nameids[name]
-            docname = app.env.docname
             section_name = node.attributes.get("title")
             domain.anonlabels[name] = docname, label
             domain.labels[name] = docname, label, section_name
 
+            # Track node order for validation
+            node_type = node.get("type", "unknown")
+            node_label = node.get("label", "")
+            target_label = node.get("target_label", None)  # Only for solution nodes
+
+            app.env.sphinx_exercise_node_order[docname].append(
+                {
+                    "type": node_type,
+                    "label": node_label,
+                    "target_label": target_label,
+                    "line": node.line if hasattr(node, "line") else None,
+                }
+            )
+
 
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("hide_solutions", False, "env")
+    app.add_config_value("exercise_style", "", "env")
 
     app.connect("config-inited", init_numfig)  # event order - 1
     app.connect("env-purge-doc", purge_exercises)  # event order - 5 per file
     app.connect("doctree-read", doctree_read)  # event order - 8
     app.connect("env-merge-info", merge_exercises)  # event order - 9
+    app.connect("env-updated", validate_exercise_solution_order)  # event order - 10
     app.connect("build-finished", copy_asset_files)  # event order - 16
 
     app.add_node(

sphinx_exercise/directive.py

@@ -222,7 +222,11 @@ class : str,
     solution_node = solution_node
 
     def run(self) -> List[Node]:
-        self.defaults = {"title_text": f"{translate('Solution to')}"}
+        # Set default title based on exercise_style config
+        if self.env.app.config.exercise_style == "solution_follow_exercise":
+            self.defaults = {"title_text": f"{translate('Solution')}"}
+        else:
+            self.defaults = {"title_text": f"{translate('Solution to')}"}
         target_label = self.arguments[0]
         self.serial_number = self.env.new_serialno()
 

sphinx_exercise/post_transforms.py

@@ -141,30 +141,45 @@ def resolve_solution_title(app, node, exercise_node):
     exercise_title = exercise_node.children[0]
     if isinstance(title, solution_title):
         entry_title_text = node.get("title")
-        updated_title_text = " " + exercise_title.children[0].astext()
-        if isinstance(exercise_node, exercise_enumerable_node):
-            node_number = get_node_number(app, exercise_node, "exercise")
-            updated_title_text += f" {node_number}"
+
         # New Title Node
         updated_title = docutil_nodes.title()
-        wrap_reference = build_reference_node(app, exercise_node)
-        wrap_reference += docutil_nodes.Text(updated_title_text)
-        node["title"] = entry_title_text + updated_title_text
-        # Parse Custom Titles from Exercise
-        if len(exercise_title.children) > 1:
-            subtitle = exercise_title.children[1]
-            if isinstance(subtitle, exercise_subtitle):
-                wrap_reference += docutil_nodes.Text(" (")
-                for child in subtitle.children:
-                    if isinstance(child, docutil_nodes.math):
-                        # Ensure mathjax is loaded for pages that only contain
-                        # references to nodes that contain math
-                        domain = app.env.get_domain("math")
-                        domain.data["has_equations"][app.env.docname] = True
-                    wrap_reference += child
-                wrap_reference += docutil_nodes.Text(")")
-        updated_title += docutil_nodes.Text(entry_title_text)
-        updated_title += wrap_reference
+
+        # Check if exercise_style is set to "solution_follow_exercise"
+        if app.config.exercise_style == "solution_follow_exercise":
+            # Simple title: just "Solution" without reference to exercise
+            updated_title += docutil_nodes.Text(entry_title_text)
+            node["title"] = entry_title_text
+        else:
+            # Build full title with exercise reference
+            updated_title_text = " " + exercise_title.children[0].astext()
+            if isinstance(exercise_node, exercise_enumerable_node):
+                node_number = get_node_number(app, exercise_node, "exercise")
+                updated_title_text += f" {node_number}"
+
+            # Create hyperlink (original behavior)
+            wrap_reference = build_reference_node(app, exercise_node)
+            wrap_reference += docutil_nodes.Text(updated_title_text)
+
+            # Parse Custom Titles from Exercise
+            if len(exercise_title.children) > 1:
+                subtitle = exercise_title.children[1]
+                if isinstance(subtitle, exercise_subtitle):
+                    wrap_reference += docutil_nodes.Text(" (")
+                    for child in subtitle.children:
+                        if isinstance(child, docutil_nodes.math):
+                            # Ensure mathjax is loaded for pages that only contain
+                            # references to nodes that contain math
+                            domain = app.env.get_domain("math")
+                            domain.data["has_equations"][app.env.docname] = True
+                        wrap_reference += child
+                    wrap_reference += docutil_nodes.Text(")")
+
+            # Build the title with entry text + hyperlinked reference
+            updated_title += docutil_nodes.Text(entry_title_text)
+            updated_title += wrap_reference
+            node["title"] = entry_title_text + updated_title_text
+
         updated_title.parent = title.parent
         node.children[0] = updated_title
     node.resolved_title = True