FEAT: Add solution_after_exercise style option

[mmcky]

Add exercise_style config option for solution styling

Summary

This PR adds a new configuration option to improve the styling and usability of solution directives, particularly for projects like QuantEcon lectures where solutions immediately follow exercises.

Changes

1. New Configuration Option: exercise_style

Adds a new configuration option exercise_style (default: "") that can be enabled in conf.py:

exercise_style = "solution_follow_exercise"

Purpose: When set to "solution_follow_exercise", this simplifies solution titles by:

• Removing hyperlinks to exercises (since solutions follow exercises directly)
• Displaying just "Solution" instead of "Solution to Exercise #.#"

Before (default behavior):

Solution to Exercise 1 (Factorial Function)  [← clickable link]

After (with exercise_style = "solution_follow_exercise"):

Solution  [← plain text, no link, no exercise reference]

This is particularly useful when solutions follow exercises directly in the content, reducing visual clutter and avoiding confusion when users click on dropdowns.

2. Order Validation System

When exercise_style = "solution_follow_exercise" is set, the extension validates that solutions actually follow their referenced exercises and provides helpful warnings:

Features:

• ✅ Tracks exercise/solution node order as documents are processed
• ✅ Validates solutions appear after their referenced exercises
• ✅ Checks solutions are in the same document as their exercises
• ✅ Provides detailed warnings with file paths and line numbers
• ✅ Only runs when the config option is set (no performance impact otherwise)

Warning Examples:

/path/to/doc.md:15: WARNING: [sphinx-exercise] Solution 'sol-intro' (line 15) 
does not follow exercise 'ex-intro' (line 25). When 
exercise_style='solution_follow_exercise', solutions should appear after their 
referenced exercises.

/path/to/solutions.md:10: WARNING: [sphinx-exercise] Solution 'sol-chapter1' 
references exercise 'ex-chapter1' which is not in the same document. When 
exercise_style='solution_follow_exercise', solutions should appear in the same 
document as their exercises.

Implementation Details

• Modified Files:

  • sphinx_exercise/__init__.py - Registered config option, added order tracking and validation
  • sphinx_exercise/post_transforms.py - Simplified solution title logic, cleaned up redundant code
  • docs/source/syntax.md - Documentation for configuration option
  • docs/source/install.md - Updated to use modern pip install -e .
  • CHANGELOG.md - Documented all changes

• New Files:

  • tests/test_exercise_style.py - Tests for solution title styling
  • tests/test_order_validation.py - Tests for order validation warnings

Features

✅ Backward compatible - Default behavior unchanged (opt-in configuration)
✅ Well-tested - 6 new tests, all 116 tests pass
✅ Properly handles:

• Numbered and unnumbered exercises
• Exercises with and without titles
• Math expressions in titles (ensures MathJax is loaded)
• Cross-document references (with warnings)
• Wrong order detection (with helpful line numbers)

Testing

All tests pass across Python 3.10-3.13 and Sphinx 6-8:

======================= 116 passed, 1 warning in 35s ========================

New tests verify:

• Simplified solution titles when exercise_style='solution_follow_exercise'
• Full solution titles with hyperlinks when exercise_style='' (default)
• Order validation warnings for solutions before exercises
• Cross-document reference warnings
• No validation when config is not set

Usage Example

Configuration (conf.py):

extensions = [
    "sphinx_exercise",
    "sphinx_togglebutton",  # for dropdown functionality
]

# Enable new styling for solutions that follow exercises
exercise_style = "solution_follow_exercise"

Content:

:::{exercise} Factorial Function
:label: ex-factorial

Write a function to calculate the factorial of a number.
:::

:::{solution} ex-factorial
:class: dropdown

Here's the solution...
:::

With exercise_style = "solution_follow_exercise":

• Solution title displays just "Solution" (plain text, no link)
• Build warnings if solution doesn't follow exercise
• Build warnings if solution is in different document

Documentation

• Updated docs/source/syntax.md with configuration documentation
• Updated docs/source/install.md to use modern pip install
• Added CHANGELOG.md entries for all changes

Related Issues

Addresses user request for QuantEcon lectures where solutions follow exercises, reducing visual clutter and improving UX with the dropdown class.

Breaking Changes

None - this is a fully opt-in feature. Default behavior remains unchanged.

[mmcky]

• testing completed on real world lecture repository Test sphinx-exercise PR #81: style_solution_after_exercise feature QuantEcon/lecture-python.myst#670