---
phase: quick-260321-i40
plan: 01
subsystem: docs
tags: [pygments, sphinx, syntax-highlighting, css, lexer]

# Dependency graph
requires: []
provides:
  - "Custom Pygments lexer for SQL grammar notation (sqlgrammar)"
  - "4-color syntax highlighting in reference doc Syntax sections"
affects: [docs]

# Tech tracking
tech-stack:
  added: [pygments-custom-lexer]
  patterns: [sphinx-custom-lexer-registration, scoped-css-for-highlight-blocks]

key-files:
  created:
    - docs/_ext/sqlgrammar_lexer.py
    - docs/_ext/__init__.py
    - docs/_static/css/sqlgrammar.css
  modified:
    - docs/conf.py
    - docs/reference/create-semantic-view.rst
    - docs/reference/drop-semantic-view.rst
    - docs/reference/describe-semantic-view.rst
    - docs/reference/show-semantic-views.rst
    - docs/reference/semantic-view-function.rst
    - docs/reference/explain-semantic-view-function.rst

key-decisions:
  - "Token.Keyword for SQL keywords, Token.Name.Variable for angle-bracket placeholders, Token.Name.Tag for brackets/ellipsis, Token.Literal.String for string literals"
  - "CSS scoped to .highlight-sqlgrammar to avoid affecting standard sql code blocks"
  - "Dark mode variant via [data-theme=dark] selector for Shibuya theme compatibility"

patterns-established:
  - "Custom Pygments lexer registration: sys.path.insert + app.add_lexer() in conf.py setup()"
  - "Scoped CSS: .highlight-{lang} class for per-language styling"

requirements-completed: []

# Metrics
duration: 3min
completed: 2026-03-21
---

# Quick Task 260321-i40: Custom Pygments Lexer for SQL Grammar Syntax Highlighting

**Custom Pygments RegexLexer with 4-color scheme (keywords/placeholders/brackets/strings) applied to all 6 reference doc Syntax sections with light and dark mode CSS**

## Performance

- **Duration:** 3 min
- **Started:** 2026-03-21T13:08:19Z
- **Completed:** 2026-03-21T13:11:01Z
- **Tasks:** 3 (2 auto + 1 build verification)
- **Files modified:** 10

## Accomplishments
- Created SqlGrammarLexer with 4 distinct token types for SQL grammar notation
- Added scoped CSS with light mode and dark mode (Shibuya theme) color variants
- Registered lexer in Sphinx conf.py via setup() function
- Updated exactly 6 Syntax section code blocks to use sqlgrammar; all other code blocks unchanged
- Sphinx build succeeds with no lexer-related warnings
- HTML output confirmed: .k (keyword), .nv (placeholder), .nt (bracket/ellipsis), .s (string) classes all present

## Task Commits

Each task was committed atomically:

1. **Task 1: Create the custom Pygments lexer, CSS, and register in conf.py** - `6f985e3` (feat)
2. **Task 2: Update Syntax sections in all 6 reference docs** - `fb672de` (feat)
3. **Task 3: Verify rendered output** - Build verification only (no commit needed)

## Files Created/Modified
- `docs/_ext/__init__.py` - Empty init for _ext package
- `docs/_ext/sqlgrammar_lexer.py` - Custom Pygments RegexLexer with 4 token types
- `docs/_static/css/sqlgrammar.css` - 4-color scheme CSS for light and dark modes
- `docs/conf.py` - Added sys.path, html_static_path, html_css_files, setup() with add_lexer
- `docs/reference/create-semantic-view.rst` - Syntax block changed to sqlgrammar
- `docs/reference/drop-semantic-view.rst` - Syntax block changed to sqlgrammar
- `docs/reference/describe-semantic-view.rst` - Syntax block changed to sqlgrammar
- `docs/reference/show-semantic-views.rst` - Syntax block changed to sqlgrammar
- `docs/reference/semantic-view-function.rst` - Syntax block changed to sqlgrammar
- `docs/reference/explain-semantic-view-function.rst` - Syntax block changed to sqlgrammar

## Decisions Made
- Token type mapping: Keyword, Name.Variable, Name.Tag, Literal.String chosen to match Pygments CSS class conventions (.k, .nv, .nt, .s)
- CSS includes both .s and .s1 selectors for string tokens (Pygments may emit either)
- Dark mode colors selected as lighter variants of the light mode palette for contrast on dark backgrounds

## Deviations from Plan

None - plan executed exactly as written.

## Build Verification (Task 3)

Sphinx build output:
- **Exit code:** 0 (success)
- **Warnings:** 1 pre-existing intersphinx warning (DuckDB objects.inv 404) - unrelated to lexer
- **Lexer-related warnings:** None
- **HTML verification:** All 6 reference pages contain `highlight-sqlgrammar` wrapper divs with correct token classes (.k, .nv, .nt, .s)
- **Example sections:** Confirmed 11 standard `highlight-sql` blocks remain unchanged in create-semantic-view.html

Awaiting human visual verification of rendered output in browser.

## Issues Encountered
None

## User Setup Required
None - no external service configuration required.

## Next Steps
- Human visual verification: open `docs/_build/html/reference/create-semantic-view.html` in browser
- Check 4-color rendering in Syntax section vs standard SQL in Examples
- Toggle dark mode to verify color variants

## Self-Check: PASSED

- All 4 created files verified on disk
- Commit 6f985e3 (Task 1) verified in git log
- Commit fb672de (Task 2) verified in git log
- 6 sqlgrammar code blocks confirmed in reference docs
- Sphinx build exit code 0 with no lexer warnings
