Skip to content

Add collapsible stderr warnings feature#333

Merged
mmcky merged 6 commits intomainfrom
feature/collapsible-stderr-warnings
Nov 24, 2025
Merged

Add collapsible stderr warnings feature#333
mmcky merged 6 commits intomainfrom
feature/collapsible-stderr-warnings

Conversation

@mmcky
Copy link
Copy Markdown
Contributor

@mmcky mmcky commented Nov 23, 2025

Overview

Automatically detects and collapses stderr output in Jupyter notebook cells to improve readability when code produces verbose warnings from upstream packages.

Problem Statement

When Jupyter notebooks execute code that produces warnings (via stderr), these warnings can be verbose and visually distracting. Example from QuantEcon lectures:

W1123 10:15:26.780179   23830 cuda_executor.cc:1802] GPU interconnect information not available

While these warnings can be useful for debugging, they:

  • Disrupt the reading flow
  • Take up significant visual space
  • Are often repetitive
  • May not be relevant to most readers

Solution

This PR implements an automatic collapsible interface for stderr warnings with a compact "⚠ Warnings" button that expands/collapses on click.

Features

Automatic detection - No configuration required
Clean UI - Amber warning badge with ⚠ icon
Smooth animations - CSS transitions for expand/collapse
Accessibility - ARIA attributes for screen readers
Dark theme - Full dark mode support
merge_streams compatible - Works correctly with myst-nb's merge_streams option

Implementation

  • JavaScript (+67 lines): Detects and wraps stderr in collapsible interface
  • CSS (+108 lines): Styled warning button with animations
  • Tests: 2 HTML test files with multiple test cases
  • Docs: 3 comprehensive documentation files

Testing

  • Manual testing via tests/stderr_warning_test.html
  • merge_streams compatibility via tests/stderr_merged_streams_test.html
  • Integration testing: npm run build && tox -e docs-update

Breaking Changes

None. This is purely additive functionality that requires no configuration.

Files Changed

  • Modified: CHANGELOG.md, index.js, index.scss
  • Added: 5 new documentation and test files

See full PR description in PR_DESCRIPTION.md for complete details.

- Automatically detects and wraps stderr output in notebook cells
- Displays compact '⚠ Warnings' button that expands/collapses
- Improves readability when code produces verbose warnings
- Includes dark theme support and accessibility features
- No configuration required - works automatically

Files added:
- docs/features/stderr_warnings.md: User documentation
- docs/features/STDERR_WARNINGS_IMPLEMENTATION.md: Technical docs
- tests/stderr_warning_test.html: Standalone test page

Files modified:
- src/quantecon_book_theme/assets/scripts/index.js: Detection & toggle logic
- src/quantecon_book_theme/assets/styles/index.scss: Styling & animations
- CHANGELOG.md: Updated with new feature
- Test file demonstrates behavior with merge_streams=True/False
- Analysis document explains correct behavior in all scenarios
- Confirms feature works correctly regardless of merge_streams setting
@codecov
Copy link
Copy Markdown

codecov bot commented Nov 23, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@768fe14). Learn more about missing BASE report.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #333   +/-   ##
=======================================
  Coverage        ?   31.23%           
=======================================
  Files           ?        2           
  Lines           ?      381           
  Branches        ?        0           
=======================================
  Hits            ?      119           
  Misses          ?      262           
  Partials        ?        0           
Flag Coverage Δ
pytests 31.23% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions github-actions bot temporarily deployed to commit November 23, 2025 22:03 Inactive
- Update README.md to include collapsible stderr warnings in features list
- Update CHANGELOG.md with improved feature description
- Update docs/index.md to link to stderr warnings documentation
- Update feature docs to reflect 'Code warnings' label
- Remove development-only implementation and analysis docs
@github-actions github-actions bot temporarily deployed to commit November 24, 2025 03:19 Inactive
@mmcky mmcky merged commit aa53d00 into main Nov 24, 2025
10 checks passed
@mmcky mmcky deleted the feature/collapsible-stderr-warnings branch November 24, 2025 03:20
mmcky added a commit that referenced this pull request Feb 19, 2026
Complete rewrite of the dark theme for a modern, consistent, and readable dark mode experience.

Color palette:
- Replace ad-hoc grays (#222/#333/#444) with a cohesive navy-charcoal palette
- Body background: #1a1a2e, Surfaces: #252540/#2d2d4a
- Text: #d4d4e4 (soft white, reduces eye strain vs pure #fff)
- Links: #6cb6ff (distinguishable from body text)
- Borders: #3a3a5c (subtle, consistent)

Syntax highlighting:
- Add complete dark mode token colors for all ~40 syntax classes
- VS Code Dark+ inspired palette
- Previously only 3 of ~40 tokens had dark overrides

Bug fixes:
- Fix table row text color (#333 on dark bg was unreadable)
- Fix links being indistinguishable from body text (all were #fff)
- Fix inline code having light border on dark background
- Fix sidebar search area remaining white in dark mode
- Fix toolbar border remaining light gray
- Fix image inversion being too aggressive (now uses subtle opacity)

New dark mode coverage:
- Modals, admonitions (type-specific accents), homepage elements
- Collapse/toggle bars, tooltips, anchor links, autodoc, footnotes
- Non-QuantEcon project color overrides, toctree caption text

UX improvements:
- Eliminate FOUC with early dark mode injection script
- SVG icons use currentColor instead of forced white
- Images use subtle opacity reduction instead of aggressive inversion
- Stderr warnings updated to match new palette
mmcky added a commit that referenced this pull request Feb 19, 2026
Complete rewrite of the dark theme for a modern, consistent, and readable dark mode experience.

Color palette:
- Replace ad-hoc grays (#222/#333/#444) with a cohesive navy-charcoal palette
- Body background: #1a1a2e, Surfaces: #252540/#2d2d4a
- Text: #d4d4e4 (soft white, reduces eye strain vs pure #fff)
- Links: #6cb6ff (distinguishable from body text)
- Borders: #3a3a5c (subtle, consistent)

Syntax highlighting:
- Add complete dark mode token colors for all ~40 syntax classes
- VS Code Dark+ inspired palette
- Previously only 3 of ~40 tokens had dark overrides

Bug fixes:
- Fix table row text color (#333 on dark bg was unreadable)
- Fix links being indistinguishable from body text (all were #fff)
- Fix inline code having light border on dark background
- Fix sidebar search area remaining white in dark mode
- Fix toolbar border remaining light gray
- Fix image inversion being too aggressive (now uses subtle opacity)

New dark mode coverage:
- Modals, admonitions (type-specific accents), homepage elements
- Collapse/toggle bars, tooltips, anchor links, autodoc, footnotes
- Non-QuantEcon project color overrides, toctree caption text

UX improvements:
- Eliminate FOUC with early dark mode injection script
- SVG icons use currentColor instead of forced white
- Images use subtle opacity reduction instead of aggressive inversion
- Stderr warnings updated to match new palette
mmcky added a commit that referenced this pull request Feb 23, 2026
* feat: comprehensive dark theme overhaul

Complete rewrite of the dark theme for a modern, consistent, and readable dark mode experience.

Color palette:
- Replace ad-hoc grays (#222/#333/#444) with a cohesive navy-charcoal palette
- Body background: #1a1a2e, Surfaces: #252540/#2d2d4a
- Text: #d4d4e4 (soft white, reduces eye strain vs pure #fff)
- Links: #6cb6ff (distinguishable from body text)
- Borders: #3a3a5c (subtle, consistent)

Syntax highlighting:
- Add complete dark mode token colors for all ~40 syntax classes
- VS Code Dark+ inspired palette
- Previously only 3 of ~40 tokens had dark overrides

Bug fixes:
- Fix table row text color (#333 on dark bg was unreadable)
- Fix links being indistinguishable from body text (all were #fff)
- Fix inline code having light border on dark background
- Fix sidebar search area remaining white in dark mode
- Fix toolbar border remaining light gray
- Fix image inversion being too aggressive (now uses subtle opacity)

New dark mode coverage:
- Modals, admonitions (type-specific accents), homepage elements
- Collapse/toggle bars, tooltips, anchor links, autodoc, footnotes
- Non-QuantEcon project color overrides, toctree caption text

UX improvements:
- Eliminate FOUC with early dark mode injection script
- SVG icons use currentColor instead of forced white
- Images use subtle opacity reduction instead of aggressive inversion
- Stderr warnings updated to match new palette

* docs: add dark mode documentation and v0.17.1 release updates

* docs: update CHANGELOG with dark theme overhaul changes

* fix: address Copilot review feedback on dark theme PR

- Flatten SCSS nesting to plain CSS in layout.html <style> tag (browsers can't parse SCSS)
- Add missing semicolon in .toctree-wrapper .caption-text rule
- Scope svg g selector to UI icon containers only (.qe-toolbar, .qe-sidebar, .topbar-main, nav) to avoid breaking matplotlib/plotly charts
- Remove duplicate .highlight rules (unreachable :where() block)
- Use strict equality (=== '1') in FOUC prevention script

* UPDATE: Regenerate all visual snapshots (6 files)

* ci: trigger CI and preview build

* refactor: convert dark theme hardcoded colors to CSS custom properties

Declare 16 CSS custom properties on body.dark-theme so downstream
projects can override palette colors without duplicating selectors:

  --qe-dark-bg, --qe-dark-surface, --qe-dark-surface-alt,
  --qe-dark-border, --qe-dark-text, --qe-dark-text-muted,
  --qe-dark-heading, --qe-dark-heading-top, --qe-dark-text-light,
  --qe-dark-link, --qe-dark-link-hover, --qe-dark-link-visited,
  --qe-dark-code-bg, --qe-dark-inline-code, --qe-dark-accent,
  --qe-dark-accent-dark

All ~120 hardcoded palette hex values replaced with var() references.
Semantic colors (admonition accents, modal button text) remain
hardcoded intentionally.

Docs updated with full reference table of available properties.

* fix: double logo in dark theme when dark_logo is configured

The :only-child fallback was matching .logo-img:only-child, but each
<img> is always the sole child of its own <a> wrapper, so it matched
even when a dark logo existed — showing both logos.

Fixed by checking :only-child on the <a> wrapper instead:
  p.logo > a:only-child > .logo-img

When a dark logo IS configured there are two <a> siblings inside
<p class="logo">, so a:only-child won't match and only the dark
logo is shown.

Fixes: double logo issue reported in PR #365

* fix: page header and changelog unreadable in dark theme

The page header (title link, authors, 'Last changed' button) and the
changelog dropdown used colors.$body (#444) which is invisible on
the dark background. Added dark theme overrides for the full
.qe-page__header section:

- Title link → heading-top color
- Authors → primary text
- 'Last changed' button → muted text with accent border
- Changelog dropdown → dark surface background, proper borders
- Commit hash, author, time, message → appropriate text colors

* docs: update CHANGELOG with recent dark theme fixes

Add entries for:
- CSS custom properties refactor (16 overridable --qe-dark-* vars)
- Double logo fix (only-child selector bug)
- Page header/changelog readability fix

* fix: remove extra font-weight on links in dark theme

The dark theme applied font-weight: 600 to .reference links, making
them visually heavier than in light mode. Color alone provides
sufficient contrast on dark backgrounds.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant