docs: simplify exception examples with @repl

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.

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)**.

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

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

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

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

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`

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
+
 ```

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"

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