# 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:**

```python
# In conf.py
exercise_style = "solution_follow_exercise"
```

Or for Jupyter Book:

```yaml
# 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:**

````md
```{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:

```bash
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`:
   ```python
   exercise_style = "solution_follow_exercise"
   ```

2. Rebuild your documentation:
   ```bash
   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

## 🔗 Related PRs

- [#81](https://github.com/executablebooks/sphinx-exercise/pull/81) - Add `exercise_style` configuration and order validation

## 📚 Documentation

For complete documentation, see:
- [Configuration Options](../syntax.md#solution-title-styling)
- [Installation Guide](../install.md)

## 💡 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