Context
The Control-Toolbox Handbook documents a historical limitation of DocumenterVitepress: before v0.3.5, ANSI-colored output from @repl could be rendered as raw escape sequences. DocumenterVitepress v0.3.5 fixes this behavior (#373), so documentation workarounds may now be obsolete.
Requested review
Please audit the OptimalControl.jl documentation for:
- @repl blocks using try/catch solely to prevent documentation-build failures;
- manual showerror(IOContext(stdout, :color => false), e) calls used only to avoid ANSI rendering issues;
- @example blocks chosen solely because colored @repl output was historically broken;
- opportunities to use direct exception expressions in @repl, relying on REPL-style exception capture;
- cases where @Ansi is more appropriate for an explicit terminal-color demonstration.
Keep @example where regular evaluated-example formatting is preferable, and preserve explicit monochrome output when it is a deliberate presentation choice. Confirm the documentation environment uses DocumenterVitepress >= 0.3.5 and verify the generated site with the documentation build.
Reference implementation
CTBase.jl applied this cleanup in PR control-toolbox/CTBase.jl#547, tracked by issue control-toolbox/CTBase.jl#546. The updated Handbook guidance is available at:
https://github.com/control-toolbox/Handbook/blob/main/VITEPRESS-DOC.md
Please report which blocks were reviewed and update the relevant documentation where appropriate.
Context
The Control-Toolbox Handbook documents a historical limitation of DocumenterVitepress: before v0.3.5, ANSI-colored output from @repl could be rendered as raw escape sequences. DocumenterVitepress v0.3.5 fixes this behavior (#373), so documentation workarounds may now be obsolete.
Requested review
Please audit the OptimalControl.jl documentation for:
Keep @example where regular evaluated-example formatting is preferable, and preserve explicit monochrome output when it is a deliberate presentation choice. Confirm the documentation environment uses DocumenterVitepress >= 0.3.5 and verify the generated site with the documentation build.
Reference implementation
CTBase.jl applied this cleanup in PR control-toolbox/CTBase.jl#547, tracked by issue control-toolbox/CTBase.jl#546. The updated Handbook guidance is available at:
https://github.com/control-toolbox/Handbook/blob/main/VITEPRESS-DOC.md
Please report which blocks were reviewed and update the relevant documentation where appropriate.