dandi / dandi/dandi-docs

Add ANSI color rendering to validation output code blocks

Open
#234 0 comments 0 reactions 1 assignee Claimed by @yarikoptic View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.