Release v1.2.0

Release v1.2.0#

Release Date: November 5, 2025

This release introduces new configuration options for styling solutions that follow exercises, along with order validation to help maintain document structure consistency.

✨ New Features#

Solution Title Styling Configuration#

A new exercise_style configuration option allows you to customize how solution titles are displayed when solutions follow their exercises.

Configuration:

# In conf.py
exercise_style = "solution_follow_exercise"

Or for Jupyter Book:

# In _config.yml
sphinx:
  config:
    exercise_style: "solution_follow_exercise"

Behavior:

  • When enabled (exercise_style = "solution_follow_exercise"):

    • Solution titles show just “Solution” (simplified)

    • No hyperlinks back to exercises

    • No exercise number references

    • Ideal for lecture-style content where solutions immediately follow exercises

  • Default (exercise_style = ""):

    • Solution titles show “Solution to Exercise #.#”

    • Clickable hyperlinks to the exercise

    • Full exercise references included

    • Maintains original behavior

Example:

```{exercise}
:label: my-exercise

What is 2 + 2?
```

```{solution} my-exercise

The answer is 4.
```

With exercise_style = "solution_follow_exercise", the solution will display with the simple title “Solution” instead of “Solution to Exercise 1”.

Order Validation System#

When exercise_style = "solution_follow_exercise" is enabled, sphinx-exercise now validates that solutions appear in the correct order:

Validations performed:

  • Solutions must appear after their referenced exercises

  • Solutions must be in the same document as their exercises

Warning messages:

WARNING: [sphinx-exercise] Solution 'my-solution' appears before its exercise 'my-exercise'.
When exercise_style='solution_follow_exercise', solutions should follow their exercises.
Location: /path/to/file.md:42

WARNING: [sphinx-exercise] Solution 'my-solution' references exercise 'my-exercise'
which is not in the same document. When exercise_style='solution_follow_exercise',
solutions should appear in the same document as their exercises.

Benefits:

  • Helps maintain consistent document structure

  • Prevents confusing layouts where solutions appear before exercises

  • Provides clear, actionable warnings with file paths and line numbers

  • Warnings prefixed with [sphinx-exercise] for easy identification

👌 Improvements#

Enhanced User Experience#

  • Simplified titles: Cleaner, more concise solution headings for lecture-style content

  • Better organization: Order validation helps maintain logical document flow

  • Helpful diagnostics: Clear warnings with file locations and line numbers

Code Quality#

  • Removed redundant title building logic in post_transforms.py

  • Cleaner separation between directive initialization and post-transform processing

  • Improved configuration naming for clarity when used alongside other extensions

📦 Installation#

Install or upgrade via pip:

pip install --upgrade sphinx-exercise

🔄 Migration Notes#

If you’re upgrading from v1.1.1:

  • No breaking changes - existing projects continue to work without modification

  • No action required - default behavior is unchanged

  • Optional enhancement: Add exercise_style = "solution_follow_exercise" if you want simplified solution titles

If you want to use the new features:

  1. Add the configuration to your conf.py:

    exercise_style = "solution_follow_exercise"

  2. Rebuild your documentation:

    sphinx-build -b html source build/html

  3. Review any warnings about solution ordering

Compatibility:

  • Python 3.10, 3.11, 3.12, 3.13

  • Sphinx 6, 7, 8

  • All existing directives and configurations continue to work

📚 Documentation#

For complete documentation, see:

💡 Use Cases#

This release is particularly useful for:

  • Lecture notes where solutions immediately follow exercises

  • Tutorial content with inline solutions

  • Educational materials that benefit from simplified styling

  • Projects that want validation of exercise/solution ordering

Contents