fix(docs): add ┴ junctions to two outer-box bottom borders to satisfy ascii-guard - #15260
fix(docs): add ┴ junctions to two outer-box bottom borders to satisfy ascii-guard#15260perlowja wants to merge 1 commit into
Conversation
… ascii-guard ascii-guard 2.3.0's validate_box() treats inner-box ┬ characters (appearing in content lines of an outer box) as table-column junctions belonging to the outer box. When it finds ┬/┼ at column N in the outer box's content, it expects a matching ┴ at column N of the outer box's bottom border. The diagrams in architecture.md and gateway-internals.md have inner-box rows whose bottoms use ┬ to connect downward to a second inner-box row — a legitimate ASCII art pattern that ascii-guard misinterprets as a dangling column boundary. Two options: rewrite the diagrams to avoid the ┬ junctions (large, invasive), or add ┴ characters at the flagged positions of the outer bottom border (minimal, surgical). This PR takes the second option. The resulting diagrams still read correctly — the ┴ on the outer box bottom can be read as "the column space continues out of this box", which is consistent with the arrow labels below it. ## Files - website/docs/developer-guide/architecture.md (line 38, cols 11/29/47) - website/docs/developer-guide/gateway-internals.md (line 49, cols 9/23/37) ## Validation ascii-guard 2.3.0 lint on each file before and after: Before: architecture.md: 10 boxes, 3 warnings (Line 39 Col 12/30/48) gateway-internals.md: 4 boxes, 3 warnings (Line 50 Col 10/24/38) After: architecture.md: 10 boxes, 0 warnings, 0 errors gateway-internals.md: 4 boxes, 0 warnings, 0 errors No other docs files changed; other unrelated lint findings on stale committed skill-docs (which the CI regenerates via generate-skill-docs.py before the ascii-guard step) are unaffected and out of scope.
alt-glitch
added
type/docs
CI status update
What my fix did (the intended win)The 6 ascii-guard warnings on The 4 new errors are unrelatedThey're in two CI-regenerated skill docs: Both files are auto-generated by I've filed this as #15305 ("generate-skill-docs.py produces ASCII-guard-failing output for 2 bundled skills") so it can be tracked and fixed independently. What this means for merging #15260This PR still does what it says on the tin — removes 6 genuine ascii-guard warnings on hand-authored architecture diagrams. But the Two paths forward:
My preference is (1) — the fix on Also: |
|
Closing this — verified locally with |
2 participants
What does this PR do?
Fixes 6 pre-existing ascii-guard 2.3.0 warnings that currently block the `docs-site-checks` CI on every PR touching `website/**`.
Both diagrams have a two-row nested-box pattern where the first inner-box row's bottom uses `┬` to connect downward to a second inner-box row. ascii-guard's `validate_box()` routine looks for `┬`/`┼` characters anywhere in the outer box's content lines (not just in its top border) via `get_column_positions()` and concludes those are table-column boundaries belonging to the outer box. It then expects a matching `┴` in the outer box's bottom border — and warns when it finds `─` instead. That interpretation is wrong for this geometry (the `┬` is a purely internal inner-box-to-inner-box connection), but the linter rule is what it is, and the fix is trivial: add `┴` at the three flagged columns of each outer bottom border.
After the fix, the `┴` reads visually as "the column space continues past this box," which matches the arrows already sitting below each outer box. No readability regression.
Related Issue
No existing issue — noticed while filing #15214 (docs cookbook). Verified the warnings are pre-existing on `main` (`architecture.md` last touched in #11373, `gateway-internals.md` much older).
Fixes #
Type of Change
Changes Made
Diff: 2 files changed, 2 insertions(+), 2 deletions(-) — every changed character is a single Unicode swap.
How to Test
Validated locally against ascii-guard 2.3.0 (same version the CI workflow installs via `python -m pip install ascii-guard==2.3.0`).
Before (on clean `upstream/main`):
```
$ ascii-guard lint website/docs/developer-guide/architecture.md
Checking .../architecture.md...
Found 10 ASCII box(es)
⚠ Line 39, Col 12: Bottom border missing junction point at column 11 (expected ┴, got '─')
⚠ Line 39, Col 30: Bottom border missing junction point at column 29 (expected ┴, got '─')
⚠ Line 39, Col 48: Bottom border missing junction point at column 47 (expected ┴, got '─')
$ ascii-guard lint website/docs/developer-guide/gateway-internals.md
Checking .../gateway-internals.md...
Found 4 ASCII box(es)
⚠ Line 50, Col 10: Bottom border missing junction point at column 9 (expected ┴, got '─')
⚠ Line 50, Col 24: Bottom border missing junction point at column 23 (expected ┴, got '─')
⚠ Line 50, Col 38: Bottom border missing junction point at column 37 (expected ┴, got '─')
```
After (on this branch):
```
$ ascii-guard lint website/docs/developer-guide/architecture.md
Checking .../architecture.md...
Found 10 ASCII box(es)
✓ No issues found
✓ Errors: 0
$ ascii-guard lint website/docs/developer-guide/gateway-internals.md
Checking .../gateway-internals.md...
Found 4 ASCII box(es)
✓ No issues found
✓ Errors: 0
```
No other files changed. Other pre-existing ascii-guard findings on committed-but-regenerated-in-CI skill-docs (`skills/bundled/research/research-research-paper-writing.md`, `skills/bundled/mlops/mlops-models-segment-anything.md`) are out of scope for this PR — CI runs `generate-skill-docs.py` before the lint step, which overwrites those files with clean output, so they don't actually fail CI.
Checklist
Code
Documentation & Housekeeping
For New Skills
N/A.
Screenshots / Logs
The 3 `┴` characters on `architecture.md` line 38 now align with the `┬` connectors on line 30 (same columns: 11, 29, 47). Same pattern for `gateway-internals.md`.
Unblocks #15214 (and every other open PR touching `website/**`) from the same CI failure.