Add ANSI color rendering to validation output code blocks
- Dominant language
- No language data
- Stars
- 6
- Forks
- 18
- Avg merge
- 18h 52m
- Merged PRs (30d)
- 2
Description
## Summary
The validation documentation code blocks (e.g., `$ dandi validate ...` examples) currently (PR yet to be sent for extended docs on validate, TODO) show plain uncolored text. `dandi validate` uses Click's `secho` to color output by severity (red=ERROR, yellow=WARNING, blue=HINT), but the generation script strips ANSI codes since standard markdown code blocks can't render them.
## Proposed Solution
Use [`pygments-ansi-color`](https://github.com/chriskuehl/pygments-ansi-color) — a Pygments lexer plugin that parses ANSI escape sequences and renders them as colored HTML. It registers an `ansi-color` language identifier that works with `pymdownx.highlight`.
### Implementation Steps
1. **Add dependency**: `pygments-ansi-color` to `requirements.txt` (requires Python >= 3.10)
2. **Add CSS**: Either:
- Use [`markdown-exec[ansi]`](https://github.com/pawamoy/markdown-exec) which bundles `pygments-ansi-color` + ready-made CSS with light/dark theme support
- Or manually add an `ansi.css` file (e.g., from markdown-exec's assets) to `docs/css/` and reference it in `extra_css`
3. **Update generation script** (`scripts/generate-validation-examples.sh`):
- Force color output: set `FORCE_COLOR=1` or equivalent env var for dandi-cli/Click
- **Do not** strip ANSI codes from the output files that will use `ansi-color` blocks
- Keep sanitizing absolute paths
4. **Update code blocks** in `docs/user-guide-sharing/validating-files.md`:
- Change ` ```console ` to ` ```ansi-color ` for blocks that show `dandi validate` output
- The ANSI escape sequences in the example files will be rendered as colored HTML
### Example
A code block like:
````markdown
```ansi-color
[31m[ERROR][0m [pynwb.GENERIC] sub-RAT123/sub-RAT123.nwb — nwb_version '2.0b' is not a proper semantic version.
[33m[WARNING][0m [NWBI.check_subject_age] sub-RAT123/sub-RAT123.nwb — Subject age, '12 mo', does not follow ISO 8601...
[34m[HINT][0m [BIDS.README_FILE_MISSING] dataset_description.json — The recommended file /README is missing.
```
````
Would render with red/yellow/blue colors matching what users see in their terminal.
### Caveats
- The example files must contain **literal ANSI escape bytes**, not the text representation `\033[31m`
- `pygments-ansi-color` supports standard 8 colors + bright variants + bold — sufficient for Click's `secho` output
- Need to verify colors render well against both mkdocs-material default and slate (dark) themes
- Also consider [`click-extra`](https://kdeldycke.github.io/click-extra/pygments.html) which extends `pygments-ansi-color` with ANSI-aware shell session lexers (could allow ` ```console ` blocks with colored output)
### Related
- https://github.com/chriskuehl/pygments-ansi-color
- https://github.com/pawamoy/markdown-exec (bundles ansi support)
- https://kdeldycke.github.io/click-extra/pygments.html (ANSI-aware console lexer)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.