control-toolbox / control-toolbox/CTModels.jl

Review ANSI @repl documentation examples with DocumenterVitepress 0.3.5

Open
#418 0 comments 0 reactions 1 assignee Claimed by @ocots View on GitHub
Dominant language
Julia
Stars
3
Forks
1
Avg merge
4h 10m
Merged PRs (30d)
20

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 CTModels.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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.