Skip to content

Review ANSI @repl documentation examples with DocumenterVitepress 0.3.5 #904

Description

@ocots

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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions