From 693618228441a28929620ef068d8f269bf6bbda8 Mon Sep 17 00:00:00 2001
From: Olivier Cots <olivier.cots@irit.fr>
Date: Sun, 30 Aug 2026 23:44:46 +0200
Subject: [PATCH] docs: simplify exception examples with repl blocks

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 docs/README.md                              | 32 ++++++++++-----------
 docs/src/getting-started.md                 | 15 ++--------
 docs/src/guide/descriptions.md              | 10 ++-----
 docs/src/guide/differentiation.md           |  5 +---
 docs/src/guide/exceptions.md                | 29 ++++---------------
 docs/src/guide/implementing-a-strategy.md   |  6 ----
 docs/src/guide/options-system.md            | 25 ++++------------
 docs/src/guide/orchestration-and-routing.md | 15 ++--------
 docs/src/guide/traits.md                    |  5 +---
 docs/src/guide/unicode.md                   |  4 ---
 10 files changed, 36 insertions(+), 110 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index e78f8182..5391e9cc 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,19 +16,19 @@ Documentation conventions and build workflow:
 
 ## `@repl` vs `@example` — ANSI color rule
 
-DocumenterVitepress processes code block output differently depending on how it is produced:
-
-| Block type | Output fence | ANSI codes | Result |
-| --- | --- | --- | --- |
-| `@example` | ` ```ansi ` | processed by Shiki | **colors render correctly** |
-| `@repl` | ` ```julia ` | parsed as Julia syntax | **raw escape sequences — ugly** |
-
-**Rules:**
-
-- Use **`@example`** when the output comes from a `show` method that uses ANSI colors
-  (strategy instances, `StrategyOptions`, `StrategyMetadata`, `StrategyRegistry`, …).
-- Use **`@repl`** only when the output is a plain scalar value with no custom colored `show`
-  (integers, booleans, symbols, plain strings, tuples of symbols, types).
-- Use **`@repl` + `try/catch # hide` + `showerror(IOContext(stdout, :color => false), e) # hide`**
-  to display exceptions — the `showerror` call produces plain text that renders cleanly inside a
-  `julia`-fenced block.
+Before `DocumenterVitepress` **v0.3.5**, ANSI-colored output from `@repl` could be rendered as raw
+escape sequences. This was fixed in v0.3.5 ([#373](https://github.com/LuxDL/DocumenterVitepress.jl/pull/373)):
+colored `@repl` output is now rendered correctly while the input remains Julia syntax-highlighted.
+
+**Rules for v0.3.5 and later:**
+
+- Use **`@repl`** for interactive examples, including output from custom ANSI-colored `show`
+  methods (strategy instances, `StrategyOptions`, `StrategyMetadata`, `StrategyRegistry`, …).
+- Use **`@example`** for regular evaluated examples when REPL formatting is not needed; keep existing
+  blocks whose output already renders correctly.
+- Use **`@ansi`** when explicitly demonstrating terminal styling or raw ANSI output.
+- Use **`@repl`** with a direct expression that raises an exception when demonstrating native REPL
+  error handling; `@repl` captures the exception as output instead of failing the documentation build.
+
+For versions before v0.3.5, use `@example` or `@ansi` for colored output, or use an explicit
+`try/catch` and `showerror(IOContext(stdout, :color => false), e)` when a colorless output is required.
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
index 969449c9..39bf7e6c 100644
--- a/docs/src/getting-started.md
+++ b/docs/src/getting-started.md
@@ -69,11 +69,8 @@ CTBase.Descriptions.complete(:implicit; descriptions=descs)
 CTBase.Descriptions.complete(:euler; descriptions=descs)
 
 # No entry contains both :runge_kutta and :implicit → raises AmbiguousDescription
-try # hide
 CTBase.Descriptions.complete(:runge_kutta, :implicit; descriptions=descs)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 For more, see the **[Descriptions guide](guide/descriptions.md)**.
@@ -86,27 +83,21 @@ Each type carries structured context fields for actionable error messages.
 
 ```@repl walkthrough
 # IncorrectArgument — invalid input value
-try # hide
 throw(CTBase.Exceptions.IncorrectArgument(
     "state dimension must be positive";
     got="0",
     expected="n > 0",
     suggestion="Pass a positive integer for the state dimension",
 ))
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 
 # NotImplemented — interface stub
-try # hide
 throw(CTBase.Exceptions.NotImplemented(
     "solve! is not implemented";
     required_method="solve!(::MyStrategy, ocp)",
     suggestion="Import the package that provides this strategy",
 ))
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 For more, see the **[Exceptions guide](guide/exceptions.md)**.
diff --git a/docs/src/guide/descriptions.md b/docs/src/guide/descriptions.md
index 275ae70d..d6ea9a7f 100644
--- a/docs/src/guide/descriptions.md
+++ b/docs/src/guide/descriptions.md
@@ -35,13 +35,10 @@ algorithms = CTBase.Descriptions.add(
 Attempting to add a duplicate raises [`CTBase.Exceptions.IncorrectArgument`](@ref):
 
 ```@repl desc
-try # hide
 CTBase.Descriptions.add(
     algorithms, (:descent, :bfgs, :bisection),
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ## Completing a partial description
@@ -63,13 +60,10 @@ largest overlap is returned (first wins on tie). If no entry matches,
 [`CTBase.Exceptions.AmbiguousDescription`](@ref) is raised:
 
 ```@repl desc
-try # hide
 CTBase.Descriptions.complete(
     :euler; descriptions=algorithms,
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ## Removing symbols from a description
diff --git a/docs/src/guide/differentiation.md b/docs/src/guide/differentiation.md
index 4b9bcf32..27ab77c0 100644
--- a/docs/src/guide/differentiation.md
+++ b/docs/src/guide/differentiation.md
@@ -315,13 +315,10 @@ backends must override:
 struct MyBackend <: Differentiation.AbstractADBackend
     options::Strategies.StrategyOptions
 end
-try # hide
 Differentiation.gradient(
     MyBackend(Strategies.StrategyOptions()), x -> sum(x), [1.0],
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ## See also
diff --git a/docs/src/guide/exceptions.md b/docs/src/guide/exceptions.md
index ac06a044..758f06a2 100644
--- a/docs/src/guide/exceptions.md
+++ b/docs/src/guide/exceptions.md
@@ -72,22 +72,15 @@ Adding a duplicate description:
 ```@repl
 using CTBase
 algorithms = CTBase.Descriptions.add((), (:a, :b))
-try # hide
 CTBase.Descriptions.add(algorithms, (:a, :b))  # Error: duplicate
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 Using invalid indices for the Unicode helpers:
 
 ```@repl
 using CTBase
-try # hide
 CTBase.Unicode.ctindice(-1)  # Error: must be between 0 and 9
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
 ```
 
 **Use this exception** whenever *one input value* is outside the allowed domain
@@ -114,11 +107,8 @@ valid description.
 ```@repl
 using CTBase
 D = ((:a, :b), (:a, :b, :c), (:b, :c))
-try # hide
 CTBase.Descriptions.complete(:f; descriptions=D)  # Error: no match found
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 **Use this exception** when *the high-level choice of description itself* is wrong
@@ -253,15 +243,12 @@ CTBase.Exceptions.ParsingError <: CTBase.Exceptions.CTException
 
 ```@repl
 using CTBase
-try # hide
 throw(CTBase.Exceptions.ParsingError(
     "unexpected token 'end'",
     location="line 42, column 10",
     suggestion="Check for unmatched 'begin' or remove extra 'end'"
 ))
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 **Use this exception** when parsing user input, configuration files, or DSL expressions.
@@ -297,15 +284,12 @@ The enriched display automatically suggests:
 
 ```@repl
 using CTBase
-try # hide
 throw(CTBase.Exceptions.ExtensionError(
     :Plots,
     feature="result visualization",
     context="plot_results function",
 ))
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 **Use this exception** when:
@@ -354,16 +338,13 @@ nothing # hide
 The enriched display shows the solver-specific return code:
 
 ```@repl solver-failure
-try # hide
 throw(CTBase.Exceptions.SolverFailure(
     "ODE integration failed",
     retcode=":Unstable",
     suggestion="Reduce time step or check initial conditions",
     context="SciML integrator",
 ))
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 **Common return codes**:
diff --git a/docs/src/guide/implementing-a-strategy.md b/docs/src/guide/implementing-a-strategy.md
index 5aa346a4..ed92dd9a 100644
--- a/docs/src/guide/implementing-a-strategy.md
+++ b/docs/src/guide/implementing-a-strategy.md
@@ -197,11 +197,7 @@ Strategies.is_default(Strategies.options(c), :scheme)
 A typo in an option name triggers a helpful error with Levenshtein suggestion:
 
 ```@repl strategy
-try # hide
 Collocation(grdi_size = 500)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
 ```
 
 ## Adding a Second Strategy: DirectShooting
@@ -381,9 +377,7 @@ Collocation(
 **Known option with wrong type** — normally rejected, accepted with `bypass`:
 
 ```@repl strategy
-try # hide
 Collocation(grid_size = "oops")   # type error: grid_size expects Int
-catch e; showerror(IOContext(stdout, :color => false), e) end # hide
 ```
 
 ```@example strategy
diff --git a/docs/src/guide/options-system.md b/docs/src/guide/options-system.md
index 371fa106..cb54bdea 100644
--- a/docs/src/guide/options-system.md
+++ b/docs/src/guide/options-system.md
@@ -67,14 +67,11 @@ The constructor automatically:
 Type mismatch in the constructor:
 
 ```@repl options
-try # hide
 Options.OptionDefinition(
     name = :count, type = Integer,
     default = "hello", description = "A count",
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ### Aliases
@@ -115,11 +112,8 @@ nothing # hide
 Validator failure:
 
 ```@repl options
-try # hide
 Options.extract_option((tol = -1.0,), validated_def)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ## NotProvided
@@ -173,11 +167,8 @@ Options.OptionValue(42, :computed)
 Invalid source:
 
 ```@repl options
-try # hide
 Options.OptionValue(42, :invalid_source)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 Provenance tracking enables introspection — you can tell whether a value was explicitly chosen or inherited from defaults:
@@ -351,11 +342,8 @@ Options.is_default(opts, :verbose)
 Rejects unknown options with a helpful error message:
 
 ```@repl options
-try # hide
 CTBase.Strategies.build_strategy_options(DemoStrategy; max_itr = 500)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ### Permissive mode
@@ -400,11 +388,8 @@ The function:
 Type mismatch in extraction:
 
 ```@repl options
-try # hide
 Options.extract_option((grid_size = "hello",), def_grid)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ### `extract_options`
diff --git a/docs/src/guide/orchestration-and-routing.md b/docs/src/guide/orchestration-and-routing.md
index f733854a..eb940762 100644
--- a/docs/src/guide/orchestration-and-routing.md
+++ b/docs/src/guide/orchestration-and-routing.md
@@ -268,13 +268,10 @@ Orchestration.extract_strategy_ids(:plain_value, resolved)
 Passing an unknown strategy ID throws an error:
 
 ```@repl routing
-try # hide
 Orchestration.extract_strategy_ids(
     Strategies.route_to(unknown = 42), resolved,
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ## Complete Example
@@ -315,25 +312,19 @@ routed.strategies
 ### Error: unknown option
 
 ```@repl routing
-try # hide
 Orchestration.route_all_options(
     method, families, action_defs,
     (foo = 42,), registry,
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 ### Error: ambiguous option without disambiguation
 
 ```@repl routing
-try # hide
 Orchestration.route_all_options(
     method, families, action_defs,
     (backend = :sparse,), registry,
 )
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
diff --git a/docs/src/guide/traits.md b/docs/src/guide/traits.md
index 77502b06..5385d75d 100644
--- a/docs/src/guide/traits.md
+++ b/docs/src/guide/traits.md
@@ -253,11 +253,8 @@ If a type does not declare a trait, the predicates throw an informative error
 rather than returning a wrong default:
 
 ```@repl traits
-try # hide
 Traits.is_autonomous(3.14)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
+
 ```
 
 !!! note "Trait types are shared"
diff --git a/docs/src/guide/unicode.md b/docs/src/guide/unicode.md
index 6c16bd85..f7e7b17c 100644
--- a/docs/src/guide/unicode.md
+++ b/docs/src/guide/unicode.md
@@ -46,11 +46,7 @@ Passing a negative integer or a value outside 0–9 to the single-digit function
 raises [`CTBase.Exceptions.IncorrectArgument`](@ref):
 
 ```@repl uni
-try # hide
 CTBase.Unicode.ctindice(12)
-catch e # hide
-showerror(IOContext(stdout, :color => false), e) # hide
-end # hide
 ```
 
 ## Function Reference