control-toolbox / control-toolbox/OptimalControl.jl
Review ANSI @repl documentation examples with DocumenterVitepress 0.3.5
- Dominant language
- Julia
- Stars
- 135
- Forks
- 11
- Avg merge
- 6h 54m
- Merged PRs (30d)
- 56
Description
## 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.
Contributor guide
Assessment
This issue has not been assessed yet.